Workflow Definition Operations

A workflow definition describes when a workflow runs and provides the framework for how the workflow behaves. It defines the workflow type, associated keys, and high-level configuration settings, but it does not include the workflow steps themselves.

After a workflow definition is created, workflow steps are configured in a separate step using the workflow builder workspace. Together, the workflow definition and its configured steps determine how and when a workflow executes.

A typical workflow lifecycle includes the following stages:

• Create a workflow definition

• Configure the workflow steps

• Enable and publish the workflow

• Manage the workflow as needed, such as exporting or deleting it

The sections that follow describe each stage of this process in detail.

Use this section to add a new workflow definition, copy an existing definition to create a similar workflow of the same type, or modify an existing workflow definition.

To create a new workflow definition or to copy or modify an existing workflow definition:

1. Open a Workflow Definition

   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 as 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 definition dialog.

   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.

2. Give the Workflow a Name

   In the Add/Copy/Edit Workflow Definition dialog in the Definition Details section, enter a Name for your workflow.

   

   Figure 189: Create a New Workflow Definition

3. Add a Description

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

4. Choose a Workflow Type

   In the Workflow 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 a copy or edit.

5. Select Keys

   Workflow keys determine which requests or events a workflow definition applies to. Each key can be assigned to only one workflow definition, and key values are unique within a workflow type.

   A workflow definition can be associated with multiple keys. This allows the same workflow behavior to be applied to multiple requests or events of the same workflow type.

   Note:  Global workflow definitions for enrollment and revocation do not use configurable key values. Each global workflow definition has a single system-defined key with a null value. These are the only workflow definitions that do not require a key value.

   Once a workflow type is selected, action buttons appear in the keys configuration section. Click Add to define one or more keys for the selected workflow type. The available key values depend on the workflow type, as described below.

   • Certificate Entered Collection and Certificate Left Collection

     The key is the Certificate Collection.

   • Certificate Entered Store and Certificate Left Store

     The key is the Certificate Store Type.

   • Enrollment

     The key is the certificate Template and the optional subkey is the Enrollment Pattern.

   • Expiration

     The key is the Expiration Alert.

     The expiration alert must be created 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).

   • Key Rotation

     The key is the Key Rotation Alert.

     The key rotation alert must be created 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).

   • Revocation

     The key is the certificate Template.

   • Revocation Monitoring

     The key is the Revocation Monitoring Alert.

     The revocation monitoring alert must be created 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 a search select dropdown, begin typing in the input field. Matching results will appear as you type, and you can scroll to locate a record. Templates that have been configured with a template friendly name are displayed using that friendly name. The search function, however, matches only the template name, not the friendly name.

   Use Edit to update the selected key. Use Delete to remove the selected key from the workflow.

   Note:  Workflow keys are automatically removed from a workflow definition if the entity used to define the key is deleted from Keyfactor Command. If the workflow definition is associated with only one workflow key, the entity cannot be deleted. In this case, the user is notified that the workflow definition depends on the entity.

6. Continue to Configure Steps or Save

   At the bottom of the dialog, click Configure Steps to proceed directly to editing the workflow steps. Click Save to save the workflow definition without configuring steps at this time.

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

This section describes how to add, arrange, and configure workflow steps using the workflow builder workspace.

Configure Workflow Steps

Workflow steps are configured in the workflow builder workspace. You can open the workflow builder workspace in either of the following ways:

• From the workflow definition dialog:

  After creating, copying, or editing a workflow definition, click Configure Steps to proceed directly to step configuration.

• From the Workflow Definitions page:

  Locate the workflow definition in the list and click Configure Steps to open the workflow builder workspace for that workflow.

Both methods open the same workflow builder workspace, where workflow steps can be added and configured.

Working with the Workflow Workspace

The workflow builder workspace displays workflow steps arranged vertically in the center of the workspace. The step configuration panel appears in a collapsible window on the right, and workspace controls appear in the lower-left corner.

When a workflow contains many steps or is viewed on a smaller screen, not all steps may be visible at once. Use the following controls to navigate and adjust the workspace layout:

• Click and drag the workspace background to reposition the workflow steps and access steps that are not initially visible.

• Click the open button () to display the step configuration panel, or the close button () to collapse it.

• Click the plus button within the workspace () to add a new step at that point in the workflow.

• Click the zoom in button in the lower-left corner () to enlarge the workflow steps.

• Click the zoom out button in the lower-left corner () to reduce the size of the workflow steps.

• Click the auto size button in the lower-left corner () to recenter the workflow and fit all steps within the window.

