Refer to the following table for a list of the substitutable special text tokens that are available in the dropdown to customize 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. email messages, conditions, and select parameter A parameter or argument is a value that is passed into a function in an application. configuration fields along with a selection of some additional tokens that are not found in the dropdown but which exist in the data bucket (see tip).
A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. for an enrollment 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). request you can use $(CSR). Refer to the CurrentStateData field in the response to the GET /Workflow/Instances/{instanceId} 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. method for information on all the data found in the current (as opposed to initial) data bucket (see GET Workflow Instances Instance ID).Table 13: Tokens for Workflow Definitions
| Variable | Display Name | In Drop down? | Description |
|---|---|---|---|
| $(Additional Attributes) | n/a | No |
An array containing the additional enrollment fields, if any, in key value pair format. See the following workflow example: Update Additional Enrollment Field on Enrollment |
| $(alertId) | Alert Id | Yes | An integer indicating the Keyfactor Command reference ID of the alert. |
| $(approval signal cmnts) | Approval Signal Comments | Yes | The comment provided when a workflow request that requires approval is approved or denied. |
|
$(CA) |
Certificate Authority |
Yes |
A string containing the Issuing CA logical name and hostname for the certificate authority that issued the certificate or to which the certificate request is directed. |
|
$(certid) |
Certificate Id |
Yes |
The Keyfactor Command reference ID of the certificate request or issued certificate. This is not the same as the request ID issued by the CA. |
| $(Certificate ToBe Renewed) | n/a | No | On certificate renewal requests, the base-64 encoded certificate being renewed. |
| $(cert store client machine) | Client Machine | Yes | Typically the fully qualified domain name or IP address of the target server or device on which the certificate store is located. |
| $(cert store container) | Container | Yes | The optional certificate store container with which the certificate store is associated. |
| $(cert store id) | Certificate Store Id | Yes | The Keyfactor Command reference ID of the certificate store. |
| $(cert store path) | Store Path | Yes | The path to the certificate store, sometimes including the store file name, on the target server or device. |
| $(cmnt) | Revocation Comment | Yes | The comment entered at revocation time to explain the revocation. |
| $(code) | Revocation Code | Yes | The reason selected at revocation time to explain the revocation as a string (e.g. Affiliation Changed). |
| $(Container Id) | n/a | No | 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. |
| $(cn) | Common Name | Yes | The certificate common name. |
| $(CSR) | n/a | No | The CSR generated for the enrollment. |
| $(Curve) | n/a | No | For enrollment requests with an ECC key, the elliptical curve. |
| $(Custom Name) | n/a | No | The custom friendly name, if any, set for the certificate on enrollment. |
| $(Delegate) | n/a | No | A Boolean indicating whether delegation was enabled for the request (true) or not (false). |
| $(Disposition Message) | n/a | No | For expiration workflows with a step of type Renew Expired Certificates, the CA’s disposition message, if any, for the renewal (updated) certificate. This is most common for certificates requiring approval at the CA level. |
| $(dn) | Distinguished Name | Yes | The certificate distinguished name. |
| $(effdate) | Effective Date | Yes | The date on which the revocation becomes effective as a date in ISO 8601 format. |
| $(Effective Date) | n/a | No | The date on which the revocation becomes effective as a string in ISO 8601 format. |
| $(endpoint type) | Endpoint Type | Yes | The revocation monitoring endpoint type (CRL or OCSP). |
| $(Enrollment Start Time) | n/a | No | The date and time at which the enrollment request was initiated. |
| $(Enrollment Workflow Instance Id) | n/a | No | For expiration workflows with a step of type Renew Expired Certificates, the Keyfactor Command reference ID of the enrollment workflow generated to enroll for the renewal (updated) certificate. |
| $(expdate) | Expiration Date | Yes | Expiration date of the certificate or SSH key. |
| $(Expiry Date) | n/a | No | The expiration date for the CRL configured for the revocation monitoring endpoint, |
| $(Format) | n/a | No | The value selected during PFX Enrollment for the format for the certificate. Possible values are: JKS, PFX, Store, Zip |
| $(Include Chain) | n/a | No | A Boolean indicating whether the certificate chain should be included with the issued certificate for PFX enrollment requests (true) or not (false). |
| $(Initiating User Name) | Initiating User Name | Yes | The user initiating the workflow. If this is initiated automatically for an alert, this will be Timer Service. |
| $(Initiating User Roles) | Initiating User Roles | Yes |
The role(s) of the user initiating the workflow instance. This token will apply to non-timer service started workflows, only. This token resolves to a comma-separated array of strings indicating the role names for the roles granted to the user who triggered the workflow. For example: ["Enrollment Users", "Administrator", "Read Only"]
|
| $(IsPFX) | n/a | No | A Boolean indicating whether the certificate request was made using the PFX Enrollment method in Keyfactor Command (true) or not (false). |
| $(issuance date) | Issuance Date | Yes | The date on which the certificate was issued. |
| $(issuedcert: CA) | Issued Certificate’s Certificate Authority | Yes |
A string containing the Issuing CA logical name and hostname for the certificate authority that issued the certificate. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: cn) | Issued Certificate’s Common Name | Yes |
The certificate common name. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: dn) | Issued Certificate’s Distinguished Name | Yes |
The certificate distinguished name. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: expdate) | Issued Certificate’s Expiration Date | Yes |
The expiration date of the certificate. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(Issuedcert: id) | Issued Certificate’s Certificate ID | Yes |
The certificate ID for the certificate as stored in the Keyfactor Command database. This differs from the Keyfactor Command request ID. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: issuance date) | Issued Certificate’s Issuance Date | Yes |
The issuance date of the certificate. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: issuerdn) | Issued Certificate’s Issuer DN | Yes |
The distinguished name of the issuer of the certificate. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: keysize) | Issued Certificate’s Key Size | Yes |
The key size of the certificate. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: keytype) | Issued Certificate’s Key Type | Yes |
The key type of the certificate. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: locations) | Issued Certificate’s Locations | Yes |
The certificate store locations to which the certificate is scheduled to be deployed or has been deployed. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: sans) | Issued Certificate’s Subject Alternative Name | Yes |
Subject alternative name(s) contained in the certificate (see $(sans)). If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(Issuedcert: sans formatted print) | Issued Certificate’s Formatted SANs | Yes |
Subject alternative name(s) contained in the certificate (see $(sans)), formatted in a cleaner fashion. For example, for a given certificate, the $(sans) response might look like this: {"dns": ["mysan1.keyexample.com", "mysan2.keyexample.com", "mysan3.keyexample.com", "mysan4.keyexample.com"], "ip": ["10.4.3.45"]}
For the same certificate, the $(sansformattedprint) response might look like this: DnsName: mysan1.keyexample.com, IPAddress: 10.4.3.45, DnsName: mysan2.keyexample.com, DnsName: mysan3.keyexample.com, DnsName: mysan4.keyexample.com
If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: serial) | Issued Certificate’s Serial Number | Yes |
Certificate serial number. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: Template) | Issued Certificate’s Template | Yes |
The short name (often the name with no spaces) of the certificate template used to issue the certificate. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuedcert: thumbprint) | Issued Certificate’s Thumbprint | Yes |
Thumbprint of the certificate. If this token is used in the workflow before the enroll step or the enroll step does not return a certificate (e.g. the request requires approval at the CA level), this value will be empty. |
| $(issuerdn) | Issuer DN | Yes | The distinguished name of the issuer of the certificate. |
| $(Key Retention) | n/a | No | A Boolean indicating whether the private key for the certificate has been retained in Keyfactor Command (true) or not (false). |
| $(keysize) | Key Size | Yes | The key size of the certificate. |
| $(keytype) | Key Type | Yes | The key type of the certificate. |
| $(location) | Location | Yes | The revocation monitoring location. For a CRL endpoint, this will be the path defined for the CRL. For an OCSP endpoint, this will be the path to the OCSP server and will not indicate the specific CA. Use the Name value (defining the Name appropriately) to reference the CA for OCSP endpoints. |
| $(locations) | Locations | Yes | The certificate store locations to which the certificate will be deployed following enrollment, for enrollment requests, or in which the certificate is found, for other request types. |
| $(Management Job Time) | n/a | No | The schedule for the management job to add the certificate to certificate stores on issuance. The field, if populated, will have a value of either “Immediate”: true or “Exactly Once” with the date and time at which the management job should begin. See the following workflow example: Update Enrollment Request Requiring Approval with Certificate Store Info Using Embedded REST Request |
| $(Metadata) | n/a | No | A dictionary containing all the metadata fields configured for the certificate. This field name is case sensitive. See the following workflow example: Copy Approval Comment to Metadata Field on Enrollment |
| $(name) | Name | Yes | The name of the revocation monitoring endpoint. For an OCSP endpoint, use this to reference the CA so that you can alert on the specific CA’s endpoint in emails since the Location references the OCSP server. |
| $(OCSP Parameters) | n/a | No | For an OCSP revocation monitoring endpoint, the configuration parameters indicating the CA information including certificate authority ID and name. The contents of this will vary depending on whether the OCSP endpoint was configured by doing a lookup in Active Directory or using a file. |
| $(Operation Start) | n/a | No | A string indicating the date the workflow was initiated as an ISO 8601 string (e.g. 2024-04-20T10:37:11.3723743+10:00). See also $(subdate). |
| $(owner role id) | Owner Role Id | Yes |
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.
|
| $(owner role email) | Owner Role Email | Yes |
A string indicating the email address, if any, configured for 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.
|
| $(Published Date) | n/a | No | The publication date for the CRL configured for the revocation monitoring endpoint. |
| $(Raw Certificate) | n/a | No | The raw certificate file generated from a certificate enrollment, without BEGIN and END blocks. |
| $(Renewed CertId) | n/a | No | For expiration workflows with a step of type Renew Expired Certificates, the Keyfactor Command reference ID of the renewal (updated) certificate. See also $(certid). |
| $(request: cn) | Requested Common Name | Yes | The common name contained in the certificate request. |
| $(request: dn) | Requested Distinguished Name | Yes | The distinguished name contained in the certificate request. |
| $(request: keysize) | Request Key Size | Yes | The key size contained in the certificate request. |
| $(request: keytype) | Request Key Type | Yes | The key type contained in the certificate request. |
| $(Request Disposition) | n/a | No | For expiration workflows with a step of type Renew Expired Certificates, the status of the renewal request at the CA level (issued, pending). See the following workflow example: Renewal and Email Notification on Approaching Certificate Expiration |
|
$(requester) |
Requester |
Yes |
The user account that requested the certificate from the CA, in the form DOMAIN\ username. |
|
Requester’s Email |
Yes |
The email address retrieved from Active Directory of the user account that requested the certificate from the CA, if present. Note: This substitutable special text token is only supported in environments using Active Directory as an identity provider.
|
|
|
Requester’s First Name |
Yes |
The first name retrieved from Active Directory of the user account that requested the certificate from the CA, if present. Note: This substitutable special text token is only supported in environments using Active Directory as an identity provider.
|
|
|
Requester’s Last Name |
Yes |
The last name retrieved from Active Directory of the user account that requested the certificate from the CA, if present. Note: This substitutable special text token is only supported in environments using Active Directory as an identity provider.
|
|
|
Requester's Display Name |
Yes |
The display name retrieved from Active Directory of the user account that requested the certificate from the CA, if present. Note: This substitutable special text token is only supported in environments using Active Directory as an identity provider.
|
|
| $(reviewlink) | Review Link | Yes |
Link pointing to the review page in the Management Portal for the workflow instance where the person responsible for providing signal input (e.g. approving the request) can go to review the request and provide the input. Note: This option is only useful in workflows that contain a step that requires signal input (e.g. requires approval).
|
| $(Revoke Code) | n/a | No | An integer indicating the reason selected at revocation time to explain the revocation (e.g. 3). See also $(code). For details on the mapping of numeric revocation codes to revocation strings, refer to the POST /Certificates /Revoke API endpoint (see POST Certificates Revoke). |
| $(revoker) | Revoker | Yes | The user requesting the revocation. |
| Formatted SANs | Yes |
Subject alternative name(s) contained in the certificate or certificate request, cleanly formatted for use in emails and similar (see $(sans)). |
|
|
$(sans) |
Subject Alternative Name |
Yes |
Subject alternative name(s) contained in the certificate or certificate request. There are four possible sources for the SANs that appear here:
The $(sans) token functions differently in workflow output depending on the configuration of the Use Deprecated Sans Token Parser application setting. When this application setting is set to True, the $(sans) token output is very similar to the $(sansformattedprint) token output, with the SANs in a cleanly formatted string. When this application setting is set to False, the $(sans) token output is a serialized as a JSON string, which supports the use of ConvertFrom-Json -AsHashtable. $(sans formatted print) output example: DnsName: appsrvr45.keyexample.com, DnsName: appsrvr45A.keyexample.com, DnsName: appsrvr45B.keyexample.com, IPAddress: 10.4.3.6
$(sans) output example with Use Deprecated Sans Token Parser true: dns: appsrvr45.keyexample.com, dns: appsrvr45A.keyexample.com, dns: appsrvr45B.keyexample.com, ip: 10.4.3.6
$(sans) output example with Use Deprecated Sans Token Parser false: {"dns": ["appsrvr45.keyexample.com", "appsrvr45A.keyexample.com", "appsrvr45B.keyexample.com"], "ip": ["10.4.3.6"]}
|
| $(serial) | Serial Number | Yes | The certificate serial number. |
| $(Serial Number) | n/a | No | For expiration workflows with a step of type Renew Expired Certificates, the certificate serial number of the renewal (updated) certificate. |
| $(SshKeyId) | n/a | No | An integer indicating the Keyfactor Command reference ID of the SSH key. |
| $(StaleDate) | n/a | No | The next publishing date for the CRL configured for the revocation monitoring endpoint. |
| $(status) | Status | Yes | The status of the revocation monitoring endpoint (e.g. Valid, Expired, or Unavailable). |
| $(Stores) | n/a | No | The certificate store(s) to which the certificate will be delivered on issuance. See the following workflow example: Update Enrollment Request Requiring Approval with Certificate Store Info Using Embedded REST Request |
|
$(subdate) |
Submission Date |
Yes |
The date the workflow was initiated specified using the RFC 1123 standard (e.g. Sat, 20 Apr 2024 00:37:11 GMT). |
| $(Subject) | n/a | No |
For CRL revocation monitoring endpoints, 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, the subject of the certificate. |
|
$(template) |
Template |
Yes |
The short name (often the name with no spaces) of the certificate template used to create the certificate request. |
| $(thumbprint) | Thumbprint | Yes |
The thumbprint of the certificate. For expiration workflows with a step of type Renew Expired Certificates, this will be the thumbprint of the renewal (updated) certificate in workflow steps following the renewal step. |
| $(URL) | n/a | No | For a CRL revocation monitoring endpoint, the path to the CRL location. This value is also found in the Location token for CRL revocation monitoring endpoints. |
| $(username) | User Name | Yes | User name of the SSH user owning the key. |
|
Email-Contact (metadata) |
Yes |
Example of a custom metadata field. Your custom metadata fields would be referenced similarly (e.g. $(metadata: AppOwner FirstName) for metadata field AppOwner FirstName). |
Table 14: Workflow Token Availability by Request Type
| Variable | Certificate Entered / Left Collection | Certificate Entered / Left Store | Enrollment | Expiration | Key Rotation | Revocation Monitoring | Revocation |
|---|---|---|---|---|---|---|---|
| $(Additional Attributes) |
|
||||||
| $(alertId) |
|
|
|||||
| $(approval signal cmnts) |
|
|
|
|
|
|
|
| $(CA) |
|
|
|
|
|
||
| $(certid) |
|
|
|
|
|||
| $(Certificate ToBe Renewed) |
|
||||||
| $(cert store client machine) |
|
||||||
| $(cert store container) |
|
||||||
| $(cert store id) |
|
||||||
| $(cert store path) |
|
||||||
| $(cmnt) |
|
||||||
| $(code) |
|
||||||
| $(Container Id) |
|
||||||
| $(cn) |
|
|
|
|
|||
| $(CSR) |
|
||||||
| $(Curve) |
|
||||||
| $(Custom Name) |
|
||||||
| $(Delegate) |
|
||||||
| $(Disposition Message) |
|
||||||
| $(dn) |
|
|
|
|
|||
| $(effdate) |
|
||||||
| $(Effective Date) |
|
||||||
| $(endpoint type) |
|
||||||
| $(Enrollment Start Time) |
|
||||||
| $(Enrollment Workflow Instance Id) |
|
||||||
| $(expdate) |
|
|
|
|
|
||
| $(Expiry Date) |
|
||||||
| $(Format) |
|
||||||
| $(Include Chain) |
|
||||||
| $(Initiating User Name) |
|
|
|
|
|
|
|
| $(IsPFX) |
|
||||||
| $(issuance date) |
|
|
|
|
|||
| $(issuedcert: CA) |
|
||||||
| $(issuedcert: cn) |
|
||||||
| $(issuedcert: dn) |
|
||||||
| $(issuedcert: expdate) |
|
||||||
| $(Issuedcert: id) |
|
||||||
| $(issuedcert: issuance date) |
|
||||||
| $(issuedcert: issuerdn) |
|
||||||
| $(issuedcert: keysize) |
|
||||||
| $(issuedcert: keytype) |
|
||||||
| $(issuedcert: locations) |
|
||||||
| $(issuedcert: sans) |
|
||||||
| $(Issuedcert: sans formatted print) |
|
||||||
| $(issuedcert: serial) |
|
||||||
| $(issuedcert: Template) |
|
||||||
| $(issuedcert: thumbprint) |
|
||||||
| $(issuerdn) |
|
|
|
|
|||
| $(Key Retention) |
|
||||||
| $(keysize) |
|
|
|
|
|||
| $(keytype) |
|
|
|
|
|
||
| $(location) |
|
||||||
| $(locations) |
|
|
|
|
|
||
| $(management job time) |
|
||||||
| $(Metadata) |
|
||||||
| $(name) |
|
||||||
| $(OCSP Parameters) |
|
||||||
| $(Operation Start) |
|
||||||
| $(owner role id) |
|
|
|
|
|
||
| $(owner role email) |
|
|
|
|
|
||
| $(Published Date) |
|
||||||
| $(Raw Certificate) |
|
||||||
| $(Renewed CertId) |
|
||||||
| $(request: cn) |
|
||||||
| $(request: dn) |
|
||||||
| $(request: keysize) |
|
||||||
| $(request: keytype) |
|
||||||
| $(Request Disposition) |
|
||||||
|
$(requester) |
|
|
|||||
|
$(requester: mail) |
|
|
|||||
|
$(requester: given name) |
|
|
|||||
|
$(requester: sn) |
|
|
|||||
|
$(requester: display name) |
|
|
|||||
| $(reviewlink) |
|
|
|
|
|
|
|
| $(Revoke Code) |
|
||||||
| $(revoker) |
|
||||||
|
$(sans formatted print) |
|
|
|
|
|
||
|
$(sans) |
|
|
|
|
|
||
| $(serial) |
|
|
|
|
|||
| $(Serial Number) |
|
||||||
| $(SshKeyId) |
|
||||||
| $(StaleDate) |
|
||||||
| $(status) |
|
||||||
| $(stores) |
|
||||||
|
$(subdate) |
|
|
|
|
|
||
| $(Subject) |
|
|
|||||
|
$(template) |
|
|
|
|
|
||
| $(thumbprint) |
|
|
|
|
|||
| $(URL) |
|
||||||
| $(username) |
|
||||||
|
$(metadata: Email- Contact) |
|
|
|
|
|