| 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
-
Open Jenkins in a browser (e.g.
http://<jenkins-host>:8080) -
Navigate to Manage Jenkins → Manage Plugins view
-
Under the Available tab find the Worksoft Execution Manager plugin and check the box adjacent to the plugin and click Install without restart:
Manual Install
-
Download ws-execution-manager.hpi from https://plugins.jenkins.io/ws-execution-manager
-
Open Jenkins in a browser (e.g.
http://<jenkins-host>:8080) -
Navigate to Manage Jenkins → Manage Plugins and select the Advanced tab.
-
Click the Choose File button in the Upload Plugin section.
-
Find the location of the ws-execution-manager.hpi file and click the Open button and Upload the file.
-
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:
Configure the URL of the Execution Manager (typically http://<em-host>/executionmanager):
And 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:
Select the type of request to execute:
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.
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.
Optionally, a result folder can be specified by filling in the Results folder text box:
Certify Processes
Select Certify Processes to execute a list of Certify processes without creating a request or bookmark first.
Provide a database alias name of the Certify connection saved in Management Studio → Configuration → Certify Configuration:
Specify the Certify project where processes reside:
Optionally, specify a folder where Certify Results will be saved. If not specified, results go to the root results folder:
Specify a name to be given to the request execution:
Provide a fully qualified path to each process to execute:
Add additional processes by clicking the Add Certify Process button:
Configure Alternative Execution Manager
An Execution Manager build step can override the global Execution Manager configuration (see above) by configuring an alternative:
Configure the URL of the Execution Manager (typically http://<em-host>/executionmanager):
And credentials:
Additional Options
Each request type (request, bookmark and processes) can be configured to be executed with additional Certify parameters and wait configuration:
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} :
Optionally, execution wait configuration can be specified. Both the polling interval and maximum run time must be specified in seconds:
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
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 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'