When ExtraView is configured to work directly to an LDAP server, the following functions are enabled, all without any need for custom programming within ExtraView:
- Access to an unlimited number of LDAP fields
- Customized mapping of one or more fields in ExtraView to one or more fields LDAP fields
- Customized pre-population of mapped fields on the ExtraView Add and Edit Screens
- Customized pre-population of fields through a popup link
- The upsert of data to the ExtraView user table, based on a configuration value. Upsert is a combination of insert and update. If a record exists, it is updated, if it does not exist, it is inserted.
Setup Access Details to your LDAP Server
There are two background tasks that can be used to enhance the LDAP server performance. Only one of these should be configured at one time, and for most purposes, this should be the task titled LDAP Background Task and not the LDAP Synchronization Task. Click on the links to see the documentation for each of these topics.
There are several behavior settings that control access to your LDAP server. These should be configured first, to provide the basic connection from ExtraView to your LDAP server. These settings are:
| Setting | Purpose |
| LDAP_USER_LOOKUP | This is the basic on/off switch for LDAP. Set this to YES if you intend to use an LDAP server for user lookup |
| LDAP_DEFAULT_AREA | This is the ID of the business area to associate with a new user who is added to ExtraView via the LDAP server. To find this number, look at the data dictionary field AREA, and click the List button. By each business area you will see the ID. It is essential that you provide a valid entry for this setting. |
| LDAP_DEFAULT_PROJECT | This is the ID of the project within the business area to associate with a new user who is added to ExtraView via the LDAP server. To find this number, look at the data dictionary field PROJECT, and click the List button. Select the business area and you will see a list of the IDs associated with each project. Normally you will choose the DATA project within the business area. It is essential that you provide a valid entry for this setting. |
| LDAP_HOST | This is the URL to your LDAP server. It is essential that you provide a valid entry for this setting. |
| LDAP_MANAGER | The “Security Principal” or user accessing LDAP |
| LDAP_PSWRD | The password to the LDAP server |
| LDAP_ROOT | The root directory of the LDAP server or search base, e.g. ou=blahWorker, o=blah.com. It is essential that you provide a valid entry for this setting. |
| LDAP_ALLOWED_STALE_INTERVAL | The minimum number of minutes between LDAP upsert operations on a single user. This stops ExtraView accessing the LDAP server with every operation that requires user information in order to optimize performance. After this interval, a fresh check of the LDAP server is made. The LDAP Background Task should be running for this to work |
| LDAP_SEARCH_FILTER | LDAP filters may be defined in the behavior setting or may be defined in the Configuration.properties file. The behavior setting takes precedence over the Configuration.properties entry. LDAP filters are defined in RFC 2254. As an example, if you wanted to add a filter to only retrieve records with mycompany within the email address, you could set this as the filter: (mail=*mycompany*) The parentheses are essential. |
| LDAP_UPSERT |
This setting controls upserting LDAP information to ExtraView. THe possible values are YES or NO. When this value is NO, LDAP will not be used to add or update ExtraView user information. A valid LDAP user that is not already an ExtraView user will not be able to log in to ExtraView.
If this setting is YES, then SSO_UPSERT should always be set to a value of NO. |
| LDAP_UPSERT_DEFAULT_USER_ROLE | If this setting contains a valid role, then this is the role a user is given when the LDAP upsert takes place. If this setting does not contain a value, then the role defined in the behavior setting named LIMITED_USER_ROLE is used instead. |
| LDAP_USER_LOOKUP | When this behavior setting is set to YES, whenever a user performs an operation to lookup the details of another user, ExtraView will ask the LDAP server for the information. At the same time this is done, the information for the user within ExtraView, will be synchronized with the information within the LDAP record |
Setting LDAP Fields in the Configuration.properties File
In the configuration file of the application server (Configuration.properties), there is a parameter named LDAP_FIELDS. These are the meta-names of the mappings to be used with LDAP. These must be comma separated, listed on one line. The following fields are mandatory and must be provided as the fields for the upsert operation:
| LDAP_FIELDS = | LDAP_PRIMARYKEY, |
| LDAP_SURNAME, | |
| LDAP_GIVENNAME, | |
| LDAP_COMMONNAME, | |
| LDAP_EMAIL, | |
| LDAP_STREET, | |
| LDAP_CITY, | |
| LDAP_STATE, | |
| LDAP_POSTALCODE, | |
| LDAP_COUNTRY, | |
| LDAP_PHONE |
Other fields may be added. They should follow the same naming convention. These represent the fields for which information will be retrieved. For example, you might add more fields such as:
| LDAP_MOBILE, | |
| LDAP_PAGER, | |
| LDAP_COMPANYNAME, | |
| LDAP_DEPARTMENT, | |
| LDAP_TITLE | |
| LDAP_ADDITIONAL_EMAIL | |
| LDAP_ADDRESS_LINE2 | |
| LDAP_PHONE | |
| LDAP_HOME_PHONE | |
| LDAP_COMPANYNAME | |
| LDAP_FAX | |
| LDAP_USER_DEFINED_1 | |
| LDAP_USER_DEFINED_2 | |
| LDAP_USER_DEFINED_3 | |
| LDAP_USER_DEFINED_4 | |
| LDAP_USER_DEFINED_5 | |
| LDAP_USER_DEFINED_6 | |
| LDAP_USER_DEFINED_7 | |
| LDAP_USER_DEFINED_8 | |
| LDAP_USER_DEFINED_9 | |
| LDAP_USER_DEFINED_10 |
Map the Fields in LDAP_FIELDS to Values in the LDAP Directory
These fields are mapped with a 1:1 relationship, similar to the following example:
| LDAP_PRIMARYKEY | = | employeenumber |
| LDAP_LOGINID | = | uid |
| LDAP_SURNAME | = | sn |
| LDAP_GIVENNAME | = | givenname |
| LDAP_COMMONNAME | = | cn |
| LDAP_EMAIL | = | |
| LDAP_STREET | = | street |
| LDAP_CITY | = | l |
| LDAP_STATE | = | st |
| LDAP_POSTALCODE | = | postalcode |
| LDAP_COUNTRY | = | postaladdress |
| LDAP_PHONE | = | telephonenumber |
| LDAP_MOBILE | = | mobile |
| LDAP_PAGER | = | pager |
| LDAP_COMPANYNAME | = | displayname |
| LDAP_DEPARTMENT | = | department |
| LDAP_TITLE | = | title |
Map the Fields in LDAP_FIELDS to Values in ExtraView
There can be more than one ExtraView field mapped to an LDAP_FIELD. You must prefix the name of the LDAP field meta-name with the characters EV_. For example, LDAP_PRIMARYKEY becomes EV_LDAP_PRIMARYKEY. You should separate multiple values with a comma.
| EV_LDAP_PRIMARYKEY | = | USR_ID |
| EV_LDAP_SURNAME | = | USR_LNAME |
| EV_LDAP_GIVENNAME | = | USR_FNAME |
| EV_LDAP_COMMONNAME | = | USR_NAME |
| EV_LDAP_EMAIL | = | USR_EMAIL |
| EV_LDAP_STREET | = | |
| EV_LDAP_CITY | = | USR_CITY |
| EV_LDAP_STATE | = | USR_STATE |
| EV_LDAP_POSTALCODE | = | |
| EV_LDAP_COUNTRY | = | |
| EV_LDAP_PHONE | = | USR_PHONE,USR_PHONE2 |
| EV_LDAP_MOBILE | = | USR_MOBILE |
| EV_LDAP_PAGER | = | |
| EV_LDAP_COMPANYNAME | = | |
| EV_LDAP_DEPARTMENT | = | USR_DEPT |
| EV_LDAP_TITLE | = |
List Fields to be Pre-populated
Ensure each of these is placed on ONE line:
Add Screen
This is a comma-separated list of ExtraView field names that are to be filled in on add screens, from values in the LDAP, and based on a search for a user. Example:
ADD_SCREEN_LDAP_FIELDS = USR_NAME, USR_TITLE, USR_DEPT, USR_EMAIL, USR_PHONE, USR_PHONE2, USR_MOBILE, USR_FAX, USR_CITY, USR_STATE, USR_BUILDING
Edit Screen
This is a comma-separated list of ExtraView field names that are to be filled in on edit screens, from values in the LDAP, and based on a search for a user. Example:
EDIT_SCREEN_LDAP_FIELDS = USR_NAME, USR_TITLE, USR_DEPT,USR_EMAIL, USR_PHONE,USR_PHONE2
Searching on the Add and Edit Screens
This is a comma-separated list of ExtraView field names whose values are to be used as the search key for filling the field values on the add or edit screens. Example:
LDAP_USER_FIELD_NAMES = USR_NAME, USR_TITLE
Specify if you want to Update ExtraView User Information with the Latest Information from the LDAP Server
If you specify YES, then when each user signs in to ExtraView, the code will upsert that user’s information to the ExtraView user table, directly from the LDAP directory.
LDAP_UPSERT = YES
If LDAP_UPSERT is NO, a user will not be able to sign on to ExtraView if they have not already been added to the system. The default value for this behavior is YES, so new users will be upserted and will be signed on.
Extending the Query Capability
When you have configured your LDAP connection to ExtraView, and you click on the search icon by a user field, a popup allows you to search the LDAP directory for users and to return one or more user’s details into the form on the screen. It is sometimes useful to configure the fields used for the query.
This is accomplished with the LDAP_SEARCH_FIELDS property within the Configuration.properties file. This is a comma-separated list of LDAP field names. The LDAP search may be filtered by these additional attributes.
For example, entering the following on a single line within the Configuration.properties file:
LDAP_SEARCH_FIELDS = SURNAME,
GIVENNAME,
PRIMARYKEY,
PHONE, COMPANYNAME
extends the search for users on user pop-ups to use the PHONE and the COMPANYNAME fields in addition to the standard fields.
User Name Lookup
There is an optional field within the Configuration.properties files named LDAP_EDIT_FIELDS_CHANGE_ON_REFRESH. When there is a parent user field mapped to an LDAP field and this is placed on an edit screen and this field is set to a value of NO, the child fields that are mapped are not altered when the parent field is changed. This allows the values of a record on the LDAP server to be placed on an edit screen and not be altered once they have been read from the LDAP server. The default value for this property is YES, allowing the child fields to be refreshed when the parent is altered.
When LDAP is configured for user lookup, and LDAP_LOGINID is configured to map to the same LDAP name as LDAP_PRIMARYKEY, the values returned for an LDAP search will contain the mapping: LDAP_PRIMARYKEY –> SECURITY_USER_ID and LDAP_LOGINID_KEY –> LOGIN_ID for the user. The primary effect of this is on user custom code that expects the LOGIN_ID to be the value returned for LDAP_LOGINID. Note that this is not the result.
User ID’s
Some LDAP installations are configured to support User ID’s that contain space characters. ExtraView does not support space characters within a User ID. It is considered bad practice to use User ID’s that contain space characters. User ID’s that contain space characters on the LDAP server cannot be mapped to User ID’s in ExtraView.
Upsert of Users
If the Configuration.properties file contains the entry LDAP_UPSERT = YES, then you may specify which fields within ExtraView are updated with the upsert operation. The entry LDAP_UPSERT should be followed with an entry named UPSERT_LDAP_FIELDS. This will include all or a subset of the fields in the following list:
UPSERT_LDAP_FIELDS = LDAP_COMMONNAME, LDAP_GIVENNAME, LDAP_SURNAME, LDAP_EMAIL, LDAP_ADDITIONAL_EMAIL, LDAP_STREET, LDAP_ADDRESS_LINE2, LDAP_PHONE, LDAP_HOME_PHONE, LDAP_MOBILE, LDAP_PAGER, LDAP_COMPANYNAME, LDAP_POSTALCODE, LDAP_STATE, LDAP_CITY, LDAP_COUNTRY, LDAP_FAX, LDAP_USER_DEFINED_1, LDAP_USER_DEFINED_2, LDAP_USER_DEFINED_3, LDAP_USER_DEFINED_4, LDAP_USER_DEFINED_5, LDAP_TITLE
If the UPSERT_LDAP_FIELDS statement is not included then all the fields are assumed to be updated upon the upsert operation.
Timeouts
It is important that the connection from ExtraView to the LDAP server is extremely fast. A poor LDAP connection will introduce unacceptable performance problems into the environment. To guard against LDAP connections that do not return information in a timely manner, there are two timeouts:
TCP connection timeout. If there is general network slowness, there is a two-minute timeout period.
LDAP read timeout. This is set to one minute, and guards against a response not being received from the LDAP server. Note that Java 1.6 (or greater) is required for this timeout to work.
Pre-population of Fields from the LDAP Server
Assuming that you have set up the above configuration parameters, when you load the ExtraView add screen, the fields you selected for ADD_SCREEN_LDAP_FIELDS in Configuration.properties will pre-populate with values from the LDAP directory, according to the LDAP mappings configured in the Configuration.properties file.
In the example below, the circled fields are all pre-populated from the LDAP entry based on the current user (Campbell, Rob).
Example of fields pre-populated from an LDAP server
Popup Link Configuration
After you have decided which fields to put on your Add and Edit screen layouts, you can pick one (usually a primary identifier such as the user’s name) to have a URL link popup window beside it. This popup window will allow for dynamic searching of the LDAP directory. It will also populate multiple fields on the Add or Edit screen with the values for the primary identifier. ExtraView fields will be populated from the LDAP directory based on the mappings you set up in Configuration.properties.
First, configure the link with the appropriate URL, within the Data Dictionary. Full instructions for this are in the Data Dictionary section of this administration guide.
Data Dictionary entry where the popup link is configured
- Set Display as URL to Yes.
-
Enter the first part of the URL, exactly as shown. Do not complete the field entry yet
?p_action=doDisplay&p_option=security.SearchLDAPDisplay
-
Append to the URL the list of fields you want populated in the following pattern, but using the fields for your installation:
&FIELD=USR_NAME&FIELD=USR_TITLE&FIELD=USR_DEPT &FIELD=USR_EMAIL&FIELD=USR_PHONE &FIELD=USR_PHONE2&FIELD=USR_MOBILE &FIELD=USR_FAX&FIELD=USR_CITY&FIELD=USR_STATE &FIELD=USR_BUILDING
where the pattern for each field is &FIELD=DataDictionaryName
The final URL will look something like this:
?p_action=doDisplay&p_option=security.SearchLDAPDisplay &FIELD=USR_NAME&FIELD=USR_TITLE&FIELD=USR_DEPT &FIELD=USR_EMAIL&FIELD=USR_PHONE &FIELD=USR_PHONE2&FIELD=USR_MOBILE &FIELD=USR_FAX&FIELD=USR_CITY&FIELD=USR_STATE &FIELD=USR_BUILDING
Popup Link Usage
When you click on the popup link beside the primary identifier, ExtraView will open a new window, where you can search for users by typing in search criteria. This is shown in the following screen shot.
Searching for users in the LDAP directory
After using the search criteria, click on one of the results in the ID field. The fields on the parent add or edit screen will be populated with all the fields you requested.