Jira¶

The Jira connector enables Zuar Runner to pipe data from Jira Cloud or Jira Server and store the data in a database. The Zuar Runner Jira Connector currently uses Version 3 of Jira’s REST API. However, this can be adjusted to older versions depending on your use case be leveraging the api_version: parameter within the Zuar Runner job configuration. There are a variety of endpoints that are available via GET requests and these endpoints are well documented here: The Jira Cloud platform REST API, most of which are retrievable via the Issues endpoint and a Store job. See below for details.

Authentication/Credentials¶

The Zuar Runner Jira connector will require a credential set that includes base_url , api_token , and user . It is recommended that you create an encrypted Generic credentials to be used in the Zuar Runner job configuration. It should be configured like:

{
  "base_url": "https://company.atlassian.net",
  "api_token": "tokenstring",
  "username": "username@company.com"
}

Base URL: The base url is in reference to your company’s Jira deployment. This can simply be found by navigating to your Jira instance within the browser and retrieving the address from the url. Example: https://company.atlassian.net
API Token: This token should be created by the admin user that has access to Jira. Follow Jira’s documentation to Create an API token here: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
Username: This is the admin username that was used to generate the above API token.

Anatomy of a Zuar Runner Jira Job¶

Zuar Runner Job Configuration for Jira.

Note

Zuar is currently in the process of documenting Zuar Runner Job Configuration for Jira Customer Service Desk. These have different use requirements and may have different configuration requirements. Contact Zuar for details about Jira Service Desk.

Jira¶

Input: The input section within a Jira job configuration should consist at minimum of credentials and use. It also accepts additional parameters expand, jql, and api_version.

input: {
    credentials: MY-JIRA-CREDS
    use: jira.iov2.input#JiraIssuesInput
    expand: names
    jql: project=Support
    api_version: 3
  }

Credentials: The name of the encrypted Generic Saved Credential created in Zuar Runner’s credential store. Again, this consists of base_url , api_token , and user (see above reference for creating the saved credential).
USE: The use section specifies the use of the input for using jobs to call Jira’s REST API. The generic input for most Jira jobs will be jira.iov2.input#JiraIssuesInput.
Expand: Optional Parameter set to None by default - Use expand to include additional information about the issues in the response. This parameter accepts a comma-separated list. Example: Expand options for the Issues endpoint include:

renderedFields Returns field values rendered in HTML format.

names Returns the display name of each field.

schema Returns the schema describing a field type.

transitions Returns all possible transitions for the issue.

editmeta Returns information about how each field can be edited.

changelog Returns a list of recent updates to an issue, sorted by date, starting from the most recent.

versionedRepresentations Returns a JSON array for each version of a field’s value, with the highest number representing the most recent version. Note: When included in the request, the fields parameter is ignored (Not applicable as we do not currently enable the fields parameter and instead get all fields)

JQL: Optional Parameter set to None by default. The advanced search allows you to build structured queries using the Jira Query Language (JQL) to search for issues. You can specify criteria that you can’t define in the quick or basic searches (the ORDER BY clause, for example). View Jira Documentation for more information here: https://support.atlassian.com/jira-service-management-cloud/docs/use-advanced-search-with-jira-query-language-jql/
API Version: Optional parameter set to 3 by default. If you have are hosting Jira Server and require an older version of the API, this can be set as an integer within this parameter, e.g. api_version: 2
Output: This is the standard output configuration section used to specify the location of where Zuar Runner should pipe the data retrieved from the GET request. The minimum configuration for the output section requires dbo, schema, tablename, use.

Note

There may be slight variation to this section depending on your output destination database. Please consult documentation for your specific database from the Zuar Runner help docs.

output: {
   dbo: postgresql://localhost/analytics
   schema: jira
   tablename: issues
   use: call:mitto.iov2.db#todb
 }

DBO: This is the database string used to connect to the destination database for outputting data.
Schema: The schema under which the table will be created. If a schema does not already exist, Zuar Runner will create a new one.
Tablename: The name of the table for the data that will be outputted.
Use: Zuar Runner function to specify how to output the data.

Example Job Configurations¶

Depending on your use case, you may consider configuring your Jira Zuar Runner job to create a store and leverage upsert. Creating a store will enable the creation of:doc:` additional jobs </jobs/store-input/>` to un-nest the nodes within the JSON blob that is retrieved from the GET request.

Get all Issues, expand names, create a store, and ignore avatarUrls:

{
  input: {
    credentials: MY-JIRA-CREDS
    expand: names
    use: jira.iov2.input#JiraIssuesInput
  }
  output: {
    dbo: postgresql://localhost/analytics
    schema: jira
    tablename: issues
    use: call:mitto.iov2.db#todb
  }
  steps: [
    {
      transforms: [
        {
          ignores: [
            $.*.avatarUrls
          ]
          use: mitto.iov2.transform#ExtraColumnsTransform
        }
        {
          use: mitto.iov2.transform#ColumnsTransform
        }
      ]
      use: mitto.iov2.steps#Input
    }
    {
      use: mitto.iov2.steps#CreateTable
    }
    {
      transforms: [
        {
          use: mitto.iov2.transform#FlattenTransform
        }
      ]
      use: mitto.iov2.steps#Output
    }
    {
      use: mitto.iov2.steps#CollectMeta
    }
  ]
  store: {
    key: $.id
    updated_at: $.fields.updated
  }
}

Create a table using a Store job that references the store created above (Issues) and extract an array of data stored within the Components node of the JSON retrieved by the Issues GET request:

../_images/jira__json.png — nested “components” node¶

{
  input: {
    jpath: $.fields.components[*]
    members: [
      {
        name: issue_id
        value: $.id
      }
    ]
    name: jira_issues
    use: mitto.iov2.input#StoreInput
  }
  output: {
    dbo: postgres://localhost/analytics
    schema: jira
    tablename: issues__components
    use: call:mitto.iov2.db#todb
  }
  steps: [
    {
      transforms: [
        {
          use: mitto.iov2.transform#ExtraColumnsTransform
        }
        {
          use: mitto.iov2.transform#ColumnsTransform
        }
      ]
      use: mitto.iov2.steps#Input
    }
    {
      use: mitto.iov2.steps#CreateTable
    }
    {
      transforms: [
        {
          use: mitto.iov2.transform#FlattenTransform
        }
      ]
      use: mitto.iov2.steps#Output
    }
    {
      use: mitto.iov2.steps#CollectMeta
    }
  ]
}

Error Troubleshooting¶

The Jira Cloud platform REST API uses the standard HTTP status codes. If applicable, please refer to the status code guide to help troubleshoot job failures. Otherwise file a support ticket!