Table of Contents

Introduction

The corporate enterprise directory, or LDAP, is the most common target of integration with HCL Leap

...

Version 11 created September 29, 2017 by Christopher Dawes

This topic is divided into two categories: steps required to configure Leap to enable users to login and create apps and then enabling services that enable form designers to leverage corporate LDAP information.

Deploying and Configuring HCL Provided Assets

System Configuration

Leap is a web application that runs on WebSphere.  All of Leap's access is controlled by WebSphere through a federated repository that is setup in the Global Security section of the WebSphere Administrative Console.  You can read more about how to configure Leap and federated repositories in  the IBM WebSphere Knowledge Center

Provide LDAP Services for Form Design

Many of the workflow features of Forms Experience Builder can be used with your corporate LDAP, for example:

• pre-populating information about the current user
• retrieving the current user's manager
• retrieving the managers list of employees

All of these functions and more can be implemented within your Leap environment by creating an LDAP Transport.  The Leap Knowledge Center provides a starting point for the LDAP Transport.  In order to enable LDAP type queries in your Leap apps you have to do 2 things:

1. Deploy the CustomLDAPTransport jar file into your extensions directory.
2. Deploy the Service Configuration XML files that represent the different LDAP services that you want to offer to your Leap designers.

The custom transport supports all 3 of the credential providers that Leap offers, you can read more about the providers and their features in the Knowledge Center. Note: The Credential providers are not supported on WAS liberty.

The jar file that has been provided can be used as-is, but the expectation is that you will have someone that can setup a Java Development IDE so that they can build and modify the transport code if you need additional functionality that has not already been provided. 

CustomLDAPServiceTransport.jar

Transport Parameters

...

The LDAP filter to use for the search.  For example:

...

...

.  HCL has provided a transport and a few sample service descriptions that can be used to perform this integration.

When the transport and associated service description XML files are deployed, then application designers can setup their applications to auto-populate user information.  This document describes how to configure and deploy all the artifacts necessary to enable applications to communicate with LDAP.

System Configuration

Leap is a web application that runs on WebSphere.  All of Leap's access is controlled by WebSphere through a federated repository that is setup in the Global Security section of the WebSphere Administrative Console.  You can read more about how to configure Leap and federated repositories in  the IBM WebSphere Knowledge Center

Provide LDAP Services for Form Design

Many of the workflow features can be used with your corporate LDAP, for example:

• pre-populating information about the current user
• retrieving the current user's manager
• retrieving the managers list of employees

All of these functions and more can be implemented within your Leap environment by creating an LDAP Transport.  The Leap Knowledge Center provides a starting point for the LDAP Transport.  In order to enable LDAP type queries in your Leap apps you have to do 2 things:

1. Deploy the CustomLDAPTransport jar file into your extensions directory.
2. Deploy the Service Configuration XML files that represent the different LDAP services that you want to offer to your Leap designers.

The custom transport supports all 3 of the credential providers that Leap offers, you can read more about the providers and their features in the Knowledge Center. Note: The Credential providers are not supported on WAS liberty.

The jar file that has been provided can be used as-is, but the expectation is that you will have someone that can setup a Java Development IDE so that they can build and modify the transport code if you need additional functionality that has not already been provided. 

CustomLDAPServiceTransport.jar

Transport Parameters

<constant>
                    <id>filter</id>
                    <value>(&amp; (objectClass=person)(managerSerialNumber={0}*)(managerCountryCode={1}*))</value>
                </constant>

 <mapping target="transport:filter-arg-0" source="parameter:searchSerialNumber" />
    <mapping target="transport:filter-arg-1" source="parameter:searchCountryCode" />

<constant>
                    <!-- OPTIONAL: The filter variables must be specified in this format "result-attribute:<name-of-ldap-attribute>"
                                the "result-attribute" value tells the transport to pull the attribute from the parent result set.
                    -->
                    <id>sub-filter-arg-0</id>
                    <value>result-attribute:hrOrganizationCode</value>
                </constant>

<searchresults>
    <searchresult>
        <ldapattrribute1/>
        <ldapattrribute2/>
        <subsearchresults>
            <subsearchresult>
                <ldapattrribute1/>
                <ldapattrribute2/>
            </subsearchresult>
        </subsearchresults>
    </searchresult>    
</searchresults>

...

Deploying the

...

After deploying the jar file to your extensions directory, now you must create the service description XML files that will define the different LDAP queries you want to provide to your LEAP users.  I have provided three examples of common LDAP queries that you can modify for your LDAP.

1. Download these XML files.

LDAPLookup_GetEmployee.xml - Returns ONE employee, that matches the search criteria (name, email, uid).

LDAPLookup_SearchEmployeesByName.xml - Returns a list of employees that match the search criteria

LDAPLookup_ManagerEmployees.xml

LDAPLookup_GetManager.xml

2. For each of these services you will need to update a few of the parameters, a description of each follows:

