Documentation Suite v25.1

Submit Search

GET Workflow Instances Instance ID

The GET /Workflow A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store./Instances/{instanceId} method is used to retrieve the initiated workflow with the specified instance GUID. Both in progress and completed workflows will be returned. This method returns HTTP 200 OK on a success with details about the workflow instance.

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

/workflows/instances/read/

/workflows/instances/read/pending/

/workflows/instances/read/mine/

Users with /mine/ or /pending/ will only be able to retrieve the workflow instances created by them (/mine/) or assigned to them (/pending/) unless they also have the higher level just /read/.

Table 983: GET Workflow Instances {instanceId} Input Parameters

Name	In	Description
instanceId	Path	Required. A string indicating the Keyfactor Command reference GUID of the workflow instance to retrieve. Use the GET /Workflow/Instances method (see GET Workflow Instances) to retrieve a list of all the workflow instances to determine the GUID. Note that the integer workflow IDs (returned with GET /Workflow/Instances/{instanceId}) cannot be used with the API; only the GUID from GET /Workflow/Instances can be used in this case.

Name

Description

instanceId

Path

Required. A string indicating the Keyfactor Command reference GUID of the workflow instance to retrieve.

Use the GET /Workflow/Instances method (see GET Workflow Instances) to retrieve a list of all the workflow instances to determine the GUID. Note that the integer workflow IDs (returned with GET /Workflow/Instances/{instanceId}) cannot be used with the API; only the GUID from GET /Workflow/Instances can be used in this case.

Table 984: GET Workflow Instances {instanceId} Response Data

Name Description

Id A string indicating the Keyfactor Command reference GUID of the workflow instance.

Status

A string indicating the current status of the workflow instance. The possible statuses are:

CanceledForRestart
Complete
Failed

Rejected
Running
Suspended

Current Step ID A string indicating the Keyfactor Command reference GUID of the workflow instance step.

Status Message

A string indicating the current status message for the workflow instance. Possible status messages vary and may include:

Access is denied
Awaiting # more approval(s) from approval roles.
Either the credentials are invalid, or the CA on [CA hostname] is not running
Issued
Issued. The private key was successfully retained.
Post-process Failed: [Message indicating reason for failure generally from the CA]
Pre-process failed: [Message indicating details of the failure]
Revoked
Step ‘Keyfactor-Enroll’ failed: [Message indicating details of the failure]
Step ‘Keyfactor-Revoke’ failed:[Message indicating details of the failure]
Step [custom step name] failed: [Message indicating details of the failure]
Taken Under Submission. The certificate template requires manager approval, and is marked as pending.
Workflow rejected by user with Id #.

Signals

An array of objects containing the data used at the point in the workflow step where the workflow needs to continue based on user input. These will vary depending on the type of workflow and the type of step. Show RequireApproval signal details.

Value

Description

SignalName

A string indicating the name of the signal. For a RequireApproval step, this is ApprovalStatus.

StepSignalId

A string indicating the Keyfactor Command reference GUID of the signal in the step.

SignalReceived

A Boolean indicating whether a signal (input) has been received from at least one end user (true) or not (false).

For a RequireApproval workflow that requires approval from more than one user, the SignalReceived may be true while the workflow instance still has a Suspended status indicating further input is needed.

Definition

An object containing the workflow definition. Show workflow definition details.

