You can use the open source Head utility to browse your Elasticsearch cluster, view the status and topology of the Elasticsearch cluster, and perform index- and node-level operations. You can also use the Head utility to call the Elasticsearch RESTful API. The Head utility has been tested successfully on Firefox and Internet Explorer browsers in this configuration. Some issues have been seen in Chrome with requests other than HTTP GETs.

Viewing Elasticsearch health and topology

In the Overview tab, you see the status of the cluster, the nodes, and the indexes. Here, you see the primary shards and the replicas for each node, the size of each index on the node, and the number of documents that have been indexed.

Elasticsearch_Health and topology

Checking index status

To see more in-depth information about the index, click Info and select Index Status.

Elasticsearch__Checking index status

Viewing index data

Select the Browser tab to view index documents and their data. To see the details and field values for a specific document, select an index to restrict the tabular view to show only documents from one index and then select a document within the tabular view.

Elasticsearch__Viewing index data

Making REST calls

You can make Elasticsearch REST calls in the Any Request tab, which you do to verify the queries that the Process Federation Server made.

Elasticsearch_Making REST calls

The forwarder application

The Elasticsearch Head utility can work with the HTTP port of the Elasticsearch service. However, because some browsers do not support mixed content on the same page and that the HTTP port does not support authentication, authorization, or secure communications, keep the Elasticsearch HTTP port disabled (the default configuration). As a secure alternative to the Elasticsearch HTTP port, Process Federation Server provides an application, called the forwarder application, that securely forwards REST requests to the Elasticsearch service, acting like a proxy server. However, the forwarder application forwards the requests internally only to the Elasticsearch process that runs on the same server. Before the forwarder application accepts Elasticsearch HTTP requests, it checks the authorization of the user who sent the request.

Note: For single sign-on to work correctly, the host name and port in the URL must be the same for both the Head utility and the forwarder application.

Ensuring security credentials can be shared

To ensure that security credentials can be shared across the Elasticsearch Head utility and the forwarder application, run the Elasticsearch Head utility from the Process Federation Server that also hosts the forwarder application. To run the Head utility from your Process Federation Server Liberty server installation, download the Head utility and then repackage it into a deployable web application archive (WAR file) that can be run on the Process Federation Server Liberty server.

For more information about the Elasticsearch Head utility, see

Packaging the Head utility

  1. On, click Download ZIP to download the file.

       2. The files contained within the zip file have a directory structure that looks like this:




¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬† – …

            Copy the contents of the extracted zip file under elasticsearch-head-master directory into c:\temp\eshead\ directory. The structure will look like this:




¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬†¬† – …

         Notice that all the files under the elasticsearch-head-master directory are now under the new eshead directory.

      3. Create a  c:\temp\eshead\WEB-INF directory:





¬†¬†¬†¬†¬†¬†¬†¬†¬†¬† ¬† ¬† – …

       4. Create a web.xml file in the c:\temp\eshead\WEB-INF directory:






¬†¬†¬†¬†¬†¬†¬†¬†¬†¬† ¬†¬†¬†¬†¬†¬†¬†¬† – …

        5. Edit the web.xml file and copy the following text into the file:

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="ESHead" xmlns=""
xsi:schemaLocation="" version="2.4">

        6. Create a .zip file of the c:\temp\eshead\ directory and call it ESHead.war. The zip file will have the following structure:





¬†¬†¬†¬†¬†¬†¬†¬†¬†¬† ¬† ¬† ¬† ¬†¬†¬† – …

            Notice that the structure does not have the elasticsearch-head-master directory.

Setting up the Head utility

To configure Process Federation Server Liberty, complete the following steps:

  1. Edit the server.xml file.
  2. Ensure that the forwarder application feature is enabled in the <featureManager> section:
  3. Ensure that the Elasticsearch port is disabled by updating the attributes of  the <ibmPfs_elasticSearch> section:
  4. Add authorized users, groups, or special subjects in the <authorization-roles id=””> element. For example, to allow all logged-in users to administer, monitor, and search the Elasticsearch data, use the following configuration:
    <authorization-roles id="">
            <security-role name="bpmadmin">
                <special-subject type="ALL_AUTHENTICATED_USERS"/>
            <security-role name="bpmmonitor">
                <special-subject type="ALL_AUTHENTICATED_USERS"/>
            <security-role name="bpmuser">
                <special-subject type="ALL_AUTHENTICATED_USERS"/>
  5. Copy the ESHead.war file into the pfs_install_root/usr/shared/apps directory on your  Process Federation Server Liberty server.
  6. Add the following sections to the server.xml file. Note that the location is the name of the .zip file that you created previously; the default directory is \usr\shared\apps directory. The security role that you define must be the same as the role that is defined in the web.xml file (in this example it is “esadmin”). You can also authorize a group or special subject¬†instead of a user.
         <webApplication contextRoot="ESHead" location="ESHead.war">
               <security-role name="esadmin">               
                  <user name="uid=admin,o=defaultWIMFileBasedRealm"/>
  7. Ensure the user, group, or special subject is in the bpmadmin and bpmmonitor security roles of the authorization role, as previously described. In this example, all authenticated users have access to the forwarder application, but only the admin user has access to the Head utility.
  8. Restart Process Federation Server Liberty.

Accessing the Head utility

  1. Go to https://<host name>:<secure port>/ESHead.
  2. In the Head utility, enter the location of the administrative forwarder application, for example https://localhost:9443/elasticsearch-admin/

2 comments on"Good practice – Monitor the Process Federation Server embedded Elasticsearch service by using the Head utility"

  1. Thanks, Laura. Very interesting will try this today as soon as my PFS is working.
    Do you know by any chance what may cause the following messages?
    [ERROR ] Error creating a task index document. Index data was not found for indexKeyField=task.tkiid.key indexKey=83074


    [ERROR ] CWWKG0058E: with the unique identifier is missing required attribute name
    Info is very scarce on PFS. Thanks in advance. Vlad


  2. Hi, Vlad.

    I spoke with one of our lead IBM BPM developers, David Enyeart, and he said the first error can happen if the underlying IBM BPM task is deleted before PFS indexing occurs. In this case, it would be a benign error because the task does not need to be indexed in PFS anymore.

    Regarding the second error, please send David more context of what you were doing along with a full log showing the problem. His email address is

    I hope this helps.


Join The Discussion

Your email address will not be published. Required fields are marked *