PowerShell script reference for Adaptable Bulk Provisioning

Venafi Adaptable Drivers utilize PowerShell scripts—one for each driver—that contain functions called during various stages of the certificate lifecycle. The Adaptable Bulk Provisioning scripts have only one function: Install-Certificates.

Similar to the Adaptable Application PowerShell script, a FIELD DEFINITIONS header in the Adaptable Bulk Provisioning script defines extra fields that allow a user to provide additional metadata to the script.

For additional information about Venafi Adaptable Drivers and using PowerShell scripts, see About Venafi Adaptable Driver PowerShell scripts.

Specific hash table variables

Variable Name

Data Type

Description

Certificate

Hash Table Array

Certificates to be provisioned in Base64 PEM format.

Each certificate in the certificates array is a hash table that includes the following:

  • Name:  the certificate Common Name (if it exists) or a DNS SAN (if it exists), or an OU (if it exists); otherwise, the serial number
  • Serial:  the serial number of the certificate
  • Thumbprint:  the SHA1 thumbprint of the certificate
  • ValidTo:  the expiration date of the certificate as a YYYYMMDD string
  • Certificate:  the Base64-encoded X509 certificate PEM
  • PrivateKey:  the Base64-encoded, non-encrypted private key PEM
General hash table variables

Variable Name

Data Type

Description

BulkJobDN

String

Contains the Trust Protection Platform distinguished name (DN) of the calling application object.

AuxPass

String

The password portion of the Secondary Credential when a user name or a password credential is assigned, or the PKCS#12 password when a certificate credential is assigned

AuxPfxData

Byte Array

A PKCS#12 byte array that contains a client certificate and private key when a certificate credential is assigned as the Secondary Credential

AuxUser

String

The user name portion of the Secondary Credential when a user name credential is assigned

HostAddress

String

Contains the hostname or IP address specified by the device object.

TcpPort

Integer

A value containing the TCP port specified by the application object.

UserName

String

The user name portion of the user name or private key credential assigned to the device or application object. Used for authenticating with the device.

UserPass

String

The password portion of the user name credential assigned to the device or application object. Used for authenticating with the device.

UserPrivKey

String

The privacy-enhanced electronic mail (PEM)-formatted RSA private key portion of the private key credential assigned to the device or application object. Used for authenticating with the device via SSH.

VarBool1

Boolean

The value of the Yes/No (true/false) user-defined field as defined by the header at the top of the PowerShell script.

VarBool2

Boolean

The value of the Yes/No (true/false) user-defined field as defined by the header at the top of the PowerShell script.

VarPass

String

Contains the value of the password field as defined by the header at the top of the PowerShell script.

VarText1

String

The text contained in the user-defined field as defined by the header at the top of the PowerShell script.

VarText2

String

The text contained in the user-defined field as defined by the header at the top of the PowerShell script.

VarText3

String

The text contained in the user-defined field as defined by the header at the top of the PowerShell script.

VarText4

String

The text contained in the user-defined field as defined by the header at the top of the PowerShell script.

VarText5

String

The text contained in the user-defined field as defined by the header at the top of the PowerShell script.

Returns

Return

Data Type

Description

Result

String

Specify "Success" to indicate the job completed normally and in a manner that should be considered successful. Specify any value other than "Success" (e.g. "Failed") to indicate the job completed but encountered problems.

Fatal errors during execution of the script should be reported by throwing exceptions. Exception messages are captured in log events for the job. See Viewing Bulk Provisioning log events in Policy Tree.

RejectedCertificates

String Array

SHA1 thumbprints for certificates that could not be imported for expected reasons.

FailedCertificates

String Array

SHA1 thumbprints for certificates that could not be imported for unexpected reasons.

For information about processing stages, see About certificate lifecycle management.

About debug logging

When a user has requested debug logging by checking Enable Debug Logging for Adaptable FlowAdaptable Bulk Provisioning, the driver sets a global variable called $DEBUG_FILE whenever it executes a PowerShell function. So your PowerShell script should reference the value of the $DEBUG_FILE variable to decide whether or not to log information for troubleshooting purposes. The value the driver assigns to the $DEBUG_FILE variable is a recommended file path name on the Trust Protection Platform server for use when logging events to a file. The file name is designed to be unique to the instance of the Adaptable component so as to avoid conflicts when multiple scripts are running at the same time and writing to the log file. If the recommended file name is used, the resulting log file appears in the <Venafi Home>\Logs directory by default (e.g. C:\Program Files\Venafi\Logs).

For information about where Enable Debug Logging is configured for Adaptable FlowAdaptable Bulk Provisioning, see Creating a new Bulk Provisioning job.

Related Topics Link IconRelated Topics