Introductory Jira

7 minute read

Introduction

This tutorial provides instructions for the 4 step process to create a functional plugin called SampleJira which retrieves issues from a remote AtlassianJira server.

The four step plugin creation process

  1. Create Plugin Workspace.

  2. Define plugin spec and generate plugin.

  3. Implement additional logic.

  4. Build plugin and test.

Prerequisites

These are assumptions for this Tutorial.

  1. An active CloudBees CD instance.

  2. Internet connection.

  3. pdk installed and set up.

In this tutorial we will use a public Jira instance of the Jenkins CI project, but you can use any Jira instance you have access to.

Step 1 : Create plugin workspace

After making sure pdk is available in your PATH, you can create a plugin workspace.

Change to your working directory

cd ~/work

Call pdk as follows

`pdk generate workspace`

In the interactive prompt type SampleJira as plugin name. For the rest of the options (except the plugin language) which are all optional, choose defaults if available or provide your own values. For the plugin language you should use 'groovy'

GeneratedWorkspace

The generated workspace would have the following 2 files:

Files inWorkspace

Step 2: Define plugin spec and generate plugin

The pluginspec.yaml has 2 sections one for configuration and the other for procedures.

Update configuration section of YAML

To interact with Jira we need the following config values:

  1. Jira endpoint

  2. Username for authorization.

  3. Password for authorization.

Replace the configuration section with following:

# Plugin configuration description configuration: # A set of fields will be added to process debug level in the configuration hasDebugLevel: true parameters: - name: config documentation: The name for the created configuration required: true type: entry label: Configuration Name - name: desc documentation: Description for the configuration required: false type: entry label: Description - name: endpoint documentation: Third-party endpoint to connect to (Jira server URL), e.g. 'http://jira:8080/' required: true type: entry label: Endpoint - name: basic_credential documentation: Jira credentials required: false type: credential label: Jira Credential

Rename the auto-generated specification called credential to basic_credential and set the 'required' attribute to false.

Update procedures section

We will implement a procedure called "GetIssue". Replace the procedures section with following:

procedures: - name: 'GetIssue' description: 'Saves details for Jira issue to the properties' # configuration field will be generated automatically hasConfig: true shell: 'ec-groovy' parameters: - name: jiraKey documentation: Key of the issue to retrieve. required: true type: entry label: Jira Key outputParameters: issueStatus: 'Name of the status of the retrieved issue'

Generate plugin

Execute the following command from the root level directory of the plugin workspace.

`pdk generate plugin`

After execution, it should look as follows.

image

With this step, plugin generation is complete.

Review the auto-generated code

This section is provided to give a perspective on how the boiler plate generated code looks like and what it means.

The dsl/properties folder has the following structure:

  • groovy/lib

  • groovy/scripts

  • perl/core

Important: Do not modify any file under core folders. Core folders has plugin-related internal code, which should not be edited by plugin developer.

The only folder that could be modified is the groovy/lib folder.

Notice that dsl/properties/groovy/lib/SampleJira.groovy has been auto-generated and contains the following code.

