In this section: |
The iWay LDAP High Water Mark (HWM) listener follows the HWM design pattern by acquiring new or changed records (LDAP entries) from a data store (the LDAP server) that meet a specific, evolving criteria. The data that is returned is determined by the scope and the specified filter. To avoid retrieving duplicate entries, the iWay LDAP HWM listener keeps track of the highest value of the filter attribute which has been read. Usually the filter value is the creation or modification time of the entry, but any unique and steadily increasing value can be used. Each entry satisfying the filter is returned as an iWay XML document for further processing in an iWay Service Manager channel.
The iWay LDAP HWM listener is triggered (begins processing messages) when an entry is inserted or modified in the LDAP directory that is based on an increasing value of an attribute. The iWay LDAP HWM listener works similar to the iWay Relational Database High Water Mark listener.
The iWay LDAP HWM Listener acquires LDAP entries, formats them into XML format, and inserts them into an iWay channel for further processing. The configuration process for the LDAP HWM listener defines the properties that the listener requires to accomplish these tasks. For example, the address of the LDAP server, account authentication credentials, filter criteria, and which attributes to return.
For best results in building an application using the LDAP HWM listener, having knowledge about the schema that is employed by your LDAP implementation is recommended.
Note: This section describes how to configure an iWay LDAP HWM listener. To construct a fully populated iWay Service Manager channel, incorporate the listener into an inlet and then use the inlet in a channel. For more information on how to design and build a channel, see the iWay Service Manager User's Guide.
To configure the iWay LDAP HWM listener:
The Listeners pane opens, as shown in the following image.
The table that is provided lists any existing listeners and a short description for each.
The Select listener type pane opens.
The Configuration parameters for new listener of type LDAP High Watermark/File pane opens.
Note: An asterisk indicates a required property.
Property |
Definition |
---|---|
Provider URL * |
URL that identifies the service, and the optional root context. For example: ldap://localhost:389/dc=etcee,dc=com |
User Name |
LDAP defined user name. |
Password |
LDAP defined password. |
Context * |
Context under which the search is to take place. For example: ou=bookkeeping |
Filter * |
The criteria for selecting entries from the LDAP server. The question mark character (?) is substituted by the current HWM value. The filter must be set to a non-operational attribute. Attributes that have special meaning to the Directory server (for example, createTimestamp, modifiersName, modifyTimestamp) are known as operational attributes. |
Attributes Wanted * |
A list of attributes to be returned. The attributes are presumed to be strings. Any attribute can be single or multi-valued. If an asterisk character (*) is entered, then all attributes are read. |
Maximum Rows |
Maximum number of rows that will be read into the current XML document. Any unread rows meeting the HWM criteria will be read in the next iteration of the listener. |
HWM Field * |
Name of the attribute which is the source of the next HWM value. This must be a single-valued attribute. For example, if the last modified timestamp was the high water mark, then the following filter would not work: modifyTimeStamp>=? As a result, the value in the HWM field must be a non-operational attribute. |
HWM Type |
The type of HWM field. This property is used to test HWM attributes. Select one of the following values from the drop-down list:
Note: Dates are recorded in most LDAP directories as strings using the following format: yyyymmddhhmmss As a result, a string compare is sufficient. Date attributes should be described as date types to ensure compatibility. |
HWM Path * |
Name of the file in which the HWM value is stored. |
HWM Default * |
Value to be used as the HWM on the first run of the listener, or if the HWM value file cannot be found. |
Base 64 |
Each value is examined and if the value cannot be represented in the normal character set, it is replaced with its base64 representation. This is not necessary for binary data if processing the result will not be processed as an iWay XML document. |
Parse Attributes |
Determines whether values can be parsed, which means that the attributes are in the form of token/value pairs separated by commas. If so, the value node contains an element for each token. For example: <attribute values="1" name="distinguishedName"> <value> <CN>Herz, Judy</CN> <OU>USERS</OU> </value> </attribute> If the contents of the value do not meet the criteria for parsing, the value is not parsed. For a more detailed sample, see Sample LDAP HWM iWay Documents. |
Whitespace Normalization |
Specifies how the parser treats whitespaces in element content. Choose preserve (default) to disable all normalization as prescribed by the XML specification. Choose condense to remove extra whitespaces in pretty printed documents and for compatibility with earlier versions. |
Accepts non-XML (flat) only |
If set to true, the listener expects only flat (non-XML) files and the preparsers do not run. |
Optimize Favoring |
Select one of the following values from the drop-down list:
Note: Selecting memory is recommended if you are expecting large input documents. |
Multithreading |
Number of documents that can be processed in parallel. |
Maximum threads |
Number of parallel threads that can grow automatically on demand. |
Execution Time Limit |
Time limit (in seconds) for a document to execute before it is terminated. |
Polling Interval |
Interval at which to check for new input. |
Default Java File Encoding |
Default encoding if the incoming message is not self-declaring, for example, XML. |
Always reply to listener default |
If set to true, the default reply definition is used in addition to the defined replies. |
Error Documents treated normally |
If set to true, error documents are processed by any configured preemitters. |
Listener is Transaction Manager |
If set to true, agents run within a local transaction managed by the listener. |
Record in Activity Log(s) |
If set, activity on this channel will be recorded in the activity logs, otherwise the activity will not be recorded. |
AES Key |
If the channel will receive encrypted AFTI messages, set the AES key (maximum 16 characters) to be used for decrypting. |
The Select listener type pane opens.
The newly created LDAP HWM listener is added to the list in the Listeners pane.
The XML document that is produced by one iteration of the LDAP HWM listener is formed as follows:
<listenerName> <row> <attribute values="count of values" name="attribute name> <value>data<value>*
With no parsing of the attributes, the resulting document appears as:
<?xml version="1.0" encoding="UTF-8" ?> <ibidca> <row> <attribute values="1" name="l"> <value>New York</value> </attribute> <attribute values="1" name="uSNCreated"> <value>159019</value> </attribute> <attribute values="1" name="distinguishedName"> <value>CN=Herz\,Judy,OU=USERS,OU=EI,OU=IWAY, OU=COR,DC=ibi,DC=com</value> </attribute> <attribute values="1" name="postalCode"> <value>10121</value> </attribute> <attribute values="1" name="co"> <value>United States</value> </attribute> <attribute values="1" name="cn"> <value>Herz, Judy</value> </attribute> <attribute values="1" name="st"> <value>NY</value> </attribute> <attribute values="1" name="streetAddress"> <value>2 Penn Plaza</value> </attribute> </row> </ibidca>
If the base64 attribute is selected, each attribute value is checked as to whether it can be represented in the ISO-8859-1 character set. Those that cannot, are converted to base64:
<attribute values="1" name="objectGUID"> <value>base64(77+9Sinvv71nUk9P77+96LhG77+978+9JO+/vm==value> </attribute>
The parsing parameter causes the listener to attempt to break down the value of each attribute into token/value pairs:
<?xml version="1.0" encoding="UTF-8" ?> <ibidca> <row> <attribute values="1" name="l"> <value>New York</value> </attribute> <attribute values="1" name="uSNCreated"> <value>159019</value> </attribute> <attribute values="1" name="distinguishedName"> <value> <CN>Herz, Judy</CN> <OU>USERS</OU> <OU>EI</OU> <OU>IWAY</OU> <OU>COR</OU> <DC>ibi</DC> <DC>com</DC> </value> </attribute> <attribute values="1" name="st"> <value>NY</value> </attribute> <attribute values="1" name="streetAddress"> <value>2 Penn Plaza</value> </attribute> </row> </ibidca>
Later, an option will allow selection of DSML or another standard.
The following command invokes the command line diagnostic tool from the iWay Service Manager command console:
tool testldap <providerurl> <userid> <password>
Three prompts are subsequently presented for the context, filter, and attribute list. Queries made to the LDAP server from within the diagnostic tool are standalone, for example, the LDAP HWM listener filter character and HWM value storage are not active. The diagnostic tool displays the query result as an iWay XML document, exactly as it would be constructed by the LDAP HWM listener during run time.
To exit the diagnostic tool, enter a simple null line or the word end at the context request prompt.
iWay Software |