Customizing value streams#

Customize the json file to reflect your typical workflow.

When you create a value stream, default stages and phases are configured and displayed in the Value Stream tab. The structure of the value stream is determined by the json file attached to the value stream. You can customize the json file by using the following methods:

A value stream json file consists of the following areas:

The following code block shows the default value stream json file:

{
  "_id": "velocity-generated-value",
  "pipelineId": "velocity-generated-value",
  "tenantId": "velocity-generated-value",
  "description": null,
  "query": "",
  "phases": [
    {
      "name": "Planning",
      "description": "",
      "stages": [
        {
          "name": "Backlog",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Queue",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        }
      ]
    },
    {
      "name": "Development",
      "description": "",
      "stages": [
        {
          "name": "In Progress",
          "query": "",
          "description": "",
          "wipLimit": 10,
          "gates": null
        },
        {
          "name": "In Review",
          "query": "",
          "description": "",
          "wipLimit": 5,
          "gates": null
        },
        {
          "name": "Merged",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        }
      ]
    },
    {
      "name": "Deployment",
      "description": "",
      "stages": [
        {
          "name": "DEV",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "QA",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "PROD",
          "query": "",
          "description": "",
          "wipLimit": null,
          "gates": null
        }
      ]
    }
  ],
  "leadTime": {
    "start": "Backlog",
    "end": "PROD"
  },
  "cycleTime": {
    "start": "In Progress",
    "end": "PROD"
  },
  "mappings": {
    "priority": {
      "Lowest": [
        "Lowest"
      ],
      "Low": [
        "Low"
      ],
      "Medium": [
        "Medium"
      ],
      "High": [
        "High"
      ],
      "Highest": [
        "Highest"
      ]
    }
  },
  "integrations": [],
  "linkRules": [],
  "metrics": [
    {
      "name": "Work Item Type",
      "repeatEvery": "1 minute",
      "repeatAt": null,
      "metricDefinitionId": "WORK_ITEM_TYPE",
      "properties": {
        "query": null,
        "field": "issue.type"
      }
    }
  ],
  "metricsBar": null
}

Heading#

The heading properties are common to all value streams.

Property Description
_id Value stream identifier. The value is generated by HCL Accelerate.
pipelineId Identifier of the pipeline associated with the value stream. The value is generated by HCL Accelerate.
tenantId Tenant identifier. The value is generated by HCL Accelerate.
description Value stream description.
query A query that sets the scope to the entire value stream, not just a stage. If you share a Jira instance, for example, you might define a query that restricts the value stream to a single team's issues.

Phases#

The phases JSON array defines the value stream phases and stages. The single phases array for each value stream contains stages objects that define the stages for the containing phase. A phases array can contain any number of stages objects.

The following code fragment shows a Planning phase that contains stages named Backlog Scrum, and Selected for Development.

"phases": [
    {
      "name": "Planning",
      "description": "Planning stage",
      "stages": [
        {
          "name": "Backlog Scrum",
          "query": "issue.status=\"Backlog\"",
          "description": null,
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Selected For Development",
          "query": "issue.status=\"TO DO\" or issue.status=\"To Do\"",
          "description": null,
          "wipLimit": null,
          "gates": null
        }
      ]
    },
Property Description
name Stage name
query The DevOps query that defines which dots are displayed in the stage. In general, query parameters reference the tools integrated into the value stream. See the examples later in this topic.
description Stage description
wipLimit Represents the 'work in progress' limit. If the number of stage items exceeds the limit, a warning is displayed. To disable warnings, leave the value blank.
gates Gates determine if objects are valid for a given context. Valid objects are referred to as passing the gate; invalid ones are referred to as failing the gate. Valid objects can appear in value streams.

Lead- and cycle-time metrics#

The lead- and cycle-time properties provide useful metrics about value stream performance. The lead-time property reflects the elapsed-time from project start through final disposition. The cycle-time property reflects the time that individual project elements take to complete.

Configure the metrics by assigning a starting stage to the start property, and an ending stage to the end property. For example, if you set start to the Backlog stage, items are tracked when they move from the Backlog stage to the next stage. To carry the example forward, if you set end to the Deployed stage, items are finished when they move into the Deployed stage.

When you configure the metrics, the calculated values are displayed on the Value Stream tab in the Metric bar.

The following code example illustrates typical lead- and cycle-time configurations.


      "leadTime": {
        "start": "Backlog",       
        "end": "Deployed",
      },
       "cycleTime": {
        "start": "In Progress",       
        "end": "Merged",
      }, 

Mapping#

The mappings object defines status values for issue tracking systems. The following code example illustrates the default mappings:

"mappings": {
    "priority": {
      "Lowest": [
        "Lowest"
      ],
      "Low": [
        "Low"
      ],
      "Medium": [
        "Medium"
      ],
      "High": [
        "High"
      ],
      "Highest": [
        "Highest"
      ]
    }
  },

Query examples#

A DevOps query determines the dots that are displayed. A query at the value stream level filters, or scopes, the entire value stream. A query at the stage level filters the stage, and a query at the gate level filters the gate. Gates are discussed later in this topic.

In general, query parameters reference the tools integrated into the value stream or applications that belong to the associated pipeline. For a Jira integration you might restrict dots appearing in a stage named "In progress" with the following query:

"query":"issue.status="In Progress"

For a Git integration you can restrict dots appearing in a stage named "Merged" with the following query:

"query":"(pr.status=merged OR pr.status=closed) AND deployment.env!=DEV AND deployment.env!=QA AND deployment.env!=PROD and build.status!=success"

The following code fragment shows a planning phase with several stages and the corresponding queries.

{
      "name": "Development",
      "description": null,
      "stages": [
        {
          "name": "In Progress",
          "query": "issue.status=\"In Progress\" and build.status!=success",
          "description": null,
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Review",
          "query": "issue.status!=Done and pr.status=open",
          "description": null,
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Merged",
          "query": "(pr.status=merged OR pr.status=closed) AND deployment.env!=DEV AND deployment.env!=QA AND deployment.env!=PROD and build.status!=success",
          "description": null,
          "wipLimit": null,
          "gates": null
        },
        {
          "name": "Build",
          "query": "build.status=success AND deployment.env!=DEV AND deployment.env!=QA AND deployment.env!=PROD",
          "description": null,
          "wipLimit": null,
          "gates": null
        }
      ]
    },

For more information, see the DevOps query language reference.

Link rules define how integrated tools are related to one another. When tools are linked, objects that appear in a value stream provide information and links to the associated tools. You might link an issue tracking system, for example, to a source control tool

When links are established, you can access information about the linked tools from the affected dots in the value stream. In general, you can define linking rules for any integrated tools, and define multiple linking rules in a single value stream.

Metrics#

You can provide metric data to your value stream by querying the data integrated into HCL Accelerate. The data can originate from plug-in integrations, or REST API calls from external clients. DevOps Query Language (DQL) queries can be defined in the value_stream_name-vsm.json file.

You can use the default Work Item Type metric definition as a template for your metrics.

Metric bar#

You can provide metrics data to value streams and display the data in charts and graphs attached to the stream. To enable the Metric bar, add metricsBar definitions to the value_stream_name-vsm.json file attached to the value stream.

Integrations array#

You provide data from external tools to value streams by defining integration objects. For information about the supported plug-ins, see Creating value stream integrations.

Troubleshooting#

The figure below displays the error message when the value_stream_name-vsm.json file with invalid syntax is uploaded. The error message also displays the .json parse error position in the value_stream_name-vsm.json file. The system will generate similar error messages whenever an invalid value_stream_name-vsm.json file is uploaded.

Error message

Parent topic: Creating value streams