Contents


Configure the IBM Process Federation Server to give your IBM BPM process users a single point of access

With the different development paths for Business Process Choreographer and Business Process Designer in IBM BPM, varied deployment environments, and coexistence of multiple product versions, the demand for one user interface for interacting with tasks related to both business process definitions (BPDs) and Business Process Execution Language (BPEL) is becoming more urgent.

With a single task list user interface, the users of your process applications can work on individual tasks, unaware of the different and complex back-end systems.

IBM Process Federation Server is based on the IBM WebSphere Application Server Liberty Profile server. It provides application programming interface (API) access to lists of resources that are federated across IBM BPM systems, such as the task list and launch list. It includes the distributed index for the federated environment that is based on an Elasticsearch service. The Elasticsearch service provides fast access to federated resources, and relieves federated IBM BPM systems from expensive queries.

As shown in Figure 1, the Process Federation Server acts as a single point of entry for all back-end IBM BPM systems.

Figure 1. Process Federation Server structure
Process Federation Server structure
Process Federation Server structure

All task queries are served by the Process Federation Server instead of the individual IBM BPM system. Also, the clients (the browser in this case) are automatically redirected to the corresponding IBM BPM system when your business process users want to claim or complete their tasks. In this approach, more and more back-end IBM BPM systems can be federated into a single domain, benefiting from the Elasticsearch service, and Process Federation Server can still provide a very good response time.

This tutorial demonstrates detailed steps to install and configure Process Federation Server to access two back-end IBM BPM systems so that you can get a full understanding of the overall topology and learn how to configure your environment. After setting up Process Federation Server, you can create your own client user interface (for example, Federated portal in Figure 1) to access a federated IBM BPM system through Representational State Transfer (REST) APIs. You can create your own client user interface for IBM BPM V8.5.6 if you want your end users to work with all their tasks more easily, whether the tasks came from BPDs or BPEL.

You walk through an introduction of how to set up a simple Process Federation Server environment with two back-end IBM BPM environments:

  • IBM BPM V8.5.6 with an Oracle Real Application Cluster database
  • IBM BPM V8.0.1.3 with an IBM DB2 database

Figure 2 shows detailed topology and environment information. To give a typical example, the examples in this tutorial use two versions of IBM BPM and two kinds of databases.

Figure 2. Sample system topology
Illustration of the sample system topology in this tutorial
Illustration of the sample system topology in this tutorial

The sample topology includes one IBM HTTP Server (PFSIHS) that connects to two Process Federation Servers (PFS1 and PFS2), which federate two back-end IBM BPM systems: an IBM BPM Advanced Process Server V8.5.6 three-cluster deployment environment (DE1) with an Oracle Real Application Cluster database, and IBM BPM Advanced Process Server V8.0.1.3 three-cluster deployment environment (DE2) with an IBM DB2 database. Both IBM BPM systems have IBM HTTP servers (BPM856IHS and BPM8013IHS) in front of them. The sample topology includes one Lightweight Directory Access Protocol (LDAP) server that all Process Federation Servers and IBM BPM servers connect with.

Table 1 shows the machines involved in the sample topology.

Table 1. Environments
ServerHost nameOperating systemSoftware version
IBM HTTP Server 1 PFSIHS.cn.ibm.com Windows Server 2008 R2 IBM HTTP Server V8.5 or V8.5.5
Process Federation Server 1 PFS1.cn.ibm.com Red Hat Enterprise Linux 6.1 Process Federation Server included with IBM BPM V8.5.6
Process Federation Server 2 PFS2.cn.ibm.com Red Hat Enterprise Linux 6.1 Process Federation Server included with IBM BPM V8.5.6
IBM HTTP Server 2 BPM856IHS.cn.ibm.com Windows Server 2008 R2 IBM HTTP Server V8.5 or V8.5.5
IBM BPM V8.5.6 – Node 1 BPM1.cn.ibm.com Red Hat Enterprise Linux 6.1 IBM BPM V8.5.6
IBM BPM V8.5.6 - Node 2 BPM2.cn.ibm.com Red Hat Enterprise Linux 6.1 IBM BPM V8.5.6
Oracle database DB856.cn.ibm.com Red Hat Enterprise Linux 6.1 Oracle 12c Real Application Cluster
IBM HTTP Server 3 BPM8013IHS.cn.ibm.com Windows Server 2008 R2 IBM HTTP Server V8.5 or V8.5.5
IBM BPM V8.0.1.3 – Node 1 BPM3.cn.ibm.com Red Hat Enterprise Linux 6.1 IBM BPM V8.0.1.3
IBM BPM V8.0.1.3 – Node 2 BPM4.cn.ibm.com Red Hat Enterprise Linux 6.1 IBM BPM V8.0.1.3
IBM DB2 DB8013.cn.ibm.com Red Hat Enterprise Linux 6.1 IBM DB2 10.

To work through this tutorial, make sure that you meet the following prerequisites:

  • The IBM BPM V8.5.6 server must be set up with IBM BPM Advanced Process Server V8.5.6 with three clusters and an Oracle Real Application Cluster database.
  • The IBM BPM V8.5.6 server must be configured correctly with the IBM HTTP server for IBM BPM V8.5.6.
  • The IBM BPM V8.0.1.3 server must be set up with IBM BPM Advanced Process Server V8.0.1.3 with 3 clusters and an IBM DB2 database
  • The IBM BPM V8.0.1.3 server must be configured correctly with the IBM HTTP Server for IBM BPM V8.0.1.3.
  • The IBM BPM V8.5.6 server and the IBM BPM V8.0.1.3 server must be configured correctly with LDAP.

Setting up the entire topology is not simple. Figure 3 marks major steps and the path in red.

Figure 3. Sample system topology with configuration steps
Illustration of the sample system topology with configuration                 steps
Illustration of the sample system topology with configuration steps

Figure 3 includes the following configuration steps (labeled with C):

  1. Create the PFS1 and PFS2 IBM Process Federation Servers: Installing and creating IBM Process Federation Servers
  2. Configure the Process Federation Servers:
    1. Step C1 - Authenticating users on Process Federation Server
    2. Step C2 - Configuring single sign-on
    3. Configuring the Elasticsearch service
  3. Federate the IBM BPM systems: Step C3 - Federating the IBM IBM systems
  4. Secure communications: Step C4 - Securing communication
  5. Configure the IBM HTTP Server: Step C5 - Configuring the IBM HTTP Server for the Process Federation Servers

This tutorial describes each of the separate steps in detail.

Installing and creating Process Federation Servers

  1. Install Process Federation Server by completing the following steps:
    1. In the Process Federation Server image folder, run the installPFS.sh file. For example, type:
       [root@rehl217 20150306-132310.0.linux]# ./installPFS.sh
    2. On the Install Packages page, select the WebSphere Application Server Liberty, the Process Federation Server, and the WebSphere SDK, as shown in Figure 4.
    Figure 4. Process Federation Server Installation
    Process Federation Server Installation
    Process Federation Server Installation
  2. Create a Process Federation Server based on the ibmPfs:ibmProcessFederationServer template by running the following command:
    # export JAVA_HOME=/opt/IBM/WebSphere/Liberty/java/java_1.7_64
    # cd /opt/IBM/WebSphere/Liberty/bin
    #./server create server1 -–template=ibmPfs:ibmProcessFederationServer
  3. After successful installation, start the server. Verify there are no errors in the server log file like /opt/IBM/WebSphere/Liberty/usr/servers/server1/logs/message.log. For example, run the following command:
    # ./server start server1
    #vi /opt/IBM/WebSphere/Liberty/usr/servers/server1/logs/message.log
  4. Repeat the steps on another machine to create another Process Federation Server.

Configuring the Process Federation Servers

After successful installation, configure the Process Federation Servers. In general, there are two major areas to configured:

  1. Configure security so that user can be authenticated and can access both Process Federation Server and back-end systems in a single sign on approach. This configuration includes two parts:
    • Authenticating users on Process Federation Server.
    • Configuring single sign-on.
  2. Configure the Elasticsearch service as the data container for all federated systems.

Authenticating users on Process Federation Server

Users must be authenticated before accessing Process Federation Server and IBM BPM resources. So you need to configure Process Federation Server to bind with a user repository for authentication.

A common user registry is required across the client application, Process Federation Server, and the federated IBM BPM systems, so that authenticated users can access the entire environment through single sign-on (SSO). Supported user registries include LDAP and a custom user registry. In development and test environments, you can also use a file-based basic registry.