Name	Description
Id	A string indicating the Keyfactor Command reference GUID of the workflow definition.
Display Name	A string indicating the display name defined for the workflow definition.
Version	An integer indicating the version number of the workflow definition.
Workflow Type	A string indicating the type of workflow definition. The currently supported types are: CertificateEnteredCollection Initiates a workflow instance when a certificate is identified that newly meets the query criteria of a certificate collection. For example, when a certificate discovered on an SSL scan becomes part of the Weak Keys collection, an email message can be generated notifying the PKI administrators that a new certificate with a weak key has been discovered. The workflow is initiated by two automated tasks that Keyfactor Command runs periodically. The first runs against your collections to identify certificates that newly meet the query criteria of each certificate collection. Certificates are added to a temporary table from which workflows of this type draw. Certificates are added for all collections regardless of whether they have active workflows. The second reads the temporary table and generates workflow instances for any active workflows of this type. The temporary table is cleared each time the first task runs. Each of these tasks runs every 10 minutes by default and the schedules for them are not end-user configurable. If the task has run to create the temporary table of certificates that newly meet the query criteria of the specified certificate collection but a workflow has not yet run for the given collection—perhaps it is disabled or has not yet been created—there is a window of time (until the temporary table is cleared) during which if a workflow is created or enabled for the certificate collection, the user creating or enabling the workflow will receive a warning message indicating that the workflow will run multiple times and asking the user for confirmation to continue. The user must enter RUN followed by the number of workflow instances that will be initiated to continue. Figure 634: Warning on Save for Certificate Entered or Left Collection Workflow CertificateLeftCollection Initiates a workflow instance when a certificate is identified that no longer meet the query criteria of the specified certificate collection. For example, when a certificate in the Web Server Certificates collection disappears, a REST request can be made to open a support ticket request to investigate the removal of a web server certificate. The workflow is initiated by two automated tasks that Keyfactor Command runs periodically. The first runs against your collections to identify certificates that no longer meet the query criteria of each certificate collection. Certificates are added to a temporary table from which workflows of this type draw. Certificates are added for all collections regardless of whether they have active workflows. The second reads the temporary table and generates workflow instances for any active workflows of this type. The temporary table is cleared each time the first task runs. Each of these tasks runs every 10 minutes by default and the schedules for them are not end-user configurable. If the task has run to create the temporary table of certificates that no longer meet the query criteria of the specified certificate collection but a workflow has not yet run for the given collection—perhaps it is disabled or has not yet been created—there is a window of time (until the temporary table is cleared) during which if a workflow is created or enabled for the certificate collection, the user creating or enabling the workflow will receive a warning message indicating that the workflow will run multiple times and asking the user for confirmation to continue. The user must enter RUN followed by the number of workflow instances that will be initiated to continue. CertificateEnteredStore Initiates a workflow instance when a certificate has been added to or has entered a certificate store for the specified certificate store type and optional certificate store container. For example, when a certificate appears in a trusted certificate store, a REST request can be made to check the support ticketing system for a change request, and the workflow can then generate an email message notifying the PKI administrators that a new certificate has appeared in a trusted store if a change request is not found. The workflow is initiated by two automated tasks that Keyfactor Command runs periodically. The first runs against your certificate store types to identify certificates that have been added to or have entered a certificate store for the specified certificate store type and optional certificate store container. Certificates are added to a temporary table from which workflows of this type draw. The second reads the temporary table and generates workflow instances for any active workflows of this type. The temporary table is cleared each time the first task runs. Included in the workflow information are the certificate ID, certificate store ID, and certificate store container ID. If the certificate store is not in a container, the container ID will be -1. Each of these tasks runs every 10 minutes by default and the schedules for them are not end-user configurable. CertificateLeftStore Initiates a workflow instance when a certificate has been removed from or has left a certificate store for the specified certificate store type and optional certificate store container. For example, when a certificate on your F5 device disappears, a REST request can be made to open a support ticket request to investigate the removal of a certificate from the device. The workflow is initiated by two automated tasks that Keyfactor Command runs periodically. The first runs against your certificate store types to identify certificates that have been removed from or have left a certificate store for the specified certificate store type and optional certificate store container. Certificates are added to a temporary table from which workflows of this type draw. The second reads the temporary table and generates workflow instances for any active workflows of this type. The temporary table is cleared each time the first task runs. Included in the workflow information are the certificate ID, certificate store ID, and certificate store container ID. If the certificate store is not in a container, the container ID will be -1. Each of these tasks runs every 10 minutes by default and the schedules for them are not end-user configurable. Enrollment (Including Renewals) The workflow is initiated by enrollment for a new or renewed certificate. Steps during the workflow can be used to do things such as require manager approval for the enrollment or manipulate the subject and/or SANs for the certificate request. Note: An enrollment workflow is considered complete when the certificate reaches a state of Active (issued), Failed (denied approval in workflow or error at the CA level), Pending, or Waiting for External Validation. The workflow does not wait for external approvals before completing. Expiration The workflow is initiated by an expiration alert. Steps during the workflow can be used to do things such as send an email notification regarding expiring certificates, run a PowerShell script to write notifications to the event log, or automate renewal of certificates. Key Rotation The workflow is initiated by an SSH key rotation alert. Steps during the workflow can be used to do things such as send an email notification regarding SSH keys that are approaching their stale date or run a PowerShell script to write notifications to the event log. Revocation The workflow is initiated by revoking a certificate. Steps during the workflow can be configured to do things such as modify the revocation comment entered when the certificate is revoked, append an additional comment, and store the resulting extended comment in a metadata field. Revocation Monitoring The workflow is initiated by a revocation monitoring alert. Steps during the workflow can be used to do things such as send an email notification regarding CRLs that are expiring or OCSP endpoints that are unreachable or run a PowerShell script to write notifications to the event log.

