HCL Leap and LDAP: Version 11

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

<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>

Configuring the LDAP Services

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:

The Inputs (or search criteria) for the LDAP query will appear as you defined them in the xml file:

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.

The Outputs (or values that will be returned) by the LDAP query will also appear as you defined them:

Select an output from the service result (on the left side), then select the corresponding field on your form (on the right side) where you want the value to be placed and click the link button in the middle to create a binding.

Click OK to complete the service configuration setup.

Now you need to setup when this service will be called. For example, you might want to call it in the onItemChange of an email field to validate the email address that a user provides against the company LDAP. Select the properties for the email field and click on the Events tab, check the Call a Service check box and then select the service that you created from the list.

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:

- You may have a syntactical error in your XML file causing your service to not appear in the list of available services
- You may have an error in the mapping definition of inputs or outputs causing nothing to happen when the service executes (but it is visible in the list of services).

1. Enable the Leap tracing. Within WebSphere Application Server add the trace string "com.ibm.support.examples.*=finest", then inspect the SystemOut.log and trace.log that gets created to see what it may be saying about the situation. The log file will tell you if the xml file was loaded successfully and usually will give a brief explanation if it was not.

The trace also contains detailed information about the input and out parameters that it processed during the service execution:

[12/13/13 17:45:47:806 PST] 00000023 ServicesServi 3 com.ibm.form.nitro.service.services.impl.ServicesService invoke Inbound service data is: {'metadata':null,'payload':{'emailAddress':'cdawes@ca.ibm.com'}}
[12/13/13 17:45:47:829 PST] 00000023 ServicesServi 3 com.ibm.form.nitro.service.services.impl.ServicesService invoke Outbound service data is: {'cn':'Christopher Dawes'}

It will also indicate when it has refreshed the contents of the files (in case you are making changes and wondering when they have been applied):

[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:

1. Create a New OSGI Plugin Project, for example let's use the project name "MyLDAPServiceTransport".

2. Create a OSGI-INF folder and create an XML file called "MyLDAPServiceTransport.xml".  The content of the file should be:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"
    configuration-policy="optional" immediate="true"
    name="com.ibm.form.examples.MyLDAPServiceTransport.service">
    <implementation class="com.ibm.form.examples.MyLDAPServiceTransport" />
    <service>
        <provide interface="com.ibm.form.nitro.service.services.IServiceTransport" />
    </service>
</scr:component>

3. Modify the META-INF/Manifest.mf file:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: MyLDAPServiceTransport
Bundle-SymbolicName: MyLDAPServiceTransport
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Service-Component: OSGI-INF/*.xml
Import-Package: com.ibm.form.nitro.service.model,
 com.ibm.form.nitro.service.services,
 com.ibm.form.platform.service.framework.i18n

4. Copy the java source into the project and place it in the desired package.

MyLDAPServiceTransport.java|View Details

5. Save the project

6. Export the code as a jar file and deploy it into the Leap extensions directory.  Check the SystemOut.log to insure that it deployed without error.