Add Workflow Steps

Use the following steps to add workflow steps. The order in which steps run is determined by where each step is added in the workflow and cannot be changed after the step is created.

1. Add a Step

   In the workflow workspace, click the plus button 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 193: Click Plus to Add a New Workflow 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.

2. Open the Step Configuration Panel

   Click the new step box to load the step in the step configuration panel. If the panel is not already open, clicking a step will open it, or you can open a step by clicking the panel open button () and then clicking the desired step to load it into the panel.

3. Choose a Step Type

   In the General section of the step configuration panel, select a Step Type for the step in the search select dropdown. To narrow the list of results in a search select dropdown, begin typing in the input field. Matching results will appear as you type, and you can scroll to locate a record. See Workflow Steps for a description of each step type.

   

   Figure 194: Select a Workflow 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.

4. Add a Display Name

   In the General section, enter a Display Name for the step. This name appears as the title of the step box in the workflow workspace and at the top of the step configuration panel.

   

   Figure 195: Display Name is Step Name Title

5. Add a Unique Name

   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.

6. Add Step Execution Conditions

   In the Workflow Step Execution Conditions section, click the Workflow Step Enabled toggle to control whether the step runs. The toggle is set to allow execution by default for step types that support conditions.

   Click Add in the Optional Workflow Step Conditions for Execution section to create a new condition for the step. Conditions are Boolean (true or false) expressions that determine whether the step runs and can be based on tokens.

   In the Condition Variable field, enter one of the following:

   • A static value of true or false

   • A token that resolves to a Boolean value when the step runs

     When a token is used in the Condition Variable field (e.g., $(shouldRun)), the token is resolved to its text value at runtime. The step runs only if the resolved value is true.

     For predictable behavior, return true or false explicitly from the step that sets the variable.

   Multiple conditions can be added to a single step. When multiple conditions are present, all conditions must evaluate to true for the step to run. If any condition evaluates to false, the step does not run. The step cannot be saved if a condition value is not true, false, or a valid token.

   For an example, see 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 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 196: Tokens are Highlighted

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

7. Add Configuration Parameters

   In the Configuration Parameters section, configure parameters if appropriate for the workflow step.

   The fields in the Configuration Parameters section 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).

8. Add Signals

   The Signals section displays the signal inputs defined by the selected workflow step. Each signal group represents a type of input that the step can receive. When a workflow step is configured to require signals, workflow execution pauses at that step until the required signal input is submitted.

   Use this section to specify which users are permitted to submit signal input. Signal submitters can be defined by selecting one or more security roles or by entering a token that resolves to a security role. Users who belong to the specified security role (see Security Roles and Claims) or resolved token value can submit signal input for the step.

   Signals represent data evaluated when workflow execution resumes based on user input. The built-in Require Approval step uses approval decisions as signals. Custom workflow steps can define additional signal inputs and signal types, which are displayed in this section.

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

   

   Figure 197: Signals Configuration for a Requires Approval Workflow Step

   Important:  If all security roles configured for a workflow step are removed from Keyfactor Command, or if a configured token resolves to a role that no longer exists, no users will be able to submit signals for workflow instances initiated with that workflow definition. To resolve this condition, update the workflow definition to reference one or more valid security roles or a token that resolves to a valid role, republish the workflow, and then restart any workflow instances that are waiting for signals.

9. Add Further Steps as Needed and Save

   In the workflow workspace, click the plus button between workflow steps to add a step at that position. Steps run in the order in which they are added and cannot be moved later. Click Save Workflow to save the current set of workflow steps.

10. Publish the Workflow

    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 Publish a Workflow Definition).

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

Workflow definitions can be set to run or to be ignored. When a workflow definition is set to be ignored, it does not participate in processing. Any action that would normally trigger the workflow, such as an enrollment request, either bypasses workflow processing or uses a default workflow, depending on the workflow type. This behavior is similar to a workflow definition that has not yet been published.

Workflow instances that are waiting for processing cannot be retried while the workflow definition is set to be ignored. Workflow instances that are already in progress continue running to completion. Changing the availability of a workflow definition does not interrupt active workflow instances.

To set the availability of a workflow definition:

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

An audit log entry is created each time workflow definition availability is changed. See Audit Log for details.

To delete a workflow definition:

1. On the Workflow Definitions page, select a workflow definition and click Delete from either the toolbar or right-click menu.
2. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

An audit log entry is created each time a workflow definition is deleted. See Audit Log for details.

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 Workflow Step Configuration) or from the workflow definitions page.

