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 heading identifies the value stream.
  • The phases defines the value stream's phases and stages. It contains a query that filters the dots appearing in the stage.
  • The leadTimeChange is the quantity of time it takes a dot to progress from commit to production deployment. The metrics calculation is based on the date of the commit and date of the deployment into production. The lead time for changes metrics is a default metric added to all available value streams metrics bar.
  • The leadTime defines the lead-time metric. In general, lead-time reflects the time from the start of a project until its final disposition.
  • The cycleTime defines the cycle-time metric. In general, cycle-time reflects the time project elements take to resolve or complete.
  • The devcycleTime defines the development cycle-time metric. In general, dev-cycle time reflects the time project elements take to reach from development in-progress to development complete (before the PROD stage).
  • The mapping defines status levels for issue tracking systems.
  • The integration defines integration with external tools. The default stages are empty until you integrate tools into the value stream. You add your tools to a value stream by defining integration objects.
  • The Metrics provides metric data to the value stream.
  • The metricsBar section displays metrics data in the value stream Metric bar.
  • The linkRules defines relationships between integrated tools.

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,
          "showAlerts": false,
          "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"
  },
  "devCycleTime": {
    "start": "In Progress",
    "end": "In Review"
  },
  "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.

Table 1. Properties for stages object
Property Description
_id Value stream identifier. The value is generated by Velocity.
pipelineId Identifier of the pipeline associated with the value stream. The value is generated by Velocity.
tenantId Tenant identifier. The value is generated by Velocity.
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
        }
      ]
    },

Table 2. Properties for stages object
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.
showAlerts Alerts for change in status of dots. By default, the showAlerts property is set to false for Backlog and Production stages and true for any other stages. You can set the showAlerts property for any stages. Possible values are true and false.
showSpeed Defines whether to show the stage speed or not. By default, the showSpeed property is set to true, allowing you to view the stage speed through the visual representation of the stage circle. Click the Legend on the Value streams page to view the stage speed corresponding to the stage circle representation. You can set this property to false if you don't wish to see the stage speed. For more information about the stage circle speed, seeNavigating value streams.
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 time, cycle time, and dev-cycle time metrics

The lead time, cycle time, and dev-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",
      },
      "devCycleTime": {
        "start": "In Progress",
        "end": "In Review"
  },

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

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 Velocity. The data can originate from plugin 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 plugins, 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.
Figure 1. Error message
Error message