iWay LDAP High Water Mark Listener

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.


Top of page

x
Configuring the iWay LDAP 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.



x
Procedure: How to Configure the iWay LDAP HWM Listener

To configure the iWay LDAP HWM listener:

  1. In the left console pane of the Registry menu, select Listeners.

    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.

  2. Click Add.

    The Select listener type pane opens.

  3. Select the LDAP High Watermark/File listener from the drop-down list, then click Next.

    The Configuration parameters for new listener of type LDAP High Watermark/File pane opens.

  4. Provide the appropriate property values for the LDAP HWM listener, as defined in the following table.

    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:

    • Date
    • Number
    • String

    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:

    • performance
    • memory

    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.

  5. Click Next.

    The Select listener type pane opens.

  6. Provide a name and, optionally, a description, for the LDAP HWM listener, and click Finish.

    The newly created LDAP HWM listener is added to the list in the Listeners pane.



x
Sample LDAP HWM iWay Documents

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.


Top of page

x
Using the Diagnostic Tool

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