BMC Compuware ISPW Operations

Overview

The BMC Compuware ISPW Operations plugin allows Jenkins users to execute ISPW operations, such as Generate, Promote, Deploy or Regress on the mainframe. Users can seamlessly integrate ISPW build process with Jenkins. 

Prerequisites

The following are required to use this plugin:

• Jenkins
• Jenkins Credentials plugin
• Jenkins Plain Credentials plugin
• Compuware Common Configuration plugin - latest
• BMC Compuware mainframe ISPW
• BMC Compuware CES

See also

• License
• Change Log

Additional Information for the Git to ISPW Sync Functionality

• Refer to the following guide for more information
• Required: minimum version of Topaz Workbench CLI version 20.01.01 installed

Installing in a Jenkins Instance

• Install the BMC Compuware ISPW Operations plugin according to the Jenkins instructions for installing plugins. Dependent plugins will automatically be installed.

Configuring Host Connections and CES Tokens

• If no host connection appears in the Host Connections section, click **Add Host Connection **and add a host connection by entering the following information:

  • In the **Description **field, enter a description of the connection.

  • In the **Host:port **field, enter the z/OS host to connect to.

  • From the Code page list, select the desired code page to be used for this connection. The code page is used to translate data sent to and from the host. The default is 1047.

  • In the Read/write timeout (minutes) field, enter the number of minutes for the plugin to wait for a response from the host before timing out.

  • In the CES URL field, enter the CES server URL. The default is empty. It is not required for other BMC Compuware plugins but is required to use this plugin. Please do NOT attach any context path, it should be in the format: http://host:port.

  Note: Click Delete Host Connection to delete an existing connection.

• If you intend to use webhook callback

  • Jenkins URL in section Jenkins Location must be defined with the Jenkins server IP address (not localhost or 127.0.0.1)
  • If you do NOT want the CES callback to provide Jenkins crumb, you need to go to Manage Jenkins | Configure Global Security page, then turn off 'Prevent Cross Request Forgery exploits' in CSRF Protection section. Otherwise, you have to acquire the Jenkins crumb from CES server host and provide the Jenkins crumb as property events.httpHeaders=Jenkins-Crumb:{Jenkins crumb} in the Request body in the job. To acquire a Jenkins crumb, please reference - https://wiki.jenkins.io/display/JENKINS/Remote+access+API

• If no CES token appears in the CES secret token section, 

  • Click Credentials | System | Global credentials | Add Credentials, select Kind to 'Secret text'
  • Provide the CES token as Secret
  • Leave ID as blank (it will generated by Jenkins)
  • Give a a meaningful description, then Add

🆕 Important

Starting with v1.09, the ISPW Jenkins Operations plugin can support certificates to connect with ISPW. For information about using certificates with Jenkins, see https://www.jenkins.io/doc/book/using/using-credentials/

Executing ISPW Operations

• On the Configuration page of the job or project, select Execute a BMC Compuware ISPW Operation from the Build section.

• From the Host connection list, select the host connection to be used to connect to CES host. Alternatively, to add a connection, click Manage connections. The Host connections section of the Jenkins configuration page appears so a connection can be added.

• In the CES secret token list, select the CES token configured in the CES host for the ISPW. Alternatively, click Add to add secret text as token using the Plain Credentials plugin. Refer to the Jenkins documentation for the Plain Credentials plugin.

• In the Action section to define what ISPW operation to perform

  • AddTask
  • BuildAssignment
  • BuildRelease
  • BuildTask
  • CancelAssignment
  • CancelDeployment
  • CancelRelease
  • CloseAssignment
  • CloseRelease
  • CreateAssignment
  • CreateRelease
  • DeployAssignment
  • DeployRelease
  • DeployTask
  • FallbackAssignment
  • FallbackRelease
  • GenerateTask
  • GenerateTasksInAssignment
  • GenerateTasksInRelease
  • GetAssignmentInfo
  • GetAssignmentTaskList
  • GetContainerList
  • GetReleaseInfo
  • GetReleaseTaskGenerateListing
  • GetReleaseTaskInfo
  • GetReleaseTaskList
  • GetSetInfo
  • GetSetTaskList
  • GetWorkList
  • PromoteAssignment
  • PromoteRelease
  • RegressAssignment
  • RegressRelease
  • RemoveFromRelease
  • SetOperation
  • TaskLoad
  • TransferTask

• In the Request section, please specify additional request parameters, click the question mark for more details. Each of the action may have different set of properties, if the job support web hook callback, additional event related properties must be provided. The webhook callback only works for pipeline build.

Using Pipeline Syntax to Generate Pipeline Script

1. Do one of the following:

   • When working with an existing Pipeline job, click the Pipeline Syntax link in the left panel. The Snippet Generator appears.

   • When configuring a Pipeline job, click the Pipeline Syntax link at the bottom of the Pipeline configuration section. The Snippet Generator appears.

