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

 Name Request Type In Drop down?

Description

$(Additional Attributes) n/a Enrollment No

An array containing the additional enrollment fields, if any, in key value pair format.
$(approval signal cmnts) Workflow Approval or Denial Comment Certificate Collection, Enrollment and Revocation Yes The comment provided when a workflow request that requires approval is approved or denied.

$(CA)

Issuing CA

 Certificate Collection, Enrollment and Revocation Yes

A string containing the Issuing CA logical name and hostname.
$(CA Certificate) n/a Enrollment No Any array of information about the chain certificate(s) for the request, including the certificate.

$(certid)

Request ID

 Certificate Collection and Revocation Yes

The request ID for the certificate as stored in the Keyfactor Command database. This is not the same as the request ID issued by the CA.
$(cmnt) Revocation Comment Revocation Yes The comment entered at revocation time to explain the revocation.
$(code) Revocation Reason Revocation Yes The reason selected at revocation time to explain the revocation as a string (e.g. Affiliation Changed).
$(cn) Common Name Certificate Collection and Revocation Yes The certificate common name.
$(CSR) n/a Enrollment No The CSR generated for the enrollment.
$(Custom Name) n/a Enrollment No The custom friendly name, if any, set for the certificate on enrollment.
$(dn) Distinguished Name Certificate Collection and Revocation Yes The certificate distinguished name.
$(effdate) Revocation Effective Date Revocation Yes Date on which the revocation becomes effective.
$(Format) n/a Enrollment No The value selected during PFX Enrollment for the format for the certificate. Possible values are: JKS, PFX, Store, Zip
$(IsPFX) n/a Enrollment No A Boolean indicating whether the certificate request was made using the PFX Enrollment method in Keyfactor Command (true) or not (false).
$(issuerdn) Issuer DN Certificate Collection and Revocation Yes The distinguished name of the issuer of the certificate.
$(Key Retention) n/a Enrollment No A Boolean indicating whether the private key for the certificate has been retained in Keyfactor Command (true) or not (false).
$(keysize) Key Size Certificate Collection and Revocation Yes The key size of the certificate.
$(keytype) Key Type Certificate Collection and Revocation Yes The key type of the certificate.
$(locations) Certificate Store Locations Certificate Collection, Enrollment and Revocation 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 revocation requests.
$(management job time) n/a Enrollment 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.
$(request: cn) Requested Common Name Enrollment Yes The common name contained in the certificate request.
$(request: dn) Requested Distinguished Name Enrollment Yes The distinguished name contained in the certificate request.
$(request: keysize) Request Key Size Enrollment Yes The key size contained in the certificate request.
$(request: keytype) Request Key Type Enrollment Yes The key type contained in the certificate request.

$(requester)

Requester

 Enrollment and Revocation Yes

The user account that requested the certificate from the CA, in the form DOMAIN\ username.

$(requester: mail)

Requester’s Email

 Enrollment and Revocation 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: givenname)

Requester’s First Name

 Enrollment and Revocation 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: sn)

Requester’s Last Name

 Enrollment and Revocation 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: displayname)

Requester's Display Name

 Enrollment and Revocation 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 Certificate Collection, Enrollment and Revocation 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 Revocation No The reason selected at revocation time to explain the revocation as an integer (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).

$(sans)

Subject Alternative Names

 Enrollment Yes

Subject alternative name(s) contained in the 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 Adding or Modifying a CA Record. 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. See Installing the Keyfactor CA Policy Module Handlers.
$(serial) Serial Number Certificate Collection and Revocation Yes Certificate serial number.
$(stores) n/a Enrollment No The certificate store(s) to which the certificate will be delivered on issuance.

$(subdate)

Submission Date

 Enrollment and Revocation Yes

Date the workflow was initiated.

$(template)

Template Name

 Certificate Collection and Enrollment Yes

The short name (often the name with no spaces) of the certificate template used to create the certificate request.
$(thumbprint) Thumbprint Certificate Collection and Revocation Yes Thumbprint of the certificate.

$(metadata: Email- Contact)

Email-Contact

 Certificate Collection, Enrollment and Revocation 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).