Current Step Display Name A string indicating the display name defined for the workflow instance step.

Current Step Unique Name A string indicating the unique name defined for the workflow instance step. This value is unique among the steps in a particular workflow definition. It is intended to be used as a user-friendly reference ID.

Title

A string indicating a description for the action taking place in the step, made up of the InitiatingUserName (either DOMAIN\\username or Timer Service) followed by an indication of the type of action and a specific message about the action. For example:

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

"KEYEXAMPLE\\jsmith is revoking certificate with CN=appsrvr12.keyexample.com."

Last Modified A string indicating the date and time on which the initiated instance was last updated. The instance is updated each time a step in the workflow is completed, when signals are received for a step that accepts signals (e.g. a requires approval step), or when an instance is stopped or restarted.

Start Date A string indicating the date and time when the instance was initiated.

Initial Data

An object containing the data included in the workflow instance when the workflow was initiated. Show initial workflow instance data.

Name Operation Type Description

Additional Attributes Enrollment An object indicating values for any custom enrollment fields set on the certificate template to supply custom request attributes to the CA during the enrollment process.

AlertId Key Rotation Alerts, Revocation Monitoring An integer indicating the Keyfactor Command reference ID of the alert.

Certificate Authority Enrollment and Revocation A string indicating the certificate authority that will be used to enroll against, for enrollment requests, or that issued the certificate, for revocation requests in hostname\logical name format.

Certificate Id Certificate Entered/Left Collection, Certificate Entered/Left Store, Expiration Alert, and Revocation An integer indicating the Keyfactor Command reference ID for the certificate.

Certificate StoreId Certificate Entered/Left Store A string containing the Keyfactor Command reference GUID of the certificate store.

Certificate ToBe Renewed Enrollment On certificate renewal requests, a string containing the base-64 encoded certificate being renewed.

Comment Revocation A string containing a freeform reason or comment on why the certificate is being revoked.

ContainerId Certificate Entered/Left Store An integer indicating the Keyfactor Command reference ID of the optional certificate store container with which the certificate store is associated. A value of -1 indicates that the certificate store is not associated with a container.

Curve Enrollment For enrollment requests with an ECC key, a string indicating the elliptical curve.

Custom Name Enrollment A string indicating a custom friendly name for the certificate.

Delegate Revocation A Boolean indicating whether delegation is enabled for the certificate authority that issued the certificate (true) or not (false).

Effective Date Revocation A string containing the date and time when the certificate will be revoked.

Enrollment Pattern Enrollment An integer indicating the enrollment pattern used for the enrollment request.

Enrollment Start Time Enrollment A string containing the date and time at which the enrollment request was initiated.

Format Enrollment A string indicating 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 Enrollment A Boolean indicating whether to include the certificate chain in the enrollment response (true) or not (false).

Initiating User Name Certificate Collection, Enrollment, Key Rotation Alerts, and Revocation A string indicating the name of the user who initiated the workflow, generally in DOMAIN\\username format.

IsPFX Enrollment A Boolean indicating whether the certificate enrollment type that initiated the workflow instance was PFX (true) or CSR (false).

KeyLength Enrollment An integer indicating the key size contained in the certificate request.

KeyType Enrollment A string indicating the key type contained in the certificate request.

Management Job Time

Enrollment

An object indicating the schedule for the management job to add the certificate to the certificate store(s). Show management job time details.

Name Description

Immediate

A Boolean that indicates a job scheduled to run immediately (true) or not (false).

Tip: In some instances, jobs initially scheduled as Immediate will appear on a GET as null.

Exactly Once

A dictionary that indicates a job scheduled to run at the time specified with the parameter:

Name	Description
Time	The date and time to next run the job. The date and time should be given using the ISO 8601 UTC time format YYYY-MM-DDTHH:mm:ss.000Z (e.g. 2023-11-19T16:23:01Z).

For example, exactly once at 11:45 am:

Copy

