App Connectors: JIRA

👤 This documentation is intended for Site Administrators and/or Database Administrators.

Connectors are Periscope Data’s built-in mechanisms for customers to connect to and ingest from popular data sources.

Note: Connectors are supported for customers with Data Engine on your Warehouse or Warehouse infrastructure. Site administrators can contact their Account Manager if interested in enabling Connectors.

<div>
<UL>
<LI><a href="#AddingaConnector">Adding a Connector</a></LI>
<LI><a href="#SetUpIngestion">Set Up Ingestion</a></LI>
<UL>
<LI><a href="#SetupDatabasePermissions">Setup Database Permissions</a></LI>
<LI><a href="#TablePermissions">Table Permissions</a></LI>
<LI><a href="#HowToSetUpIngestionforaConnector">How To Set Up Ingestion for a Connector</a></LI>
<LI><a href="#ReauthorizeaConnector">Reauthorize a Connector</a></LI>
<LI><a href="#SuspendIngestionforaConnector">Suspend Ingestion for a Connector</a></LI>
</UL>
<LI><a href="#DeleteaConnector">Delete a Connector</a></LI>
<LI><a href="#SupportedConnectors">Supported Connectors</a></LI>
</UL>
</div>
<HR>

<a name="AddingaConnector"></a>

Adding a Connector

To connect to JIRA, please make sure to have the following prior to attempting a connection:

Setup Requirements for Cloud-Hosted JIRA:

  1. A user account that has access to the issues, projects, worklogs, etc. that you want to ingest from JIRA. Periscope is only able to access the same objects that the user authenticating the integration has access to. See Atlassian’s documentation for more info about permissions in JIRA.
  2. An API token. See Atlassian Documentation for instructions for generating a token: https://confluence.atlassian.com/cloud/api-tokens-938839638.html
  3. Base URL: The URL for your JIRA site. For example: periscope.atlassian.net

Setup Requirements for Self-Hosted JIRA:

  1. If connecting to a self-hosted version of JIRA, you will need to make sure that these IP addresses are whitelisted for access to the JIRA server:
  • 52.23.137.21/32
  • 52.204.223.208/32
  • 52.204.228.32/32
  • 52.204.230.227/32
  1. HTTPs protocol support. To connect to a self-managed JIRA instance, your server must use HTTPs as the protocol. HTTP is not supported for security reasons. If your JIRA base URL is not HTTPs, you will receive a connection error.
  2. A user account that has access to the issues, projects, worklogs, etc. that you want to ingest from JIRA. Periscope is only able to access the same objects that the user authenticating the integration has access to. See Atlassian’s documentation for more info about permissions in JIRA. *Note: connections to Self-Hosted instances of JIRA use password authentication.
  3. Base URL: The URL for your JIRA site. For example: periscope.atlassian.net

To add a Connector, administrators can first click Settings menu in the bottom left hand corner.

Then, click the App Connections option:

In the top right corner, click the green Connect Source button.

From the Data Source Type dropdown, select the 'JIRA' option.

Enter the display name for the Connector in the Display Name section of the Connect Source menu.

Supply the JIRA username, API Key/ Password, and the Base URL in the appropriate boxes and click ‘Add’.

The process of establishing a new connection will take a few minutes as all of the tables that are associated with that source are being discovered. During this time a spinning Periscope Data icon will appear.

Available tables from the connected data source will appear as they become available.

In the event that the connection was unsuccessful, a Connection failed screen will appear.  Please verify that the JIRA username, API Key/ Password, and the Base URL that were entered are correct, and that the user has access to the issues, projects, worklogs, etc. that should be ingested.

<a name="SetUpIngestion"></a>

<a href="#top">Back to top</a>

Setup Ingestion

Once the JIRA Connector has been set up successfully, table permissions need to be taken into account.

<a name="SetupDatabasePermissions"></a>

<a href="#top">Back to top</a>

Setup Database Permissions

In order to ingest data into Periscope, certain database permissions will need to be updated the first time a connector is added.

Periscope Warehouse:

Periscope will create a new database user and grant the necessary permissions to load data into your warehouse from your connected Sources. Periscope will also grant the Read User the necessary schema permissions so you can query your Sources' data from within Periscope.

Data Engine on Your Warehouse:

In order to ingest data into your Redshift or Snowflake warehouse using Periscope App Connectors, Periscope requires a database user that can perform write operations on your database. Create permissions are required to create the necessary database objects to load and store your data. Read permissions on system tables are required to validate the existence and structure of existing database objects.

You will need to grant the following privileges to the database user you wish to use for the App Connectors function:

Snowflake:

