HCL Accelerate with HCL Compass

HCL Accelerate, our value stream management platform, can integrate with HCL Compass, our change and issue management platform, to provide value stream management of work items and integration with other systems, including source control, builds, and deployments. HCL Compass is a flexible tool that allows mapping of work item status in ways that other issue trackers do not. This flexibility can be useful within a value stream map where it provides different ways for work items to be queried.

Requirements

• HCL Accelerate version 2.0.0 or later
• HCL Compass server version 1.0.1.00 or later

1. Ensure that the HCL Compass Plugin is Installed

In HCL Accelerate, navigate to “Settings” –> “Integrations” –> “Plugins”. If the HCL Compass plugin is not already installed, install it now.

Option A – The HCL Compass plugin should be listed with available plugins. Simply click “Install” to install the plugin.

Option B – You can also manually pull the image and load/install it into HCL Accelerate as follows:

1. Run the command docker pull urbancode/ucv-ext-compass:<version number> (ex. docker pull urbancode/ucv-ext-compass:1.0.9) from a computer with access to dockerhub.
2. (This step may not be required) Transfer the docker image to your instance of Docker running HCL Accelerate.
3. Click “Load Plugin”. Provide the plugin image name and version formatted as “ucv-ext-compass:<version number>” (ex. urbancode/ucv-ext-compass:1.0.9)

2. Create a HCL Compass Integration

2.1 Create an Access key

You will need an HCL Accelerate “User Access key”, so we will create one before proceeding. Navigate to “Settings” –> “My Profile” and click “Create” to create a key. Name it something like “HCL Compass workbook”. Copy this key and save it for the integration.

2.2 Create the Integration

Navigate to “Settings” –> “Integrations” –> “Plugins” and Click “Add Integration“. Provide the necessary properties to create a HCL Compass integration:

2.2.1 Integration Properties

After clicking on “Add integration” fill out the create integration form as shown below. The “Compass Timezone” and “Resync” fields might not be required in future versions.

2.2.2 Custom Mapping Fields

Custom mapping fields are not necessarily required since mapping can be derived from Compass json data. However, custom mapping fields must be provided either from Compass configuration or else from the HCL Accceleratre create integration form. The create integration form will take precedence.

HCL Compass custom field mapping is used to map HCL Compass field names to normalized HCL Accelerate field names. The format is an array of objects, each object specifies “type” and “fieldMapping”. “fieldMapping” is itself an object that must contain the fields shown below. Note that mapping is by type as specified by the record_type field, so a new mapping object is required for every type in your database.

Compass json: If json data is being provided from Compass it may use name instead of type to define the kind of issue.

Custom Field Mapping Object Properties

Example Custom Filed Mapping JSON

[{
 "type": "<entry type>",
 "fieldMapping": {
  "name": "<HCL Compass Field Name>",
  "creator": "<HCL Compass Field Name>",
  "owner": "<HCL Compass Field Name>",
  "priority": "<HCL Compass Field Name>",
  "description": "<HCL Compass Field Name>"
 }
}]

All five HCL Accelerate fields must be mapped. If they are not mapped they will have values of undefined. Example text is shown below. This would be entered directly into the “Custom Field Mapping” form field.

[{
 "type": "Defect",
 "fieldMapping": {
  "name": "Owner",
  "creator": "Submitter",
  "owner": "Owner",
  "priority": "Priority",
  "description": "Description"
 }
}]

2.3 Verify the Integration

Confirm that the integration was created and added to the integrations list. The status should be “Online” and green. You can view integration details by clicking the dropdown arrow on the left of the row. You can view integration logs and edit configuration by clicking the vertical dots on the right of the integration row.

Running the Integration: Data between the HCL Compass server and HCL Accelerate is synchronized by the syncHCL CompassIssueEvent scheduled event which runs every five minutes by default. A data sync can be forced by toggling disable/enable on the integration.

Example Logs

3. Add the Integration to a value stream

3.1 Create a new Value Stream

Navigate to “Value Stream” and click “Create”. Provide a value stream name and team, then click “Save”.

3.2 Use a vsm.json file to add the integration

3.2.1 Download a vsm.json File

From a new value stream, click “Download sample” to download a vsm.json file. This file is used to configure value streams. In fact, all value stream configuration can be done as a single step at this point; however, you will likely repeat this download/upload process many times as you experiment with your value stream configuration.

For an already configured value stream, a vsm.json file can be downloaded from the tool icon as shown below:

3.2.2 Add the Integration to the json Configuration

Open the vsm.json file, search for the “integrations” property. This should be an empty array for a new value stream. The HCL Compass integration can be added by name as shown below (named “compass-1” in this example). Save the file when done.

"integrations": [
 {
  "name":"compass-1"
 }
]

3.2.3 Upload the vsm.json File

From the value stream, click “Upload” (or “Replace value stream map” from the tool dropdown) to upload the modified vsm.json file. The new configuration should take effect and add the integration. You can confirm that the integration was added by downloading the vsm.json file and inspecting the “integrations” property, which should now contain integration details. You will still need to configure stage queries before seeing any dots.

4. HCL Compass Data within a Value Stream

4.1 Stage Queries and DevOps Query Language

DevOps Query Language (DQL) is an essential part of any HCL Accelerate value stream. Dots can be directly queried from the value stream; however, dots will only appear in your value stream if they match a stage query. Stage queries themselves use DQL and are defined within the vsm.json file. Therefore, to visualize you data the first thing to do is use DQL to define a stage query within your vsm.json file, upload that file to configure our value stream, and confirm that you can in fact see dots from our HCL Compass integration.

DQL CheatSheet

