Customizing value streams#
Customize the value-stream-name.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 view. The structure of the value stream is determined by the JSON file attached to the value stream, value-stream-name.json
. You can download the file, modify it, and then reattach it to the value stream by uploading it to UrbanCodeā¢ Velocity.
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 particles appearing on the stage.
- 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 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.
- Gates determine if objects meet user-defined criteria for a given context.
- The Metrics provides metric data to the value stream.
- The metricsBar section displays metrics data in the value stream Metrics 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": null,
"mappings": {
"priority": {
"Lowest": [
"Lowest"
],
"Low": [
"Low"
],
"Medium": [
"Medium"
],
"High": [
"High"
],
"Highest": [
"Highest"
]
}
},
"phases": [
{
"name": "Planning",
"stages": [
{
"name": "Backlog"
},
{
"name": "Queue"
}
]
},
{
"name": "Development",
"stages": [
{
"name": "In Progress"
},
{
"name": "In Review"
},
{
"name": "Merged"
}
]
},
{
"name": "Deployment",
"stages": [
{
"name": "DEV"
},
{
"name": "QA"
},
{
"name": "PROD"
}
]
}
],
"integrations": [],
"linkRules": []
}
Heading#
The heading properties are common to all value streams.
Property | Description |
---|---|
_id | Value stream identifier. The value is generated by UrbanCode Velocity. |
pipelineId | Identifier of the pipeline associated with the value stream. The value is generated by UrbanCode Velocity. |
tenantId | Tenant identifier. The value is generated by UrbanCode 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's 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 particles 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 easy-to-use metrics about value stream performance. The lead-time property reflects the elapsed-time from the start of a project until its 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 view Metrics 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 particles 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 particles appearing in a stage named "In progress" with a simple query similar to this one: "query":"issue.status="In Progress"
.
For a Git integration you might restrict particles appearing in a stage named "Merged" with a query similar to this one: "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 their 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.
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. To be considered valid, an object must fulfill the gate's DevOps query expression.
The following code fragment shows a typical gate.
{
"name": "Deployment",
"description": null,
"stages": [
{
"name": "Integrated",
"query": "issue.status=\"Integrated\"",
"description": null,
"wipLimit": null,
"gates": [
{
"name": "Unit Test",
"description": null,
"query": "metricDefinition=\"Unit Tests\" AND value.failed=0"
}
]
},
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 instance, to a source control tool
When links are established, you can access information about the linked tools from the affected particles 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 UrbanCode Velocity. 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.json
file.
Metrics Bar#
You can provide metrics data to value streams and display the data in charts and graphs attached to the stream. To enable the Metrics bar, add metricsBar
definitions to the value_stream_name.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.
Parent topic: Creating value streams