Configuring the post-implementation script

(SPE2307)

BMC AMI Enterprise Connector for Venafi supports a post-implementation script that you can use to perform site-specific tasks after the successful creation of a certificate, for example:

  • Issuing a command to refresh a started task running on the system
  • Running a Write to Operator (WTO) macro that your site's automation product can pick up

The post-implementation script is a REXX exec.

Related topics

Planning

Installing

Configuring-after-installation

You configure the post-implementation script by copying a sample script provided with EC for Venafi, and by specifying the script name in Venafi Trust Protection Platform (TPP). For an example of a post-implementation script, see Sample post-implementation script.

The sample script is included in the RSMSAMP library, which is installed with the application. For more information, see Reviewing-the-product-configuration.

To configure the post-implementation script

  1. From the SAMPLIB library installed with EC for Venafi, copy the POSTIMPL sample script.
  2. Modify the functions, arguments, and variables according to the needs of your organization. For details, see Scripting requirements and variables.
  3. Save the script. You can rename the script. If so, use that name to specify the script in TPP, as described in step 5.
  4. Copy the script to the PDS library specified in your agent's started task ECIREXX JCL statement.
  5. Specify the script in TPP as follows. For detailed instructions on working with application objects, see the TPP documentation.
    1. Navigate to the application object associated with the certificate for which you want to run the post-implementation script.
    2. In the Post-implementation script name field, specify the name of the script.
    3. (Optional) Add any additional arguments to pass to the script at runtime.
    4. Click Save.

Important

Where particular values for TPP object fields are not specified in this procedure, you can leave them at 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.

Scripting requirements and variables

For instructions on using REXX language, see the IBM documentation.

The post-implementation script is subject to the following requirements:

  • To retrieve the entry variables, the script must start with a call to the ecentry() function and it must return with a call to the ecreturn() function.
  • To write messages to the EC for Venafi log file, you must use the rsvxlog() function, which requires the following parameters:
    • The value that appears in the left-hand column of the log entry
    • The value that appears in the right-hand column of the log entry
  • To run a WTO, you must use the rsvxwto() function.

You can use the following variables after the ecentry() call.

Variable

Description

EC_APPTRACE

Indicates if application tracing is active:

  • On—Active
  • Off—Not active

EC_ESMTYPE

Security protocol: RACF, TSS, or ACF2

EC_GATEWAY

Name of the LPAR where the EC for Venafi gateway is running

EC_HLQ

High-level qualifier used for the EC for Venafi data set

EC_REXXTRACE

Indicates if REXX tracing is active:

  • On—Active
  • Off—Not active

EC_SYSID

Name of the LPAR where the current agent is running

EC_SYSPLEX

SYSPLEX name

EC_TRANID

Transaction ID for this transaction

EC_TRANSTATE

Transaction state

TPP_CERTEXPIRY

Expiry date of the certificate

TPP_CERTLABEL

Certificate label

TPP_COUNTRY

Country where the certificate was issued

TPP_KEYINICSF

Indicates if the certificate will be stored in ICSF:

  • True—The certificate is stored in ICSF
  • False—The certificate is not stored in ICSF

TPP_KEYSIZE

Size of the key

TPP_NUMENDPOINTS

Total number of endpoints sent from TPP

TPP_OWNERID

Owner ID

TPP_SITECERTIFICATE

Indicates that the certificate is a site certificate

TPP_STATE

State or province where the certificate was issued

TPP_SUBJECTCN

Subject Canonical Name, using the DNS domain name format

TPP_SUBJECTL

Subject Locality, being the city or municipality where the certificate was issued

TPP_SUBJECTO

Subject Organization, being the name of the organization to which the certificate was issued

TPP_SUBJECTOU

Subject Organizational Unit, being the name of the division or department to which the certificate was issued

TPP_ENDPOINTS.0

Number of endpoints (LPARs) processed

TPP_ENDPOINTS.X.CERTLABEL

Certificate label for endpoint X

TPP_ENDPOINTS.X.CERTOWNERID

Owner ID for the certificate for endpoint X

TPP_ENDPOINTS.X.RINGS

Number of keyrings for the certificate in TPP for endpoint X

TPP_ENDPOINTS.X.SITECERTIFICATE

Indicates if this is a site certificate for endpoint X:

  • True—The certificate is a site certificate
  • False—The certificate is not a site certificate

TPP_ENDPOINTS.X.TARGETENVIRONMENT

The target environment for endpoint X

TPP_KEYRINGS.0

Number of keyrings provided by TPP

TPP_KEYRINGS.X.DEFAULTCERT

Indicates if the certificate is the default certificate in the keyring:

  • True—The certificate is the default
  • False—The certificate is not the default

TPP_KEYRINGS.X.KEYRINGNAME

Keyring name

TPP_KEYRINGS.X.OWNERID

Owner ID for the keyring

Sample post-implementation script

/* Rexx */
/************************************************/
/* enterpriseConnector : Venafi-TPP Interface */
/* */
/* Post implementation sample exit using SDSF */
/* */
/************************************************/
parse arg arg1, arg2, arg3, arg4, arg5, arg6
/************************************************/
/* Retrieve Script name */
/************************************************/
Parse source . . exec_mem . exec_dsn . . envname .
/************************************************/
/* Retrieve entry variables */
/************************************************/
rc = ecentry()
/************************************************/
/* Issue Message to agent log */
/************************************************/
call rsvxlog '****************', exec_mem 'Exit Started ***************'
/************************************************/
/* Show sample variables in SYSTSPRT */
/************************************************/
say 'System = 'EC_Sysid
say 'Gateway = 'EC_Gateway
say 'ESM = 'ecesm()
say 'arg1 = 'arg1
say 'arg2 = 'arg2
say 'arg3 = 'arg3
call rsvxlog '****************', exec_mem 'Processing ***************'
/************************************************/
/* Issue command (e.g. F PAGENT,REFRESH) */
/************************************************/
if pos('3270', TPP_CERTLABEL) > 0 then do
rc = issue_command('F PAGENT,REFRESH')
end
/************************************************/
/* Process response */
/************************************************/
do i=1 to isfulog.0
say isfulog.i
end
/************************************************/
/* Issue wto */
/************************************************/
rc = rsvxwto('ABC1234E Message to trigger automation -'TPP_CERTLABEL)
/************************************************/
/* Check result */
/************************************************/
if rc<>0 then nop /* Do something */
/************************************************/
/* Issue Message */
/************************************************/
call rsvxlog '****************', exec_mem 'Exit Ended ***************'
/************************************************/
/* Return to caller */
/************************************************/
rc = ecreturn()
/************************************************/
/* Sample issue command function */
/************************************************/
issue_command:
arg command
rc = isfcalls('ON')
cmd.0=1;cmd.1=command
Address SDSF ISFSLASH "("cmd.") (WAIT)" /* Wait for response */
rc = isfcalls('OFF')
return 0

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*