<body>
<blockquote>
<br>GRANT CREATE ON WAREHOUSE warehouse_name TO periscope_ingest;
<br>GRANT CREATE ON DATABASE database_name TO periscope_ingest;
</blockquote>
</body>

Redshift:

<body>
<blockquote>
<br>GRANT CREATE ON DATABASE database_name TO periscope_ingest;
<br>GRANT SELECT ON ALL TABLES IN SCHEMA information_schema TO periscope_ingest;
<br>GRANT SELECT ON ALL TABLES IN SCHEMA pg_catalog TO periscope_ingest;
</blockquote>
</body>


You can add the above permissions to the existing Warehouse Admin created for Data Engine, but Periscope recommends providing an additional user to perform the App Connectors function.This will ensure that one service account is not responsible for too many actions.

If you want to query the data imported into your warehouse using the Connectors feature, you must also grant query permissions on the newly-created schema and its tables to the read user. The name of the schema will be the Display Name of the connected Source. After the first replication job has been completed, run the following commands to grant permissions to query the schema from within Periscope:

Snowflake:

<body>
<blockquote>
<br>GRANT USAGE ON SCHEMA database_name.schema_name TO ROLE periscope_read;
</blockquote>
</body>

Redshift:

<body>
<blockquote>
<br>GRANT USAGE ON SCHEMA schema_name TO periscope_read;
<br>GRANT SELECT ON ALL TABLES IN SCHEMA schema_name TO periscope_read;
</blockquote>
</body>

Note: The following IPs will need to be whitelisted for access to the destination database server:

  • 52.23.137.21/32
  • 52.204.223.208/32
  • 52.204.228.32/32
  • 52.204.230.227/32

<a name="TablePermissions"></a>

<a href="#top">Back to top</a>

Table Permissions

Tables in JIRA require different permissions. Please ensure that the user being used to connect to JIRA has access to all of the objects you may wish to ingest. For more information about permissions, see Atlassian’s documentation.

<div><table>
<thead>
<tr>
<th style="width:200px;text-align:left">Table</th>
<th style="width:200px;text-align:left">Ingestion Requirements</th>
</tr>
</thead>
<tbody>
<tr>
<td>changelogs</td>
<td>The “issues” table must also be selected for ingestion. When an issue is updated, all of the changelogs for that issue will also be ingested.<br><br>The Browse Projects <a href="https://confluence.atlassian.com/adminjiracloud/managing-project-permissions-776636362.html">project JIRA permission</a> is required.</td>
</tr>
<tr>
<td>issue_comments</td>
<td>The “issues” table must also be selected  for ingestion. When an issue is updated, all of the changelogs for that issue will also be ingested.<br><br>The Browse Projects <a href="https://confluence.atlassian.com/adminjiracloud/managing-project-permissions-776636362.html">project JIRA permission</a> is required.</td>
</tr>
<tr>
<td>issue_transitions</td>
<td>The “issues” table must also be selected for ingestion. When an issue is updated, all of the changelogs for that issue will also be ingested.<br><br>The Browse Projects <a href="https://confluence.atlassian.com/adminjiracloud/managing-project-permissions-776636362.html">project JIRA permission</a> is required.</td>
</tr>
<tr>
<td>Issues*</td>
<td>The Browse Projects <a href="https://confluence.atlassian.com/adminjiracloud/managing-project-permissions-776636362.html">project JIRA permission</a> is required.</td>
</tr>
<tr>
<td>project _categories</td>
<td>Periscope will only ingest data from the projects that are accessible to the user credentials that are <b>authenticating the integration.</b><br><br>If there are missing projects, please verify that the authenticating user has access to the missing projects.</td>
</tr>
<tr>
<td>project_types</td>
<td>Periscope will only ingest data from the projects that are accessible to the user credentials that are <b>authenticating the integration.</b><br><br>If there are missing projects, please verify that the authenticating user has access to the missing projects.</td>
</tr>
<tr>
<td>projects</td>
<td>Periscope will only ingest data from the projects that are accessible to the user credentials that are <b>authenticating the integration.</b>.<br><br>If there are missing projects, please verify that the authenticating user has access to the missing projects.</td>
</tr>
<tr>
<td>resolutions</td>
<td>The Administer JIRA <a href="https://confluence.atlassian.com/adminjiracloud/managing-global-permissions-776636359.html">global JIRA permission</a> is required.</td>
</tr>
<tr>
<td>roles</td>
<td>The Administer JIRA <a href="https://confluence.atlassian.com/adminjiracloud/managing-global-permissions-776636359.html">global JIRA permission</a> is required.</td>
</tr>
<tr>
<td>users</td>
<td>The Administer JIRA <a href="https://confluence.atlassian.com/adminjiracloud/managing-global-permissions-776636359.html">global JIRA permission</a> is required.</td>
</tr>
<tr>
<td>versions</td>
<td>The projects table must also be selected for ingestion.<br><br>The Browse Projects <a href="https://confluence.atlassian.com/adminjiracloud/managing-project-permissions-776636362.html">project JIRA permission</a> is required.</td>
</tr>
<tr>
<td>worklogs</td>
<td>For a worklog to be ingested, it must be set in JIRA as Viewable by All Users, or the authenticating user must be a member of the project role/group with permission to view the work log.</td>
</tr>
</tbody>
</table></div>

