Documentation Suite v11.3

GET Workflow Instances Instance ID

The GET /Workflow 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./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 817: 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 818: 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 The workflow is initiated by an automated task that Keyfactor Command runs periodically against your collections to identify certificates that now meet the query criteria of the specified 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. CertificateLeftCollection The workflow is initiated by an automated task that Keyfactor Command runs periodically against your collections to identify certificates 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. 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. 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.

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

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 Collection and Revocation An integer indicating the Keyfactor Command reference ID for the certificate.

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

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

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.

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

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

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

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

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

Include Chain Enrollment A Boolean indicating whether to include the certificate chain in the enrollment response (true) or not (false).

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.

Value	Description
rfc822	RFC 822 Name
dns	DNS Name
directory	Directory Name
uri	Uniform Resource Identifier
ip4	IP v4 Address
ip6	IP v6 Address
registered id	Registered ID (an OID)
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"
   ],
   "ip4": [
      "192.168.2.73"
   ]
}

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.

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.

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.

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

Subject Enrollment A string containing the subject name of the requested certificate using X.500 format.

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).

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 Command Management 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" }`

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.

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

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.

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

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

Certificate Id Certificate Collection and Revocation An integer indicating the Keyfactor Command reference ID for the certificate.

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

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

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.

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

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

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

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

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

Include Chain Enrollment A Boolean that indicates whether to include the certificate chain in the enrollment response (true) or not (false).

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.

Value	Description
rfc822	RFC 822 Name
dns	DNS Name
directory	Directory Name
uri	Uniform Resource Identifier
ip4	IP v4 Address
ip6	IP v6 Address
registered id	Registered ID (an OID)
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"
   ],
   "ip4": [
      "192.168.2.73"
   ]
}

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.

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

Subject Enrollment A string containing the subject name of the requested certificate using X.500 format.

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]" }`
Certificate Id	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).

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 for the unique parameters defined for the certificate store type that need to be populated for the certificate. The key is the name of the specific 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 NetScaler, the key name that is optionally used to associate the certificate with a virtual server is NetscalerVserver and is returned by GET CertificateStoreTypes like so: "JobProperties": [ "NetscalerVserver" ] It can be seen in the Keyfactor Command Management Portal when editing the certificate store type in the field for Management Job Custom Fields. The setting is referenced using the following format: Copy `"Properties": { "NetscalerVserver":"MyVirtualServerName" }` Note: The only built-in certificate store type that makes use of properties that can be set on a certificate-by-certificate basis in the store is NetScaler. You may have custom certificate store types that make use of this functionality.

Management Job Time

Enrollment

An object indicating the schedule for the management job to add the certificate to any 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.

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

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.

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

Key Retention Enrollment A Boolean indicating whether the private key for the certificate resulting from the enrollment will be retained in Keyfactor Command (true) or not (false).

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

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

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.

Disposition Message

Enrollment

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.

CA Certificate Request

Enrollment

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

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

Serial Number Enrollment A string indicating the serial number of the certificate.

Issuer Dn Enrollment A string indicating the distinguished name of the issuer.

Thumbprint Enrollment A string indicating the thumbprint of the certificate.

Keyfactor Id Enrollment An integer indicating the Keyfactor Command reference ID for the certificate.

Key Status

Enrollment

An integer 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

Private Key Converter Enrollment An internally used Keyfactor Command field.

Reference Id A integer indicating the Keyfactor Command reference ID for the workflow instance.

Tip: See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor API

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. endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflow development. It also serves secondarily as documentation for the API. The link to the Keyfactor API Reference and Utility is in the dropdown from the help icon (

) at the top of the Management Portal page next to the Log Out button.

Version v11.3

On this page: