Workflow Definition Operations

The workflow builder workspace is laid out with the workflow steps running from top to bottom in the middle (initially), the Workflow Definition dialog in a collapsible window on the right, and workspace controls at the bottom left. If you create several steps in a workflow or are working on a smaller browser screen, you may have more workflow steps than will fit in the configuration window. To navigate around the workspace and personalize it:

• Click and drag the workspace background to move the steps around the workspace. In this way you can reach steps at the top or bottom of the workflow that do not initially appear.

• Click the open button () to open the Workflow Definition dialog and the close button () to close the Workflow Definition dialog.

• Click the plus button with a circle around it () to add a new workflow step at that point in the workflow.

• Click the plus button in the lower left of the workspace () to zoom in on the steps.

• Click the minus button in the lower left of the workspace () to zoom out on the steps.

• Click the auto size button in the lower left of the workspace () to recenter and fit the steps to the window.

To add a new workflow definition or modify an existing one:

1. In the Management Portal, browse to Workflow > Workflow Definitions.

2. On the Workflow Definitions page:

   • Click Add from the top menu to create a new blank workflow definition.

   • Click Copy from either the top or right click menu to copy an existing workflow to create a new one.

   • Double-click or click Edit from either the top or right click menu, to modify an existing workflow definition.

   This will open the workflow in the workflow builder workspace with the Workflow Definition dialog open on the right.

   Note:  When you create a new workflow definition by copying an existing one, the word copy will be appended to the end of the definition name and the workflow key (e.g. template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. or certificate collection The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports).) will be cleared. Other data from the copied workflow will be retained.

3. In the Add/Edit Workflow Definition dialog on the Definition tab, enter a Name for your workflow.

   

   Figure 184: Create a New Workflow Definition

4. In the Description field, enter a description for the workflow definition.

5. In the Type dropdown, select the type of requests this workflow will handle. See Workflow Types for a description of each workflow type.

   Note:  This field cannot be modified on an edit.

6. Once you have selected a type, a key field will appear.

   • If you selected a type of Enrollment or Revocation, the key field is Template.

   • If you selected a type of Certificate Entered Collection or Certificate Left Collection, the key field is Certificate Collection.

   • If you selected a type of Certificate Entered Store or Certificate Left Store, the key field is Certificate Store Type with an optional Container field.

     Note:  If a certificate enters or leaves a certificate store with a certificate store type that has a matching workflow, that workflow will run only if there is a certificate store container match between the certificate store and the workflow. If the workflow is configured with no container, the workflow will run only if the certificate store that the certificate entered or left has no associated container.

   • If you selected a type of Expiration, the key field is Expiration Alert. You must have created the expiration alert with the Workflow option enabled before creating the workflow in order for the alert to appear in this key field (see Adding or Modifying an Expiration Alert).

   • If you selected a type of Key Rotation, the key field is Key Rotation Alert. You must have created the key rotation alert with the Workflow option enabled before creating the workflow in order for the alert to appear in this key field (see Adding or Modifying a Key Rotation Alert).

   • If you selected a type of Revocation Monitoring, the key field is Revocation Monitoring Alert. You must have created the revocation monitoring alert with the Workflow option enabled before creating the workflow in order for the alert to appear in this key field (see Adding or Modifying a Revocation Monitoring Location).

   To narrow the list of results in the search select field, begin typing a search string in the search field. Scroll down to locate your desired template, certificate collection, certificate store type, or alert. Templates that have been configured with a template friendly name will appear by friendly name.

   Note:   The key cannot be changed on an edit.

7. On the Workflow Configuration page, click the plus button in between two workflow steps where you want to add a new step. A new step box will be added below the plus that you clicked.

   

   Figure 185: Click Plus to Add a New Workflow Definition Step

   Tip:  To delete a step, click the X at the top right of the step box and confirm that you want to delete the step.
8. Click the new step box to load the step in the Add/Edit Workflow Definition dialog. If the dialog is not already open, clicking a step will open it, or you can open a step by clicking the open button () and then clicking the desired step to load it into the dialog.

9. In the Add/Edit Workflow Definition dialog on the Step tab in the General section, select a Step Type for the step in the search select. To narrow the list of results in the search select field, begin typing a search string in the search field. See Workflow Steps for a description of each step type.

   

   Figure 186: Select a Workflow Definition Step

   Note:  On an edit, if you change the workflow step type, you must also change the Unique Name. Changing the workflow step type without changing the unique name will result in an error similar to the following:

   System.Collections.Generic.KeyNotFoundException: The given key was not present in the dictionary

   Instead of changing both the workflow step type and unique name, you may be prefer to delete the step and create a new step of the desired type.

10. In the Add/Edit Workflow Definition dialog on the Step tab in the General section, enter a Display Name for the step. This name appears as the title of the step box on the workflow workspace page.

    

    Figure 187: Display Name is Step Name Title

11. In the Add/Edit Workflow Definition dialog on the Step tab in the General section, either accept the automatically generated Unique Name for the step or modify it. This name must be unique among the steps within the particular workflow. It is intended to be used as a user-friendly reference ID.

