Workflow Instances Operations

A workflowClosed A workflow is a series of steps necessary to complete a process. In the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked. instance is created for every certificate enrollmentClosed Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA)., renewal, or revocation request you make through the Keyfactor Command Management Portal. The addition and removal of certificates from certificate collections can be configured to flow through workflow as well, but these create workflow instances only if configured. If a given request is made using a workflow definition (see Workflow Definitions) that has been configured with steps to require approvals for the request, run a PowerShell script, or make an APIClosed A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. request as part of the request flow, you may find yourself on the Workflow Instances page needing to manage the instances.

Workflow instance operations include:

Tip:  The following permissions (see Security Overview) are required to use this feature:

Workflow Instances: Read - All

To view a workflow instance:

  1. In the Management Portal, browse to Workflow > Workflow Instances.
  2. On the Workflow Instances page, double-click or click View from either the top or right click menu.

  3. The Instance Review dialog includes the following information:.

    Instance Section

    • Id

      A GUID indicating the Keyfactor Command reference ID for the instance.

    • Title

      A description for the action taking place in the step. For example:

      "KEYEXAMPLE\jsmith is enrolling for a certificate with CN=appsrvr12.keyexample.com."

      Or:

      "KEYEXAMPLE\mjones is revoking certificate with CN=appsrvr14.keyexample.com."

    • Status

      The current status message of the workflow instance.

      For example, for an enrollment that succeeded, the status message might be:

      Issued. The private key was successfully retained.

      For a workflow suspended and awaiting approval, the status message might be:

      Awaiting 2 more approval(s) from approval roles.

      For an enrollment that could not be submitted because a regular expression rule was not met, the status message might be something like:

      Pre-process failed: Invalid ST provided: Value must be one of California, Washington, Texas, New York, Illinois or Ohio.

      For an enrollment that failed due to rejection by the CA, the status message might be:

      The certificate request failed with the reason '[CA reason]'

      A workflow that failed at a PowerShell step might include the PowerShell error in the status message:

      Step 'Run PowerShell' failed: At line:5 char:19
+    [datetime]$Date
+                   ~
Missing ')' in function parameter list.
At line:7 char:1
+ )
+ ~
Unexpected token ')' in expression or statement.

    • Current Step

      The display name defined for the workflow instance step at which the instance has paused or stopped. For a successfully completed enrollment or revocation workflow, this will be either Keyfactor-Revoke or Keyfactor-Enroll. For a suspended workflow, this will be the custom step that is awaiting user input to continue the workflow. For a failed workflow, this will be the step at which the workflow failed.

    • Figure 190: Workflow Instance Review

    Current Data Section

    The data included in this section will vary depending on the request type, the status of the request, and the configuration of the workflow.

    For an enrollment, this section may include:

    For a revocation, this section may include:

    • Certificate Authority

      The certificate authority that that issued the certificate.

    • Certificate Id

      The Keyfactor Command reference ID for the certificate being revoked.

    • Comment

      A freeform reason or comment to explain why the certificate is being revoked.

    • Delegate

      A flag indicating whether delegation was enabled for the certificate authority that issued the certificate at the time revocation was requested (true) or not (false). For more information, see Authorization Methods Tab.

    • Effective Date

      The date and time when the certificate will be revoked.

    • Initiating User Name

      The name of the user who initiated the workflow in DOMAIN\\username format.

    • Operation Start

      The time at which the revocation workflow was initiated.

    • RevokeCode

      The specific reason that the certificate is being revoked. Possible values are:

    • Serial Number

      The serial number of the certificate being revoked.

    • Thumbprint

      The thumbprint of the certificate being revoked.

    • (Custom)

      Optional user-generated custom fields returning response data from PowerShell scripts or REST requests. These will be sorted alphabetically in among the other fields on the page.

    For a certificate that entered or left a certificate collectionClosed 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)., this section generally includes:

    • Certificate Id

      The Keyfactor Command reference ID for the certificate added to or removed from the certificate collection.

    • Initiating User Name

      The name of the user who initiated the workflow—generally Timer Service in this case.

    Figure 191: View a Workflow Instance

  4. Click Close to close the viewer.
Tip:  The following permissions (see Security Overview) are required to use this feature:

Workflow Instances: Read - All
Workflow Definitions: Read

The workflow definition as it existed at the time a particular workflow instance was generated may not necessarily match the current workflow definition. Using the Workflow Definition option on the Workflow Instances page, you can view the workflow definition for the selected instance as it was at the time the instance was initiated using the workflow workspace.

To view a workflow instance definition:

  1. In the Management Portal, browse to Workflow > Workflow Instances.
  2. On the Workflow Instances page, select a workflow instance and click View Definition from either the top or right-click menu.
  3. A read-only copy of the workflow definition at the time the instance was initiated will open in the workflow definition workspace. For information about using the workflow definition workspace, see Adding or Modifying a Workflow Definition.

If a workflow instance has been initiated in error or with a workflow definition that is not configured correctly, you have the option to stop the workflow instance.

Tip:  The following permissions (see Security Overview) are required to use this feature:

Workflow Instances: Read - All
Workflow Instances: Manage

To stop a workflow instance:

  1. In the Management Portal, browse to Workflow > Workflow Instances.
  2. On the Workflow Instances page, select a workflow instance and click Stop from either the top or right-click menu.
  3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.
Note:  Only workflow instances with a Status of Suspended can be stopped.

If a workflow instance has failed or been stopped to correct an issue, you may restart it to reinitialize the request after correcting whatever issue caused the failure (e.g. a PowerShell script failed or a CA was not responding on enrollment). You may also choose to use restart if a workflow instance was initiated with a workflow definition that had an incorrect definition that can easily be corrected—for example, the definition requires approval from just one user and that user is no longer available. In this case, you can update the definition, republish it, and then restart the workflow with the latest published version.

Tip:  The following permissions (see Security Overview) are required to use this feature:

Workflow Instances: Read - All
Workflow Instances: Manage
Workflow Definitions: Read

When you restart a workflow instance, it starts over from the beginning, not from the failure point.

To restart a workflow instance:

  1. In the Management Portal, browse to Workflow > Workflow Instances.
  2. On the Workflow Instances page, select a workflow instance and click Restart from either the top or right-click menu.
  3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.
Note:  Only workflow instances with a Status of Failed or Suspended can be restarted.

After restarting a workflow instance, you can view any differences between the original instance and the newly restarted instance by looking at the audit log record (see Audit Log Operations) for the workflow instance restart. The Related Entries in the audit log record do not include the original workflow instance that failed since restarting a workflow instance generates a new workflow instance.

Tip:  If user John Smith restarts a workflow instance that was originally started by user Martha Jones, the audit log message for this will look something like:
"The user 'KEYEXAMPLE\jsmith' restarted workflow instance, 'KEYEXAMPLE\mjones is enrolling for a certificate with CN=appsrvr12.keyexample.com.'"

In a scenario like this, the user listed at the top of the audit log details will be the user who restarted the instance, not the user who originally started the request.

Figure 192: View an Audit Log Entry for a Restarted Workflow Instance

If a workflow instance has failed, you may wish to remove the failed instance from the grid.

Tip:  The following permissions (see Security Overview) are required to use this feature:

Workflow Instances: Read - All
Workflow Instances: Manage

To delete a workflow instance:

  1. In the Management Portal, browse to Workflow > Workflow Instances.
  2. On the Workflow Instances page, select a workflow instance 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 instance (see Audit Log). Instances deleted as the result of system action (e.g. purging old records) are not audited.