The examples in this tutorial use the LDAP of IBM Tivoli Directory Server, used by the IBM BPM environments.

Complete the following steps:

  1. On process federation server machine, edit the server.xml file under the server folder:
    # cd /opt/IBM/WebSphere/Liberty/usr/servers/server1
    # vi server.xml
  2. Add following statement to the server.xml file:
    <ldapRegistry baseDN="OU=WORKMANAGEMENTSVT,O=IBM.COM"
     bindDN="cn=root" bindPassword="password" host="ldap.cn.ibm.com"
     id="MyStressLDAP" realm="defaultWIMFileBasedRealm" port="389"
     ldapType="IBM Tivoli Directory Server" >
    <idsFilters  userFilter="(&amp;(uid=%v)(|(objectclass=person)
    (objectclass=ePerson)))" groupFilter="(&amp;(cn=%v)(|
    (objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))" />
    </ldapRegistry>

After configuration, without restarting the Process Federation Server, you can access the Process Federation Server resource list task REST APIs to verify that users need to input user credentials before accessing those REST APIs. For example, use the REST client in your browser to issue either of the following REST requests, and see that user credentials are required:

https://PFSIHS.cn.ibm.com/rest/bpm/federated/v1/systems
https://PFSIHS.cn.ibm.com/rest/bpm/federated/v1/tasks/query/IBM.DEFAULTALLTASKSLIST_75

Configuring single sign-on

When the users of your process application want to claim or complete tasks, the client needs to talk directly to the corresponding IBM BPM system. To avoid having the users input their credentials again, it's necessary to configure single sign-on between the Process Federation Server and the federated IBM BPM systems.

When single sign-on is enabled, users log in to an IBM BPM server or Process Federation Server, then they can access the other servers for which they are authorized without getting prompted again. For client applications to work, a similar configuration of single sign-on is necessary between the client web application server, Process Federation Server, and the federated IBM BPM systems.

We can configure single sign-on based on LTPA keys or third-party authentication products. Here we use LTPA keys for single sign-on for example.

In single sign-on environments, Lightweight Third Party Authentication (LTPA) keys are exchanged between Process Federation Server and each IBM BPM server in the federated environment. When users log in to an IBM BPM server, they can access all the other servers for which they are authorized without getting prompted again for their credentials.

Before you configure single sign-on, ensure that the following conditions are met:

  • Domains: The Process Federation Server and the IBM BPM servers must be in the same domain.
  • User registries for Process Federation Server and IBM BPM servers:
    • The user registries must be shared between Process Federation Server and each IBM BPM server. Different IBM BPM environments can use different user registries but you must configure these user registries on Process Federation Server too.
    • You cannot mix LDAP servers with other authentication services, such as a basic user registry or a custom user registry.
    • The user registries must use the same realm. The realm name must be the same as the one that you set for Process Federation Server.
  • LTPA key file:
    • The keys are active.
    • All the IBM BPM servers share the same LTPA key file.
  • System time: To avoid problems with LTPA expiry intervals, ensure that the system time on Process Federation Server and each IBM BPM server in the production environment are the same.

Then, to configure single sign-on, complete the following steps:

  1. Configure single sign-on for Process Federation Server. On Process Federation Server machine, add following statement to the server.xml file:
    <webAppSecurity ssoDomainNames="cn.ibm.com" ssoRequiresSSL="true"
    singleSignonEnabled="true" ssoCookieName="LtpaToken2"> 
    </webAppSecurity>
  2. Enable single sign-on on all IBM BPM servers.

    On both IBM BPM V8.5.6 and IBM BPM V8.0.1.3, complete the following steps:

    1. Log in to the administrative console.
    2. Open the Global security page by clicking Security > Global security. Expand Web and SIP security and click Single sign-on (SSO), as shown in Figure 5.
      Figure 5. Single sign-on configuration on the administrative console
      Screen capture of single sign-on configuration on the administrative                 console
      Screen capture of single sign-on configuration on the administrative console
    3. In the Single sign-on (SSO) window, configure the following settings:
      • Select Enabled.
      • Select Requires SSL (optional, but enable it for this tutorial).
      • Set the domain name, which must be the same as the ssoDomainNames that are configured in Process Federation Server server.xml file, for example: cn.ibm.com, as shown in Figure 6.
        Figure 6. SSO configuration values
        Screen capture of the SSO General                                             Properties                             page
        Screen capture of the SSO General Properties page
  3. Disable the automatic LTPA key generation on the IBM BPM servers. Because the LTPA keys are shared between Process Federation Server and the IBM BPM servers, automatic generation of keys causes the shared keys to become out-of-sync over time. See Disabling automatic generation of Lightweight Third-Party Authentication keys in the WebSphere Application Server documentation.
  4. Share the LTPA key file among all the servers in the federated process environment.
    To minimize the impact on existing IBM BPM environments that need to share LTPA keys, get and share the LTPA key file from one of the IBM BPM servers:
    1. On IBM BPM V8.5.6, export the IBM BPM server LTPA key file. In the administrative console, select Security > Global security > Authentication mechanisms and expiration > LTPA. Enter the password that is used to encrypt the keys and the fully qualified key file name, and then click Export keys. Get the LTPA key file, for example: fpltpa.keys, as shown in Figure 7.
      Figure 7. LTPA key export
      Screen capture of LTPA key export
      Screen capture of LTPA key export
    2. On IBM BPM V8.0.1.3, import the LTPA key file got from step a.

      Manually copy the fpltpa.keys file to IBM BPM V8.0.1.3. In the administrative console, select Security > Global security > Authentication mechanisms and expiration > LTPA. Enter the encryption password (the password you set in Step a) and the fully qualified key file name fpltpa.keys, and then click Import keys.

    3. On Process Federation Server 1, import the LTPA key you got from Step a. Manually copy the fpltpa.keys file to Process Federation Server 1. For example, copy it to the pfs_install_root/usr/servers/server_name/resources/security directory. Then add the following entry to the server.xml file:
      <ltpa keysFileName="pfs_install_root/usr/servers/server_name/resources/security/fpltpa.keys" keysPassword="keys_Password"/>
  5. Repeat the steps on Process Federation Server 2.
  6. To access Process Federation Server and IBM BPM systems by domain name, you must register domain names into DNS. For simplicity in this tutorial, add following domain name entries into client's hosts file:
    • For the IBM HTTP Server for Process Federation Server: PFSIHS.cn.ibm.com
    • For the IBM HTTP Server for IBM BPM V8.5.6 server: BPM856IHS.cn.ibm.com
    • For the IBM HTTP Server for IBM BPM V8.0.1.3 server: BPM8013IHS.cn.ibm.com
  7. Verify the single sign-on configurations. You can verify single sign-on by accessing the Process Portal for one of the IBM BPM systems. Then open a new tab to access the other system. Finally you can access the Process Federation Server REST API to verify that users can also be recognized by Process Federation Server.

Configuring the Elasticsearch service

The Elasticsearch service on Process Federation Server provides a distributed index that contains the data from the IBM BPM systems in the federated environment. The distributed index ensures that users have fast access to federated data, and relieves IBM BPM systems from expensive queries. It supports complex and dynamic queries with both task metadata and business data. There is an indexing service for each IBM BPM server in the federated environment, and a common REST-based query service that provides data to users. The Elasticsearch service can automatically rebalance the distributed index. For example, as you add more process federation servers to handle loads, partitions of the federated index (shards) are automatically relocated to the new servers.

The server.xml configuration file on Process Federation Server contains configuration properties with default values for the Elasticsearch service. By default, the Elasticsearch service is configured for a single-server, quick-start environment.

To configure the Elasticsearch service, complete the following steps:

  1. On Process Federation Server 1, edit the pfs_install_root/usr/servers/server1/server.xml configuration file.
  2. Update the ibmPfs_elasticSearch element with configuration properties for your environment. See the following example:
    <ibmPfs_elasticSearch
            cluster.name="federated_cluster1"
            node.name="node1"
            node.master="true"
            node.data="true"
            transport.tcp.port="9300"
    transport.tcp.ssl="true"
     transport.tcp.ssl.keystore="
    {server.config.dir}/resources/security/key.jks"
            transport.tcp.ssl.keystore_password="passw0rd"
            transport.tcp.ssl.keystore_algorithm="ibm"
            transport.tcp.ssl.truststore="${server.config.dir}/resources/security/server1trust.pk12"
            transport.tcp.ssl.truststore_password="passw0rd"
            transport.tcp.ssl.truststore_algorithm="PKIX"
            transport.tcp.ssl.protocol="TLS"
            http.enabled="true"
            http.cors.enabled="true"
            http.cors.allow-origin="*"
            http.port="9200"
            discovery.zen.minimum_master_nodes="1"
    discovery.zen.ping.multicast.enabled="false"
    discovery.zen.ping.unicast.hosts=" PFS1.cn.ibm.com:9300, PFS2.cn.ibm.com:9300" />
  3. On the PFS2 Process Federation Server, update the ibmPfs_elasticSearch element with configuration properties for your environment. See the following example:
    	<ibmPfs_elasticSearch
    	        cluster.name="federated_cluster1"
    	        node.name="node2"
    	        node.master="true"
    	        node.data="true"
    	        transport.tcp.port="9300"
    	        transport.tcp.ssl="true"
                transport.tcp.ssl.keystore="${server.config.dir}/resources/security/key.jks"
    	        transport.tcp.ssl.keystore_password="passw0rd"
    	        transport.tcp.ssl.keystore_algorithm="ibm"
                transport.tcp.ssl.truststore="${server.config.dir}/resources/security/server1trust.pk12"
    	        transport.tcp.ssl.truststore_password="passw0rd"
    	        transport.tcp.ssl.truststore_algorithm="PKIX"
    	        transport.tcp.ssl.protocol="TLS"
    	        http.enabled="true"
    	        http.cors.enabled="true"
    	        http.cors.allow-origin="*"
    	        http.port="9200"
    	        discovery.zen.minimum_master_nodes="1"
    	        discovery.zen.ping.multicast.enabled="false"
    	        discovery.zen.ping.unicast.hosts=" PFS1.cn.ibm.com:9300, PFS2.cn.ibm.com:9300" />

Pay attention to the following requirements:

  • Servers in the same cluster need to have the same cluster.name.
  • Servers in the same cluster should have different node.name.
  • If a server in the cluster can be a master node, set node.master="true".
  • If a server in the cluster can be a data node, set node.data="true".
  • To avoid brain split, set discovery.zen.minimum_master_nodes to define a quorum of cluster members that are required before the service becomes available.
  • List servers in the same cluster in discovery.zen.ping.unicast.hosts for the unicast mode cluster.
  • For key.jks and server1trust.pk12, see the Securing communication section.

Federating the IBM BPM systems

To federate the IBM BPM systems, you must enable indexing on a federated IBM BPM system, and then you must configure and maintain the IBM BPM systems in federated environments.

Enabling indexing on a federated IBM BPM system

The distributed Process Federation Server index enables process participants to see a consolidated list of tasks related to both BPDs and BPEL – from all the IBM BPM systems in the federated environment. For data from a federated IBM BPM system to appear in the index, you must enable indexing on the system.

Before you enable indexing on a federated IBM BPM system, ensure that the following conditions are met:

  • If you are enabling indexing on an IBM BPM system that is earlier than V8.5.6, verify that the required interim fixes are installed on the system. For more information, see Technote 1699090.
  • Verify that the Process Server on the IBM BPM server is stopped.

To enable indexing on a federated IBM BPM system, complete the following steps:

  1. On IBM BPM V8.0.1.3 server, stop all IBM BPM processes. Apply the 8.0.1.3-WS-BPM-IFJR51915.zip fix.
  2. Enable indexing of data from BPDs on an IBM BPM server. When running on an IBM BPM system, BPD-related data is written to the Process Server database (BPMDB). For this data to be included in the Process Federation Server index, on both IBM BPM V8.5.6 and IBM BPM V8.0.1.3 you must create change log tables, configure the IBM BPM server to emit task status changes to those tables, and enable BPD indexing on Process Federation Server.
    1. Create change log tables in the Process Server database on the IBM BPM system by completing the following steps.
      • On Process Federation Server, copy pfs_install_root\ibmProcessFederationServer\wlp-ext\dbscripts\oracle\create_bpd_change_log.ddl to the IBM BPM database machine.

        Because the IBM BPM V8.5.6 server is using Oracle, refer to scripts in the oracle folder. The IBM BPM V8.0.1.3 server is using DB2, so you need to select scripts in the db2 folder.

      • Read the instructions in the scripts and replace the variables with the correct values. for example, Replace @SCHEMA@ with the schema name, for example, BPMDB
      • Run the scripts to create related tables.
    2. Configure the IBM BPM server to emit status changes for tasks to the change log tables.
      • On IBM BPM server, update the 100Custom.xml file to include the federated-index-enabled configuration parameter. And restart all servers.

        See the following example:

        # vi /opt/IBM/BPM/profiles/Dmgr01/config/cells/Test01Cell01/nodes/Test01Node01
            /servers/BPM.AppCluster.Test01Node01.0/process-center/config/100Custom.xml
      • Add the following code snippet:
        <server>
              <search-index merge="mergeChildren">
                 <federated-index-enabled merge="replace">true</federated-index-enabled>
               </search-index>
        </server>
      • Then restart all servers, and verify that there are no errors in the SystemOut.log file.
    3. Enable BPD indexing on Process Federation Server.

      On Process Federation Servers, add specific database library and dataSource elements for your Process Server database in the server.xml file.
      See the following example for IBM BPM V8.5.6 using Oracle Real Application Cluster:

      <library id="OraLib" name="OraLib">
          <fileset dir="
      /opt/IBM/WebSphere/Liberty/ibmProcessFederationServer/wlp-ext/jdbcdrivers/Oracle "
       includes="ojdbc6.jar"></fileset>
      </library>
      
      <dataSource jndiName="jdbc/bpmdatarac" id="bpm_oracle"
       type="javax.sql.DataSource"
      isolationLevel="TRANSACTION_READ_COMMITTED">
        <properties.oracle URL="jdbc:oracle:thin:@//
       DB856:1521/pdb1" serverName=" DB856.cn.ibm.com "
       databaseName="pdb1" user="racbpm" password="password"
       serviceName="pdb1"></properties.oracle>
        <jdbcDriver libraryRef="OraLib"></jdbcDriver>
      </dataSource>

      See the following example for IBM BPM V8.0.1.3 using DB2:

      <library id="DB2JCC4Lib">
        <fileset dir="/home/holly_test/jdbcdrivers/DB2"
       includes="db2jcc4.jar db2jcc_license_cisuz.jar"/>
      </library>
      
      <dataSource commitOrRollbackOnCleanup="commit"
       id="bpm_db252"
       isolationLevel="TRANSACTION_READ_COMMITTED"
       jndiName="jdbc/bpmdata52" type="javax.sql.DataSource">
        <jdbcDriver libraryRef="DB2JCC4Lib"/>
        <properties.db2.jcc databaseName="BPMDB" serverName="
       DB8013.cn.ibm.com " portNumber="50000" user="db2inst1"
       password=" Passw0rd" />
      </dataSource>

      This DB information is needed later in the tutorial. Update the configuration properties for the BPD indexing service in the ibmPfs_federatedSystem, ibmPfs_bpdIndexer, and ibmPfs_bpdRetriever elements.

  3. Enable indexing of BPEL-related data on the IBM BPM server. When a BPEL process runs on an IBM BPM system, BPEL process and task-related data is written to the Business Process Choreographer database. This database is the shared database and defaults to the CMNDB database. For this data to be included in the Process Federation Server index, you must create change log tables on the IBM BPM server, and enable BPEL indexing on Process Federation Server. The steps are similar to enabling indexing of BPD-related data. See the IBM BPM documentation for details.

Configuring and maintaining IBM BPM systems in federated environments

Federated environments consist of the Process Federation Server and multiple federated IBM BPM systems. Use properties in the Process Federation Server server.xml configuration file to configure an IBM BPM system for the federated environment and to configure and maintain the indexing service for the system.

To configure and maintain IBM BPM systems in federated environments, complete the following steps:

  1. On Process Federation Servers, edit the pfs_install_root/usr/servers/server1/server.xml configuration file.
  2. Add ibmPfs_federatedSystem, index, and REST retriever implementation elements with configuration properties for both IBM BPM V8.5.6 and IBM BPM V8.0.1.3.
    See the following example of adding BPD-related data for IBM BPM V8.5.6:
<ibmPfs_federatedSystem id="bpm170"
 index.number_of_shards="12" index.number_of_replicas="1"
 allowedOrigins="*"   restUrlPrefix="https://
 BPM856IHS.cn.ibm.com/rest/bpm/wle"
 taskCompletionUrlPrefix="https://
 BPM856IHS.cn.ibm.com/teamworks"/>

<ibmPfs_bpdIndexer federatedSystemRef="bpm170"
 dataSourceRef="bpm_oracle" schemaName="racbpm"
 indexingInterval="30s">
  <partitioningService dataSourceRef="bpm_oracle"
 schemaName="racbpm"/>
  </ibmPfs_bpdIndexer>

<ibmPfs_bpdRetriever federatedSystemRef="bpm170"
 connectTimeout="10s" readTimeout="10s"
 internalRestUrlPrefix="https://
 BPM856IHS.cn.ibm.com/rest/bpm/wle"/>

Add a similar section for the IBM BPM V8.0.1.3 server. Pay attention to the following considerations:

  • Ensure that the value of the federatedSystemRef property in the implementation elements is the same as the id property in the ibmPfs_federatedSystem element.
  • Ensure that the indexer connects directly to the IBM BPM database server by specifying a value for the dataSourceRef property that you created in the previous step.
  • The Index has been divided into 12 shards, which have one replica by default for data replication. Shards are dynamically allocated across cluster members.
  • For the users of your process application to claim and complete tasks, you need to provide IBM BPM URLs in the restUrlPrefix, taskCompletionUrlPrefix, and internalRestUrlPrefix properties. For details about configuration properties see the IBM BPM documentation.

Securing communication

Communication in federated environments is secured with the Secure Sockets Layer (SSL) protocol by default. The SSL protocol provides transport layer security that includes authenticity, data signing, and data encryption to ensure that the connection between the client and the server is secure.

There are several ways to secure communications, but in this tutorial you configure securing inbound and outbound communications between Process Federation Server and the federated IBM BPM systems.

The server.xml file that is provided as a template includes a default SSL configuration, and a default keystore. When Process Federation Server starts for the first time, it creates a Java KeyStore and a self-signed certificate in the keystore. Clients must be configured to trust the Process Federation Server certificate signer.

To get more secure communication in a production environment, replace the Process Federation Server default self-signed certificate with a properly chained certificate that is signed by a trusted certificate authority. To manage the Process Federation Server keystore and certificates, use keytool utility for your Java Virtual Machine, or the IBM HTTP Server iKeyman utility.

For the topology in this tutorial, enable secure communication with the SSL protocol between Process Federation Server and IBM BPM by importing the signer certificate of each federated IBM BPM system into the truststore for the Process Federation Server. Because the IBM HTTP Server is in front of IBM BPM clusters, the simple way is to import only the certificate for the IBM HTTP Server for IBM BPM.

Complete the following steps to secure communication:

  1. On Process Federation Server, edit the pfs_install_root/usr/servers/server1/server.xml configuration file. Add following elements:
    <sslOptions id="mySSLOptions" sslRef="mySSLSettings" />
    <ssl id="mySSLSettings" keyStoreRef="myKeyStore"
     trustStoreRef="myTrustStore" sslProtocol="TLS" />
    <keyStore id="myKeyStore"  location="$
    {server.config.dir}/resources/security/key.jks" type="JKS"
      password="password" />
    <keyStore password="password" id="myTrustStore" location="$
    {server.config.dir}/resources/security/server1trust.pk12"></
    keyStore>
    <sslDefault sslRef="mySSLSettings" />

    Consider the following points:

    • For the key.jks keystore, if the key.jks file does not exist, the server creates it when it starts. You can use the Liberty profile security utility to encode passwords.
    • For the server1trust.pk12 truststore, check the following steps.
  2. On the IBM BPM V8.5.6 server get the personal certificate for the IBM HTTP Server and import it into the Process Federation Server truststore.
    1. On the IBM HTTP Server for IBM BPM V8.5.6, use the key-management program iKeyman to extract the IBM HTTP Server Personal certificate:
      execute C:\IBM\HTTPServer\bin\ikeyman.bat
    2. Open the IBM HTTP Server Personal certificate (for example: C:\IBM\HTTPServer\bin\key1.kdb). Input the password in the window, as shown in Figure 8.
      Figure 8. Example of locating the personal certificate for the IBM HTTP Server
      Screen capture of the Open window for Personal                                     Certificates
      Screen capture of the Open window for Personal Certificates
    3. Click Extract Certificate to extract it to a file, as shown in Figure 9.
      Figure 9. Example of extracting the personal certificate for the IBM HTTP Server
      Screen capture of the New window for Personal                                     Certificates
      Screen capture of the New window for Personal Certificates
    4. Copy the generated certificate file to Federated Process Server machine. And import it into Process Federation Server trust store:
      #cd /opt/IBM/WebSphere/Liberty/java/java_1.7_64/bin
      #./keytool -import -keystore
       /opt/IBM/WebSphere/Liberty/usr/servers/server1/resources/s
      ecurity/server1trust.pk12 -alias IHS2Cert -file
       /home/holly_test/certIHS2.arm

For the IBM HTTP server for IBM BPM V8.0.1.3, repeat Step 2.

Configuring the IBM HTTP Server for the Process Federation Servers

To achieve high availability and disaster recovery for the Process Federation Server, it's better to configure the two Process Federation Servers (PFS1 and PFS2) with the IBM HTTP Server (PFSIHS).

To configure the IBM HTTP server for the Process Federation Servers, complete the following steps:

  1. As usual, use the iKeyman tool to create an IBM HTTP Server personal certificate and root certificate. Configure IBM HTTP Server in front of Process Federation Server, and modify the IBM HTTP Server parameter based on your environment.
  2. On the IBM HTTP Server (PFSIHS), use the Websphere Customization Toolbox to create the Process Federation Server response file, as shown in Figure 10.
    Figure 10. Websphere Customization Toolbox
    Screen capture of the Websphere Customization toolbox
    Screen capture of the Websphere Customization toolbox
    1. Locate the httpd.conf and enter the port, as shown in Figure 11.
      Figure 11. Selecting the httpd.conf web server configuration file
      Screen capture of selecting                                     the httpd.conf web server configuration file
      Screen capture of selecting the httpd.conf web server configuration file
    2. Give the definition a unique name for web server, as shown in Figure 12.
      Figure 12. Example of naming the web server definition
      Example of                                     naming the web server definition
      Example of naming the web server definition
    3. Enter the host name of the Process Federation Server 1, as shown in Figure 13.
      Figure 13. Example host name in the configuration scenario
      Screen capture of the host name in the configuration scenario
      Screen capture of the host name in the configuration scenario
    4. Then, under the config folder of plugins, verify that several files are created. Delete all files except the *.responseFile file.
  3. Configure the plugin-cfg.xml file.
    1. Generate the plugin-cfg.xml file and copy it to the IBM HTTP Server plugin folder.

      On the PFS1 Process Federation Server, use the Java Monitoring and Management Console (JConsole) utility in Java SDK to generate a plugin-cfg.xml file. Run the following command:

      #cd /opt/IBM/WebSphere/Liberty/java/java_1.7_64/bin
      #./jconsole

      The server process is listed in the choices that are waiting for connection, as shown in Figure 14.

      Figure 14. JConsole new connection to the Process Federation Server
      Screen capture of the JConsole New                                 Connection window
      Screen capture of the JConsole New Connection window
    2. Connect to your Process Federation Server then click the MBeans tab. Expand WebSphere and locate the com.ibm.ws.jmx.mbeans.generatePluginConfig management bean (Mbean), as shown in Figure 15.
      Figure 15. The generatePluginConfigMbean on the Mbeans tab on the JConsole
      Screen capture of the                         generatePluginConfigMbean on the Mbeans tab on the JConsole
      Screen capture of the generatePluginConfigMbean on the Mbeans tab on the JConsole
    3. Enter the root folder of your plugin, and the name of web server plugin, then click generatePluginConfig. The generated plugin-cfg.xml file should be under the same folder as the server.xml file, as shown in Figure 16.
      Figure 16. Select generatePluginConfig on the Mbeans tab on the JConsole
      Screen capture of generatePluginConfig on the Mbeans tab on the JConsole
      Screen capture of generatePluginConfig on the Mbeans tab on the JConsole
    4. Then copy the plugin-cfg.xml to the IBM HTTP Server plugins config folder.
  4. Repeat step 3 for the PFS2 Process Federation Server, and get another plugin: cfg1.xml. Copy it to the IBM HTTP Server plugins config folder. Then merge the files into one file, called plugin-config.xml in the examples in this tutorial. Edit the final plugin-cfg.xml, change the keyring, stashfile, and and certLabel properties to the correct value based on your IBM HTTP Server and web plugins settings:
    <Property Name="keyring" Value="your_key_database_file.kdb"/>
    <Property Name="stashfile" Value="your_password_stash_file.sth"/>
    <Property Name="certLabel" Value="your_certificate_label"/>
  5. Copy the IBM HTTP Server SSL key database file and password stash file to the Federated Portal Liberty profile, for example:
    ${server.config.dir}/resources/security.
  6. Add the pluginConfiguration element into the server.xml file:
    <pluginConfiguration webserverPort="80" webserverSecurePort="443"
     sslCertlabel="IHSCert" sslKeyringLocation="$
    {server.config.dir}/resources/security/key1.kdb" sslStashfileLocation="$
    {server.config.dir}/resources/security/key1.sth" />
  7. Restart the IBM HTTP Server and the Process Federation Servers. Verify that there are no errors in the IBM HTTP Server logs. Try to access Process Federation Server through IBM HTTP Server link.

Verify the solution with Elasticsearch clients

There are many clients that can be used to verify the Elasticsearch service. The examples in this tutorial use elasticsearch-head. Currently elasticsearch-head can only be installed as a stand-alone client then pointed to your Elasticsearch service.

  1. Install stand-alone elasticsearch-head.
  2. Start elasticsearch-head by opening index.htm under elastic-search-head-master, as shown in Figure 17.
    Figure 17. The elasticsearch-head tool
    Screen capture of the elasticsearch-head files
    Screen capture of the elasticsearch-head files
  3. Point to your Process Federation Server. You can see tasks indexed in the Elasticsearch cluster as shown in Figure 18:
    Figure 18. Connecting to the Process Federation Server on the elasticsearch-head tool
    Screen capture of the elasticsearch-head tool connected                             to the Process Federation Server
    Screen capture of the elasticsearch-head tool connected to the Process Federation Server

Verify the solution with the Process Federation Server REST API

Process Federation Server in IBM BPM V8.5.6 provides REST APIs that you can use to build custom client applications to support task worker scenarios in federated environments, for example, querying a federated task list, working on the returned tasks, and starting new instances from a federated launch list. See REST interface for IBM Process Federation Server resources in the IBM BPM V8.5.6 documentation.

Process Federation Server REST APIs are shown in the following sections with a response, which is not available in the IBM BPM V8.5.6 documentation. Because each of the URLs represents an HTTP GET request, you can test each REST API directly in your browser and examine the response content.

Systems Metadata REST API

Systems Metadata provides information about the federated IBM BPM systems. Use the API to detect whether a system is available or to retrieve system-specific settings. Attributes are returned for each IBM BPM system and depend on the system type.

Example URL:

https://PFSIHS.cn.ibm.com/rest/bpm/federated/v1/systems

Example response:

{"federationResult":[{"indexRefreshInterval":1000,"id":"bpm170","statusCo
de":200,"taskCompletionUrlPrefix":"https:\/\/BPM856IHS.cn.ibm.com \/teamw
orks","restUrlPrefix":"https:\/\/BPM856IHS.cn.ibm.com\/rest\/bpm\/wle","
systemType":"SYSTEM_TYPE_WLE","indexName":"bpm170","systemID":"e2021188-
db69-46e3-9f24-30c5e2ffb3db","version":"8.5.6.0"},{"indexRefreshInterval"
:1000,"id":"bpm37","statusCode":200,"taskCompletionUrlPrefix":"https:\/\/
BPM8013IHS.cn.ibm.com \/teamworks","restUrlPrefix":"https:\/\/BPM8013IHS.c
n.ibm.com \/rest\/bpm\/wle","systemType":"SYSTEM_TYPE_WLE","indexName":"bp
m37","systemID":"4998fd69-9e05-45c5-930e-ceb1829a6cf8","version"
:"8.0.1.3"}],"systems":[{"systemID":"e2021188-db69-46e3-9f24-
30c5e2ffb3db","systemType":"SYSTEM_TYPE_WLE","version":"8.5.6.0","gro
upWorkItemsEnabled":false,"resources":
["tasks","taskTemplates","processes"],"taskHistoryEnabled":false,"bui
ldLevel":"BPM8560-20150127-
000101","substitutionEnabled":false,"workBasketsEnabled":false,"subst
itutionManagementRestrictedToAdministrators":false,"businessCategorie
sEnabled":false,"taskSearchEnabled":true,"notificationWebMessagingEna
bled":false,"taskListWebMessagingEnabled":false,"apiVersion":"1.0","s
upports":null,"hostname":"BPM856IHS.cn.ibm.com"},
{"systemID":"4998fd69-9e05-45c5-930e-
ceb1829a6cf8","systemType":"SYSTEM_TYPE_WLE","version":"8.0.1.3","gro
upWorkItemsEnabled":false,"resources":
["tasks","taskTemplates","processes"],"taskHistoryEnabled":false,"bui
ldLevel":"BPM8013-20140814-
155433","substitutionEnabled":false,"workBasketsEnabled":false,"subst
itutionManagementRestrictedToAdministrators":false,"businessCategorie
sEnabled":false,"taskSearchEnabled":true,"notificationWebMessagingEna
bled":false,"taskListWebMessagingEnabled":false,"apiVersion":"1.0","
supports":null,"hostname":"BPM8013IHS.cn.ibm.com"}]}

Task List REST API

Task List provides the federated task list. Only the default task list, IBM.DEFAULTALLTASKSLIST_75, is supported. Attributes are returned for each task and depend on the federated IBM BPM system type. The attributes include a system ID that indicates the system that the task runs on. The federationResult section in the response data contains an entry for each system ID that indicates the URLs to use for working with that system.

Example basic URL:

https://PFSIHS.cn.ibm.com/rest/bpm/federated/v1/tasks/query/IBM.DEFAULTALLTASKSLIST_75

Part of response:

{"entityTypeName":"TASK","federationResult":
[{"statusCode":200,"id":"bpm170","indexRefreshInterval":1000,"taskCom
pletionUrlPrefix":"https:\/\/BPM856IHS.cn.ibm.com\/teamworks","restUr
lPrefix":"https:\/\/BPM856IHS.cn.ibm.com\/rest\/bpm\/wle","systemType"
:"SYSTEM_TYPE_WLE","indexName":"bpm170","systemID":"e2021188-db69-
46e3-9f24-30c5e2ffb3db","version":"8.5.6.0"},
{"statusCode":200,"id":"bpm37","indexRefreshInterval":1000,"taskCompl
etionUrlPrefix":"https:\/\/BPM8013IHS.cn.ibm.com\/teamworks","restUr
lPrefix":"https:\/\/BPM8013IHS.cn.ibm.com\/rest\/bpm\/wle","systemTyp
e":"SYSTEM_TYPE_WLE","indexName":"bpm37","systemID":"4998fd69-
9e05-45c5-930e-ceb1829a6cf8","version":"8.0.1.3"}],"totalCount"
:5,"items":[{"TAD_DISPLAY_NAME":"Step: task3","AT_RISK_TIME":"20
15-02-11T10:49:01Z","STATE":"STATE_FINISHED","NAME":"task3","SNAPSH
OT_NAME":"NN1","PRIORITY":30,"SNAPSHOT_ID":"2064.337e8aa9-f430-
4777-bb80-1fdf799385c4","DUE":"2015-02-11T10:55:01Z","STATUS"
:"Closed","PI_DISPLAY_NAME":"bpd2:59","OWNER":"user1_2","CONTAINM
ENT_CTX_ID":"59","PROCESS_INSTANCE.PIID":"59","PI_PIID":"59","TAD_DESCR
IPTION":"Step: task3","PI_NAME":"bpd2:59","TKIID":"57","ORIGINATOR"
:"bpmadmin","IS_AT_RISK":true,"PROCESS_APP_ACRONYM":"HT1","systemI
D":"e2021188-db69-46e3-9f24-30c5e2ffb3db","ACTIVATED":"2015-02-
11T09:55:01Z","TASK.TKIID":"57","COMPLETED":"2015-02-
16T09:15:38Z","KIND":"KIND_PARTICIPATING","PT_PTID":"25.b489c0a8-
66fb-4f4e-817f-6df7601e9a28","ASSIGNED_TO_ROLE_DISPLAY_NAME":null},
{"TAD_DISPLAY_NAME":"Step: task5","AT_RISK_TIME":"2015-02-
11T11:03:02Z","STATE":"STATE_READY","NAME":"task5","SNAPSHOT_NAME":
"OP2","PRIORITY":30,"SNAPSHOT_ID":"2064.b0cf716d-6a50-4b08-a6b7-
061a2321bbc2","DUE":"2015-02-11T11:09:02Z","STATUS":"Received","PI_DIS
PLAY_NAME":"bpd3:62","OWNER":null,"CONTAINMENT_CTX_ID":"62","PROC
ESS_INSTANCE.PIID":"62","PI_PIID":"62","TAD_DESCRIPTION":"Step: ta
sk5","PI_NAME":"bpd3:62","TKIID":"58","ORIGINATOR":"bpmadmin","IS_AT_RI
SK":true,"PROCESS_APP_ACRONYM":"HT1","systemID":"e2021188-db69-
46e3-9f24-30c5e2ffb3db","ACTIVATED":"2015-02-11T10:09:02Z","TASK.TKIID":
"58","COMPLETED":null,"KIND":"KIND_PARTICIPATING","PT_PTID":"25.55622acd-50c3-
43c0-8651-227ab2636d9b","ASSIGNED_TO_ROLE_DISPLAY_NAME":"All Users"},
{"TAD_DISPLAY_NAME":"Step: required2","AT_RISK_TIME":"2015-02-
11T11:04:15Z","STATE":"STATE_READY","NAME":"required2","SNAPSHOT_NA
ME":"OP2","PRIORITY":30,"SNAPSHOT_ID":"2064.b0cf716d-6a50-4b08-
a6b7-061a2321bbc2","DUE":"2015-02-11T11:10:15Z","STATUS":"Receiv
ed","PI_DISPLAY_NAME":"bpd3:62","OWNER":null,"CONTAINMENT_CTX_ID":"62","PRO
CESS_INSTANCE.PIID":"62","PI_PIID":"62","TAD_DESCRIPTION":"Step: requ
ired2","PI_NAME":"bpd3:62","TKIID":"59","ORIGINATOR":"bpmadmin","IS_AT_RI
SK":true,"PROCESS_APP_ACRONYM":"HT1","systemID":"e2021188-db69-46e3-
9f24-30c5e2ffb3db","ACTIVATED":"2015-02-11T10:10:15Z","TASK.TKIID":
"59","COMPLETED":null,"KIND":"KIND_PARTICIPATING","PT_PTID":"25.55622acd-
50c3-43c0-8651-227ab2636d9b","ASSIGNED_TO_ROLE_DISPLAY_NAME":"All Users"}

Example URL for a query with interaction filter and full text search for tasks that include the term 'Step':
https://PFSIHS.cn.ibm.com/rest/bpm/federated/v1/tasks/query/IBM.DEFAULTALLTASKSLIST_75?interactionFilter=ASSESS_AND_WORK_ON&searchFilter=Step

Part of response:

{"entityTypeName":"TASK","federationResult":[{"statusCode":200,"id":"bpm3
7","indexRefreshInterval":1000,"taskCompletionUrlPrefix":"https:\/\/BPM80
13IHS.cn.ibm.com\/teamworks","restUrlPrefix":"https:\/\/BPM8013IHS.cn.ib
m.com\/rest\/bpm\/wle","systemType":"SYSTEM_TYPE_WLE","indexName":"bpm37
","systemID":"4998fd69-9e05-45c5-930e-ceb1829a6cf8","version":"8.0.1.3"},
{"statusCode":200,"id":"bpm170","indexRefreshInterval":1000,"taskCompletio
nUrlPrefix":"https:\/\/BPM856IHS.cn.ibm.com\/teamworks","restUrlPrefix":"ht
tps:\/\/BPM856IHS.cn.ibm.com\/rest\/bpm\/wle","systemType":"SYSTEM_TYPE_WL
E","indexName":"bpm170","systemID":"e2021188-db69-46e3-9f24-30c5e2ffb3db","v
ersion":"8.5.6.0"}],"totalCount":4,"items":
[{"TAD_DISPLAY_NAME":"Step: task5","AT_RISK_TIME":"2015-02-11T11:03:02Z","ST
ATE":"STATE_READY","NAME":"task5","SNAPSHOT_NAME":"OP2","PRIORITY":30,"SNAPS
HOT_ID":"2064.b0cf716d-6a50-4b08-a6b7-061a2321bbc2","DUE":"2015-02-11T11:09:
02Z","STATUS":"Received","PI_DISPLAY_NAME":"bpd3:62","OWNER":null,"CONTAINME
NT_CTX_ID":"62","PROCESS_INSTANCE.PIID":"62","PI_PIID":"62","TAD_DESCRIPTION
":"Step: task5","PI_NAME":"bpd3:62","TKIID":"58","ORIGINATOR":"bpmadmin","IS
_AT_RISK":true,"PROCESS_APP_ACRONYM":"HT1","systemID":"e2021188-db69-46e3-9f24-
30c5e2ffb3db","ACTIVATED":"2015-02-11T10:09:02Z","TASK.TKIID":"58","COMPLETED"
:null,"KIND":"KIND_PARTICIPATING","PT_PTID":"25.55622acd-50c3-43c0-8651-227ab2
636d9b","ASSIGNED_TO_ROLE_DISPLAY_NAME":"All Users"},{"TAD_DISPLAY_NAME":"Ste
p: required2","AT_RISK_TIME":"2015-02-11T11:04:15Z","STATE":"STATE_READY","NA
ME":"required2","SNAPSHOT_NAME":"OP2","PRIORITY":30,"SNAPSHOT_ID":"2064.b0cf716d-
6a50-4b08-a6b7-061a2321bbc2","DUE":"2015-02-11T11:10:15Z","STATUS":"Received","PI
_DISPLAY_NAME":"bpd3:62","OWNER":null,"CONTAINMENT_CTX_ID":"62","PROCESS_INSTAN
CE.PIID":"62","PI_PIID":"62","TAD_DESCRIPTION":"Step: required2","PI_NAME":"bp
d3:62","TKIID":"59","ORIGINATOR":"bpmadmin","IS_AT_RISK":true,"PROCESS_APP_ACRON
YM":"HT1","systemID":"e2021188-db69-46e3-9f24-30c5e2ffb3db","ACTIVATED":"2015-
02-11T10:10:15Z","TASK.TKIID":"59","COMPLETED":null,"KIND":"KIND_PARTICIPATING",
"PT_PTID":"25.55622acd-50c3-43c0-8651-227ab2636d9b","ASSIGNED_TO_ROLE_DISPLAY_NA
ME":"All Users"}

Task Instance Queries REST API

Task Instance Queries provides the list of task queries that are available. Only the default task list, IBM.DEFAULTALLTASKSLIST_75, is supported.

Example URL:

https://PFSIHS.cn.ibm.com/rest/bpm/federated/v1/tasks/queries

Example response:

{"federationResult":
[{"indexRefreshInterval":1000,"id":"bpm170","statusCode":200,"taskCom
pletionUrlPrefix":"https:\/\/BPM856IHS.cn.ibm.com
\/teamworks","restUrlPrefix":"https:\/\/BPM856IHS.cn.ibm.com\/rest\/b
pm\/wle","systemType":"SYSTEM_TYPE_WLE","indexName":"bpm170","systemI
D":"e2021188-db69-46e3-9f24-30c5e2ffb3db","version":"8.5.6.0"},
{"indexRefreshInterval":1000,"id":"bpm37","statusCode":200,"taskCompl
etionUrlPrefix":"https:\/\/BPM8013IHS.cn.ibm.com
\/teamworks","restUrlPrefix":"https:\/\/BPM8013IHS.cn.ibm.com
\/rest\/bpm\/wle","systemType":"SYSTEM_TYPE_WLE","indexName":"bpm37",
"systemID":"4998fd69-9e05-45c5-930e-
ceb1829a6cf8","version":"8.0.1.3"}],"items":
[{"authorizationType":"INSTANCE_BASED","kind":"FEDERATED","entityType
Name":"TASK","systemIDs":["e2021188-db69-46e3-9f24-
30c5e2ffb3db","4998fd69-9e05-45c5-930e-ceb1829a6cf8"],"locales":
["zh","tr","sv","ru","ro","pl","no","nb","ko","ja","default","en","ar
","cs","da","de","el","es","fi","fr","iw","hu","it","zh_TW","pt_BR"],
"name":"IBM.DEFAULTALLTASKSLIST_75","description":"This is the
 default tasks list. Define custom tasks lists to show selected
 business
 data.","displayName":"All","keyAttribute":"TASK.TKIID"}],"identifier"
:"name"}

Task Instance Query Attributes REST API

Task Instance Query Attributes provides the list of attribute names in the default task list that you can use in task list queries.

Example URL:

https://PFSIHS.cn.ibm.com/rest/bpm/federated/v1/tasks/query/IBM.DEFAULTALLTASKSLIST_75/attributes

Example response:

{"federationResult":
[{"indexRefreshInterval":1000,"id":"bpm170","statusCode":200,"taskComp
letionUrlPrefix":"https:\/\/BPM856IHS.cn.ibm.com\/teamworks","restUr
lPrefix":"https:\/\/BPM856IHS.cn.ibm.com\/rest\/bpm\/wle","systemType
":"SYSTEM_TYPE_WLE","indexName":"bpm170","systemID":"e2021188-db69-
46e3-9f24-30c5e2ffb3db","version":"8.5.6.0"},
{"indexRefreshInterval":1000,"id":"bpm37","statusCode":200,"taskCompl
etionUrlPrefix":"https:\/\/BPM8013IHS.cn.ibm.com\/teamworks","restUrl
Prefix":"https:\/\/BPM8013IHS.cn.ibm.com\/rest\/bpm\/wle","systemType
":"SYSTEM_TYPE_WLE","indexName":"bpm37","systemID":"4998fd69-
9e05-45c5-930e-ceb1829a6cf8","version":"8.0.1.3"}],"totalSystemTypeCount":1,
"items":[{"content":"instance.processinstancename.string",
"sourceAttribute":"instance.processinstancename.string",
"name":"PI_DISPLAY_NAME","sourceQueryTableIdentifier":"n\/a",
"type":"string","isArray":false},{"content":"process.processtemplateid.key",
"sourceAttribute":"process.processtemplateid.key","name":"PT_PTID",
"sourceQueryTableIdentifier":"n\/a","type":"string","isArray":false},
{"content":"task.duetime.date","sourceAttribute":"task.duetime.date",
"name":"DUE","sourceQueryTableIdentifier":"n\/a","type":"date","isArray":false},
{"content":"task.isatrisk.boolean","sourceAttribute":"task.isatrisk.boolean",
"name":"IS_AT_RISK","sourceQueryTableIdentifier":"n\/a","type":"boolean",
"isArray":false},{"content":"task.status.key","sourceAttribute":"task.status.key",
"name":"STATUS","sourceQueryTableIdentifier":"n\/a","type":"string","isArray":false},
{"content":"task.atrisktime.date","sourceAttribute":"task.atrisktime.date",
"name":"AT_RISK_TIME","sourceQueryTableIdentifier":"n\/a","type":"date",
"isArray":false},{"content":"instance.processinstancename.string",
"sourceAttribute":"instance.processinstancename.string","name":"PI_NAME",
"sourceQueryTableIdentifier":"n\/a","type":"string","isArray":false},
{"content":"task.tkiid.key","sourceAttribute":"task.tkiid.key","name":"TKIID",
"sourceQueryTableIdentifier":"n\/a","type":"string","isArray":false},
{"content":"task.groupid.key","sourceAttribute":"task.groupid.key","name":"GROUP_ID",
"sourceQueryTableIdentifier":"n\/a","type":"number","isArray":false},
{"content":"task.owner.key","sourceAttribute":"task.owner.key","name":"OWNER",
"sourceQueryTableIdentifier":"n\/a","type":"string","isArray":false},
{"content":"task.completiontime.date","sourceAttribute":"task.completiontime.date",
"name":"COMPLETED","sourceQueryTableIdentifier":"n\/a","type":"date","isArray":false},
{"content":"task.priority.long","sourceAttribute":"task.priority.long","name":"PRIORITY",
"sourceQueryTableIdentifier":"n\/a","type":"number","isArray":false},
{"content":"task.description.string","sourceAttribute":"task.description.string",
"name":"TAD_DESCRIPTION","sourceQueryTableIdentifier":"n\/a","type":"string",
"isArray":false},{"content":"instance.snapshotname.string",
"sourceAttribute":"instance.snapshotname.string","name":"SNAPSHOT_NAME",
"sourceQueryTableIdentifier":"n\/a","type":"string","isArray":false},
{"content":"task.userid.key","sourceAttribute":"task.userid.key","name":"USER_ID",
"sourceQueryTableIdentifier":"n\/a","type":"number","isArray":false},
{"content":"instance.piid.key","sourceAttribute":"instance.piid.key",
"name":"PROCESS_INSTANCE.PIID","sourceQueryTableIdentifier":"n\/a",
"type":"string","isArray":false},{"content":"instance.snapshotid.key",
"sourceAttribute":"instance.snapshotid.key","name":"SNAPSHOT_ID",
"sourceQueryTableIdentifier":"n\/a","type":"string","isArray":false},
{"content":"task.activationtime.date","sourceAttribute":"task.activationtime.date",
"name":"ACTIVATED","sourceQueryTableIdentifier":"n\/a","type":"date",
"isArray":false},
{"content":"task.state.key","sourceAttribute":"task.state.key","name"
:"STATE","sourceQueryTableIdentifier":"n\/a","type":"string","isArray":false},
{"content":"task.name.string","sourceAttribute":"task.name.string","name"
:"NAME","sourceQueryTableIdentifier":"n\/a","type":"string","isArray
":false},
{"content":"instance.piid.key","sourceAttribute":"instance.piid.key",
"name":"PI_PIID","sourceQueryTableIdentifier":"n\/a","type":"string","isAr
ray":false},
{"content":"process.processappacronym.string","sourceAttribute":"proc
ess.processappacronym.string","name":"PROCESS_APP_ACRONYM","sourceQue
ryTableIdentifier":"n\/a","type":"string","isArray":false},
{"content":"task.containmentcontextid.key","sourceAttribute":"task.co
ntainmentcontextid.key","name":"CONTAINMENT_CTX_ID","sourceQueryTable
Identifier":"n\/a","type":"string","isArray":false},
{"content":"task.originator.key","sourceAttribute":"task.originator.k
ey","name":"ORIGINATOR","sourceQueryTableIdentifier":"n\/a","type":"s
tring","isArray":false},
{"content":"task.tkiid.key","sourceAttribute":"task.tkiid.key","name"
:"TASK.TKIID","sourceQueryTableIdentifier":"n\/a","type":"string","is
Array":false},
{"content":"task.assignedtoroledisplayname.string","sourceAttribute":
"task.assignedtoroledisplayname.string","name":"ASSIGNED_TO_ROLE_DISP
LAY_NAME","sourceQueryTableIdentifier":"n\/a","type":"string","isArra
y":false},
{"content":"task.kind.key","sourceAttribute":"task.kind.key","name":"
KIND","sourceQueryTableIdentifier":"n\/a","type":"string","isArray":f
alse},
{"content":"task.displayname.string","sourceAttribute":"task.displayn
ame.string","name":"TAD_DISPLAY_NAME","sourceQueryTableIdentifier":"n
\/a","type":"string","isArray":false}]}

Launch Entities REST API

Launchable Entities provides a federated list of the processes, services, and tasks that can be started by the current logged-on user. Attributes are returned for each startable item and depend on the federated IBM BPM system type. The attributes include a system ID that indicates the system that the item runs on. The federationResult section in the response data contains an entry for each system ID that indicates the URLs to use for working with that system.

Example URL:

https://PFSIHS.cn.ibm.com/rest/bpm/federated/v1/launchableEntities

Example response:

{"federationResult":
[{"statusCode":200,"id":"bpm170","indexRefreshInterval":1000,"taskCom
pletionUrlPrefix":"https://BPM856IHS.cn.ibm.com/teamworks","restUrlPr
efix":"https://BPM856IHS.cn.ibm.com/rest/bpm/wle","systemType":"SYSTE
M_TYPE_WLE","indexName":"bpm170","systemID":"e2021188-db69-46e3-9f24-
30c5e2ffb3db","version":"8.5.6.0"},
{"statusCode":200,"id":"bpm37","indexRefreshInterval":1000,"taskCompl
etionUrlPrefix":"https://BPM8013IHS.cn.ibm.com/teamworks","restUrlPre
fix":"https://BPM8013IHS.cn.ibm.com/rest/bpm/wle","systemType":"SYSTE
M_TYPE_WLE","indexName":"bpm37","systemID":"4998fd69-9e05-45c5-930e-
ceb1829a6cf8","version":"8.0.1.3"}],"items":
[{"snapshotID":"2064.95c9fb3c-e4a2-48af-
91df-dbcda7a90a17","itemID":"1.36bdcc65-8d6a-4635-85cf-
57cab68a7e45","systemType":"SYSTEM_TYPE_WLE","processAppName":"Proces
s Portal","isMobileReady":false,"launchableEntityType":"SERVICE","snaps
hotCreatedOn":"2015-01-28T04:29:34Z","display":"Process
 Diagram","type":"service","startURL":"https://WIN2008R2X64RU.c
n.ibm.com/teamworks/executecf?modelID=1.36bdcc65-8d6a-4635-85cf-
57cab68a7e45&branchID=2063.34a0ce6e-631b-465d-b0dc-
414c39fb893f","tip":true,"processAppID":"2066.23d3ecec-6fdb-4033-
9c57-e931aa13761f","branchID":"2063.34a0ce6e-631b-465d-b0dc-
414c39fb893f","isDefault":false,"snapshotName":"8.5.6.0","subtype":"u
rl","itemReference":"/1.36bdcc65-8d6a-4635-85cf-
57cab68a7e45","ID":"2015.18","branchName":"Main","systemID":"e2021188
-db69-46e3-9f24-30c5e2ffb3db","processAppAcronym":"TWP"},
{"snapshotID":"2064.5327bc35-5faa-4052-9317-
d2a4b6e96a28","itemID":"25.c904b3b1-afc1-4698-bf5a-
a20892c20275","systemType":"SYSTEM_TYPE_WLE","processAppName":"Hiring
 Sample","isMobileReady":false,"launchableEntityType":"PROCESS","snaps
hotCreatedOn":"2014-11-27T16:19:33Z","display":"Standard HR Open New
 Position","type":"process","startURL":"https://WIN2008R2X64RU.cn.ibm
.com/rest/bpm/wle/v1/process?action=start&bpdId=25.c904b3b1-afc1-4698-
bf5a-a20892c20275&branchId=2063.1a52abd6-b068-4f9e-91a9-
ded9793eb34e","tip":true,"processAppID":"2066.9ab0d0c6-d92c-4355-9ed5-d8a05
acdc4b0","branchID":"2063.1a52abd6-b068-4f9e-91a9-ded9793eb34e","isDefault"
:false,"snapshotName":"Standard Hiring Sample v8560","itemReference":"/25.c
904b3b1-afc1-4698-bf5a-a20892c20275","ID":"2015.37","branchName":"Main","sys
temID":"e2021188-db69-46e3-9f24-30c5e2ffb3db","processAppAcronym":"HSS"},
{"snapshotID":"2064.b2076323-2a32-49a1-9e6f-570c3bf28935","itemID":"1.2a8bb2d0-
5038-43be-b17e-31a192f8847c","systemType":"SYSTEM_TYPE_WLE","processAppName":"T
estApp","isMobileReady":false,"launchableEntityType":"SERVICE","snapshotCreat
edOn":"2015-03-03T09:53:08Z","display":"HS_Service","type":"service","startURL"
:"https://HollyIHS1.cn.ibm.com/teamworks/executeServiceByName?
processApp=TEST1&serviceName=HS_Service&snapshot=ServiceExpose_1","ti
p":false,"processAppID":"2066.5b5acd2d-0374-4a0a-b405-
50a14e2a8e7c","branchID":"2063.c2536580-fe7c-4feb-946e-
7078301b8608","isDefault":true,"snapshotName":"ServiceExpose_1","subt
ype":"startable_service","itemReference":"/1.2a8bb2d0-5038-43be-b17e-
31a192f8847c","ID":"2015.109","branchName":"ServiceExpose_1","systemI
D":"4998fd69-9e05-45c5-930e-
ceb1829a6cf8","processAppAcronym":"TEST1"},
{"snapshotID":"2064.a4b8b434-29d2-4bd7-92ea-
7f3e30630b06","itemID":"1.04c8755c-b4fb-4f53-b0bc-
c0816add8a02","systemType":"SYSTEM_TYPE_WLE","processAppName":"HollyT
est1","isMobileReady":false,"launchableEntityType":"SERVICE","snapsho
tCreatedOn":"2015-01-
29T02:50:34Z","display":"HT11","type":"service","startURL":"https://W
IN2008R2X64RU.cn.ibm.com/teamworks/executeServiceByName?
processApp=HT1&serviceName=HT11&snapshot=V11","
tip":false,"processAppID":"2066.c7603da0-1c6e-402f-b631-
f54326c18ea5","branchID":"2063.60f8fbee-1282-4283-acd5-
4fa76f39a339","isDefault":false,"snapshotName":"V11","subtype":"star
table_service","itemReference":"/1.04c8755c-b4fb-4f53-b0bc-
c0816add8a02","ID":"2015.163","branchName":"Main","systemID":"e2021188-
db69-46e3-9f24-30c5e2ffb3db","processAppAcronym":"HT1"} ,
{"snapshotID":"2064.fe64ffd7-eaf6-4671-8b40-ac57241bb4d3","itemID"
:"25.ddd4df2a-09b7-4ab0-87f4-eede42a1f8c4","systemType":"SYSTEM_TYPE_
WLE","processAppName":"FailSysTask","isMobileReady":false,"launchableEnt
ityType":"PROCESS","snapshotCreatedOn":"2015-03-07T08:34:47Z","display"
:"FST","type":"process","startURL":"https://HollyIHS1.cn.ibm.com/rest/bp
m/wle/v1/process?action=start&bpdId=25.ddd4df2a-09b7-4ab0-87f4-
eede42a1f8c4&snapshotId=2064.fe64ffd7-eaf6-4671-8b40-ac57241bb4d3","ti
p":false,"processAppID":"2066.00dfe332-f13a-46e2-b9e8-b81546a0f0e4","branchI
D":"2063.24932202-8f85-4e8b-9215-6892f3be29cc","isDefault":false,"snapsho
tName":"failedSysLinkProcess","itemReference":"/25.ddd4df2a-09b7-4ab0-87f4-
eede42a1f8c4","ID":"2015.113","branchName":"failedSysLinkProcess","systemI
D":"4998fd69-9e05-45c5-930e-ceb1829a6cf8","processAppAcronym":"FST"}]}

Troubleshooting the Process Federation Server

The Process Federation Server has a unified logging component that handles messages that are written by the Process Federation Server and includes a first failure data capture (FFDC) capability. You can configure the <logging> element in the server.xml file to control trace information in the trace.log file.

To use set the trace information for your Process Federation Server, complete the following steps:

  1. On the Process Federation Server, edit the pfs_install_root/usr/servers/server1/server.xml configuration file.
  2. Extend the traceSpecification property for each component that you want to trace. See the following example:
    <logging consoleLogLevel="INFO" traceFormat="ENHANCED"
    traceSpecification="*=info:com.ibm.bpm.federated.*=all " />

See the IBM BPM documentation on IBM Knowledge Center for detailed troubleshooting for the Process Federation Server.

Consult the following table for other troubleshooting:

IssuePossible causeAction plan
Can't access Process Federation Server REST API Most likely the LDAP is not configured properly. Check the messages.log.
The system status, task, and launch list info are incorrect in the REST API response Either the SSO or the SSL is not configured properly so the target IBM BPM can't be reached. Enable the following trace: com.ibm.bpm.federated.rest.query.*=all:com.ibm.bpm.federated.config.*=all: com.ibm.bpm.federated.retriever.*=all
The Process Federation Server cluster does not work properly The Process Federation Server cluster service is not configured properly or does not work properly. Enable the following trace: com.ibm.wbimonitor.partitioning.*=all
New tasks are not indexed The Process Federation Server tasks and processes indexer does not work properly. Enable the following trace: com.ibm.bpm.federated.indexer.*=all

Conclusion

In this tutorial, you learned how to install and configure Process Federation Server to access two back-end IBM BPM systems by following a detailed example. You learned about the overall topology and how to configure your environment. Now you can apply what you have learned to your own IBM BPM environment.

Acknowledgements

The authors would like to thank Wu Mi Zhong for his review and comments.


Downloadable resources


Related topics

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware
ArticleID=1026056
ArticleTitle=Configure the IBM Process Federation Server to give your IBM BPM process users a single point of access
publish-date=01272016