Integration Script Explained

Applies to Zephyr Squad Cloud, last modified on September 21, 2023

About the script file

You can create automation tasks, run them and push test results to Zephyr Squad directly from your CI/CD workflow. To do this, you can create a special script file that works with Zephyr Squad through API.

Windows (.bat in .zip)

bat-script.zip

Linux and MacOS (.sh in .zip)

sh-script.zip

Before using these files, you need to replace values in them – access key, user ids, project key, result file name, and others – with values relevant to your project and tests. Below is a detailed explanation of what you need to change. For quick reference, search for the icon – it indicates the code parts that need to be updated.

You can modify these files in any text editor.

Prologue comment

The script starts with a comment describing the script file:

.bat file

:: =========================================
::  This .bat file demonstrates how to create or update an automation task in Zephyr Squad, run this task, and publish test results to Zephyr.
::  Author: SmartBear Software
:: =========================================

.sh file

######################################################################
#  This .sh file demonstrates how to create or update an automation task in Zephyr Squad, run this task, and publish test results to Zephyr.
#  Author: SmartBear Software
######################################################################

Zephyr URL constant

The constant below specifies the Zephyr base URL:

.bat file

set "$zephyrBaseUrl=https://prod-api.zephyr4jiracloud.com/connect"

.sh file

zephyrBaseUrl="https://prod-api.zephyr4jiracloud.com/connect"

Keep this value exactly as it is in the sample script. Don’t change it!

Connection keys and ID

The following access and secret keys are needed for connection to Zephyr Squad, and the ID of the user account is needed to create or update automation tasks:

.bat file

set "$accessKey=XXXXXXXXXXXXXXXXXXXXYzdkLTliNzEtZjllMTZmZTZlNWQxIDU1NzA1OCUzQTg0NzBkN2EzLWY3NTgtNDBkYS04ZDc4LWRhNjBlZjEyNTM3MSBVU0VSX0RFRkFVTFRfTkFNRQ"
set "$secretKey=XXXXXXXXXXXXXXXXXXXXrj1usQ3mhvJslXkmTSjrOFY"
set "$accountId=557058:XXXXXXXX-XXXX-XXXX-XXXX-da60ef125371"

.sh file

accessKey="XXXXXXXXXXXXXXXXXXXXYzdkLTliNzEtZjllMTZmZTZlNWQxIDU1NzA1OCUzQTg0NzBkN2EzLWY3NTgtNDBkYS04ZDc4LWRhNjBlZjEyNTM3MSBVU0VSX0RFRkFVTFRfTkFNRQ"
secretKey="XXXXXXXXXXXXXXXXXXXXrj1usQ3mhvJslXkmTSjrOFY"
accountId="557058:XXXXXXXX-XXXX-XXXX-XXXX-da60ef125371"

Replace these values with the values relevant to your Jira project and user account. You can find all these values in Jira.

How to get access and secret keys

How to get the account ID

JWT generation

The block below generates a JSON Web Token (JWT) that is needed to access Zephyr Squad through API. To create this token, the script sends an API request to Zephyr Squad:

.bat file

echo "Generating a JSON Web Token ..."
for /F "tokens=*" %%i in (' curl -s -X POST -H "Content-Type: application/json" --data "{ \"accessKey\":\"%$accessKey%\", \"secretKey\":\"%$secretKey%\",\"accountId\":\"%$accountId%\",\"zephyrBaseUrl\": \"%$zephyrBaseUrl%\",\"expirationTime\":360000}" "https://prod-vortexapi.zephyr4jiracloud.com/api/v1/jwt/generate" ')  do set jwtgenerated=%%i
set "$finaljwt=%jwtgenerated%"
echo %$finaljwt%

.sh file

echo "Generating a JSOM Web Token ... \n"
curl -o headers -s -d '{ "accessKey": "'"$accessKey"'" , "secretKey": "'"$secretKey"'" ,"accountId": "'"$accountId"'","zephyrBaseUrl": "'"$zephyrBaseUrl"'","expirationTime":360000}' -H "Content-Type: application/json" -XPOST https://prod-vortexapi.zephyr4jiracloud.com/api/v1/jwt/generate
jwt="$(cat headers | head -n 1)"
echo "The generated token: \n"
echo $jwt

This block doesn’t require changes, you can use it as it is.

The created JWT token is time-limited. The expirationTime parameter in the curl command specifies the expiration period in milliseconds: ..., "expirationTime":360000}' ...

Task properties

The following block specifies properties of the automation task to be created or edited. These properties are scripting analogues to task properties you see in the Create Automation Task dialog box:

.bat file

:: Task info
set "$taskName=My task"
set "$taskDescription=Task description"
set "$automationFramework=junit"
set "$projectKey=PROJ"
set "$versionName=Unscheduled"

:: Cycle info
set "$cycleName=CICD Automation"
set "$createNewCycle=true"
set "$appendDateTimeInCycleName=false"

:: Folder info
set "$folderName=Windows"
set "$createNewFolder=true"
set "$appendDateTimeInFolderName=true"
set "$assigneeUser=557058:XXXXXXXX-XXXX-XXXX-XXXX-da60ef125371"