"ExactlyOnce": {
   "Time": "2023-11-27T11:45:00Z"
}

Tip: In some instances, jobs initially scheduled as Immediate will appear on a GET as ExactlyOnce.

Metadata Enrollment An object indicating values for the metadata fields that will be associated with the certificate once it is in Keyfactor Command. The key is the field name and the value is the value for the field.

Operation Start Revocation A string indicating the time at which the revocation workflow was initiated.

Owner Role Id

Enrollment

An integer indicating the security role ID of the security role assigned as the certificate owner.

Tip: For workflows of types other than enrollment, the certificate owner information is retrieved from the database based on the certificate ID and is not stored in the data bucket.

Pfx Password Secret Instance Id Enrollment A string indicating the Keyfactor Command reference GUID for the PFX password used to secure the PFX file on download.

PublishCRL Revocation A Boolean indicating whether a new CRL should be published at the conclusion of the revocation step (true) or not (false).

Renewal Certificate

Enrollment

An object containing the certificate information for the certificate that is being renewed. Show certificate details.

Name	Description
Certificate	An object referencing the certificate being renewed in the following format: Copy `{ "RawData":"[PEM-encoded certificate string]" }`
CertificateId	An integer containing the Keyfactor Command reference ID of the certificate being renewed.

Note: This field is only populated for enrollments that are generated by requesting a certificate renewal (see Renew in the Keyfactor Command Reference Guide and POST Enrollment Renew).

Revoke All Audit Operation Revocation A Boolean indicating whether the revocation request was part of a Revoke All operation (true) or not (false).

Revoke Code

Revocation

An integer containing the specific reason that the certificate is being revoked. Show revocation reasons.

Value	Description
-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

The default is Unspecified.

SANs

Enrollment

An object indicating the subject alternative names (SANs) for the certificate requested in the enrollment, each type an array of strings. Show SAN key values.

Standard Value	Deprecated Value	Description
directory		Directory Name
dn		Distinguished Name
dns	dnsname, dns name	DNS Name
ediparty		EDI (Electronic Data Interchange) Party Name
email	mail	Email Address
guid		Globally Unique Identifier
ip	ip4, ipaddress	IP v4 Address Note: IP v4 and IP v6 addresses are handled separately in the Keyfactor Command Management Portal to allow for the application of separate regular expressions on enrollment, but they are stored using the standard ip value.
ip	ip6	IP v6 Address
oid		Object Identifier
other		Other Name
registered id		Registered ID (an OID)
upn		User Principal Name
uri		Uniform Resource Identifier
url		Uniform Resource Locator
x400		X400 Address
	rfc822	RFC 822 Name
	ms_ ntprincipal name	MS_ NTPrincipal Name (a string)
	ms_ ntds replication	MS_ NTDS Replication (a GUID)

For example:

Copy

"SANs": {
   "dns": [
      "dnssan1.keyexample.com",
      "dnssan2.keyexample.com",
      "dnssan3.keyexample.com"
   ],
   "ip": [
      "192.168.2.73"
   ]
}

Serial Number String Revocation A string indicating the serial number of the certificate being revoked.

SshKeyId Key Rotation Alerts An integer indicating the Keyfactor Command reference ID of the SSH key.

Status Revocation Monitoring A string indicating the status of the revocation monitoring endpoint (e.g. Valid, Expired, or Unavailable).

Stores

Enrollment

An array of objects indicating the certificate stores to which the certificate should be distributed. Show store details.

Name	Description
StoreId	A string indicating the certificate store(s) to which the certificate should be deployed. Use the GET /CertificateStores method (see GET Certificate Stores) with a query of “Approved -eq true” to retrieve a list of all your approved certificate stores to determine the GUID(s) of the store(s).
Alias	A string indicating the alias of the certificate upon entry into the store. The format of and requirement for this varies depending on the certificate store type and whether the Overwrite flag is selected. See PFX Enrollment in the Keyfactor Command Reference Guide for more information.
Overwrite	A Boolean that sets whether a certificate in the store with the Alias provided should be overwritten with the new certificate (true) or not (false). The default is false. Use the GET /Certificates/Locations/{id} method (see GET Certificates Locations ID) to retrieve a list of the locations an existing certificate is in to determine the alias used for the certificate in the certificate store.
Properties	An object containing the unique entry parameters defined for the certificate store type that need to be populated for the certificate. The key is the name of the specific entry parameter from the certificate store type definition as returned in the JobProperties on the store type using the GET CertificateStoreTypes method and the value is the value that should be set for that parameter on the certificate in the certificate store. For example, for CitrixAdc, the key name that is optionally used to associate the certificate with a virtual server is virtualServerName and is returned by GET CertificateStoreTypes like so: "JobProperties": [ "sniCert", "virtualServerName"] It can be seen in the Keyfactor CommandManagement Portal when editing the certificate store type on the Entry Parameters tab. The setting is referenced using the following format: Copy `"Properties": { "sniCert":"MyCertificateName", "virtualServerName":"MyVirtualServerName" }`