2. From the Sample Step list, select ispwOperation: Perform a BMC Compuware ISPW Rest API request and return a JSON object.

3. From the Host connection list, select the host connection that contains a valid CES URL.

4. From the CES secret token, select the corresponding CES token for the CES server.

5. From the Action, select the ISPW operation to be performed.

6. From the Request body, enter the corresponding properties for the specific action, click question mark help for more detail for each action

7. Click Generate Pipeline Script. The Groovy script to invoke the BMC Compuware ISPW Operations plugin appears. The script can be added to the Pipeline section when configuring a Pipeline job. A sample script is shown below:

ispwOperation connectionId: 'e0fbb6eb-b01d-4d55-b18b-2f321c174474', credentialsId: 'f1d2762b-9a40-46ad-a9df-b982147acc85', ispwAction: 'GenerateTasksInAssignment', ispwRequestBody: '''assignmentId=PLAY000313
level=DEV2
runtimeConfiguration=TPZP'''

For webhook callback, a sample script is shown below

hook = ispwRegisterWebhook()
echo "...creating ISPW Jenkins webhook - ${hook.getURL()}"

ispwOperation connectionId: 'e0fbb6eb-b01d-4d55-b18b-2f321c174474', credentialsId: 'f1d2762b-9a40-46ad-a9df-b982147acc85', ispwAction: 'GenerateTasksInAssignment', ispwRequestBody: '''assignmentId=PLAY000313
level=DEV2
runtimeConfiguration=TPZP
events.name=Completed
events.body=Generated
events.httpHeaders=Jenkins-Crumb:no-crumb
events.credentials=admin:library'''

echo "...waiting ISPW Jenkins webhook callback - ${hook.getURL()}"

data = ispwWaitForWebhook hook
echo "...CES called back with message: ${data}"

Note: If the Response body in **console **option is checked, then debug message will be printed within the Jenkins log. 

The following is another example, that after generate and a webhook callback, an intelligent test case change set for total test is also created. Please note that event body is set to setid, so it will be replaced with CES callback, the real set id is going to be used as next query for a set info status. If the level is specified as a none empty string, it will produce a TTT change set.

node {
    stage('generate and webhook demo') {
    	
    	/* create callback endpoint in jenkins */
    	
		hook = ispwRegisterWebhook()
		echo "...creating ISPW Jenkins web hook - ${hook.getURL()}"

		/* generate on assignment with notification callback. when the generate is complete, the webhook callback should has a setid payload */
		
		ispwOperation connectionId: 'e35ab9c9-cf4e-4748-95bc-390312ebcc7e', consoleLogResponseBody: true, credentialsId: 'ces-token-xdevreg', ispwAction: 'GenerateTasksInAssignment', ispwRequestBody: '''assignmentId=PLAY003149
		level=DEV2
		runtimeConfiguration=TPZP
		events.name=Completed
		events.body=$$setid$$
		events.httpHeaders=Jenkins-Crumb:no-crumb
		events.credentials=admin:library
		'''

		echo "...waiting ISPW Jenkins web hook callback - ${hook.getURL()}"

		/* waiting for webhook callback from ces, if triggered, the data contains setid */
		
		data = ispwWaitForWebhook hook
		echo "...CES called back with message: ${data}"

		/* construct a request body with a setid and a none empty level. The value of the level is not important. The get set action will return the load libraries and the product TTT change set */

		def reqbody = "setId=${data}\nlevel=tttchangeset\n"
		ispwOperation connectionId: 'e35ab9c9-cf4e-4748-95bc-390312ebcc7e', consoleLogResponseBody: true, credentialsId: 'ces-token-xdevreg', ispwAction: 'GetSetInfo', ispwRequestBody: "${reqbody}"
    }
}

Pipeline Build Requirement

In order to use pipeline build, your ISPW, CMSC and CES have to be configured properly in order to receive webhook notification. See explanation in the following figure.

GIT to ISPW Integration Features

Pipeline build example

