Substitutable Text Tokens for Workflow

Refer to the following table for a list of the substitutable special text tokens that are available in the dropdown to customize workflowClosed 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. email messages, conditions, and select parameterClosed 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).

Tip:  In addition to the tokens in the dropdown, any data in the current data bucket can be referenced by entering an appropriate reference string. For example, to return the CSRClosed 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 enrollmentClosed Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). request you can use $(CSR). Refer to the CurrentStateData field in the response to the GET /Workflow/Instances/{instanceId} APIClosed An API is 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 16: 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.
$(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.

$(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 Chain Content) n/a No A string containing the certificates in the certificate chain, if the Include Chain option was selected for the request.
$(Certificate ToBe Renewed) n/a No On certificate renewal requests, the base-64 encoded certificate being renewed.
$(cmnt) Revocation Comment Yes The comment entered at revocation time to explain the revocation.
$(cn) Common Name Yes The certificate common name.
$(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.
$(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 The CA’s disposition message, if any, for the enrollment or renewal (updated) certificate. This is most common for certificates requiring approval at the CA level. This is found in for expiration workflows with a step of type Renew Expired Certificates as well as for enrollment requests.
$(Disposition) n/a No The CA’s disposition code, if any, for the enrollment or 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 Context) n/a No A string containing the enrollment context returned to Keyfactor Command for external validation requests.
$(Enrollment Pattern) n/a No An integer indicating ID of the enrollment pattern used for the enrollment request.
$(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 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: 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: 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).
$(KeyStatus) n/a No

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
$(keysize) Key Size Yes The key size of the certificate.
$(keytype) Key Type Yes The key type of the certificate.
$(KeyfactorId) n/a No An integer indicating the Keyfactor Command reference ID for 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

$(metadata: Email- Contact)

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).
$(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 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.
$(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.
$(PublishCRL) n/a No A Boolean indicating whether a new CRL should be published at the conclusion of the revocation step (true) or not (false).
$(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 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 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
$(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.

$(requester)

Requester

 Yes

The user account that requested the certificate from the CA, in the form DOMAIN\ username.
$(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 All Audit Operation) n/a No A Boolean indicating whether the revocation request was part of a Revoke All operation (true) or not (false).
$(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.

$(sans formatted print)

 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:

  • For CSR enrollment, the original SANs included in the CSR.
  • Any SANs added through the Keyfactor Command Management Portal. For CSR enrollment, these take the place of the SANs in the CSR if the ATTRIBUTE SUBJECT ALT NAME2 option is enabled on the CA. See CSR Enrollment.
  • A SAN matching the CN added automatically during enrollment as a result of setting the RFC 2818 compliance flag in the CA configuration. See Standalone Tab. For PFX enrollment, the user has the option of editing this entry at enrollment time; entry of something is required.
  • A SAN matching the CN added automatically by the Keyfactor Command policy module on the CA if the Keyfactor Command RFC 2818 Policy Handler is enabled, if one was not included in the CSR or added manually.

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 Number) n/a No For enrollment workflows, the certificate serial number of the enrolled or renewal (updated) certificate from the data bucket. This includes certificates enrolled via expiration workflows with a step of type Renew Expired Certificates.
$(Serial Number String) n/a No For revocation workflows, the certificate serial number from the data bucket.
$(serial) Serial Number Yes The certificate serial number.
$(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

For revocations, a string indicating the thumbprint of the certificate being revoked.

For enrollment requests, a string indicating the thumbprint of the certificate. This includes certificates enrolled via expiration workflows with a step of type Renew Expired Certificates.
$(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.

Table 17: 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)    
$(cert store client machine)            
$(cert store container)            
$(cert store id)            
$(cert store path)            
$(certid)      
$(Certificate Chain Content)            
$(Certificate ToBe Renewed)            
$(cmnt)            
$(cn)      
$(code)            
$(Container Id)            
$(CSR)            
$(Curve)            
$(Custom Name)            
$(Delegate)            
$(Disposition Message)          
$(Disposition)          
$(dn)      
$(effdate)            
$(Effective Date)            
$(endpoint type)            
$(Enrollment Context)            
$(Enrollment Pattern)            
$(Enrollment Start Time)            
$(Enrollment Workflow Instance Id)            
$(expdate)    
$(Expiry Date)            
$(Format)            
$(Include Chain)            
$(Initiating User Name)
$(Initiating User Roles)
$(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 formatted print)            
$(issuedcert: sans)            
$(issuedcert: serial)            
$(issuedcert: Template)            
$(issuedcert: thumbprint)            
$(issuerdn)      
$(Key Retention)            
$(keysize)      
$(KeyStatus)            
$(keytype)    
$(location)            
$(locations)    
$(management job time)            
$(Metadata)            

$(metadata: Email- Contact)

    
$(name)            
$(OCSP Parameters)            
$(Operation Start)            
$(owner role email)    
$(owner role id)    
$(PublishCRL)            
$(Published Date)            
$(Raw Certificate)            
$(Renewed CertId)            
$(Request Disposition)            
$(request: cn)            
$(request: dn)            
$(request: keysize)            
$(request: keytype)            

$(requester: display name)

          
$(reviewlink)  
$(Revoke All Audit Operation)            
$(Revoke Code)            
$(revoker)            

$(sans formatted print)

    

$(sans)

    
$(Serial Number String)            
$(Serial Number)            
$(serial)      
$(SshKeyId)            
$(StaleDate)            
$(status)            
$(stores)            

$(subdate)

    
$(Subject)          

$(template)

    
$(thumbprint)      
$(URL)            
$(username)