:: Fully-qualitified name of the test result file
set "$resultPath=@\"C:/Test results/junit.xml\"

.sh file

# Task info
taskName="My task"
taskDescription="Task description"
automationFramework="junit"
projectKey="PROJ"
versionName="Unscheduled"

# Cycle info
cycleName="cycle1"
createNewCycle="true"
appendDateTimeInCycleName="false"

# Folder info
folderName="RegressionTests"
createNewFolder="true"
appendDateTimeInFolderName="true"
assigneeUser="557058:XXXXXXXX-XXXX-XXXX-XXXX-da60ef125371"

# Name of the test result file
resultPath="@//Applications/<user-name>/target/junit.xml"

Replace these values with your values.

Task info

Variable Description
taskName

The name of the automation task.

taskDescription

An arbitrary descriptive text for the task.

automationFramework

String that specifies the framework used for the test run. Case-insensitive. Create Automation Task dialog box:

  • Cucumber

  • Egg Plant

  • JUNIT

  • Selenium

  • SoapUI

  • TestNG

  • Tricentis Tosca

  • UFT

projectKey

ID of your Jira project:

Jira project id

Click the image to enlarge it.

versionName

A string that specifies the version of the test run. Default: Unscheduled.

Cycle info

Variable Description
cycleName

The name of the test execution cycle in Zephyr.

createNewCycle

true or false. Specifies whether Zephyr will create the specified cycle if it doesn’t exist.

appendDateTimeInCycleName

true or false. Specifies if Zephyr will add the date and time of the cycle creation to the cycle name.

Folder info

Variable Description
folderName

The name of the folder to which the execution cycle will be added in Zephyr.

createNewFolder

true or false. Specifies if Zephyr will create the specified folder if it doesn’t exist.

appendDateTimeInFolderName

true or false. Specifies, if Zephyr will add the date and timestamp of the folder creation to the folder name.

Other values

Variable Description
assigneeId

ID of the user account to whom the automation task will be assigned. For information on how to get this ID, see above.

resultFile

Fully-qualified name of the file storing test results.

If the file name has spaces, enclose it in quotes.

Task creation

The code below sends a request to Zephyr Squad to create an automation task with the specified properties. Zephyr will run this task and import the testing results from the specified file:

.bat file

echo "Creating and running an automation task ..."
curl -v -X POST  https://prod-vortexapi.zephyr4jiracloud.com/api/v1/automation/job/saveAndExecute  -H "Content-Type: multipart/form-data" -H "Content-Type: application/json" -H "accessKey: %$accessKey%" -H "jwt: %$finaljwt%" -F "jobName=%$taskName%" -F "jobDescription=%$taskDescription%" -F "automationFramework=%$automationFramework%" -F "projectKey=%$projectKey%" -F "versionName=%$versionName%" -F "cycleName=%$cycleName%" -F "createNewCycle=%$createNewCycle%" -F "appendDateTimeInCycleName=%$appendDateTimeInCycleName%" -F "folderName=%$folderName%" -F "createNewFolder=%$createNewFolder%" -F "appendDateTimeInFolderName=%$appendDateTimeInFolderName%" -F "assigneeUser=%$assigneeUser%" -F "file=%$resultPath%"

.sh file

echo "Creating and running an automation task ..."
curl -o headers -s -v -H "accessKey: $accessKey" -H "jwt: $jwt" -H "Content-Type: multipart/form-data" -H "Content-Type: application/json" -F "jobName=$taskName" -F "jobDescription=$taskDescription" -F "automationFramework=$automationFramework" -F "projectKey=$projectKey" -F "versionName=$versionName" -F "cycleName=$cycleName" -F "createNewCycle=$createNewCycle" -F "appendDateTimeInCycleName=$appendDateTimeInCycleName" -F "folderName=$folderName" -F "createNewFolder=$createNewFolder" -F "appendDateTimeInFolderName=$appendDateTimeInFolderName" -F "assigneeUser=$assigneeUser" -F "file=$resultPath" -XPOST https://prod-vortexapi.zephyr4jiracloud.com/api/v1/automation/job/saveAndExecute
result="$(cat  headers | head -n 1)"
echo "Test results: \n"
echo $result

You can use this code as it is. It doesn’t require changes.

Task update

The script file ends with the code that demonstrates how to update an existing automation task.

The code uses variables for the task info, cycle, folder and results file defined above.

The new variable here is taskId. It specifies the ID of the automation task to be updated. You get this ID in the response to the request that created the task.

Replace the taskId variable in the example script with the value that matches your automation task.

The rest of the code doesn’t require changes. You can use it as it is.

.bat file

