POST MetadataFields
The POST /MetadataFields method is used to create a new metadata
Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In the context of Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. field in Keyfactor Command. This method returns HTTP 200 OK on a success with details of the new metadata field.
Table 360: POST MetadataFields Input Parameters
| Name | In | Description |
|---|---|---|
| Name | Body |
Required. A string indicating the name of the metadata field. This name appears in interfaces where you can use metadata, such as certificate details dialogs, alert dialogs, certificate imports and certificate requests. Once this field has a value associated with it for at least one certificate, you cannot change this name. The metadata name field cannot contain spaces; dashes and underscores are supported. |
| Description | Body | Required. A string indicating the description for the metadata field. |
| DataType | Body |
Required. An integer indicating the data type of the metadata field. |
| Hint | Body |
A string indicating a short hint for the metadata field. This hint appears in unpopulated metadata string, integer, big text and date fields on editing interfaces to provide the user with a clue as to what type of data should be entered in the field. This field is only supported for metadata fields with data types string, integer, date or big text. |
| Validation | Body | A string containing a regular expression against which data entered in a string field will be validated. When a user enters information in a metadata field that does not match the specified regular expression, he or she will see the warning message specified in the Message field. For example: ^[a-zA-Z0-9'_\.\-]*@(keyexample\.org|keyexample\.com)$ This regular expression specifies that the data entered in the field must consist of some number of characters prior to the "@" made up only of lowercase letters, uppercase letters, numbers, apostrophes, underscores, periods, and/or hyphens followed by exactly either "@keyexample.org" or "keyexample.com". This field is only supported for metadata fields with data type string. Tip: If a template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. specific option is set for a given metadata field, that takes precedence over the global options. The template-specific regular expression will be used in PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. and CSR 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. 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). requests using that template (see GET Templates ID). |
| Enrollment | Body |
An integer indicating how metadata fields should be handled on the PFX and CSR Enrollment pages. The default is optional. Tip: If a template-specific handling is set for a given metadata field, it takes precedence over this global setting. The template-specific handling will be used in PFX and CSR enrollment requests using that template (see GET Templates ID).
|
| Message | Body |
A string containing a message to present when a user enters information in a metadata field that does not match the specified regular expression (Validation field). Tip: If a template-specific regular expression message is set for a given metadata field, it takes precedence over this global regular expression message. The template-specific message will be used in PFX and CSR enrollment requests using that template (see GET Templates ID).
|
| Options | Body |
An array containing a comma separated list of values that should appear in the field dropdown for multiple choice fields. This field is required for metadata fields with data type multiple choice. For other data types, it will be ignored. Tip: If a template-specific options are set for a given metadata field, these takes precedence over these global options. The template-specific options will be used in PFX and CSR enrollment requests using that template (see GET Templates ID).
|
| DefaultValue | Body |
A string containing a default value with which to pre-populate the metadata field for new certificate requests made using PFX or CSR enrollment. Data type of Email will accept a comma separated list of email addresses (limit 100 characters per email address). This field is only supported for metadata fields with data types string, integer, Boolean, Email or multiple choice. Tip: If a template-specific default is set for a given metadata field, it takes precedence over this global default value. The template-specific default will be used in PFX and CSR enrollment requests using that template (see GET Templates ID).
|
| AllowAPI | Body |
A Boolean that sets whether methods in the Classic API This is considered deprecated and may be removed in a future release. |
| ExplicitUpdate | Body |
A Boolean that sets whether methods in the Classic API must submit an overwrite flag in the request in order to overwrite an existing value in the metadata record (true) or not (false). The default is false. This setting does not apply to the Keyfactor API. This is considered deprecated and may be removed in a future release. |
| DisplayOrder | Body | An integer indicating the order in which the metadata field should be displayed on pages where the metadata fields are displayed (e.g. PFX enrollment, certificate details). |
Table 361: POST MetadataFields Response Data
| Name | Description |
|---|---|
| ID | An integer indicating the Keyfactor Command reference ID for the metadata field. This ID is automatically set by Keyfactor Command. |
| Name |
A string indicating the name of the metadata field. This name appears in interfaces where you can use metadata, such as certificate details dialogs, alert dialogs, certificate imports and certificate requests. Once this field has a value associated with it for at least one certificate, you cannot change this name. The metadata name field cannot contain spaces; dashes and underscores are supported. |
| Description | A string indicating the description for the metadata field. |
| DataType |
An integer indicating the data type of the metadata field. |
| Hint |
A string indicating a short hint for the metadata field. This hint appears in unpopulated metadata string, integer, big text and date fields on editing interfaces to provide the user with a clue as to what type of data should be entered in the field. This field is only supported for metadata fields with data types string, integer, date or big text. |
| Validation | A string containing a regular expression against which data entered in a string field will be validated. When a user enters information in a metadata field that does not match the specified regular expression, he or she will see the warning message specified in the Message field. For example: ^[a-zA-Z0-9'_\.\-]*@(keyexample\.org|keyexample\.com)$ This regular expression specifies that the data entered in the field must consist of some number of characters prior to the "@" made up only of lowercase letters, uppercase letters, numbers, apostrophes, underscores, periods, and/or hyphens followed by exactly either "@keyexample.org" or "keyexample.com". This field is only supported for metadata fields with data type string. Tip: If a template specific option is set for a given metadata field, that takes precedence over the global options. The template-specific regular expression will be used in PFX and CSR enrollment requests using that template (see GET Templates ID). |
| Enrollment |
An integer indicating how metadata fields should be handled on the PFX and CSR Enrollment pages. Tip: If a template-specific handling is set for a given metadata field, it takes precedence over this global setting. The template-specific handling will be used in PFX and CSR enrollment requests using that template (see GET Templates ID).
|
| Message |
A string containing a message to present when a user enters information in a metadata field that does not match the specified regular expression (Validation field). Tip: If a template-specific regular expression message is set for a given metadata field, it takes precedence over this global regular expression message. The template-specific message will be used in PFX and CSR enrollment requests using that template (see GET Templates ID).
|
| Options |
An array containing a comma separated list of values that should appear in the field dropdown for multiple choice fields. This field is only supported for metadata fields with data type multiple choice. Tip: If a template-specific options are set for a given metadata field, these takes precedence over these global options. The template-specific options will be used in PFX and CSR enrollment requests using that template (see GET Templates ID).
|
| DefaultValue |
A string containing a default value with which to pre-populate the metadata field for new certificate requests made using PFX or CSR enrollment. Data type of Email will accept a comma separated list of email addresses (limit 100 characters per email address). This field is only supported for metadata fields with data types string, integer, Boolean, Email or multiple choice. Tip: If a template-specific default is set for a given metadata field, it takes precedence over this global default value. The template-specific default will be used in PFX and CSR enrollment requests using that template (see GET Templates ID).
|
| AllowAPI |
A Boolean that sets whether methods in the Classic API can be used to manipulate data in the metadata record (true) or not (false). The default is true. This setting does not apply to the Keyfactor API. This is considered deprecated and may be removed in a future release. |
| ExplicitUpdate |
A Boolean that sets whether methods in the Classic API must submit an overwrite flag in the request in order to overwrite an existing value in the metadata record (true) or not (false). The default is false. This setting does not apply to the Keyfactor API. This is considered deprecated and may be removed in a future release. |
| DisplayOrder | An integer indicating the order in which the metadata field should be displayed on pages where the metadata fields are displayed (e.g. PFX enrollment, certificate details). |
) at the top of the Keyfactor Command Management Portal page next to the Log Out button.