Subject

Enrollment and Revocation Monitoring

For CRL revocation monitoring endpoints, a string containing a pre-defined email subject, which is not used for workflow. The value contains entries similar to:

CRL Distribution Point at Location '[CRL Location]' is Available

CRL Distribution Point at Location '[CRL Location]' has Expired

For enrollment requests, a string containing the subject of the certificate.

Template Enrollment A string indicating the certificate template short name used for the enrollment request.

Thumbprint Revocation A string indicating the thumbprint of the certificate being revoked.

URL Revocation Monitoring For a CRL revocation monitoring endpoint, a string containing the path to the CRL location. This value is also found in the Location token for CRL revocation monitoring endpoints.

Current State Data

An object containing the data included in the workflow instance as it progresses. This will include data input from PowerShell scripts, REST requests, and signals along with the initial data. Show current state workflow instance data.

Name Operation Type Description

(Custom) All Optional user-generated custom fields returning response data from PowerShell scripts or REST requests.

AlertId Key Rotation Alerts, Revocation Monitoring An integer indicating the Keyfactor Command reference ID of the alert.

CA Certificate

Enrollment

An object containing the certificate information returned from the CA for the certificate that is being requested. Show CA certificate details.

Name	Description
CA Certificate Id	A string containing the ID assigned to the certificate by the CA.
CA Request ID	A string containing the ID assigned to the certificate request by the CA.
Status	An integer indicating the status for the certificate as returned by the CA.
Certificate	A string containing the certificate as returned by the CA in base-64 encoded binary format.
Certificate Template	A string indicating the certificate template used to issue the certificate.
Revocation Date	A string indicating the revocation date for the certificate as returned by the CA.
Revocation Reason	A string indicating the revocation reason for the certificate as returned by the CA.
Archived Key	A Boolean indicating whether the certificate is configured for key archival on the CA (true) or not (false).

Note: This field is only populated only after the certificate has been issued by the CA.

CA Certificate Request

Enrollment

An object containing the certificate information for the certificate that is being requested. Show certificate request details.

Name	Description
Request Id	A string containing the ID assigned to the certificate request by the CA.
CSR	A string containing the certificate signing request for the certificate request as returned by the CA.
Status	An integer indicating the status for the certificate as returned by the CA.
Requester Name	A string containing 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 Chain Content Enrollment A string containing the certificates in the certificate chain, if the Include Chain option was selected for the request.

Certificate Id Certificate Entered/Left Collection, Certificate Entered/Left Store, Expiration Alert, and Revocation An integer indicating the Keyfactor Command reference ID for the certificate.

Certificate StoreId Certificate Entered/Left Store A string containing the Keyfactor Command reference GUID of the certificate store.

Certificate ToBe Renewed Enrollment On certificate renewal requests, a string containing the base-64 encoded certificate being renewed.

Comment Revocation A string containing a freeform reason or comment on why the certificate is being revoked.

CSR Enrollment A string containing the CSR generated for the certificate request.

Curve Enrollment For enrollment requests with an ECC key, a string indicating the elliptical curve.

Custom Name Enrollment A string indicating a custom friendly name for the certificate.

Delegate Revocation A Boolean indicating whether delegation is enabled for the certificate authority that issued the certificate (true) or not (false).

Disposition

Enrollment and Expiration Alert with Renewal

An integer indicating the reference ID of the disposition for the certificate request.

Note: This field is only populated only after the certificate request has been submitted to the CA.

Disposition Message

Enrollment and Expiration Alert with Renewal

A string indicating a message about the certificate request (e.g. “The private key was successfully retained.”).

Note: This field is only populated only after the certificate request has been submitted to the CA.

Enrollment Context

Enrollment

A string containing the enrollment context returned to Keyfactor Command for external validation requests.