:: Id of your automation task. You get it after the task is created.
:: set "$taskId=XXXXXXXXXXXXXXXXXXXX42E96E8863BF7EEE44BDB95FF763DA3E9C3BC4776886"
:: echo "Updating and running the automation task"
:: curl -v -X PUT  https://prod-vortexapi.zephyr4jiracloud.com/api/v1/automation/job/updateAndExecute  -H "Content-Type: multipart/form-data" -H "Content-Type: application/json" -H "accessKey: %$accessKey%" -H "jwt: %$finaljwt%"  -F "jobId=%$taskId%" -F "jobName=%$taskName%" -F "jobDescription=%$taskDescription%" -F "automationFramework=%$automationFramework%" -F "versionName=%$versionName%" -F "cycleName=%$cycleName%" -F "createNewCycle=%$createNewCycle%" -F "appendDateTimeInCycleName=%$appendDateTimeInCycleName%" -F "folderName=%$folderName%" -F "createNewFolder=%$createNewFolder%" -F "appendDateTimeInFolderName=%$appendDateTimeInFolderName%" -F "assigneeUser=%$assigneeUser%" -F "file=%$resultPath%"

.sh file

# Id of your automation task. You get it after the task is created.
# taskId="XXXXXXXXXXXXXXXXXXXX42E96E8863BF7EEE44BDB95FF763DA3E9C3BC4776886"
#echo "Update and run the automation task... "
#curl -o headers -s -v -H "accessKey: $accessKey" -H "jwt: $jwt" -H "Content-Type: multipart/form-data" -H "Content-Type: application/json" -F "jobId=$taskId" -F "jobName=$taskName" -F "jobDescription=$taskDescription" -F "automationFramework=$automationFramework" -F "versionName=$versionName" -F "cycleName=$cycleName" -F "createNewCycle=$createNewCycle" -F "appendDateTimeInCycleName=$appendDateTimeInCycleName" -F "folderName=$folderName" -F "createNewFolder=$createNewFolder" -F "appendDateTimeInFolderName=$appendDateTimeInFolderName" -F "assigneeUser=$assigneeUser" -F "file=$resultPath" -XPUT https://prod-vortexapi.zephyr4jiracloud.com/api/v1/automation/job/updateAndExecute
#result="$(cat  headers | head -n 1)"
#echo $result

Troubleshooting

The curl command might return the following error:

Please provide Jira mandatory field details.

This means that the Create issue screen in Jira has mandatory fields, but the curl request contains no information for those fields. In this case, you need to either pass information for the mandatory fields, or make those fields optional. The example below demonstrate how to pass data of mandatory fields in a curl command:

Suppose you have the Components and Reporter Jira mandatory fields. To pass data for them, you need to do the following:

1. Declare the mandatoryFields variable in the properties of your automation task:

.bat file

set "$mandatoryFields={\"components\":[{\"label\":\"my component\",\"value\":\"my component\",\"content\":\"my component\"}],\"reporter\":{\"label\":\"John Smith\",\"name\":\"John Smith\",\"id\":\"557058:59b29c62-9138-4e8c-86c4-96c6df\"}}"

.sh file

mandatoryFields='{"components":[{"label":"my component","value":"my component","content":"my component"}],"reporter":{"label":"John Smith","name":"John Smith","id":"557058:59b29c62-9138-4e8c-86c4-96c6df"}}'

2. Specify the mandatoryFields variable in the curl request:

.bat file

curl -X POST https://prod-vortexapi.zephyr4jiracloud.com/api/v1/automation/job/saveAndExecute -H "Content-Type: multipart/form-data" -H "Content-Type: application/json" -H "accessKey: %$accessKey%" -H "jwt: %$finaljwt%" -F "jobName=%$taskName%" -F "jobDescription=%$taskDescription%" -F "automationFramework=%$automationFramework%" -F "projectKey=%$projectKey%" -F "versionName=%$versionName%" -F "cycleName=%$cycleName%" -F "createNewCycle=%$createNewCycle%" -F "appendDateTimeInCycleName=%$appendDateTimeInCycleName%" -F "folderName=%$folderName%" -F "createNewFolder=%$createNewFolder%" -F "appendDateTimeInFolderName=%$appendDateTimeInFolderName%" -F "assigneeUser=%$assigneeUser%" -F "file=%$resultPath%" -F "mandatoryFields=%$mandatoryFields%"

.sh file

echo "Creating and running an automation task ..." curl -o headers -s -v -H "accessKey: $accessKey" -H "jwt: $jwt" -H "Content-Type: multipart/form-data" -H "Content-Type: application/json" -F "jobName=$taskName" -F "jobDescription=$taskDescription" -F "automationFramework=$automationFramework" -F "projectKey=$projectKey" -F "versionName=$versionName" -F "cycleName=$cycleName" -F "createNewCycle=$createNewCycle" -F "appendDateTimeInCycleName=$appendDateTimeInCycleName" -F "folderName=$folderName" -F "createNewFolder=$createNewFolder" -F "appendDateTimeInFolderName=$appendDateTimeInFolderName" -F "assigneeUser=$assigneeUser" -F "file=$resultPath" -F "mandatoryFields=$mandatoryFields" -XPOST https://prod-vortexapi.zephyr4jiracloud.com/api/v1/automation/job/saveAndExecute result="$(cat headers | head -n 1)" echo "Test results: \n" echo $result

If you want to pass mandatory field values via API, specify them in the request body of the API operation that creates an automation task.

See Also

Continuous Integration
Jenkins Integration
Bamboo Integration

Highlight search results