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.

HCL Accelerate Jira

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).

HCL Accelerate Jira

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.

HCL Accelerate Jira

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).

HCL Accelerate Jira

1.5 Create a Card

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

HCL Accelerate Jira

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.

HCL Accelerate Jira

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

HCL Accelerate Jira

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”.

HCL Accelerate Jira

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

HCL Accelerate Jira

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).

HCL Accelerate Jira

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

HCL Accelerate Jira

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.

HCL Accelerate Jira

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”.

HCL Accelerate Jira

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”

HCL Accelerate Jira

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.

HCL Accelerate Jira

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"

},    ...

 

HCL Accelerate Jira

4. Upload the vsm.json file.

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

HCL Accelerate Jira

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”.

HCL Accelerate Jira

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.

HCL Accelerate Jira

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”.

HCL Accelerate Jira

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

HCL Accelerate Jira

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

HCL Accelerate Jira

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.

 

Comment wrap
Further Reading
article-img
Secure DevOps | June 9, 2022
Introducing HCL Accelerate v3.1
HCL Accelerate is continuing to see significant Value Stream Management adoption! With the release of HCL Accelerate 3.1, we brought significant features and performance improvements for our largest customers. If you are not far in your VSM journey, see below for some new onboarding features and guidance.
article-img
Secure DevOps | May 19, 2022
Accelerate on Kubernetes: Or, How I Learned to Stop Worrying and Love Automated Container Orchestration
Containerization is everywhere these days, and technologists are scrambling to adopt it in their organizations. But what exactly is it? Is it actually beneficial, or just a fad? What's the best way to leverage it? And most importantly, how does it relate to HCL Accelerate?
article-img
Secure DevOps | April 25, 2022
OpenShift Installation Updates
Starting from HCL Accelerate version 3.1.0, OpenShift Template installation will be removed. If you are an OpenShift user, do not worry, we will continue supporting OpenShift platforms through Helm charts.
Close
Filters result by
Sort:
|