• Conjunction: AND or and
• Disjunction: OR or or
• Double quotes: "" (required for values with spaces)
• Equality: =
• Inequality: !=
• Greater than: >
• Less than: <
• Order of operations grouping: ()
• Case Sensitive (issue.rawIssue is not the same as issue.RAWissue)

4.1.1 Configuring Phases, Stages, and Stage Queries

A vsm.json configuration includes multiple stages. These are defined as objects inside of a stages array, which in turn belongs to a phase object within a phases array. You can modify these phases and stages to match your own process. All stage queries are empty by default.

1. Download the vsm.json file.
2. Modify the json to contain stage queries.
3. Upload the modified vsm.json file

Example DQL query being added to the default “Backlog” stage.

"stages": [
 {
  "name": "Backlog",
  "query": "issue.status=Submitted",
  "description": "",
  "wipLimit": null,
  "gates": null
 },

(Optional) Feel free to add/remove phases, stages, and stage queries for your entire value stream. A simple example is shown below:

"phases": [
  {
   "name": "Pre-Work",
   "description": "Preparing Defects for Work",
   "stages": [
    {
     "name": "Submitted",
     "query": "issue.status=Submitted",
     "description": "",
     "wipLimit": null,
     "gates": null
    }
   ]
  },
  {
   "name": "In progress",
   "description": "Work Process to Resolve Defects",
   "stages": [
    {
     "name": "Opened",
     "query": "issue.status=Opened",
     "description": "",
     "wipLimit": 10,
     "gates": null
    }
   ]
  },
  {
   "name": "Post-Work",
   "description": "Defect Tracking after Work Completed",
   "stages": [
    {
     "name": "Resolved",
     "query": "issue.status=Resolved",
     "description": "",
     "wipLimit": null,
     "gates": null
    },
    {
     "name": "Closed",
     "query": "issue.status=Closed",
     "description": "",
     "wipLimit": null,
     "gates": null
    }
   ]
  }
 ]

Be aware that if you start deleting, adding, and rearranging stages you will also need to update your lead time and cycle time definitions, since they are defined according to stage names.

"leadTime": {
 "start": "Submitted",
 "end": "Closed"
},
"cycleTime": {
 "start": "Opened",
 "end": "Resolved"
}

After configuring you value stream, you should see dots displayed within your stages.

Click on a dot to view its details. This will include HCL Compass data, as well as linked data if defined (see section 4.2.1 about link rules).

4.1.2 Interactive DQL Queries

After uploading a valid stage query, you should now see HCL Compass issues within your value stream. You can dynamically query these issues from the value stream search bar.

4.1.3 HCL Compass DQL Queries

HCL Compass queries are based on issue objects. These objects have standardized HCL Accelerate fields. Some standard fields are automatically mapped, while others are defined by custom mapping. Aside from standard fields, the HCL Compass issue object also contains a rawIssue field that is unique to HCL Compass.

Automatically Mapped Fields

The following fields are automatically mapped and do not require custom mapping.

• issue.id (from id)
• issue.status (from State)
• issue.url (from serverUrl and viewURL)
• issue.created (determined from history)
• issue.lastUpdated (determined from history)
• issue.type (from record_type)
• issue.project.name (this refers to the HCL Compass project name as the database name (project.id and project.key are also available))

Custom Mapped Fields

Recall that we mapped HCL Compass values to the following pre-defined fields in HCL Accelerate. These properties are directly accessible from the DQL issues object, so the following are valid queries…

• issue.type=someValue
• issue.name=someValue
• issue.creator=someValue
• issue.owner=someValue
• issue.priority=someValue
• issue.description=someValue

rawIssue Fields

The rawIssue field allows access to non-standard fields within your HCL Compass data. For instance, if your HCL Compass data has a field named customer, then the DQL to find “customer A” would be issue.rawIssue.customer="customer A" (beta versions might require longer syntax and a two-part query for rawIssue fields. For example, issue.rawIssue.fields.value="customer A" and issue.rawIssue.fields.name="customer", which only guarantees that the value and field are both present, but does not necessarily guarantee that “customer A” is the value for the “customer” field.)

History Queries (advanced)

Issue history queries can be a powerful tool. For example, given the search criteria “I want to find all items where “user A” changed “property B” from true to false within the last year” – a DQL query for this might be constructed as follows:

issue.history.timestamp<1609459200000 AND
issue.history.timestamp>1577836800000 AND
issue.history.content.user="user A" AND
issue.history.content.field="status" AND
issue.history.content.from="Submitted" AND
issue.history.content.to="opened"

Typical issue history properties are as follows:

• issue.history.timestamp (unix epoch time stamp in milliseconds)
• issue.history.content.user
• issue.history.content.field
• issue.history.content.from
• issue.history.content.to

4.2 Additional Value Stream Configuration

Aside from DQL, HCL Compass data ties into other parts of your value stream such as priority mapping and link rules as shown below.

4.2.1 Priority Mapping

In addition to stage queries, you may also want to map your HCL Compass priority values to pre-defined HCL Accelerate priority values. These can be configured from a vsm.json file under a "mappings":{priority[]} array as shown below.

"mappings": {
 "priority": {
  "Lowest": [
   ""
  ],
  "Low": [
   "Priority 3-Normal Queue"
  ],
  "Medium": [
   "Priority 2-Give High Attention"
  ],
  "High": [
   "Priority 1-Resolve Immediately"
  ],
  "Highest": [
   ""
  ]
 }
}

4.2.1 Link Rules

HCL Accelerate uses link rules to link separate integration data into single dots. An example link rule is shown below. Exact implementation will depend on your process and integration data.

"linkRules": [
 {
  "fromIntegrationName": "Another Integration",
  "toIntegrationName": "compass-1",
  "fromField": "pr.name",
  "toField": "issue.name",
  "pattern": "([A-Z]+-[0-9]+)"
 }
]