The Jira connector enables Mitto to pipe data from Jira Cloud and store the data in a database. The Mitto Jira Connector currently uses Version 3 of Jira’s REST API.  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 Mitto Jira connector will require a credential set that includes base_url , api_token , and user . It is recommended that you create an encrypted Generic Saved Credential to be used in the Mitto job configuration. It should be configured like:

{
  "base_url": "https://company.atlassian.net",
  "api_token": "tokenstring",
  "user": "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/
  • User: This is the admin username that was used to generate the above API token.

Anatomy of a Mitto Jira Job

Mitto Job Configuration for Jira.

Zuar is currently in the process of documenting Mitto 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 and jql.

input: {
    credentials: MY-JIRA-CREDS
    use: jira.iov2.input#JiraIssuesInput
    expand: names
    jql: project=Support
  }
  • Credentials: The name of the encrypted Generic Saved Credential created in Mitto’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)

Output: This is the standard output configuration section used to specify the location of where Mitto 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 Mitto 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, Mitto will create a new one.
  • Tablename: The name of the table for the data that will be outputted.
  • Use: Mitto function to specify how to output the data.

Example Job Configurations

Depending on your use case, you may consider configuring your Jira Mitto job to create a store and leverage upsert. Creating a store will enable the creation of additional jobs 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:

json blob
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!