Configuring the Bulk Insert utility

This topic describes how to configure the Bulk Insert utility. For information about the utility, see Bulk Insert utility in the "Key features" topic.

TPP configuration

You must perform the task described in this section in Venafi Trust Protection Platform (TPP).

The Bulk Insert utility communicates with TPP via the TPP REST API, so you must register an API integration and create a TPP user account that can use it. The user account must have permission to create and modify objects in the policy folders in which you intend to create certificate and application objects.

To add a user account

Perform the following steps, referring to the TPP documentation for detailed instructions.

Important

Where particular values for TPP object fields are not specified in this procedure, you can leave their defaults or set them according to your own needs. If settings given in this section conflict with your own policies, contact BMC Support for more information.

Create a TPP user name and password for the Bulk Insert utility in Active Directory, LDAP, or in the TPP local user directory, according to the configuration of your organization.
From the TPP Platform menu, select the options to create an API integration from JSON.
Enter the following code in the text box:
{
  "id": "ecvenafibulkinsert",
  "name": "EC Venafi Bulk insert",
  "vendor": "BMC Software, Inc",
  "description": "EC Venafi Bulk insert",
  "scope": "certificate:manage;configuration:manage"
}
Click Quick Create to save the integration.
Add the user name that you created in step 1 as follows:
1. Modify User and team access.
2. Click Add.
3. Click Save.
If required, modify the lifetime of the access token issued for the API integration. For example, if you use the Bulk Insert utility only occasionally, a 1-day lifetime might be sufficient.

Data preparation

The Bulk Insert utility uses the following configuration files:

Template file—Specifies the certificate- and application-object parameters for all of the objects that you intend to create (for example, the certificate object name, subject DN, and mainframe target environment). For more information, see Template file.
Data file—Contains definitions of macro tags used in the template to customize individual certificate objects and their associated application objects. For more information, see Data file.

You can copy the template and data files to any location, but they must be on the same server as the BulkInsert.exe file.

Important

When using the template and data file to define new certificates, the following TPP policy rules apply:

Unspecified parameters inherit the default values defined in the policy.
Template parameters can override policy defaults if the policy permissions allow it.

The Bulk Insert utility stops processing and returns an error if a mandatory parameter is not defined, or if an attempt is made to set a parameter that is locked by the policy.

Template file

The template file is in JSON format, using key-name and value pairs to define the parameters. The Bulk Insert utility uses strings for the values of all key names, except for the private key size, which is an integer and common to all created objects.

You can use macro tags as variable placeholders in any of the strings. A macro tag consists of a percentage sign (%), followed by at least one capital letter or digit, and ending in a second percentage sign, (for example, %OBJECT% or %APPROVER1%). The macro tags are used in the template file and defined in the data file.

The template file contains the following key names. All key names are mandatory unless indicated otherwise.

Key name	Value type	Description
certificateObject	Dictionary	Introduces the parameters for the certificate object
folderName	String	Name of the policy folder in which to create the certificate object
objectName	String	Name of the certificate object to be created
objectDescription	String	(Optional) Description of the certificate object
DN	Dictionary	Subject Distinguished Name If you specify a value for DN, you must also specify a (string) value for CN. All of the other key names are optional: CN—Subject Canonical Name, using the DNS domain name format O—Subject Organization, the name of the organization to which the certificate was issued OU—Subject Organizational Unit, the name of the division or department to which the certificate was issued L—Subject Locality, the city or municipality where the certificate was issued ST—Subject State, the state or province where the certificate was issued C—Subject Country, the country where the certificate was issued
keySize	Integer	Private key size, in bits
customFields	Array of dictionaries	(Optional) TPP Certificate custom fields If you specify a value for customFields, you must also specify a (string) value for the following key names: name—Custom field name value—Custom field value
approvers	Array of strings	(Optional) One string per TPP user, being an approver for the certificate
applicationObject	Dictionary	Introduces the parameters for the application object
folderName	String	Name of the policy folder where the existing device object is stored
deviceName	String	Name of the device object in the policy folder
objectName	String	Name of the application object to be created
objectDescription	String	(Optional) Description of the application object
endpoints	String	Endpoint configuration
postImplementScript	String	(Optional) Script to run after the certificate implementation
forceSiteCertificate	Boolean	(Optional) Forces the certificate to be created as a site certificate

Data file

The data file is in CSV or TSV format. It contains a header row that lists all of the macro tags used in the template file, without the surrounding percentage signs (%). The header row is followed by one or more rows containing values for the macro tags, with each row corresponding to a single certificate object and its associated application object, and subject to the following limitations:

Every row must contain a value for every macro tag listed in the header row.
Values must be separated by commas (no spaces).
If a value contains commas or tabs, it must be enclosed in quotation marks.
To include an empty or null value, use a pair of quotation marks ("") for the value.
List the values in the same order as the order in which the macro tags are listed in the header row.

The Bulk Insert utility checks that every macro tag that is referenced in the template file has a definition in the data file.

Sample template and data files

Use the following template and data file samples to understand the code used to define certificates for bulk creation.

Sample template file

The following sample template file is provided with the utility. This sample includes the macro tags %OBJECT%, %DESCRIPTION%, %CN%, %CUSTOMFIELD%, %LPAR% and %POSTIMPLEMENT%. The values for these macro tags must be defined in the data file.

In this sample, most of the target environment parameters are defined in the template. Only the LPAR is defined using a macro tag. However, you can define the entire target environment by using macro tags, if required.

{
"certificateObject": {
   "folderName": "\\VED\\Policy\\Bulk Insert",
   "objectName": "%OBJECT%",
   "objectDescription": "Autogenerated certificate object - %DESCRIPTION%",
   "DN": {
     "CN": "%CN%.demo.com"
    },
   "keySize": 2048,
   "customFields": [
      {
       "name": "Certificate Custom Field",
       "value": "%CUSTOMFIELD%"
      }
    ],
   "approvers": [
     "local:masteradmin"
    ]
  },
"applicationObject": {
   "folderName": "\\VED\\Policy\\EC for Venafi",
   "deviceName": "Gateway",
   "objectName": "Bulk Insert %OBJECT%",
   "objectDescription": "Autogenerated application object - %DESCRIPTION%",
   "endpoints": "%LPAR%*FixedKeyRing*FixedLabel*OWNER*D",
   "postImplementScript": "%POSTIMPLEMENT%",
   "forceSiteCertificate": false
  }
}

Sample data file

In this sample, the data file must provide values for OBJECT, DESCRIPTION, CN, CUSTOMFIELD, LPAR, and POSTIMPLEMENT, which represent the macro tags used in the sample template:

OBJECT,DESCRIPTION,CN,CUSTOMFIELD,LPAR,POSTIMPLEMENT
First object,Description 1,object1,A custom value,LPAR1,""
Second object,"A different, and longer, description",object2,"",LPAR2,""

This sample contains a header row and two subsequent rows, each representing a certificate object and its associated application object.

First object has a null value for POSTIMPLEMENT.

Second object has commas in the string for DESCRIPTION, so the string is enclosed in quotation marks. It also has null values for CUSTOMFIELD and POSTIMPLEMENT.