Administrative Tasks and Configuration Notes

Owned by Marty Lechleider
Last updated: Jan 06, 2020 by Christopher Dawes
6 min read

This page is devoted to common administrative tasks and configuration details/clarifications that involve HCL Leap.  If you are a server administrator then you will want to review and become familiar with many of the tasks and notes on this page.  Some of these are common tasks to IBM WebSphere/Portal/DB2, but I felt it important to list them here for those that have never worked with the IBM products before.


DB2 Notes

Minimum DB Permissions required by DB2 User

If a client does not want to give the DB2 user DBADM then they need to assign the following permissions otherwise Leap usage will fail.

CONNECT
SELECT
INSERT
UPDATE
DELETE
CREATETAB
IMPLICIT_SCHEMA
USE of tablespace

How do I find the tables that contain my form data?

There may be a situation where you want to configure a reporting tool (like IBM Cognos) directly to the database table for a specific Leap form. 

In version 8.5 the form data is stored in its own schema.  The schema is a derivative of the application ID.  Take this sample application ID "78d52018-3ce3-4d22-8cc8-250d9eb092c4", the schema name would be "S__78d52018_3ce3_4d22_8cc8_250d9eb092c4".  The schema will contain a table whose name matches the ID of the form.  If your form has any table objects, then those will be in their own table within the same schema following the format of <formID>_<tableID>.


In version 8.6, 8.6.1 the form data is stored in tables in the APP_DATA schema, to get the tablename for a specific form id you can use the following query:

SELECT u.TABLENAME FROM FREEDOM.UIDS as u, FREEDOM.FORMS as f WHERE u.APP_ID = f.APP_ID AND COLUMNNAME IS NULL AND UUID = (SELECT FORM_ID FROM FREEDOM.FORMS WHERE APP_ID = '<app_id>' AND ALIAS = '<form_id>')

Replace the <app_id> with the application ID from the application details on the manage page, replace the <form_id> with the ID of the form (which you can find in the form properties when editing the application).  You can also get this information from the URL used to launch the form.  Take this URL as an example:

http://localhost:9082/forms/landing/org/app/78d52018-3ce3-4d22-8cc8-250d9eb092c4/launch/index.html?form=F_Form1

The resulting SQL query to get the DB2 table for this form would be:

SELECT u.TABLENAME FROM FREEDOM.UIDS as u, FREEDOM.FORMS as f WHERE u.APP_ID = f.APP_ID AND COLUMNNAME IS NULL AND UUID = (SELECT FORM_ID FROM FREEDOM.FORMS WHERE APP_ID = '78d52018-3ce3-4d22-8cc8-250d9eb092c4' AND ALIAS = 'F_Form1')

The result looks like:

 TABLENAME
 --------------------------
 4F2PIQ9VJJ83COP5SP05VD8F1P

Now in your reporting tool you can point it to this table in the APP_DATA schema.

If the form that you are working with contains a table, then that table data will be stored in a separate database table.  To get the APP_DATA table names that are associated with the form tables you would execute the following query:

SELECT u.TABLENAME FROM FREEDOM.UIDS as u WHERE u.APP_ID = '78d52018-3ce3-4d22-8cc8-250d9eb092c4' AND COLUMNNAME IS NULL

This will give you all the tablenames associated with the form like:

 TABLENAME
 --------------------------
 4F2PIQ9VJJ83COP5SP05VD8F1P
 60V5VIOM008R4BB5LJF415T6PJ
 58MUNPL1F8V08O45OT27HFKCG

Here you can see that it includes the tablename that we retrieved from the previous query.  The other two are for the table objects in the form.

Note:

  • The database structure is subject to change with any future release. 
  • The queries provided are intended to be used once to identify the name of the data table for a specific form, if you execute these regularly or part of a batch process then it may affect performance.
  • The information provided here is not formally documented and therefore not "supported" (you cannot open a PMR for questions related to this topic -> post in the forum!)

My LDAP account changed and now I can't see any of my applications

Leap does not have any built-in tools to manage LDAP changes.  If your user name changes and you log into Leap, Leap is going to treat you as a new user.  To fix this you will have to edit the FEB database directly.

1. Delete the new USER from the Leap DB that was created from your latest login (only do this if you logged into Leap with your new login id and that user does not have any applications):

DELETE FROM FREEDOM.USERS WHERE LOGIN_ID = 'myNewLogin'

2. Re-define the login id for your existing user account:

UPDATE FREEDOM.USERS SET LOGIN_ID = 'myNewLogin' WHERE LOGIN_ID = 'cdawes@ca.ibm.com'


The next time that you login with your new login id you should see all the applications that existed under your old login id.

WebSphere Notes

Enable Trace logging for Leap

1. Log in to the WAS admin console.

2. Select Troubleshooting...Logs and Trace.

3. Click the server where Leap is deployed.

4. Click Diagnostic Trace.

5. Click the Runtime tab.

6. Click Change log detail levels.

7. Add the Leap trace by expanding Components and Groups and selecting com.ibm.form or you can type in the new string into the field

Note: If you change the log level on the Runtime tab then the changes will take effect immediately and will be lost if the server is restarted.  If you want the settings to remain after a server restart then you will have to make the changes on the Configurationtab.

SMTP Settings for WAS CE or Liberty