- The <id>, this should be a unique value and not repeated in any other xml file deployed within the Service Catalog/1 directory.

- The <transportId>, this should be the ID that you assign the transport in the java class.

- The <name>, this should be a clear descriptive name as it will be what the form designers see in the Leap Service Configuration dialog.

- The <description>, this should be a message that explains to the form designer what the service does and how it should be used.

- The input parameters as they may differ, or you may want to provide more, than what has been defined.  Refer to your LDAP for details on the attribute names.

- The URL to connect to the LDAP.

- The basedn that is used when querying the LDAP.

- The ldap filter that will return the desired result.

- The result-attributes, this should be a comma separated list of all the attributes that you want to return from LDAP.  If you leave it blank then all the attributes will be returned.

- The outbound parameters as they may differ, or you may want to provide more, than what as been defined.  Refer to your LDAP for details on the attribute names.

3. Deploy the XML files into the ServiceCatalog/1 directory, the services should be registered and appear within the LEAP UI within 60 seconds.  If the services do not appear, try restarting the LEAP application from within the WebSphere console.  If the services are still not available refer to the Troubleshooting section below.

Note: There are many more services that you could offer your users, but it will depend on the values of your LDAP and what functionality you want to make available.  Hopefully these three examples demonstrate the basic concepts and you can apply them to any additional services you want to create.

I have created a more in-depth usage guide, which you may refer to if necessary. HCL Leap and Enterprise Directory.pdf

Testing your LDAP Service

If the ServiceCatalog/1 directory already existed (before the server was last restarted) then Leap will automatically detect (it takes about 60 seconds) the new XML file and add it to your Services Catalog.

The next time you try to add a service configuration you should see your new LDAP service:

Image Removed

...

Transport

The transport is a .jar file that must be deployed into the file structure for HCL LEAP.  All extensions are placed into the extensions directory.  The default location is /opt/HCL/Leap/extensions or C:\HCL\Leap\extensions.  You can discover more by referring to our documentation.

Once the jar file has been placed in the extensions directory you will see a message written to the log file indicating that it has been loaded and is ready for consumption:

[6/11/18 10:07:14:550 PST] 0000007a DirectoryWatc I com.ibm.form.platform.service.framework.DirectoryWatcher processArtifact FSPDI5: The Bundle, <ExtensionName>.jar loaded successfully

Configuring the Service Description

Creating a service description is a one-time action that once completed, provides the function to all HCL Leap application designers.  Three service descriptions have been provided as examples of the kind of functionality that can be provided with an integration with LDAP.  This document will use the most common service as the example.

1. Download these XML files.

LDAPLookup_GetEmployee.xml - Returns ONE employee, that matches the search criteria (name, email, uid).

LDAPLookup_SearchEmployeesByName.xml - Returns a list of employees that match the search criteria

LDAPLookup_ManagerEmployees.xml

LDAPLookup_GetManager.xml

Setting up the Global Parameters

1. Open the LDAPLookup_GetEmployee.xml in a text editor. Do not use Notepad or Wordpad, instead use a proper editor like NotePad++, UtraEdit, etc.
2. The <id>, found on line 3, must be a unique value (not used by any other xml files deployed with Leap) as this is how the service is registered with Leap.
3. The <transportId>, on line 6, must be set to CustomLDAPServiceTransport
4. The <name>, on line 13, is the name of the service that will appear in the service configuration dialog within Leap, therefore insure it is something that your users can recognize.
5. The <description>, on line 14, will appear in the service configuration dialog and should provide a clear description of what the service provides

Setting up the Inbound Parameters

1. The <inbound> element is where all the parameters are defined that will be passed to the transport. In this example, there are three: searchName, searchEmail and searchUID.  Each parameter follows the same format

<parameter>
       <id>searchName</id>
       <name xml:lang="en">Search Name</name>
       <description xml:lang="en">The employee name to search for.</description>
       <mandatory>false</mandatory>
       <type>STRING</type>
</parameter>

• The <id> must be unique, and will be referenced in the inbound <servicemapping> section
• The <name> and <description> will appear in the dialog within Leap
• If <mandatory> is true, then the service cannot be saved without specifying this value.
• <type> defines the data being provided.  The other types are documented, but in this case, all will be STRING.

Setting up the Constants

1. Define the URL to the LDAP server on line 45.
2. Define the baseDN that will be used for the LDAP queries on line 50.

3. Define the filter that will be used to define the LDAP queries on line 55.

   Code Block
   language xml
   <value>(&(objectClass=person)(cn={0}*)(emailAddress={1}*)(uid={2}*))</value>

   
   

   Tip
   The 0,1 and 2 shown in this filter reference the input parameters defined at the start of the service description.  In this case 0 is searchName, 1 is searchEmail and 2 is searchUID.  When this filter is executed the numbers will be dynamically replaced with the value passed in from the Leap application calling the service.

   
   