import com.cloudbees.flowpdf.* /** * SampleJira */ class SampleJira extends FlowPlugin { @Override Map<String, Object> pluginInfo() { return [ pluginName : '@PLUGIN_KEY@', pluginVersion : '@PLUGIN_VERSION@', configFields : ['config'], configLocations: ['ec_plugin_cfgs'], defaultConfigValues: [:] ] } /** * getIssue - GetIssue/GetIssue * Add your code into this method and it will be called when the step runs * @param config (required: true) * @param jiraKey (required: true) */ def getIssue(StepParameters p, StepResult sr) { /* Log is automatically available from the parent class */ log.info( "getIssue was invoked with StepParameters", /* runtimeParameters contains both configuration and procedure parameters */ p.toString() ) Context context = getContext() // Setting job step summary to the config name sr.setJobStepSummary(p.getParameter('config').getValue() ?: 'null') sr.setReportUrl("Sample Report", 'https://www.cloudbees.com/') sr.apply() log.info("step GetIssue has been finished") } // === step ends === }

Each plugin procedure has one or more steps. The auto-generated code for the step “GetIssue” is located in dsl/procedures/GetIssue/steps/GetIssue.groovy and contains following:

$[/myProject/groovy/scripts/preamble.groovy.ignore] SampleJira plugin = new SampleJira() plugin.runStep('GetIssue', 'GetIssue', 'getIssue')

Step 3: Implement additional logic

Add necessary library imports

We will use a framework package named com.cloudbees.flowpdf.client to perform HTTP requests and groovy.json.JsonOutput to transform the received result to JSON. Add imports to the head of the SampleJira.groovy:

import com.cloudbees.flowpdf.* import com.cloudbees.flowpdf.client.* import groovy.json.JsonOutput

Add default config values:

Edit pluginInfo function to set default values for parameters. Notice that authScheme is set to the value basic.

@Override Map<String, Object> pluginInfo() { return [ pluginName : '@PLUGIN_KEY@', pluginVersion : '@PLUGIN_VERSION@', configFields : ['config'], configLocations: ['ec_plugin_cfgs'], defaultConfigValues: [ authScheme : 'basic' ] ] }

Modify getIssue step code

The auto-generated function in step looks as follows:

/** * getIssue - GetIssue/GetIssue * Add your code into this method and it will be called when the step runs * @param config (required: true) * @param jiraKey (required: true) */ def getIssue(StepParameters p, StepResult sr) { /* Log is automatically available from the parent class */ log.info( "getIssue was invoked with StepParameters", /* runtimeParameters contains both configuration and procedure parameters */ p.toString() ) Context context = getContext() // Setting job step summary to the config name sr.setJobStepSummary(p.getParameter('config').getValue() ?: 'null') sr.setReportUrl("Sample Report", 'https://www.cloudbees.com/') sr.apply() log.info("step GetIssue has been finished") }

Modify the logic as follows:

/** * getIssue - GetIssue/GetIssue * Add your code into this method and it will be called when the step runs * @param config (required: true) * @param jiraKey (required: true) */ def getIssue(StepParameters p, StepResult sr) \{:: /* Log is automatically available from the parent class _/ log.info( "getIssue was invoked with StepParameters", /_ runtimeParameters contains both configuration and procedure parameters */;; p.toString() + ) + String issueIdentifier = p.getRequiredParameter('jiraKey').getValue() + def requestParams = [;; method: 'GET', path : sprintf('/rest/api/2/issue/%s', issueIdentifier), query : [ fields: 'summary,comment,status' ] + ] + // Initializing the client and the request def restClient = getContext().newRESTClient() def request = restClient.newRequest(requestParams) + // Executing the request def issue = restClient.doRequest(request) log.debug("Response: " + issue.dump()) + // Saving issue as a JSON def jsonIssuesStr = JsonOutput.toJson(issue) log.debug("Issue JSON: " + jsonIssuesStr) + sr.setOutcomeProperty('/myCall/issue', jsonIssuesStr) String issueStatus = issue?.fields?.status?.name ?: 'no status' log.info("Issue status is: $\{issueStatus}") + sr.apply() log.infoDiag("step GetIssue has been finished") } // === step ends ===

Set

An output parameter is set as part of the StepResult object. Add the following code inside of the step function in SampleJira.groovy before the sr.apply() call.

sr.setOutputParameter('issueStatus', issueStatus)

Set pipeline, job and jobStep summary

Set all the 3 summaries - pipeline summary, job summary and jobStep summary. Add the following code inside of the step function in SampleJira.groovy before the sr.apply() call.

sr.setPipelineSummary("Issue number", issueIdentifier) sr.setJobSummary("Issue status is ${issueStatus}") sr.setJobStepSummary("Saved json representation of ${issueIdentifier}")

Review SampleJira.groovy

This is a summary of how SampleJira.groovy looks like after you make the changes.

import com.cloudbees.flowpdf.* import com.cloudbees.flowpdf.client.* import groovy.json.JsonOutput /** * SampleJira */ class SampleJira extends FlowPlugin { @Override Map<String, Object> pluginInfo() { return [ pluginName : '@PLUGIN_KEY@', pluginVersion : '@PLUGIN_VERSION@', configFields : ['config'], configLocations: ['ec_plugin_cfgs'], defaultConfigValues: [ authScheme : 'basic' ] ] } /** * getIssue - GetIssue/GetIssue * Add your code into this method and it will be called when the step runs * @param config (required: true) * @param jiraKey (required: true) */ def getIssue(StepParameters p, StepResult sr) { /* Log is automatically available from the parent class */ log.info( "getIssue was invoked with StepParameters", /* runtimeParameters contains both configuration and procedure parameters */ p.toString() ) String issueIdentifier = p.getRequiredParameter('jiraKey').getValue() def requestParams = [ method: 'GET', path : sprintf('/rest/api/2/issue/%s', issueIdentifier), query : [ fields: 'summary,comment,status' ] ] // Initializing the client and the request def restClient = getContext().newRESTClient() def request = restClient.newRequest(requestParams) // Executing the request def issue = restClient.doRequest(request) log.debug("Response: " + issue.dump()) // Saving issue as a JSON def jsonIssuesStr = JsonOutput.toJson(issue) log.debug("Issue JSON: " + jsonIssuesStr) sr.setOutcomeProperty('/myCall/issue', jsonIssuesStr) String issueStatus = issue?.fields?.status?.name ?: 'no status' log.info("Issue status is: ${issueStatus}") // Setting outputs sr.setOutputParameter('issueStatus', issueStatus) sr.setPipelineSummary("Issue number", issueIdentifier) sr.setJobSummary("Issue status is ${issueStatus}") sr.setJobStepSummary("Saved json representation of ${issueIdentifier}") sr.apply() log.infoDiag("step GetIssue has been finished") } // === step ends === }

Step 4: Build, install, and test

Build the plugin from root directory of the SampleJira plugin workspace. :

pdk build

It should look something like this:

image

Congratulations! You have now created a functional plugin.

Install and promote the plugin

Go to your CloudBees CD instance, login and navigate to the Plugin Manager page which lists all plugins.

image

Click on "Install from File/URL" tab, click Choose File, select your build/SampleJira.zip file and click upload:

image

You will be redirected to the plugin manager page. Find your plugin SampleJira, and click "Promote" link.

After promotion the page would be automatically refreshed.

Create a pipeline and configure the plugin

After your plugin is installed, navigate to the Pipelines page and click "New" in the top right corner of the web page.

image

Click Create New, enter Sample Jira Pipeline, choose your project, click Ok.

Now you’re in your pipeline editor. Click "Add +" on the task explorer, enter "GetIssue", click "Select Task Type", scroll down the plugin list and click on your GetIssue procedure below the plugin name:

image

Now click on your procedure name and "Define" link. You will see:

image

Click on input parameters to confirm that this procedure sees all the parameters as per the YAML spec.

Provide "JENKINS-1" as a value for the "Jira Key" parameter.

image

Click on the triangle at the right of "Configuration Name" parameter input field and choose the "New Configuration" item.

For this showcase we are using Jenkins-CI public issue tracker. Provide a meaningful name and description for the configuration. Use 'https://issues.jenkins.io/' as an Endpoint. This public tracker doesn’t require authentication to browse issues, so we can leave the credential field empty.

image

Save configuration and select it on the Input Parameters form.

This concludes the plugin as well as the pipeline setup.

Running the pipeline

In the flow pipeline page click "Run" on the pipeline you have created. In the Popup menu, click "New Run" and in the modal dialog that shows up, click "Run" again. You will see the following:

image

Click on the summary link:

image

Click on the "1. GetIssue". You can see that the special step 'flowpdk-setup' was performed to transfer the dependencies.

image

Click on the "Parameters" tab to see the output parameter:

image

Click on the "Properties" tab to see the JSON representation in the "issue" job property:

image

Click back on the "Steps" link and open the "GetIssue" step log link:

image

We now have a minimal working plugin for Jira.

Summary

The following diagram is provided as a reference to enunciate the flow of control using flowpdf-groovy.

image