Lightweight Directory Access Protocol (LDAP) Adapter

The Lightweight Directory Access Protocol adapter enables Sterling B2B Integrator to communicate with local or remote LCAP servers by using a Java Naming Directory Interface (JNDI).

The following table provides an overview of the LDAP adapter:

System name None
Graphical Process Modeler (GPM) category All Services
Description Enables Sterling B2B Integrator to communicate with local or remote LDAP servers by using a Java Naming Directory Interface (JNDI). You can operate on data entries that are contained on an LDAP server, but you cannot change the underlying structure of those entries. The LDAP adapter supports Create, Read, Update, and Delete (CRUD) operations.
Preconfigured? No
Requires third-party files? No
Platform availability All supported Sterling B2B Integrator platforms
Related services No
Application requirements No
Initiates business processes? No
Invocation Runs as part of a business process.
Restrictions The LDAP adapter supports LDAP versions 2 and 3 to the extent that the Sun LDAP/JNDI libraries do, except as noted in the following points:
  • The following standard LDAP operations are not supported:

    - Adding new entry types

    - Adding or removing attributes from an entry

    - Referrals

  • Multi-value fields are supported for read, create, and update operations, but all values are treated as a single replacement value in the update operation; that is, the LDAP adapter cannot support updates of just one value in a multi-value field.
  • The LDAP adapter supports only the simple authentication type.
  • To prevent usernames and passwords from being accessible to other system users, enter usernames and passwords as instance variables only, not the BPML itself.

Requirements

To use the LDAP adapter, you must meet the following requirements:

Knowledge Requirements

To set up and use the LDAP adapter, you should know how to:
  • Use the LDAP data model
  • Use the Map Editor and the Translation service
  • Apply XML concepts

Supported LDAP Versions

The LDAP adapter supports LDAP versions 2 and 3 to the extent that the Sun LDAP/JNDI libraries do, except as noted in the following points:
  • The following standard LDAP operations are not supported:
    • Adding new entry types
    • Adding or removing attributes from an entry
    • Referrals
  • Multi-value fields are supported for read, create, and update operations, but all values are treated as a single replacement value in the update operation; that is, the LDAP adapter cannot support updates of just one value in a multi-value field.
  • The LDAP adapter supports only the simple authentication type.

System Requirements

For the LDAP adapter to work correctly, verify that:
  • You have a valid logon ID and password and can access the remote LDAP server
  • You can make a physical connection to the LDAP server from Sterling B2B Integrator at run time

How the LDAP Adapter Works

Using LDAP directories is a popular method for storing and retrieving simple data in a hierarchical structure. LDAP works well with data on a wide area network (WAN).

Note: The LDAP adapter is not used in the authentication of external users of Sterling B2B Integrator. This process does use an LDAP server, but not the LDAP adapter.

Java Naming Directory Interface (JNDI)

LDAP servers organize data into a hierarchical structure. An LDAP directory enables you to search a structured data repository and is optimized for read operations, unlike databases. Each record in the informational hierarchy can contain one or more fields or attributes. Each attribute can contain one or more values.

LDAP servers are not databases, although they can use databases to implement data storage. This distinction is important because LDAP may not support many sophisticated database features, such as advanced relational queries with table joins and transactional integrity across multiple operations. At present, the adapter accesses data in an LDAP server through the JNDI/LDAP API. The JNDI/LDAP API enables selection of LDAP data elements by name.

In general terms, LDAP is an example of a schema-based Operational Support System (OSS) as opposed to a service-based OSS. To make LDAP more service-based, Sterling B2B Integrator overlays a standard service layer named CRUD (Create, Read, Update, and Delete) to manipulate data.

The service layer works as follows:
  • Create – Adds a new entry to a directory and provides data for any attribute that already exists in the entry.
  • Read – Provides an entry search filter; the retrieved data is in Directory Service Markup Language (DSML) format.
  • Update – Modifies an LDAP entry. You need to provide a base distinguished name (baseDN) to identify the entry, and the names and values of the attributes to update.
  • Delete – Deletes an entry from the LDAP server.

Accessing Data

To access data, the LDAP adapter needs these items:
  • Service to perform – Create, Read, Update, Delete
  • A unique name that specifies a record on the LDAP server
  • Field names within the record

Adapter Process

The following steps summarize how the LDAP adapter works:
  1. The LDAP adapter sends a request to the LDAP server.
  2. The adapter takes the results returned from the LDAP server and places them back into the business process context.
  3. The adapter passes the updated internal business process context back to the business process.
  4. The adapter is ready to process the next request.