4. Define all the LDAP attributes, on line 61, that you want to be returned from the LDAP query. This is a comma-separated list.  Note: For every attribute listed here you must create a corresponding parameter definition in the <outbound> section of the XML file.
5. Define all the inbound mappings, lines 70-81. The inbound mappings connect the parameters and constants defined in the XML file to the transport parameters.  The only mappings that you may have to modify are the filter-arg-x as your search parameters may differ.

Setting up the Outbound Parameters

You must define an outbound parameter for every attribute listed in the result-attributes.  The outbound parameters all follow the same structure.

<parameter>
	<id>cn</id>
	<name xml:lang="en">Employee's Full Name</name>
	<description xml:lang="en"></description>
	<type>STRING</type>
</parameter>

• The <id> must be unique, and will be referenced in the outbound <servicemapping> section.
• The <name> and <description> appear in the service dialog
• The type defines what is being returned.

All the parameters defined within the <outbound> section will appear in the service dialog on the Outputs tab.

For every outbound parameter, there must be a corresponding <mapping>.  To properly configure the service mappings, you must understand what is being returned from the LDAP query.  In this case, the LDAP will return XML that looks like:

<searchresults>
    <searchresult>
        <ldapattrribute1/>
        <ldapattrribute2/>
        <subsearchresults>
            <subsearchresult>
                <ldapattrribute1/>
                <ldapattrribute2/>
            </subsearchresult>
        </subsearchresults>
    </searchresult>    
</searchresults>

Now that we know the structure we can create the mapping that places individual elements from the result and assigns them to the corresponding output parameters.  Take the following mapping as an example:

<mapping source="transport:resultXML" target="parameter:cn" sourceRef="string(searchresults/searchresult[1]/cn)" sourceType="xml" />

This mapping assigns the “cn” value from the xml result to the “cn” parameter.

Once all the mappings are defined you are ready to deploy the service and start using it.

Deploying the Service Description

The XML files must be deployed to the ServiceCatalog/1 directory.

Once the xml file has been placed in the ServiceCatalog/1 directory you will see a message written to the log file indicating that is has been loaded and is ready for consumption:

[6/11/18 10:07:45:904 PST] 0000008a ServiceFileCa I com.ibm.form.nitro.service.services.impl.ServiceFileCatalogDirectory add Registering service description in C:\HCL\Leap\ServiceCatalog\1\<ServiceFileName>.xml.

If you do not see this message within 60 seconds, then starting and stopping the Leap application (not WebSphere) will also cause the file to be picked up.  Note: If there is a syntax error in the XML file then you may also see a message in the log and the service will not appear in Leap.

Note: There are many more services that you could offer your users, but it will depend on the values of your LDAP and what functionality you want to make available.  Hopefully these three examples demonstrate the basic concepts and you can apply them to any additional services you want to create.

I have created a more in-depth usage guide, which you may refer to if necessary. HCL Leap and Enterprise Directory.pdf

Testing your LDAP Service

If the ServiceCatalog/1 directory already existed (before the server was last restarted) then Leap will automatically detect (it takes about 60 seconds) the new XML file and add it to your Services Catalog, otherwise you will need to restart the application (from the WebSphere console).

Now that the service is deployed you can begin using it within your applications.

1. Edit an application.
2. Click on the Settings tab.
3. Under Services, on the left-side, click one of the forms.
4. Click Add Service Configuration.
5. Select “Or, select a service”
6. Set the Service Catalog to General.

7. Locate and click on the service in the list below

Image Added

The Inputs (or search criteria) for the LDAP query will appear as you defined them in the XML file.  Decide how you want to perform the employee lookup.  Will it be based on the current user?  Or will the user of the form be entering some key information (like email address or uid) to then load details about that person?  In this example, I want to automatically load the name of the current user.  Click Current User and then connect it to the appropriate search parameter.  In my implementation of Leap user’s login with their email address, therefore I would connect the Current User with the Search Email.

Select an input from your form (on the left side), then select the corresponding input parameters (on the right side) and click the link button in the middle to create a binding.

...

Launch your form and test out the service.

Troubleshooting your Service Description

If the service that you created does not work then you may need to troubleshoot to determine the cause. Some common errors are:

...

[12/5/13 23:13:44:503 PST] 00000019 ServiceFileCa 1 com.ibm.form.nitro.service.services.impl.ServiceFileCatalog refresh Refreshing service descriptions in C:\IBM\Forms\ServiceCatalog\1. [12/5/13 23:13:44:519 PST] 00000019 ServiceFileCa 1 com.ibm.form.nitro.service.services.impl.ServiceFileCatalog refresh Finished refreshing service descriptions in C:\IBM\Forms\ServiceCatalog\1.

Creating Your Own Version of the LDAP Transport (Optional)

If the provided version does not provide the desired functionality, then you may create your own. To build your own version of this transport so that you can make modifications you will need to:

...