*Note on handling deleted issues: When an issue is hard-deleted in JIRA, the record for the issue will remain in your destination. JIRA’s API doesn’t include a way to identify deleted issues. To identify deleted issues, we suggest the following:

1. Create a status in JIRA that will be applied to issues you want to delete.

2. Before deleting the issue, apply the status.

3. Ingest the updated data into your destination.

4. Delete the issue in JIRA.

5. After the data is finished loading  use the fields__status__name field in your queries to filter issues with the deleted status you applied in step 2: For example:

<body>
<blockquote>SELECT * FROM periscope_jira.issues WHERE fields__status__name = 'Deleted'</blockquote></body>

<a name="HowToSetUpIngestionforaConnector"></a>

<a href="#top">Back to top</a>

How to Setup Ingestion

Tables listed for the connector are available for replication into the warehouse.  To select a table for replication, click on the box to the left of the table’s name.

Once a table has been selected, a list of columns that are available for replication will appear under Selected for Replication.

To select specific columns for replication, click on the box to the left of the column’s name.

Once the desired tables and columns have been selected, click Save in the bottom right.


To select an Update Interval, use the dropdown menu under Update Interval. Select the desired frequency for which the data should be replicated into the warehouse. 

Use the Anchor Time dropdown menu to select an Anchor Time. This is the time that the ingestion job will start. Be sure to allow enough time for loading the data when setting this time. If an ingestion job is not complete before the next scheduled interval, the interval will be skipped.

The Fetch Records Newer Than field indicates the date from which the replication of the data into the warehouse should begin.  Select the fetch records date by clicking into the Fetch Records Newer Than box.  

Note:  The fetch records date will default to one year in the past if a date is not manually selected.

Save the Update Interval, Anchor Time, and Fetch Records Newer Than data by clicking Save in the lower right corner of the section.

Note: The selected Update Interval, Anchor Time, and Fetch Records Newer Than date will apply for all tables and columns within a Connector that have been selected for ingestion and replication. Tables and columns within a given Connector cannot have differing Update Intervals, Anchor Times, and/or Fetch Records Newer Than dates.

It will take a few minutes for the data to be replicated into the warehouse. After a few minutes, navigate to the Database Connections tab from the Settings menu.

Select the appropriate warehouse from the dropdown menu and click on the refresh icon next to the schema for the warehouse.

Once the schema has been refreshed, the source name that was entered when the Connector was set up will appear in the schema browser and data will now be queryable.

<a name="ReauthorizeaConnector"></a>

<a href="#top">Back to top</a>

Reauthorize a Connector

In the event that changes have been made to the JIRA account associated with the JIRA Connector, the Connector will need to reauthorized.  To reauthorize an account, update the account information in the ingestion page and click Save.

This will prompt the connection to establish itself again. Once the connection is reestablished, the tables from the connection will appear.

<a name="SuspendIngestionforaConnector"></a>

<a href="#top">Back to top</a>

Suspend Ingestion for a Connector

In the event that replication for a Connector should be suspended, please select the Connector from the dropdown menu within the Ingestion page and toggle on Suspend Ingest from the Update Interval menu. Lastly, please click Save within this menu to save the changes made.

Note: It may be necessary to scroll within the menu to see this option.

<a name="DeleteaConnector"></a>

<a href="#top">Back to top</a>

Delete a Connector

To delete a Connector, navigate to the App Connections page from the Settings menu and select the name of the Connector to be deleted from the dropdown menu, and then click Delete in the bottom left.

In the Delete Source window, follow the instructions provided by typing the name of the Connector to be deleted in the field provided.

Once the name of the Connector has been entered, the Delete button will become available. Click the Delete button to delete the Connector.

<a name="SupportedConnectors"></a>

<a href="#top">Back to top</a>

Supported Connectors

Periscope Data currently supports Connectors with Google Adwords and JIRA.

The below list details future Connectors:

  • Facebook Ads
  • Google Sheets
  • Google Analytics

<a href="#top">Back to top</a>

Our support team is ready to help