HCL Accelerate value stream management with Jira

This tutorial shows how to create a Jira integration and move a “dot” (unit of work) within the Value Stream or VSM (Value Stream Management) view in HCL Accelerate. Issue tracking cards are often where work begins for a development value stream. Further tutorials will show how HCL Accelerate combines data from many different tools across the entire value stream.

1. Set up Jira

1.1 Jira Instance

This tutorial requires a Jira instance that can be accessed and authenticated against using an API Token.

If you do not have a Jira instance readily available for this purpose, one option is to use a cloud Jira instance from https://www.atlassian.com. If you have not used Jira cloud before, you can sign up for a free trial.

1.2 Kanban Template (Optional)

If you are setting up a new Jira cloud instance, you can click “skip” for all setup questions. The Kanban classic template is a good choice for this tutorial, but not required (see next section).

1.3 Create a Jira Project

If you are creating a new project, take note that the project key will be used by the HCL Accelerate integration.

1.4 Jira Board

For this tutorial, your Jira board should have the five columns and status names listed below.

1. Backlog
2. Selected for Development
3. In Progress
4. In Review
5. Merged

You can edit your board directly or use the workflow editor (Settings>Issues>Workflows) and then apply this workflow to your board (project settings).

1.5 Create a Card

We will need at least one card for this tutorial. Create a card and add it to the “Backlog”.

2. Create a Jira integration

1. Navigate to the HCL Accelerate plugins page (Settings>Integrations>Plugins) and click “Add Integration” for the Jira plugin. You will be prompted to fill out the “Add Jira Integration” form.

2. Provide an integration name. The name used for the tutorial is “JKE Jira 1”.

3. Provide the Jira base URL. This depends on your instance of Jira. For cloud Jira it will be of the form “https://<custom-part-of-url>.atlassian.net”.

4. Provide the Jira username. This should be the email address used for your Jira login.

5. Provide authentication (API Token or oAuth). This tutorial uses an API Token from cloud Jira, which can be created at https://id.atlassian.com/manage/api-tokens. Create a token and provide it as the “Password” in HCL Accelerate (a regular account login password will not work in this case).

6. As stated above, since we are using an API Token for this tutorial, we will leave the four oAuth fields blank.

7. The last field specifies Jira projects for the integration. Use the Jira project “key”, not the full name. Recall that we could edit this key when creating the project.

8. Click “Add”. The integration should then be created and visible on the integrations page. You can click the integration dropdown to view details. Integration status and execution logs are also available.

NOTE: If an upgrade is available for your integration (indicated by a blue dot beside the name), then it’s a good idea to upgrade it now. Click on the three vertical dot “kebab” menu and select “Upgrade”.

3. Add the Jira Integration to a Value Stream

3.1 Create a New Value Stream

1. Navigate to the Value Streams page and click “Create”

2. Name your value stream and select a team for it. The workbook uses the name “JKE App1” and “Default Team”. A value stream description is optional.

3.2 Create a vsm.json file

Now that the integration has been added to HCL Accelerate, it can also be added to a specific value stream. HCL Accelerate value streams are highly configurable by downloading and uploading a value stream map (VSM) json file. An example VSM configuration is provided below. Copy and save this json to a .json file, then upload this file to configure the value stream.

Because this json content references your Jira integration by name, the integration must be named “JKE Jira 1” and must be “online” before uploading it (or else edit the json accordingly).

{ 
 "tenantId": "5ade13625558f2c6688d15ce", 
 "integrations": [{ 
  "name": "JKE Jira 1"
 }], 
 "phases": [{ 
   "name": "Planning", 
   "stages": [{ 
     "name": "Backlog", 
     "query": "issue.status=Backlog"
    }, 
  { 
     "name": "Selected For Development", 
     "query": "issue.status='Selected for Development' AND pr.status!=open"
    } 
   ] 
  }, 
  { 
   "name": "Development", 
   "stages": [{ 
     "name": "In Progress", 
     "query": "pr.status=open AND issue.status!='In Review'"
    }, 
    { 
     "name": "In Review", 
     "query": "issue.status='In Review' AND pr.status!=closed"
    }, 
    { 
     "name": "Merged", 
     "query": "pr.status=closed AND build.status!=success"
    }, 
    { 
     "name": "Build", 
     "query": "build.status=success AND deployment.env!=DEV"
    } 
   ] 
  }, 
  { 
   "name": "Deployment", 
   "stages": [{ 
     "name": "DEV", 
     "query": "deployment.env=DEV AND deployment.env!=QA"
    }, 
    { 
     "name": "QA", 
     "query": "deployment.env=QA AND deployment.env!=PROD"
    }, 
    { 
     "name": "PROD", 
     "query": "deployment.env=PROD"
    } 
   ] 
  } 
 ] 
}

Explanation of VSM JSON

Integrations Array

Integrations are included based on integration name. This tutorial uses the name “JKE Jira 1”, which should be changed if the integration is named differently.

"integrations":[

{

"name":"JKE Jira 1"

}

]

Phases and Stages

Value streams are organized as phases and stages. This json file provides phase and stage definitions for this tutorial. An important part of stages are stage queries which logically define whether a work item (dot) should be included in a stage or not. Recall that we defined our Jira statuses earlier. For instance, now we can map our Jira status of “Backlog” to an HCL Accelerate stage. Different Jira status values can be used for different stages by changing this configuration.

"phases":[

{

"name": "Planning",

"stages": [

{

"name": "Backlog",

"query": "issue.status=Backlog"

},    ...

4. Upload the vsm.json file.

If you have a brand-new value stream, then the upload button will be directly available.

After a vsm.json file has been uploaded, the value stream can be later modified with additional uploads via the tools and utilities dropdown option “Replace value stream map”.

5. Confirm the Dot

Wait for HCL Accelerate to synchronize data. The Jira issue that was placed in the Backlog should now appear in the value stream Backlog.

6. Stage Changes with Jira

After setting up the Jira integration in HCL Accelerate and using the vsm.json file to add the integration and stage queries to the value stream, the Jira card should be visible as a dot within the value stream. The issue status can be updated in Jira and the work item (dot) will change stages in HCL Accelerate.

1. Move the Jira card from “Backlog” to “Selected for Development”.

2. Allow time for HCL Accelerate to synchronize (usually ~1 minute max). The work item should moved to next stage “Selected For Development”.

3. Click on the dot to view details such as a link back to the Jira card as well as work item history.

Recap: Planning to Development, from Jira to GitHub

This section has focused on the planning phase of our value stream. In this case, we used Jira as our issue tracker. We created a Jira board and issue, setup a Jira integration, added that integration to a value stream, and observed how the value stream tracked Jira status changes throughout the planning phase. In theory, we could use Jira for every stage of our value stream; however, in practice, Jira cards are limited. We can do better than that! We can directly integrate with our other systems like GitHub and Jenkins to gain a real-time, fully automated, and accurate visualization of our work item’s journey. Next up is our development phase where we will add a GitHub integration and see how Jira and GitHub can work in tandem.