12. In the Add/Edit Workflow Definition dialog on the Step tab in the Workflow Step Execution Conditions section, click the Workflow Step Enabled toggle to enable or disable the workflow. It is enabled by default for steps that support conditions.

    Workflow Step Execution Conditions

    In the Workflow Step Execution Conditions section, click Add in the Optional Workflow Step Conditions for Execution section to create a new condition for the step. Conditions are Boolean (true/false) statements indicating whether the step should run and can be based on tokens.

    In the Condition Variable field, enter either a static value of true or false or a token that will have a value of true or false at the time the step is run. More than one condition may be added. If multiple conditions are used in the same step, all conditions must have a value of true at the time the step is evaluated to be run in order for the step to run. If any single condition evaluates to false, the step will not run. The step cannot be saved if a condition is entered with a value other than true, false, or a token.

    See the following example: Require Approval on Enrollment for Selected Domains

    Tip:  Tokens (a.k.a. substitutable special text) may be used in the condition field. Tokens use a variable in the workflow definition that is replaced by data from the certificate request, certificate, or certificate metadata Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In the context of Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. at processing time. For example, you can create a token in a PowerShell step that has a value of True or False based on something determined in the step and then evaluate that token in a subsequent require approval step to determine whether to execute the require approval step based on the results from the PowerShell step. Fields that support tokens are indicated with at the top right of the field. To use a token in a field, begin typing at the location where you want the token to appear, starting with $(. Once you have typed $(, a second ) will appear automatically along with a dropdown of available tokens to choose from. You may continue typing to narrow the values in the dropdown (e.g. type $(req to see only tokens that begin “req”).

    

    Figure 188: Tokens are Highlighted

    Note:  Not all workflow step types support conditions (see Workflow Steps).

13. In the Add/Edit Workflow Definition dialog on the Step tab in the Configuration Parameters section, configure parameters if appropriate for the workflow step.

14. Configuration Parameters

    The fields in the Configuration Parameters section will vary depending on the type of step you're configuring. See Workflow Definitions Configuration Parameters for in-depth information and examples of each configuration parameter A parameter or argument is a value that is passed into a function in an application. option.

    Note:  Not all workflow step types support configuration parameters (see Workflow Steps).

15. For Require Approval steps or custom steps requiring signals, in the Add/Edit Workflow Definition dialog on the Step tab in the Signals section, select one or more security roles (see Security Roles and Claims) in the Approval Status search select. To narrow the list of results in the search select field, begin typing a search string in the search field. Click the erase icon () to clear your selections.

    Users who hold the security role(s) selected here will be able to submit signals (e.g. approve requests) for this workflow.

    Tip:  Signals represent data used at the point in the workflow step where the workflow needs to continue based on user input. Here, you're configuring which users are allowed to provide that input.

    

    Figure 189: Signals Configuration for a Requires Approval Workflow Definition Step

    Important:  If all the security roles configured for a workflow step are deleted from Keyfactor Command, no users will be able to submit signals for workflow instances initiated with that workflow definition. To remedy this, update the workflow definition with one or more current security roles, re-publish it, and then restart any outstanding workflow instances.
16. On the Workflow Configuration page, click the plus button in between two workflow steps to add another step in the workflow or click Save Workflow to save the workflow with its current steps.

17. Before you can use the workflow, it must be published to activate it. Click the Publish button at the top of the workflow workspace to publish it immediately or return to the workflow definitions page and publish it later, if desired (see Publishing a Workflow Definition).

    Tip:  Clicking Publish automatically saves the workflow.
18. To close the workflow workspace and return to the workflow definitions page, click the Close button at the top of the workflow workspace.

An audit log entry is created when you add or edit a workflow definition (see Audit Log).

Workflow definitions can be either in an enabled state or a disabled state. When disabled, the workflow will be ignored and any action that might have triggered the workflow (e.g. an enrollment) will either not go through any workflow process or fall back to the default workflow, depending on the type of workflow. This behavior is similar to a workflow that has not yet been published. Suspended instances of a workflow that has been disabled cannot be retried either automatically by the Keyfactor Command Service or manually by a user. If a workflow is already in process when it is disabled, it will run to completion; disabling the workflow does not stop active instances of the workflow.

To disable or enable a workflow definition:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, select a workflow definition and click Disable or Enable from either the top or right-click menu.
3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

An audit log entry is created when you disable or enable a workflow definition (see Audit Log).

To delete a workflow definition:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, select a workflow definition and click Delete from either the top or right-click menu.
3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

An audit log entry is created when you delete a workflow definition (see Audit Log).

Workflow definitions are drafts that cannot be actively used until you take the step to publish them. This allows you to add new workflows or update existing ones without interrupting the flow of current activity. Then, once the workflow definition is complete and ready for use, you can activate it. This can be done on the workflow workspace page while editing the workflow (see Adding, Copying or Modifying a Workflow Definition) or from the workflow definitions page.

To publish a workflow definition from the workflow definitions page:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, select a workflow definition and click Publish from either the top or right-click menu.

3. On the Publish Workflow Definition dialog, select a version to publish if desired. The most recent version is the default.

   

   Figure 190: Select a Workflow Version to Publish from the Workflow Definitions Page

4. Click Publish to publish the selected version.

Alternately, publish a workflow definition from the workflow builder workspace:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, double-click or click Edit from either the top or right click menu, to open the workflow definition you wish to publish.
3. Click the Publish button at the top of the workflow workspace to publish it.

4. On the Publish Workflow Definition dialog, select a version to publish if desired. The most recent version is the default.

   

   Figure 191: Select a Workflow Version to Publish from the Workflow Workspace

5. Click Publish to publish the selected version.

Workflow definitions can be exported either from the workflow workspace page while viewing or editing the workflow (see Adding, Copying or Modifying a Workflow Definition) or from the workflow definitions page.

• Export a workflow for backup purposes.

• Export a workflow that you've fully configured and which you need to replicate and then import under another name to create a duplicate of it.

• Export a previous version of a workflow and import it as the current version to revert to using the previous version.

To export a workflow definition from the workflow workspace:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, click Edit from either the top or right click menu. This will open the workflow in the workflow workspace with the Workflow Definition dialog open on the right.
3. At the top of the workflow workspace, select a different Version of the workflow in the dropdown, if desired (see Workflow Versions).
4. At the top of the workflow workspace, click Export.
5. Browse to place the exported file on the local computer. The file will have an extension of .json.

To export a workflow definition from the workflow definitions page:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, select a workflow definition and click Export from either the top or right-click menu.

3. In the Export Workflow Definition dialog, select a Version and click Export.

   

   Figure 192: Export Workflow Definition

4. Browse to place the exported file on the local computer. The file will have an extension of .json.

Workflow definitions can be imported either to create a new workflow or to replace an existing workflow (e.g. to revert to a backup). When you import a workflow definition while editing an existing workflow definition, it will overwrite any changes you have made to the existing workflow since the last time it was published. Previously published versions of the workflow—including the most recent—will be retained. This is useful in cases where you want to export a previous version of a workflow and reimport it to make it the currently active version. This can be used to import a new workflow customized for you by the Keyfactor team.

To import a workflow definition:

1. In the Management Portal, browse to Workflow > Workflow Definitions.
2. On the Workflow Definitions page, click Add from the top menu to create a new workflow definition into which you will import, or Edit from either the top or right click menu, to import into an existing one to revert to a previous version. This will open the workflow in the workflow workspace with the Workflow Definition dialog open on the right.
3. At the top of the workflow workspace, click Import.

4. Browse to locate the workflow definition file you wish to import. Only files with an extension of .json will appear.

   

   Figure 193: Browse to Locate a Workflow Definition to Import

   Tip:  In order to be successfully imported, the file must be correctly formatted JSON with at least WorkflowType and Steps properties. The maximum file upload size is 2 MB.
5. Click Import to import the workflow definition and populate it into the workflow workspace.
6. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

7. In the workflow workspace, edit and save the workflow definition as needed as per Adding, Copying or Modifying a Workflow Definition. The following values will need attention:

   • Key (e.g. Template or Certificate Collection)

     When the workflow definition is imported into a new workflow definition, the key is cleared. You will need to set an appropriate key (see Adding, Copying or Modifying a Workflow Definition) on the imported workflow definition before saving. The key is not cleared for imports into workflows with existing published versions.

     This is done both to support export of workflow definitions from one environment and import into another where the key set likely would be different and to support copying of workflow definitions, since you can't have two definitions for the same key.

   • Secrets

     Some types of workflow steps include secret values (e.g. passwords). Secret values are not imported. If your workflow includes steps with secret values, these will need to be re-entered. This is true for imports into new workflow definitions and workflow definitions with existing published versions.

   • Roles for Signals

     Some types of workflow steps make use of signals to allow users to provide input to the workflow midstream (e.g. provide approvals). This requires configuration of security roles that define who is allowed to provide this input. These security role values are not imported. You will need to set appropriate security roles on any workflow steps that use signals before saving. This is true for imports into new workflow definitions and workflow definitions with existing published versions.

     This is done to support export of workflow definitions from one environment and import into another where the security role set likely would be different.

   Important:  If you're importing a copy of a workflow definition that already exists in Keyfactor Command and you want to save it as a separate copy, be sure to change the Name of the workflow before saving the imported workflow to avoid overwriting the existing version of the workflow.

When you open a workflow definition for editing, you will see the version of the workflow shown at the upper left of the workflow workspace in a dropdown. By default, the current version will be shown.

When you have the current, most recent, version of the workflow loaded, you will see several options in the button bar at the top of the workflow workspace (if you have appropriate permissions) and the Add/Edit Workflow Definition Dialog will be active. If you select an older version in the dropdown, only the Version, Export, Publish, and Close options will appear on the workflow workspace button bar and the Add/Edit Workflow Definition Dialog will be read only.

This option is designed to allow you to review or publish previous versions of a workflow or export them as backups or to be re-imported to be used as a base for generating new workflows. If you need to revert to an older version of a workflow and make edits to it, you will need to export it and re-import it as a different workflow.