This article describes how you can extend HCL Leap. You can use a Service Description to provide an access point for your Form/Application Designers to call REST-based Web Services. Leap ships with a tool that can automatically generate a Service description file based on a WSDL but a description file for a REST service must be created manually and this article will walk you through this process leveraging one of the built-in REST Services.

Modifying the Sample for your Environment

For this example we are going to use one of Leap’s REST Service calls, the service will return all the apps of the currently logged in user. The URL that we are going to use for this example is:

http://localhost:9080/forms-basic/secure/org/app?page=1&pageSize=100&count=true

The service will return an XML ATOM feed in the format of:

The only thing that you need to modify for this example will be the URL of your server:

Change the "localhost:9080" to the server/port that your server uses.

Understanding the Parts

I want you to understand all the parts of the sample and how it works.

1. The service description file uses the HTTPServiceTransport that ships with Leap

2. The service automatically passes my session credentials to the REST Service call by specifying the LTPA cookie objects:

3. The parameters of the URL are broken down into their respective parts so that they can be properly encoded and used as inputs (if we so desire - they could be moved from the <constants> element and added to the <inbound> parameters).

4. The response from the REST service is XML and is automatically parsed and inserted into my defined outbound parameters:

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

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

1. Create a table on your form and add two fields to it ("ID", and "App Name")

2. Under Settings...Services...Form 1, Add a service configuration. Select "Get My Leap Apps" from the list (if it does not appear skip ahead to the troubleshooting section):

3. Click the Inputs tab. This is the search criteria for the service which we are going to leave empty:

4. Click the Outputs tab. Create "Assigned Outputs" for each of the service fields (click the property on the left, then the matching one on the left and click the connection button in the middle):

5. Click OK.

6. Click the Forms tab.

7. Open the properties for your table. Click the

8. Events tab and then the onShow event.

9. Select the "Call a Service" check box and select the service we just created from the dropdown. Click OK. Click OK.

10. Now Preview the form and the table should load with all of your apps that are on this server!

Exercise of Understanding

Let's put what you have learned to the test and extend this basic service description.

1. Move the <constants> "pageSize" to an inbound parameter so that one could change the number of results that get returned

2. Add additional outbound parameters so that we can see more data about each app.

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

1. Enable extra 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:
[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.