BMC AMI DevX Code Pipeline Operations

Overview

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

Prerequisites

The following are required to use this plugin:

• Jenkins
• Jenkins Credentials plugin
• Jenkins Plain Credentials plugin
• BMC AMI Common Configuration plugin - latest
• BMC AMI DevX Code Pipeline Mainframe
• BMC AMI Common Enterprise Services (CES)

See also

• License
• Change Log

Additional Information for the Git to Code Pipeline Sync Functionality

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

Installing in a Jenkins Instance

• Install the BMC AMI DevX Code Pipeline 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 AMI 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 Code Pipeline Jenkins Operations plugin can support certificates to connect with Code Pipeline. For information about using certificates with Jenkins, see https://www.jenkins.io/doc/book/using/using-credentials/

Executing Code Pipeline Operations

• On the Configuration page of the job or project, select Execute a BMC AMI DevX Code Pipeline 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 Code Pipeline. 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 Code Pipeline operation to perform

  • Add Task
  • Build Assignment
  • Build Release
  • Build Task
  • Cancel Assignment
  • Cancel Deployment
  • Cancel Release
  • Close Assignment
  • Close Release
  • Create Assignment
  • Create Release
  • Deploy Assignment
  • Deploy Release
  • Deploy Task
  • Fallback Assignment
  • Fallback Release
  • Generate Task
  • Generate Tasks In Assignment
  • Generate Tasks In Release
  • Get Assignment Info
  • Get Assignment Task List
  • Get Container List
  • Get Release Info
  • Get Release Task Generate Listing
  • Get Release Task Info
  • Get Release Task List
  • Get Set Info
  • Get Set Task List
  • Get WorkList
  • Promote Assignment
  • Promote Release
  • Regress Assignment
  • Regress Release
  • Remove From Release
  • Set Operation
  • Task Load
  • Transfer Task

• 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 AMI DevX Code Pipeline 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 Code Pipeline 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 AMI DevX Code Pipeline 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 Code Pipeline 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 Code Pipeline 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 Code Pipeline 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 Code Pipeline 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 Code Pipeline, CMSC and CES have to be configured properly in order to receive webhook notification. See explanation in the following figure.

GIT to Code Pipeline 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 Code Pipeline") {
            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 Code Pipeline Synchronization') {

		/* git repository */
		
		git branch: 'master', credentialsId: 'bitbucket-somebody', 
		poll: false, url: 'https://bitbucket.host/scm/~somebody/rjk2.git'
		
		/* synchronize change set to Code Pipeline */
		
		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 Code Pipeline 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 Software provides assistance for customers with its documentation and the support web site.

BMC Software 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 Software, 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.