There are a few properties that are supported but accidentally absent from the documentation.  We are correcting this mistake, but in the meantime I am listing them here:

ibm.SendMailService.mailConfig.mail_smtp_host=<SMTP host name>
ibm.SendMailService.mailConfig.mail_smtp_port=<SMTP host port>
ibm.SendMailService.mailConfig.mail_smtp_user=<SMTP login name>
ibm.SendMailService.mailConfig.mail_smtp_auth=true
ibm.SendMailService.mailConfig.mail_smtp_auth_password=<SMTP login password>

These properties should be used if you need to provide a username and password for an SMTP server when using Leap with WebSphere Community Edition or Liberty


Webserver timeouts impact on Leap operations

Certain operations in Leap can take a long time to complete, for example: Import with Data, Export with Data or even deploy (for larger applications).  I want to point out a key configuration that might cause a problem if you are using a webserver (like IHS) in front of your Leap server.  Every webserver will have its own default time-out values that will impact communication to and from the server.

The IHS parameter can be found in the plugincfg.xml and  looks like this:

<ServerCluster Name="server1_Cluster" CloneSeparatorChange="false" LoadBalance="Round Robin"
            PostBufferSize="64" IgnoreAffinityRequests="true"
            PostSizeLimit="-1" RemoveSpecialHeaders="true" RetryInterval="60">

<Server Name="server1" ConnectTimeout="5" ExtendedHandshake="false" ServerIOTimeout="60" ...>

Because the ServerIOTimeout set to 60 seconds any Leap operation that takes longer will actually have its connection closed by the webserver.  When this happens you might see an immediate error that the operation has failed or nothing may happen until the browser times out the HTTP request.

If you are seeing any strange behavior when you perform these longer operations then have a look for this timeout value as it may be the cause!


How to Create a J2C Authentication Alias

As of version 8.5, Leap leverages a J2C Authentication Alias to define the username and password of the administrative user.  If you are new to WebSphere then you may not know exactly how to do this, check out our technote to learn how to create an alias.

How to Use Custom LDAP Properties With Leap

1. Identify the attribute in my LDAP that I want to use.  I am using OpenLDAP and the attribute I chose one called "drink".

2. Make WAS/VMM aware of the custom property.  I do this by running a WAS admin task:

  i) Navigate to the WAS profile /bin directory

  ii) Execute wsadmin(.sh or .bat depending on OS) to enter the admin mode

  ii) Run the following command to add the property:

    $AdminTask addIdMgrPropertyToEntityTypes { -name drink -dataType String -isMultiValued false -entityTypeNames PersonAccount -repositoryIds OpenLDAP}

If the property that you want to add is going to be used as a login property then you need to run an additional command:

    $AdminTask addIdMgrLDAPAttr {-id "OpenLDAP" -name custom_LDAP_property  -propertyName uid -entityTypes PersonAccount}

We can see the addition was successful by the command line response:

    CWWIM0523I  The new property 'drink' was successfully added to the entity type '[PersonAccount]'.

4. Make Leap aware of the attribute.  In the Builder_config we have:

    ibm.was.MemberManager.userProps.displayName = drink

5. Restarted WAS (if you have a DMgr then you need to synchronize the nodes and restart the DMgr and nodeagent)

Now when I login to Leap I see the value of the "drink" attribute in the top right hand corner of the screen as the display name!


Are you getting Certificate errors in your logs?

If you you are seeing an error like the following in your logs:


[6/5/16 20:25:46:042 IST] 0000008a StandardExcep E com.ibm.form.nitro.platform.StandardExceptionMapper toResponse 1c91bade-99de-4bf2-968c-c6c01f3d26e4
                                 com.ibm.form.nitro.service.exception.AppAdminUserException: com.ibm.jsse2.util.j: PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is:
    java.security.cert.CertPathValidatorException: The certificate issued by CN=IBM INTERNAL INTERMEDIATE CA, O=International Business Machines Corporation, C=US is not trusted; internal cause is:
    java.security.cert.CertPathValidatorException: Certificate chaining error


This means that the server is missing a digital certificate that is required to communicate with another server (this is typically seen when creating service descriptions to communicate to a service end-point).


To resolve this you must import the certificate into the java truststore using keytool.

./keytool.sh -import -file "<path-to-crt-file>" -keystore "/opt/IBM/WebSphere/AppServer/java_1.7_64/jre/lib/security/cacerts" -storepass "changeit"


Then restart the server and re-test your service.


Leap Configuration Notes

Can't Delete Record Using Leap REST API in Leap 8.6

In version 8.6 a new property was added that restricts the ability to delete a record using the REST API.  To restore this ability add the following to your Builder_config.properties:

ibm.nitro.NitroConfig.ProtectSensitiveActions = false

Note: The default value for this property is true.


Leap Installation/Migration Notes


Setting up the Leap Portlet

There is a great article that you can reference for troubleshooting issues with setting up the Leap portlet.


Installing Leap into a Cluster

If you are installing Leap for the first time and you want to operate within a cluster (where you have more than one instance of Leap), check out our cluster installation guide.


Best Practices for Upgrading Leap

Performing a Leap upgrade is not a trivial task and it is important to take the necessary steps to insure that you don't lose any data in the event of an unexpected error.

Attached is a guide on some best practices to consider.