Workflow Instances Operations

A workflow instance is created for every certificate enrollment, 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 API 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:

Viewing a workflow instance to review details of the instance
Viewing the workflow definition as configured for the particular workflow instance to understand the configuration at the time the instance was initiated
Stopping a workflow instance
Restarting a workflow instance after correcting a failure (e.g. the CA was not responding on an enrollment) or to introduce a different workflow definition
Deleting workflow instances to clean house

Depending on the page from which the workflow instance is viewed from, different data will be shown.

Instance Data Details

Instance Section Data

Name	Description
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 231: 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.

Enrollment

Name	Description
Subject	The distinguished name of the certificate.
CSR:Raw	The unparsed version of the certificate signing request generated for the certificate request.
CSR: Parsed	The parsed version of the certificate signing request generated for the certificate request. The CSR may include: Key Length The desired key size for the certificate. Key Type The desired key encryption for the certificate. C The country (two characters) of the certificate. ST The state or province of the certificate. L The city or locality of the certificate. OU The organizational unit of the certificate. O The organization of the certificate. E The email address of the certificate. CN The common name of the certificate. DNS Name A SAN value containing a DNS name. IP Address A SAN value containing an IP v4 or IP v6 address. RFC822 Name A SAN value containing an email address. Other name:Principal A SAN value containing a user principal name (UPN).
Additional Attributes	Values for any custom enrollment fields set on the certificate template to supply custom request attributes to the CA during the enrollment process.
CA Certificate	The certificate information returned from the CA for the certificate that is being requested, including: CA Certificate ID The ID assigned to the certificate by the CA. CA Request ID The ID assigned to the certificate request by the CA. Status The numeric status for the certificate as returned by the CA. Certificate Template The certificate template used to issue the certificate. Revocation Date The revocation date for the certificate as returned by the CA, if applicable (generally not for newly enrolled certificates). Revocation Reason The revocation reason for the certificate as returned by the CA, if applicable (generally not for newly enrolled certificates). Archived Key A flag indicating whether the certificate is configured for key archival on the CA (true) or not (false). Note: This field is populated only after the certificate has been issued by the CA.
CA Certificate Data: Raw	The certificate as returned by the CA in base-64 encoded binary format.
CA Certificate Data: Parsed	Issued DN The distinguished name of the certificate. Issuer DN The distinguished name of the issuer. Thumbprint The thumbprint of the certificate. Not After The date, in UTC, on which the certificate expires. Not Before The date, in UTC, on which the certificate was issued by the certificate authority. Metadata The metadata fields populated for the certificate.
CA Certificate Request	The certificate request information returned from the CA for the certificate that is being requested, including: CA Request ID The ID assigned to the certificate request by the CA. CSR The certificate signing request for the certificate request as returned by the CA. Status The status for the certificate as returned by the CA. Requester Name The requester name on the certificate request as returned by the CA. Note: This field is populated only if the certificate request fails at the CA level or requires manager approval at the CA level.
Certificate Authority	The certificate authority that will be used to enroll against in hostname\logical name format.
Custom Name	A custom friendly name for the certificate, if entered at enrollment.
Disposition Message	A message about the certificate request. Note: This field is populated only after the certificate request has been submitted to the CA.
Format	The desired output format for the certificate. A value of STORE indicates that the certificate is intended to be delivered into one or more certificate stores.
Include Chain	A flag indicating whether to include the certificate chain in the enrollment response (true) or not (false).
Initiating User Name	The name of the user who initiated the workflow in DOMAIN\username format.
Is PFX	A flag indicating whether the certificate enrollment type that initiated the workflow instance was PFX (true) or CSR (false).
Issuer DN	The distinguished name of the issuer.
Key Retention	A flag indicating whether the private key for the certificate resulting from the enrollment will be retained in Keyfactor Command (true) or not (false).
Key Status	A numeric value indicating the status of the private key retention for the certificate within Keyfactor Command. Possible values are: 0—Unknown 1—Saved 2—Expected 3—NoRetention 4—Failure 5—Temporary
Keyfactor Id	The Keyfactor Command reference ID for the certificate.
Management Job Time	The schedule for the management job to add the certificate to any certificate store(s).
Metadata	Values for the metadata fields that will be associated with the certificate once it is in Keyfactor Command.
PFX Password Secret Instance Id	The Keyfactor Command reference ID for the PFX password used to secure the PFX file on download.
Private Key Converter	An internally used Keyfactor Command field.
Renewal Certificate	Certificate Id - The Keyfactor Command reference ID of the certificate this certificate replaces on a renewal.
Renewal Certificate Data: Raw	The certificate that this certificate replaces on a renewal as returned by the CA in base-64 encoded binary format.
Renewal Certificate Data: Parsed	The certificate details for the certificate that this certificate replaces on a renewal, including: Issued DN The distinguished name of the certificate. Issuer DN The distinguished name of the issuer. Thumbprint The thumbprint of the certificate. Not After The date, in UTC, on which the certificate expires. Not Before The date, in UTC, on which the certificate was issued by the certificate authority. Metadata The metadata fields populated for the certificate.
SANs: Type	The subject alternate names defined for the certificate. Possible types that can be entered within Keyfactor Command are DNS Name, IPv4 Address, IPv6 Address, User Principal Name, and Email. Within each type is a list of entries for that type shown with a key name of the entry number and the actual value. For example, if you had two DNS SANs, the DNS Name section would look something like: Entry 1: myfirstsan.keyexample.com Entry 2: mysecondsan.keyexample.com
Serial Number	The serial number of the certificate.
Stores	The certificate stores to which the certificate should be distributed, if applicable.
Template	The template that was used when requesting the certificate.
Thumbprint	The thumbprint of the certificate.
(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.

Revocation

For a revocation, this section may include:

Name	Description
Certificate Authority	The certificate authority 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 Delegation Section.
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: -1—Remove from Hold 0—Unspecified 1—Key Compromised 2—CA Compromised 3—Affiliation Changed 4—Superseded 5—Cessation of Operation 6—Certificate Hold 7—Remove from CRL. Only valid in the case that a cert is already on a CRL in a manner that it can be removed, such as Certificate Hold.
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.

Certificate Entered Collection and Certificate Left Collection

For a certificate that entered or left a certificate collection, this section generally includes:

Name	Description
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.

Operations

Viewing a Workflow Instance

Tip: The following permissions (see Security Roles and Claims) are required to use this feature:

/workflows/instances/read/

To view a workflow instance:

In the Management Portal, browse to Workflow > Workflow Instances.
On the Workflow Instances page, double-click or click View from either the top or right click menu.
The Instance Review dialog includes the following information:.

Figure 232: View a Workflow Instance
Click Close to close the viewer.

Viewing a Workflow Instance Definition

Tip: The following permissions (see Security Roles and Claims) are required to use this feature:

/workflows/instances/read/

/workflows/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:

In the Management Portal, browse to Workflow > Workflow Instances.
On the Workflow Instances page, select a workflow instance and click View Definition from either the top or right-click menu.
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, Copying or Modifying a Workflow Definition.

Stopping a Workflow Instance

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 Roles and Claims) are required to use this feature:

/workflows/instances/read/

/workflows/instances/manage/

To stop a workflow instance:

In the Management Portal, browse to Workflow > Workflow Instances.
On the Workflow Instances page, select a workflow instance and click Stop from either the top or right-click menu.
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.

Restarting a Workflow Instance

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 Roles and Claims) are required to use this feature:

/workflows/definitions/read/

/workflows/instances/read/

/workflows/instances/manage/

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

To restart a workflow instance:

In the Management Portal, browse to Workflow > Workflow Instances.
On the Workflow Instances page, select a workflow instance and click Restart from either the top or right-click menu.
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 233: View an Audit Log Entry for a Restarted Workflow Instance

Deleting a 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 Roles and Claims) are required to use this feature:

/workflows/instances/read/

/workflows/instances/manage/

To delete a workflow instance:

In the Management Portal, browse to Workflow > Workflow Instances.
On the Workflow Instances page, select a workflow instance and click Delete from either the top or right-click menu.
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.

Version v24.4

On this page: