Creating a guided experience for your template
This document outlines how to create a guided setup experience for your toolchain template. The guided experience takes users through the toolchain setup process with a series of steps that are presented in a logical order. A navigator on the left side of the page indicates where they are in the setup process and also provides navigation. The configuration options for the current step are displayed in the main area of the page.
The guided experience is simply an overlay on top of the classic toolchain setup rendering, and as such it utilises the artefacts of the classic definition, such as toolchain.yml. It is possible to revert to the classic rendering by setting the ENABLE_SETUP_WIZARD url param to false.
To begin you must increase the version to 3 and add a wizard object as a child of template.
The wizard object defines the structure of the guided experience. It can be defined inline, however it is recommended to use a separate file as this definition can become quite large. The example above uses wizard.yml to hold the definition.
The following outlines the required structure of a guided experience definition file.
---
version: '1'
messages:
$i18n: locales.yml
welcome:
description:
$ref: "#/messages/wizard.welcome.description"
git_accept:
label:
$ref: "#/messages/wizard.welcome.git.accept.label"
exclude:
service_labels:
- kp-vault
- hc-vault
| Property | Description |
|---|---|
| version | Currently the only supported version is 1. |
| messages | Holds the localisation strings for the guided experience and follows the same convention as in standard template definitions. |
| welcome | Allows specification of a description and a legal acceptance checkbox that are displayed on the Welcome step. If git_accept is omitted then the checkbox is not displayed. Markdown can be used for both the description and legal checkbox label. |
| exclude | Sometimes a classic toolchain definition in toolchain.yml may contain services that are not utilised in the guided experience. This results in unwanted integrations when the toolchain is created. Use the exclude.service_labels option to stop these unwanted services being loaded. |
Next comes the array of objects defining the steps that follow the Welcome step. The order of this array dictates the ordering presented to the user.
steps:
- name: app
title:
$ref: "#/messages/wizard.step.app.title"
form: wizard_app
advanced_form: app-repo
- name: inv
title:
$ref: "#/messages/wizard.step.inv.title"
form: wizard_inventory
advanced_form: inventory-repo
- name: issues
title:
$ref: "#/messages/wizard.step.issues.title"
form: wizard_issues
advanced_form: issues-repo
| Property | Description |
|---|---|
| name | A programmatic label to identify the step. This must be unique. |
| label | The label that appears in the navigator for the step. |
| title | The title that appears at the top of the main area of the step. |
| image_url | The image that is rendered beside the step title. If this is omitted the image from the form is used. |
| form | The form markup used to render the main content of the step. This can be a form or service defined in toolchain.yml or a form from the form section of this definition file. |
| advanced_form | Allows an alternative, more advanced, rendering form for this step. Setting this option allows the user to switch between basic and advanced modes using an Advanced Options toggle at the top of the step content. The intention is that the minimum set of required fields should be presented in basic mode, whereas all options should be presented in advanced mode. |
| indent_level | Indents the step label in the navigator on the left side of the page. This allows grouping of related steps under a common parent. This is an Integer property with 1 being the lowest indent value. |
| visible | A boolean or condition to show or hide the step. A condition object can be used here to show or hide the step when the parameters in other steps are changed at runtime by user input. The condition object is described later in this document. |
| conditions | An array of objects, each containing a condition and an array of actions which are executed sequentially when the condition evaluates to true. This allows the step to react to parameter changes by the user at runtime. Step conditions and actions are described in more detail later in this document. |
The summary step
It is highly recommended that the final step should be some form of summary step indicating to the user that they have successfully completed the configuration process. This step is treated as a special case, it is automatically given a Create button and the content is overridden with a warning if there are any configuration errors in the preceding steps.
Clicking the Create button in this state will take the user to the first step with a configuration error.
The form section of the guided experience configuration allows you to specify the layout for steps that do not get their rendering layout from a form or service in toolchain.yml.
form:
wizard_vault:
parameters:
key-protect: false
secrets-manager: true
hashicorp-vault: false
schema:
$ref: wizard_vault.json
wizard_app:
schema:
$ref: wizard_app.json
wizard_inventory:
schema:
$ref: wizard_inventory.json
This is an example of a condition object used in the visible property of a step.
visible:
condition:
any:
- form: wizard_vault
parameter: key-protect
value: true
The root of the condition object must contain a single operator which can be any, all or none. Below this is an array defining the parameters to be evaluated using the operator, and further nested operators if required. Each parameter definition must contain the name of the form parameter to be evaluated and the value to compare it against. Optionally you can define the form that holds this parameter, if this is omitted then the current step form is assumed.
In the above example visible will evaluate to true if the key-protect parameter from the wizard_vault form is equal to the value true.
Here's a more complicated example involving operator nesting.
visible:
condition:
any:
- form: wizard_vault
parameter: key-protect
value: true
- all:
- form: feature_flags
parameter: kp-mode
value: enabled
- form: feature_flags
parameter: allow-secrets
value: enabled
In this example visible will evaluate to true if the key-protect parameter from the wizard_vault form is equal to the value true OR the parameter kp-mode from the feature_flags form is equal to enabled AND the parameter allow-secrets from the feature_flags form is equal to enabled.
Here's an example of an actions array containing a single action.
actions:
- type: create-service
service_label: sm-vault
service_id: secretsmanager
parameters:
name: sm-compliance-secrets
There are six supported action types.
1. create-service
| Property | Description |
|---|---|
| service_label | A unique toolchain binding name for the new service. |
| service_id | The type of service to create, for example keyprotect. |
| parameters | Optional service specific parameters for the new service. |
2. delete-service
| Property | Description |
|---|---|
| service_label | The unique toolchain binding name of the service being deleted. |
| service_id | The type of service to delete, for example keyprotect. |
3. update-service
The update-service action can be used to change the type of an existing service.
| Property | Description |
|---|---|
| service_label | The unique toolchain binding name of the original service being modified. |
| service_id | The new type for the service. |
| parameters | Optional service specific parameters to be modified in the updated service. |
| keep_parameters | Optional array of parameter names that will be persisted for the service being modified. If this is omitted then all parameter values will be discarded from the original service. Note that the parameters specified in the parameters property will overwrite parameter values for the modified service, even if the same parameter is specified in keep_parameters. |
4. update-service-paramaters
The update-service-paramaters action can be used to update the parameters of an existing service.
| Property | Description |
|---|---|
| service_label | The unique toolchain binding name of the original service being modified. |
| service_id | The type of the service being modified. |
| parameters | The parameters to be updated. |
5. show-controls
The show-controls action can be used to show controls in guided experience steps. Here's an example of a show-controls action to show the control with the id cos-warning on the wizard_evidence form.
actions:
- type: show-controls
controls:
- form: wizard_evidence
ids: [cos-warning]
To show and hide controls using this mechanism the form metadata defining the controls must include a controlId. This is the id that should be included in the ids field of the show-controls action.
{
"type": "notification",
"display": {
"style": "warning",
"controlId": "cos-warning"
},
"visible": false
}
| Property | Description |
|---|---|
| controls | An array of control objects denoting which controls to show. Each control object must contain a form property and an array of ids targeting the controls to show. |
6. hide-controls
The hide-controls action is identical to show-controls except that it hides the specified controls.
Generally, the main area for a step follows the same format as used in standard template definitions. However there are some additions to enhance rendering in the guided experience.
Typically, advanced mode step content comes from a pre-existing service or form and is non customisable. However it is possible to show controls from the basic mode definition in advanced mode also. To do this set display.showInAdvancedMode to true and set the position of the control using display.advancedModePosition, which supports two options, top and bottom. The following is an extract from a basic mode form definition.
{
"type": "notification",
"display": {
"style": "warning",
"title": {
"$ref": "#/messages/wizard.evidence.cos.notification.title"
},
"subtitle": {
"$ref": "#/messages/wizard.evidence.cos.notification.subtitle"
},
"showInAdvancedMode": true,
"advancedModePosition": "bottom"
}
}
The above defines a notification control which is displayed in both basic mode and advanced mode. It will appear at the bottom of the step in advanced mode.
Take an example where an advanced mode form uses a validator to present a number of options in a dropdown control to the user. If you wish to present the same dropdown in basic mode you can use the display.mirrorAdvancedEnum property to present the same dropdown options as in advanced mode. Any changes to the advanced mode control by the validator or user input will be mirrored in basic mode.
{
"key": "repo_url",
"type": "select",
"display": {
"mirrorAdvancedEnum": true
},
"placeholder": {
"$ref": "#/messages/wizard.evidence.repoURLPlaceholder"
}
}
Above is the basic mode form definition for a dropdown control which mirrors a dropdown in advanced mode. Both the advanced and basic mode controls use the key repo_url to reference the underlying service parameter and render the options to the user.
Using an advanced welcome step configuration it is possible to allow the user to copy integration settings from an existing related toolchain. This will present the user with a dropdown in the welcome step where an existing toolchain can be selected. When the user selects a toolchain a series of conditions are evaluated and when satisfied their corresponding actions are executed.
Below is a screenshot of a welcome page with the link toolchains option enabled:
Here is an example the configuration needed:
welcome:
description:
$ref: "#/messages/wizard.welcome.description"
git_accept:
label:
$ref: "#/messages/wizard.welcome.git.accept.label"
link_toolchain:
enabled: true
notification:
style: info
subtitle:
$ref: "#/messages/wizard.welcome.linktoolchain.warning"
label:
$ref: "#/messages/wizard.welcome.linktoolchain.label"
conditions:
- condition:
any:
- source_exists: issues-repo
actions:
- type: copy-parameters
source: issues-repo
target: incident-issues-repo
- condition:
any:
- source_exists: kp-vault
actions:
- type: set-parameters
target: wizard_vault
parameters:
key-protect: true
- type: copy-parameters
source: kp-vault
target: kp-vault
parameters:
exclude: [name]
To enable this feature a link_toolchain object needs to be added to the welcome section. This object can contain the following properties:
| Property | Description |
|---|---|
| enabled | Must be set to true to enable the feature. |
| notification | Use this to show a notification control above the toolchain dropdown. You can customise the control using the style, title and subtitle options. |
| label | The text to be displayed directly over the toolchain dropdown control. |
| conditions | An array of condition objects similar to those used in steps, but with limited evaluation options and actions. condition The only supported condition is source_exists. From the example above, when the user selects a toolchain in the dropdown and the selected toolchain contains a service with the label issues-repo then the condition is satisfied and the corresponding actions will be executed.actions The only supported actions are copy-parameters and set-parameters. For copy-parameters the parameters with be copied from the source service in the selected toolchain to the target service in the toolchain that the user is setting up. You can also specify which parameters to include or exclude from the copy. In the example above all kp-vault parameters are copied with the exception of name.For set-parameters the specified parameters will be set on the target service in the toolchain that the user is setting up. |