# 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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/), 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** :ref:`credentials` to be used in the Zuar Runner
job configuration. It should be configured like:


```json
{
  "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/](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`.

```json
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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#expansion)
  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/](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 </databases/database-urls.html>`__.

```json
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](/jobs/io/store) and leverage
[upsert](/jobs/io/upsert). Creating a store will enable the creation
of[ 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:**
```json
{
  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:**

.. figure:: assets/jira__json.png

   nested "components" node
    
```json
{
  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](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). If
applicable, please refer to the status code guide to help troubleshoot job
failures. Otherwise [file a support ticket!](https://zuar.com/support)