Deploying Elasticsearch Metrics as your first use of metrics

Deploying Elasticsearch-based metrics for HCL Connections™ involves testing the environment and then switching users to the Elasticsearch Metrics component.

Before you begin

Both the RDBMS-based metrics app and the Elasticsearch Metrics component are installed during the Connections 6.0 CR updates. The RDBMS-based metrics app is provided for testing purposes only and no Cognos® server is needed. Before proceeding, make sure that you have applied both the latest CR and the latest Connections Component Pack ifix, changed the number of shards for the index (if your environment warrants it), and enabled the Metrics component to connect to your Elasticsearch server.

About this task

If you are new to Connections, complete the following steps to set up Elasticsearch Metrics for your first use. If you previously used Cognos® to provide Metrics data for your Connections deployment, skip this task and follow the instructions in Deploying Elasticsearch Metrics with the data migrated from the metrics relational database to set up Elasticsearch Metrics.

Procedure

  1. Validate that the Elasticsearch user experience is functioning well by confirming the test context root URL is working:

    Log in to the following URL as the admin user: https://Connections_server/metricssc

  2. When validation is complete, run the following Python script to switch users to the Elasticsearch Metrics component.

    This script causes the RDBMS-based app to stop capturing data, and the Elasticsearch component to start capturing it.

    1. On the WebSphere deployment manager server, start the wsadmin client as described in Starting the wsadmin client.
    2. Run the following commands to switch users to the Elasticsearch Metrics component:
      execfile('metricsEventCapture.py')
      switchMetricsToElasticSearch()
  3. (Optional) Map user profile attributes to report dimensions.

    Metrics reports support up to three different dimensions, which are based on user profile attributes. The following user attributes are supported for mapping to report dimensions:

    • com.ibm.snx_profiles.base.countryCode
    • com.ibm.snx_profiles.base.orgId
    • com.ibm.snx_profiles.base.title
    • com.ibm.snx_profiles.base.employeeTypeCode
    • com.ibm.snx_profiles.base.deptNumber
    • com.ibm.snx_profiles.base.workLocationCode
    • com.ibm.snx_profiles.base.isManager
    • com.ibm.snx_profiles.base.timezone
    • com.ibm.snx_profiles.base.profileType

    By default, mapping is provided for the following three attributes:

    • com.ibm.snx_profiles.base.countryCode - Mapped to the Geography dimension in Metrics reports
    • com.ibm.snx_profiles.base.orgId - Mapped to the Department dimension in Metrics reports
    • com.ibm.snx_profiles.base.title - Mapped to the Role dimension in Metrics reports

    You can change the attribute mapping by completing the following steps:

    Note: You should only change mappings with your first use of Metrics. Otherwise, Metrics data will be inconsistent and lead to incorrect report data.
    1. Get the default mapping:
      MetricsAdminService.getUserAttributesMapping()

      Returns:

      '{"attribute1":"com.ibm.snx_profiles.base.countryCode","attribute2":"com.ibm.snx_profiles.base.orgId","attribute3":"com.ibm.snx_profiles.base.title"}'

    2. Update the mapping:

      Do not change the keys "attribute1", "attribute2", and "attribute3". Just replace the attributes with the values that you want to use.

      Run the following command:
      MetricsAdminService.setUserAttributesMapping(mappingStr)
      For example:
      MetricsAdminService.setUserAttributesMapping('{"attribute1":"com.ibm.snx_profiles.base.profileType","attribute2":"com.ibm.snx_profiles.base.orgId","attribute":"com.ibm.snx_profiles.base.title"}' )
    3. Get the mapping again to verify that it was changed successfully:
      MetricsAdminService.getUserAttributesMapping()

      If the mapping did not update correctly, review the logs in the following location:

      app_server_root/profiles/AppSrv01/logs/Metrics_Server/

  4. Confirm that the URL for metrics is working: https://Connections_server/metrics.

What to do next

When you are ready to back up your metrics data, see Backing up and restoring data for Elasticsearch-based components.