The following figure shows how the LDAP adapter communicates with the LDAP server within a business process:

The following steps summarize how the LDAP adapter communicates with the LDAP server within a business process:
  1. The Translation service checks the translation object (.txo) in to Sterling B2B Integrator for later use by the Translation service.
  2. When initiating the business process, the user supplies the name and location of the customer input document that has the necessary information to be retrieved, such as the customer name and the name of fields.
  3. From the business process, the business process engine (BPE) receives the name of the Translation object (identified from the list of maps checked in to Sterling B2B Integrator).
  4. When the business process is started, the BPE starts the Translation service. The Translation service builds the XML file for the LDAP adapter with the necessary information from the customer document.
  5. The LDAP adapter uses the information in the file to make a connection with the LDAP server and retrieve the required information by making appropriate calls.
  6. The LDAP adapter constructs an XML document with the retrieved data.
  7. The XML document is passed to the business process.
  8. Sterling B2B Integrator performs the next step in the business process.

For example, consider the following scenario. You have customer information stored in an LDAP server (which has an internal database). To provide the sales department with the customer contact information from the LDAP database, use the LDAP adapter to access this information and then write the information to disk using the File System adapter.

Implementing the LDAP Adapter

To implement the LDAP adapter:
  1. Create an LDAP adapter service configuration. For information, see Managing Services and Adapters.
  2. Configure the LDAP adapter. For information, see Configuring the LDAP Adapter.
  3. Create XML documents, as necessary. For information, see Creating XML Documents for the LDAP Adapter.
  4. Use the LDAP adapter in a business process.

Configuring the LDAP Adapter

The following tables describe fields used to configure the LDAP adapter in Sterling B2B Integrator:

Note: The field names in parentheses represent the corresponding field names in the GPM. This information is provided for your reference.
Field Description
Name Unique and meaningful name for the adapter configuration. Required.
Description Meaningful description for the adapter configuration, for reference purposes. Required.
Host Name (hostName) Name or IP address of the host running the LDAP server. Can be overridden in a business process or process data.
Port (port) IP port number on the host. Default is 389. Can be overridden in a business process or process data.
Read Timeout in Secs (readTimeOut) Time out value in seconds. Default is No limit (0).
Max Number of Records to Read (maxReadRecords) Maximum number of records to return from the LDAP server. Zero (0) means no limit is applied.
Set Authentication? (LDAPAuthentication) Whether you will attempt to connect to the LDAP server with authentication, or anonymously.
Login Name (loginName) Login name for the host LDAP server. Can be overridden in a business process or process data.
Password (password) LDAP server password for the associated login name. Can be overridden in a business process or process data.

Creating XML Documents for the LDAP Adapter

For LDAP adapter business processes, the XML document passed into the adapter determines the operation to start on the LDAP server. The XML document must correspond to one of four Document Type Definitions (DTDs), which define the CRUD operations (Create, Read, Update, or Delete). In other words, the DTDs verify that the XML is correct for the operation it is written for.

The LDAP adapter provides the DTDs that define the XML that is passed to and received from the adapter. The Map Editor and the Translation service use these DTDs to verify data conversions to and from customer formats.

To check out the DTDs from Sterling B2B Integrator and load them to your local disk:
  1. From the Deployment menu, select Schemas.
  2. In the XML Schemas window, search for the LDAP DTDs.

    They are named LDAPCreate.dtd, LDAPRead.dtd, LDAPUpdate.dtd, LDAPDelete.dtd, and dsml.dtd.

  3. Click Source Manager.
  4. Save each DTD to your local disk.

XML Construction

When constructing XML for the LDAP adapter, remember the following points:
  • In the request element, the operation attribute specifies the operation to be performed (Create, Read, Update, or Delete), and:
    • The Base Distinguished Name (baseDN) attribute is different for each operation.
    • The Scope attribute specifies search scope and is used only in Read operations.
  • Parameter elements identify fields, and:
    • Name attributes identify the field name.
    • Usage attributes specify whether the data is input, output, or search.
    • Type attributes specify the type of data to be sent in the output parameters (for example, text/none, bin/base64).
      Note: Usage attributes other than those specified for a particular operation are discarded. For example, if a request XML for a Create operation has input and output usage attributes, the input attribute is discarded.

Examples

The following XML excerpts are examples of input documents for Create, Read, Update, and Delete operations.