To publish a workflow definition from the workflow definitions page:

1. On the Workflow Definitions page, select a workflow definition and click Publish from either the toolbar or right-click menu.

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

   

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

3. Click Publish to publish the selected version.

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

1. On the Workflow Definitions page, click Configure Steps from either the toolbar or right click menu, to open the steps for the workflow you wish to publish.
2. Click the Publish button at the top of the workflow workspace to publish it.

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

   

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

4. Click Publish to publish the selected version.

Workflows can be exported either from the workflow workspace page while viewing or editing the workflow (see Workflow Step Configuration) or from the Workflow Definitions page.

Common reasons to export a workflow definition include the following:

• Backup and archiving

  Export a workflow to retain a copy outside of the system for backup or record-keeping purposes.

• Reuse across environments

  Export a workflow to import it into another environment, such as moving a workflow from a test environment to a production environment.

To export a workflow from the Workflow Definitions page:

1. On the Workflow Definitions page, select a workflow definition and click Export from either the toolbar or right-click menu.

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

   

   Figure 200: Export Workflow Definition

3. 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 workspace:

1. On the Workflow Definitions page, click Configure Steps from either the toolbar or right click menu. This will open the workflow steps in the workflow workspace.
2. At the top of the workflow workspace, select a different Version of the workflow in the dropdown, if desired (see Workflow Versions).
3. At the top of the workflow workspace, click Export.
4. Browse to place the exported file on the local computer. The file will have an extension of .json.

Workflow definitions can be imported to create a new workflow or to replace an existing workflow, such as reverting to a previously exported backup. An import includes both the workflow definition and the associated workflow steps.

When you import a workflow while editing an existing workflow definition, the imported workflow definition and its steps replace the current draft configuration. Any unpublished changes are discarded. Previously published versions of the workflow are preserved and remain available for reference or selection.

This behavior is useful when restoring a workflow from a backup, promoting a workflow between environments, or importing a workflow customized for your environment by the Keyfactor team.

To import a workflow definition:

1. On the Workflow Definitions page, either add a new workflow definition or select an existing workflow definition to replace. See Add, Copy, or Modify a Workflow Definition for details.

   When a workflow definition is imported, the key from the import file is not applied. This supports importing workflows between environments, where available keys may differ, and prevents multiple workflow definitions from using the same key.

2. Select the workflow definition and click Configure Steps from the toolbar or right-click menu. The workflow opens in the workflow builder workspace.
3. At the top of the workflow builder workspace, click Import.

4. Browse to locate the workflow definition file to import. Only files with a .json extension are available for selection.

   

   Figure 201: Browse to Locate a Workflow Definition to Import

   Tip:  The import file must be valid JSON and include at least the WorkflowType and Steps properties. The maximum file size is 2 MB.

5. Click Import to load the workflow and populate its steps in the workflow builder workspace.

   Note:  When you export a workflow, the export includes the workflow definition, keys, and workflow steps. However, when the workflow is imported, only the workflow steps are imported. Configuration from the workflow definition and keys is not imported.
6. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

7. Review, update (see Workflow Step Configuration), and save the workflow steps as needed. Pay particular attention to the following:

   • Secrets

     Some workflow steps include secret values, such as passwords. Secret values are not retained when a workflow definition is transferred or restored. If a workflow includes steps with secret values, those values must be re-entered after the workflow definition and steps are loaded.

   • Roles for Signals

     Some workflow steps use signals to allow users to provide input while a workflow is waiting for that input, such as submitting approvals. This requires configuration that determines who is permitted to submit signal input. Approvers can be defined by selecting security roles directly or by using tokens that resolve to security roles.

     Token references are preserved when a workflow definition is transferred or restored. Explicitly selected security roles are not retained. After loading a workflow definition, review any steps that use signals and configure appropriate security roles or verify that configured tokens resolve to valid roles in the target environment.

When workflow steps are opened for editing, the workflow version is displayed in a dropdown at the upper left of the workflow builder workspace. By default, the most recent version is selected.

Only the current version of a workflow can be edited. When the current version is selected and the user has appropriate permissions, all workflow workspace actions are available and the step configuration panel is editable.

When an earlier version is selected from the dropdown, the workflow opens in a read-only state. In this state, only the Version, Export, Publish, and Close options are available, and the step configuration panel cannot be modified.

Workflow versions allow you to review earlier configurations, publish a previous version to make it the current version, or export a version for backup or reuse. To make changes based on an earlier version, publish that version to make it current, and then edit the workflow steps.