The documentation for the Connections Profile API is very helpful in understanding how it works and what parts you would need to implement for use with HCL Leap.

Modifying the Sample for your Environment

Included here is the entire service description file that implements several of the inputs and outputs that are available with the Connections Profile REST API.  Before you can use this you will have to specify your own server URL.

Understanding the Parts

I will not be describing the parts that I explained in the previous article, rather will focus on what is different.  The significant difference is the complex service mapping statements.  These statements are XPath queries that parse the XML into the defined outbound parameters.

 I was able to determine these complex queries by reviewing the XML that was returned by the Connections service, you can review the XML in the Connections documentation.

 The most significant thing to mention is the attention to namespaces.  If you review the XML result from the service you will see:

The "xmlns" are all the definitions of the namespaces that are used in the XML that gets returned by the service.  Any of the ones that are used in the elements that we want to retrieve we need to include in our serviceMapping:

Then we need to define the sourceRef for the element in the XML that we want to retrieve.  This is as simple as analyzing the XML and then specifying each level till you get to the one you want.  In this example"atom" and "sp_0" are the namespaces that insure we reference the correct element.  The "[@class='role'] is a predicate, which will return the "div" element that has a class attribute that equals "role":

Note: Further detail on all of the parts of this service description file can be found online as part of the HCL Leap Documentation.

Deploying the Service Description file

The completed xml file gets deployed according to the procedure in our documentation.

Testing Your New Connections Profile Service

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

1.  Create two fields to your form ("email", and "name").

2. Under Settings...Services...Form 1, Add a service configuration.  Select "Connections Profile Lookup Service" from the list (if it does not appear skip ahead to the troubleshooting section).

3. On the Inputs tab, link the "Email" item with your email field.

4. On the Outputs tab, link the "Name" item with the name field.

5. Click OK to complete the Service Configuration. 

6. In the properties of the email field, click the Events tab.  Select the onItemChange event, click the check box to call a service and select the service that you created. 

7. Save and Preview the form.  Enter a valid email address in the email field and tab to the next field.  The name of the person that matches the specified email should appear in the name field.  If it does not then you will have to begin the troubleshooting process.

 Troubleshooting Your Service Configuration

• 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).

 Enable the FEB tracing.  Within WebSphere Application Server add the trace string "com.ibm.form.*=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:

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