pipeline {

    agent any

    triggers {
        GenericTrigger(
            genericVariables: [
                [key: 'ref', value: '$.changes[0].ref.displayId', expressionType: 'JSONPath', regexpFilter: '^(refs/heads/\\|refs/remotes/origin/)'],
                [key: 'toHash', value: '$.changes[0].toHash', expressionType: 'JSONPath', regexpFilter: '^(refs/heads/\\|refs/remotes/origin/)'],
                [key: 'fromHash', value: '$.changes[0].fromHash', expressionType: 'JSONPath', regexpFilter: '^(refs/heads/\\|refs/remotes/origin/)'],
                [key: 'refId', value: '$.changes[0].ref.id', expressionType: 'JSONPath', regexpFilter: '^(refs/heads/\\|refs/remotes/origin/)'],
            ],
     
            causeString: 'Triggered on $ref',
            token: 'mytokenPipeline',
            printContributedVariables: true,
            printPostContent: true,
            silentResponse: false
        )
    }

    stages {
        stage("git to ispw") {
            steps {
                gitToIspwIntegration app: 'PLAY', branchMapping: '''**/dev1 => DEV1, per-commit
                **/dev2 => DEV2, per-branch
                **/dev3 => DEV3, custom, description

                ''', connectionId: '94d914d9-ea8d-472c-90e4-4b5c007c64d4', credentialsId: '702482ac-de07-4e55-92b3-fcfecbd4fcd7', gitCredentialsId: '6d38ac8e-2d78-446d-9c84-f6072d896013', gitRepoUrl: 'http://10.211.55.3:7990/bitbucket/scm/proj/gitrepo2.git', runtimeConfig: 'TPZP', stream: 'PLAY'

            }
        }
    }
}

Multibranch Jenkinsfile example with automatic build triggered by webhook callback

node {

    stage('Git to ISPW Synchronization') {

		/* git repository */
		
		git branch: 'master', credentialsId: 'bitbucket-somebody', 
		poll: false, url: 'https://bitbucket.host/scm/~somebody/rjk2.git'
		
		/* synchronize change set to ispw */
		
		gitToIspwIntegration app: 'PLAY', 
		branchMapping: '''master => DEV1, per-commit
		''', 
		connectionId: 'e35ab9c9-cf4e-4748-95bc-390312ebcc7e', 
		credentialsId: 'tso-somebody', 
		gitCredentialsId: 'bitbucket-somebody', 
		gitRepoUrl: 'https://bitbucket.host/scm/~somebody/rjk2.git', 
		runtimeConfig: 'TPZP', 
		stream: 'PLAY',
		ispwConfigPath: 'ispwconfig_vm.yml'

    }
    
	stage ('Build automatically with webhook TTT change set generate')
	 {
		 /* create webhook callback end-point on jenkins */
			
		hook = ispwRegisterWebhook()
		echo "...creating ISPW Jenkins web hook - ${hook.getURL()}"
		
		/* start automatic build and feed jenkins webhook callback URL to CES then wait for the build to complete. The expected data returned for the callback is a setid */ 
		
		ispwOperation connectionId: 'e35ab9c9-cf4e-4748-95bc-390312ebcc7e', consoleLogResponseBody: true, credentialsId: 'ces-token-somebody', ispwAction: 'BuildTask', ispwRequestBody: '''runtimeConfiguration=TPZP
		buildAutomatically = true
		events.name=Completed
		events.body=$$setid$$
		events.httpHeaders=Jenkins-Crumb:no-crumb
		events.credentials=admin:library
		'''
		
		echo "...waiting ISPW Jenkins web hook callback - ${hook.getURL()}"
		
		/* when the callback get triggered, the data contains a setid */
		
		data = ispwWaitForWebhook hook
		echo "...CES called back with message: ${data}"
		
		/* construct a request body with a setid and a none empty level. The value of the level is not important. The get set action will return the load libraries and the product TTT change set */
		
		def reqbody = "setId=${data}\nlevel=tttchangeset\n"
		ispwOperation connectionId: 'e35ab9c9-cf4e-4748-95bc-390312ebcc7e', consoleLogResponseBody: true, credentialsId: 'ces-token-somebody', ispwAction: 'GetSetInfo', ispwRequestBody: "${reqbody}"
		
	 }
}

Product Assistance

BMC Compuware provides assistance for customers with its documentation and the support web site.

BMC Compuware Support Center

You can access online information for BMC products via our Support Center site at https://support.bmc.com. Support Center provides access to critical information about your BMC products. You can review frequently asked questions, read or download documentation, access product fixes, or e-mail your questions or comments. The first time you access Support Center, you must register and obtain a password. Registration is free.

Contacting Customer Support

At BMC Compuware, we strive to make our products and documentation the best in the industry. Feedback from our customers helps us maintain our quality standards. If you need support services, please obtain the following information :

• The name, release number, and build number of your product. This information is displayed in the About dialog box.

• Installation information including installed options, whether the product uses local or network databases, whether it is installed in the default directories, whether it is a standalone or network installation, and whether it is a client or server installation.

• Environment information, such as the operating system and release on which the product is installed, memory, hardware and network specification, and the names and releases of other applications that were running when the problem occurred.

• The location of the problem within the running application and the user actions taken before the problem occurred.

• The exact application, licensing, or operating system error messages, if any.

Web

You can report issues via BMC Support Center: https://support.bmc.com.

Corporate Web Site

To access BMC site on the Web, go to https://www.bmc.com/. The BMC site provides a variety of product and support information.