Introduction:
This document captures the steps required by the UCOP team to configure the custom Jira Jenkins integration plugin on Jira server. It also lists down the steps for configuring the jenkins jobs on the Jenkins server so that it works in tandem with the custom Jira Jenkins integration plugin.
Installation:
To install plugin we need the “.obr“ file(file with .obr extension). The .obr file contains the installable version off the plugin which can be installed into the Jira server using the standard plugin installation process as described below.
Obtain the .obr file
Login into the Jira instance as a Jira administrator
Go to “manage apps” in the administration section
Now go to “manage apps“ in the “Atlassian Marketplace“ section
Click on “Upload App“ and upload the file with .obr extension
A progress bar will appear which will indicate the progress and status of installation of the plugin on the Jira server
Configuration screens in the app:
Once the application is installed it will add a dropdown in the top Jira menu bar. This dropdown will have other sub-menus under it. Each submenu when clicked on will open up a different configuration screen. Each screen can be used to configure the custom Jira plugin.
The details of each submenus and its relevant configurations are as follows,
Field Configurations
This screen is used to configure the details that it needs to function as expected. There are seven configurations which needs to have values in order for the plugin to read them at runtime and take decisions based on the values provided. The details of each field are as follows,
Event Id of the Jenkins custom event: Custom plugin needs a custom event to be raised whenever when ever we try to trigger the Jenkins job from Jira. This custom event can be created in the in the administration section of Jira. Jira administrator will have to create this custom event, associate it with any notification scheme and make a note of its id. User configuring the plugin can then put this id of the custom event in this configuration textbox
‘Test Execution' issue type Id: This configuration needs the issue type id of the ‘Test Execution’ issue type. We can get this detail from the 'issues’ menu in the administration section.
‘Test' issue type id: This configuration needs the issue type id of the 'Test’ issue type. We can get this detail from the 'issues’ menu in the administration section
Id of the custom field which lists the Jenkins Jobs on the issue details screen: Custom plugin also comes with a custom field which is called as ‘Jenkins Job Selector'. Plugin admin needs to add this custom fields to proper screen(Create, Edit and view) in Jira. This field is used to map an already configured Jenkins job to a Xray Test. We will see about how to configure Jenkins job in the custom plugin in the ‘Job Mappings’ screen. In the current configuration we have to give the custom field id of this 'Jenkins Job selector’ field. Please note that we have to append 'customfield_' in front of the actual custom field id while specifying its value in the textbox.
Users of these groups can modify the Jenkins plugin data: Here we can provide the name of the group or groups(comma separated values) members of which can edit the data in different screen of this custom plugin. If this field is left empty then only the Jira administrator can access the details of configuration of the custom plugin and can view its different screens.
Default Jira Integration account to be user for updates: This is a Jira account which is a service account which is required by the plugin to make updates to xray test statuses and to pull attachments to Jira from Jenkins.
Custom field Id of the field which stores link for Xray between Tests and Test Execution: This is a custom field used by Xray to identify Test associated with Test Executions. Please note that we have to append 'customfield_' in front of the actual custom field id while specifying its value in the textbox.
Audit log
This screen shows the logs of different events happening in the plugin at runtime. Please note that these are the events which occur on the Jira side of the plugin. This screen doesn’t capture the details of the events(logs) from Jenkins jobs. Those will be available to the users of the jenkins under the console logs under each run of the job
Jenkins Connection Settings
This is the connection form which captures the url, username and password of the Jenkins server. Plugin uses this information to pull the list of jenkins jobs from the Jenkins server so that they can be configured here in the Jira in the ‘Job Mapping’ screen.
Job Mappings
This screen is used to configure Jenkins jobs in Jira. The primary job of this screen is to house all the mappings between the Jenkins jobs and their corresponding auth tokens in Jenkins. Please note that in order to trigger a jenkins job remotely from Jira we would need a auth token which can be easily configured in one of the steps in the Jenkins jobs itself. Plugin admin will have to specify this auth token while configuring the Jenkins job in the ‘Job Mapping’ screen. Plugin admin will have to make sure that this auth token is correct as there is no way plugin can determine it unless it triggers the job while processing the Jira trigger on 'Test Execution'
Mapping Xray Test to Jenkins Job:
We can map the jobs that we have configured in the “Job Mapping“ screen to an Xray Test while creating an Xray Test or while updating an existing Xray Test issue. we can select the Jenkins Job that we want to map to the current Xray Test using ‘Jenkins Job Selector' custom field. This way the configured job will get mapped to the current Xray Test issue. Please note that ‘Jenkins Job Selector’ field in the create and update screens will only list the jobs which are configured in the 'Job Mapping’ screen of the plugin.
Attaching the Xray Test to Xray Test Execution:
To trigger the Jenkins jobs connected to each Test and to get the result status and the TestComplete custom report, we need to trigger the process using a Test Execution. Test Execution acts as a container for different Tests. It can hold both Manual Tests as well as Jenkins related Tests under it. The first step would be test add a Test under a Test Execution. That can be done by adding the existing Tests that we created as a part of previous steps to the Test Execution.
Please note that we can attach data sheets required by the Jenkins Job(or TestComplete script) to the current TestExecution as an attachment.
Once this is done then we can trigger the custom event using the menu item that appears under each Test Execution in the 'More' options dropdown on the issue details screen.
Clicking on this menu-item will trigger each job connected to each Test under the current Test Execution. As and when the Jenkins job complete their execution the test results will be posted back to Jira along with the custom reports(which will be attached(one attachment per Xray Test) to Test Execution as attachments).
