Worksoft Execution Manager

Jenkins Plugin ws execution manager plugin Jenkins Plugin Installs

Plugin Information

View Worksoft Execution Manager on the plugin site for more information.

Description

This is the official Worksoft Supported Plugin for EM. The plugin adds build steps for interacting with a Worksoft’s Execution Manager to run your Certify processes or ALM labs.

Installation

Note
This plugin requires Worksoft’s Execution Manager version 10.0.20 or later. If you use an earlier version of Execution Manager you will see a runtime error 405 Method Not Allowed.

Update Center

  1. Open Jenkins in a browser (e.g. http://<jenkins-host>:8080)

  2. Navigate to Manage Jenkins → Manage Plugins view

  3. Under the Available tab find the Worksoft Execution Manager plugin and check the box adjacent to the plugin and click Install without restart:

Plugin Installation

Manual Install

  1. Download ws-execution-manager.hpi from https://plugins.jenkins.io/ws-execution-manager

  2. Open Jenkins in a browser (e.g. http://<jenkins-host>:8080)

  3. Navigate to Manage JenkinsManage Plugins and select the Advanced tab.

  4. Click the Choose File button in the Upload Plugin section.

  5. Find the location of the ws-execution-manager.hpi file and click the Open button and Upload the file.

  6. Restart Jenkins, if necessary.

Usage

Configure Global Worksoft Execution Manager Settings

The plugin provides a means to configure an Execution Manager’s URL and credentials used by all Execution Manager build steps (unless overridden). To configure this, navigate to Jenkins global configuration settings and paths (Jenkins → Manage Jenkins → Configure System) and locate the Global Worksoft Execution Manager Settings section:

Global Settings

Configure the URL of the Execution Manager (typically http://<em-host>/executionmanager):

URL configuration

And credentials:

Credentials

Save these configuration settings after which they can be used by Execution Manager build steps (Freestyle and Pipeline).

Freestyle Project

Create a Freestyle project and add the Run Execution Manager Request build step:

Build Step

Select the type of request to execute:

Request Type

Execution Manager Request

Select EM Request to run a predefined request configured on the Execution Manager. The Name list box will be populated with all available requests of which one must be selected.

Request

Execution Manager Bookmark

Select EM Bookmark to run a predefined bookmark configured on the Execution Manager via the Management Studio. The Name list box will be populated with all available bookmarks of which one must be selected.

Bookmark

Optionally, a result folder can be specified by filling in the Results folder text box:

Results Folder

Certify Processes

Select Certify Processes to execute a list of Certify processes without creating a request or bookmark first.

Certify Process

Provide a database alias name of the Certify connection saved in Management Studio → Configuration → Certify Configuration:

Certify Database

Specify the Certify project where processes reside:

Certify Project

Optionally, specify a folder where Certify Results will be saved. If not specified, results go to the root results folder:

Results Folder

Specify a name to be given to the request execution:

Request Name

Provide a fully qualified path to each process to execute:

Paths

Add additional processes by clicking the Add Certify Process button:

Additional Processes

Configure Alternative Execution Manager

An Execution Manager build step can override the global Execution Manager configuration (see above) by configuring an alternative:

Alt execution

Configure the URL of the Execution Manager (typically http://<em-host>/executionmanager):

EM URL

And credentials:

EM Credentials

Additional Options

Each request type (request, bookmark and processes) can be configured to be executed with additional Certify parameters and wait configuration:

Addtional Options
Certify Parameters

Optionally, Certify parameters can be specified. Both a key and value must be specified. The value can refer to Jenkins environment variables using this syntax: ${JENKINS_ENV_VAR}. For example - ${BUILD_ID} :

Parameter

Optionally, execution wait configuration can be specified. Both the polling interval and maximum run time must be specified in seconds:

Wait Times

Output

Plugin version 10.0.1 and later outputs the Worksoft Execution Manager result set in JSON format to a file named - execMan-result.json - in the associated Jenkins job’s workspace directory. For example:

{
  "Status": "Completed",
  "Description": "FAILED",
  "ExecutionStatus": "FAILED",
  "Tasks": [
    {
      "Name": "test login",
      "ExecutionStatus": "Failed",
      "ResourceName": "CKAgentBox1",
      "LastReportedError": "",
      "Status": "Completed",
      "CertifyDatabaseAliasName": "CK_Certify",
      "CertifyResultID": 20075
    }
  ]
}
Note
See Certify Execution Manager’s API specification for a complete description of the result set.

This file can be read/processed in either a freestyle or pipeline job. For example, in a freestyle job, to retrieve from Certify the failed test steps, add a Groovy build step with Groovy code like:

// Requires Groovy plugin - http://wiki.jenkins-ci.org/display/JENKINS/Groovy+plugin

import groovy.json.JsonSlurper
import groovy.json.JsonOutput
import hudson.*
import hudson.model.*
import java.lang.*

def build = Thread.currentThread().executable
def resolver = build.buildVariableResolver
def workspace = build.getModuleRoot().absolutize().toString()

// Retrieve job paramaters

def API_TOKEN = resolver.resolve("API_TOKEN")
def API_URL = resolver.resolve("API_URL")
def execManResult = new File(workspace + "/execMan-result.json")

if (execManResult.exists()) {
    def result = new JsonSlurper().parse(execManResult)

    println "result=" + JsonOutput.prettyPrint(JsonOutput.toJson(result))

    // Loop through all tasks looking for failed tasks and their result ID
    for (int i = 0; i < result['Tasks'].size(); i++) {
        def logHeaderID = result['Tasks'][i]['CertifyResultID']
        def executionStatus = result['Tasks'][i]['ExecutionStatus']

        if (logHeaderID != null && executionStatus.toUpperCase().equals("FAILED")) {

            // Retrieve failed test steps from Certify and display them
            def url = API_URL + "?logHeaderID=" + logHeaderID
            def api = url.toURL().openConnection()
            api.addRequestProperty("Accept", "application/json")
            api.addRequestProperty("token", API_TOKEN)
            api.setRequestMethod("GET")
            api.connect()
            println "Tasks[" + i + "] logHeaderID=" + logHeaderID + ":" + JsonOutput.prettyPrint(api.content.text)
        }
    }
}

Similarly, a pipeline job could process the output file as follows:

// Requires the following In-Process script approvals:
// method java.net.HttpURLConnection setRequestMethod java.lang.String
// method java.net.URL openConnection
// method java.net.URLConnection addRequestProperty java.lang.String java.lang.String
// method java.net.URLConnection connect
// method java.net.URLConnection getContent
// staticMethod org.codehaus.groovy.runtime.DefaultGroovyMethods getText java.io.InputStream
// staticMethod org.codehaus.groovy.runtime.DefaultGroovyMethods hasProperty java.lang.Object java.lang.String
// staticMethod org.codehaus.groovy.runtime.DefaultGroovyMethods toURL java.lang.String

import groovy.json.JsonOutput

pipeline {
    agent {
        node {
            label "master"
        }
    }
    stages {
        stage('build') {
            steps {

                // Execute an Execution Manager request
                execMan request: [name: '<an-execution-manager-request-name>'], requestType: 'request'

                script {

                    if (fileExists('execMan-result.json')) {
                        def result = readJSON file: 'execMan-result.json'
                        echo "result=" + JsonOutput.prettyPrint(JsonOutput.toJson(result))

                        for (int i = 0; i < result['Tasks'].size(); i++) {
                            def logHeaderID = result['Tasks'][i]['CertifyResultID']
                            def executionStatus = result['Tasks'][i]['ExecutionStatus']

                            if (logHeaderID != null && executionStatus.toUpperCase().equals("FAILED")) {
                                // Retrieve failed test steps from Certify and display them
                                def url = API_URL + "?logHeaderID=" + logHeaderID
                                def api = url.toURL().openConnection()
                                api.addRequestProperty("Accept", "application/json")
                                api.addRequestProperty("token", API_TOKEN)
                                api.setRequestMethod("GET")
                                api.connect()
                                echo "Tasks[" + i + "] logHeaderID=" + logHeaderID + ":" + JsonOutput.prettyPrint(api.content.text)
                            }
                        }
                    }
                }
            }
        }
    }
}

Pipeline DSL Reference

Run an Execution Manager Request

Step Action execMan
Parameters
requestType
Type: String

Value: Request | Bookmark | Process

altEMConfig (optional)

Optional alternative Execution Manager configuration. If provided, these parameters override those specified in Jenkins global configuration.

Required Parameters
url
Type: String

URL of the ExecutionManager server

credentials
Type: String

Username and Password for EM

bookmark(optional)

Select this to run a predefined bookmark configured on the Execution Manager via Management Studio.

Required Parameters
name

Type: String Name of the bookmark to run

folder (optional)
Type: String
execParms(optional)

Optional execution request parameters.

list (optional)
Type: ArrayList of emParam’s
key
Type: String:
value
Type: String:
processList (optional)

Execute a list of Certify processes without creating a request or bookmark first.

Required Parameters
database

Alias name of the Certify connection saved in Management Studio → Configuration → Certify Configuration.

Type: String:
project

Certify project where processes reside.

Type: String:
processes

List of the fully qualified path to each process.

Type: ArrayList of certifyProcess:
processPath:
Type: String:
folder

Folder where Certify Results will be saved. If not specified, results go to the root results folder.

Type: String:
requestName

Name given to the request execution

request (optional)

Select the predefined request to run

waitConfig (optional)

Optional execution request wait configuration. Both the polling interval and maximum run time must be specified in seconds

pollInterval
Type: String
maxRunTime
Type: String

Example pipeline snippets

Simple Request execution:
execMan request: [name: 'name-of-request'], requestType: 'request'
Simple Bookmark execution:
execMan bookmark: [folder: 'result-folder-name', name: 'name-of-bookmark'], requestType: 'bookmark'
Simple Process List execution:
execMan processList: [database: 'database-alias', folder: 'result-folder-name', processes: [[processPath: 'Project1\\Folder1\\Folder2\\Process1'], [processPath: 'testproject\\testfolder\\testprocess']], project: 'certify-project-name', requestName: 'request-name'], requestType: 'processList'
Bookmark request with wait config specified:
execMan bookmark: [folder: 'result-folder-name', name: 'name-of-bookmark'], requestType: 'bookmark', waitConfig: [maxRunTime: '600', pollInterval: '10']
Request with Parameters:
execMan request: [name: 'name-of-request'], requestType: 'request', execParams: [list: [[key: 'key1-name', value: 'value1'], [key: 'key2-name', value: 'value2']]]

Changelog

Version 10.0.0.7 (Dec 11 2018)

  • Initial version

Version 10.0.1.19 (April 24 2019)

  • Output Certify Execution Manager result set to <workspace-path>/execMan-result.json

Version 10.0.3.3 (October 29 2021)

  • Fix issue with build steps in freestyle jobs not rendering correctly

  • Convert documentation to .adoc and move from wiki to Git repo

  • fix build