Create Operations

The baseDN attribute identifies the record to be created. The usage attribute is always output for Create operations.

Two values exist for Type attributes in Create operations:

  • text/none – Intended for ordinary textual data with no encoding. Default.
  • bin/base64 – For binary data. Encode as base64 in the content of the param tag.

The following example shows a Create operation:

<LDAPAdapter>
		<request operation="Create" baseDN="uid=jblow, ou=People, o=isg.stercomm.com">
		<param.1 name="objectclass" type="text/none" usage="Output">top</param.1>
		<param.2 name="objectclass" type="text/none" usage="Output">person</param.2>
		<param.3 name="ou" type="text/none" usage="Output">People</param.3>
		<param.4 name="mail" type="text/none" usage="Output">jb@ab.com</param.4>	
		<param.5 name="uid" type="text/none" usage="Output">jblow</param.5>	
		<param.6 name="sn" type="text/none" usage="Output">Blow</param.6>	
		<param.7 name="givename" type="text/none" usage="Output">Joe</param.7>	
	</request> 
</LDAPAdapter>

Read Operations

The baseDN attribute identifies the highest point in the hierarchy to begin the search, and the Scope attribute defines the extent of the search. The Scope attribute values are:
  • subTree
  • base
  • oneLevel

The search filter is a query string and is denoted with a param element where the Usage attribute is search. Use the following symbols to define the search:

Symbol Represents
Parentheses ( ) Enclosed group of compares
Ampersand & Logical operator AND
Pipe | Logical operator OR
Exclamation point ! Logical operator NOT

The logical operator should appear before the parentheses enclosing the group of compares that the logical operator affects. For example:

(&(cn=X)(sn=Y))

This example means that cn is equal to X and sn is equal to Y.

One param element must have a usage attribute value of search and must contain the search specification as defined by the LDAP model. The rest of the param elements, if any, specify the field names to be retrieved from the LDAP server for the records that match the search filter.

The following example shows a retrieval for the cn field and the jpegphoto field:

<LDAP Adapter>
	<request scope="subtree" operation="Read" baseDN="uid=jblow, ou=People, o=isg.stercomm.com">
		<param.1 usage="Search">(&(objectclass=person)(sn=Blow))</param.1>
		<param.2 name="jpegphoto" usage="Input"/>
		<param.3 name="cn" usage="Input"/>
	</request> 
</LDAP Adapter>

Read Output Documents

Because Read is the only operation that has data returned, an output document is associated with this operation. The output document is written in DSML and is added to the business process context when the operation successfully completes. DSML is a standard representation of directory information in XML format. The LDAP adapter is compatible only with DSML Version 1.0.

DSML is intended to be a simple XML schema definition that enables directories to publish basic profile information. Find the full specifications for DSML at www.dsml.org.

The following example shows DSML for a Read output document:

<dsml>
	<directory-entries>
		<entry dn="uid=scarte2, ou=People, o=isg.stercomm.com">
			<attr name="telephonenumber">
				<value>+1 408 555 6022</value>
			</attr>
			<attr name="mail">
				<value>scarte2@isg.stercomm.com</value>
			</attr>
			<attr name="uid">
				<value>scarte2</value>
			</attr>
		</entry>
	</directory-entries> 
</dsml>

Update Operations

The baseDN attribute identifies the record to be updated. Two values exist for Type attributes in Update operations:
  • text/none – Intended for ordinary textual data with no encoding. Default.
  • bin/base64 – Intended for binary data. Encode as base64 in the content of the param element.

The parameter element usage attribute value is always output.

For multivalue fields, multiple param elements can have the same name, but the content is different for each. The following example shows a multivalue first name field:

<LDAPAdapter>
	<request operation="update" baseDN="uid=jblow, ou=People, o=isg.stercomm.com">
		<param.1 name="employeenumber" type="text/none" usage="Output">1234</param.1>
		<param.2 name="firstname" type="text/none" usage="Output">Joe</param.2>
		<param.3 name="firstname" type="text/none" usage="Output">Joseph</param.3>	
		<param.4 name="firstname" type="text/none" usage="Output">Joey</param.4>
	</request> 
</LDAPAdapter>

Delete Operations

The baseDN attribute identifies the record to be deleted. The following example shows a Delete operation:

<LDAPAdapter>
	<request operation="Delete" baseDN="uid=jblow, ou=People, o=isg.stercomm.com">
	</request> 
</LDAPAdapter>