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:
Normally, you will set up the LDAP Background Task within the Task Manager administration utility before beginning configuration of your LDAP server.
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 |
| 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 |
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 |
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 |
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 | = |
Ensure each of these is placed on ONE line:
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
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
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
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.
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.
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.
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.
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.
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.
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
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
?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
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
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.
