Jira

Authentication methods

Atlassian Cloud, API Token

To generate a token:

1. Visit https://id.atlassian.com/manage-profile/security/api-tokens

2. Create an API token

3. Use it in conjunction with your username, typically your email address

API Tokens are different to the API keys that you create in the Admin app.

If you generate an API key and use it, the connector will still authenticate successfully but it'll likely have no Jira privileges. In the case of inbound Issue syncs, it may complete successfully with zero records.

Inbound Syncs

You can add a JQL clause to filter the issues in the sync.

The following streams are supported:

• issues

  • issue_worklogs *

  • issue_comments *

  • issue_links

  • issue_watchers *

• permissions

• users

• issue_types

• issue_link_types

• group_users

• groups

• project_categories

• status_categories

• statuses

• resolutions

• priorities

• agile_boards

• projects

*Please note that selecting these child streams of issues may add significant overhead to the initial sync, as these related objects often need to be fetched by individual issue.

Outbound Syncs

You can sync outbound to the following objects:

Issues

You can use the Create or Upsert sync strategies to create and/or edit Jira issues.

When linking to other objects like Assignee, Project, Reporter, Issue Type etc, the Jira API uses various combinations of id, name, key to reference these. The Omnata field mapper will name the target fields accordingly. For example, mapping to "Assignee Account ID" from a column containing an account id will link the appropriate assignee. Similarly, mapping to "Issue Type Name" from a column containing the name of a valid issue type, will link to that issue type.

Service Desk Organizations

Service Desk Organizations in Jira, are uniquely identified by name. This means that any existing Organizations will be matched, avoiding duplicates or errors.

Any Organization Detail field can be mapped to as well, these will be applied whenever the values change.

Functions

JQL_QUERY

Executes a JQL query and returns a specific page of results.

Parameters:

• CONNECTION_SLUG (VARCHAR): The slug of the connection to query

• QUERY (VARCHAR): The JQL query

• START_INDEX (INT): The offset to return, use 0 to start from the beginning

• RECORD_LIMIT (INT) The number of records to return, starting from the offset

Examples:

select RECORD
from table(OMNATA_JIRA_PLUGIN.UDFS.JQL_QUERY(
                'my-jira-connection',
                'project=KAN AND updated > -1d',
                0,
                50));

CREATE_ISSUE

Creates a Jira issue.

Parameters:

• CONNECTION_SLUG (VARCHAR): The slug of the connection to query

• SUMMARY (VARCHAR): The summary of the issue

• DESCRIPTION (VARCHAR): The description of the issue

• PROJECT_KEY (VARCHAR): The key of the project the issue will belong to

• ISSUE_TYPE (VARCHAR): The issue type to assign to the issue

• OTHER_FIELDS (OBJECT): Other field values to set on the issue

• ONLY_WHEN (BOOLEAN): Whether to create the issue or not, useful for conditional creation when joining to another source table

Returns:

• ISSUE_ID (VARCHAR): The new issue ID

• ISSUE_KEY (VARCHAR): The new issue key

Examples:

select *
from table(OMNATA_JIRA_PLUGIN.UDFS.CREATE_ISSUE(
                'my-jira-connection',
                'Please help',
                'I cannot access my files',
                'CS',
                'Task',
                {},
                TRUE));

CREATE_OR_UPDATE_ORGANIZATION

Creates an Organization if it does not exist, or updates it if it does.

Parameters:

• CONNECTION_SLUG (VARCHAR): The slug of the connection to query

• NAME (VARCHAR): The name of the organization

• SERVICE_DESKS (ARRAY, optional): An array of Service desk names or IDs (numeric) to associate the organization with.

• DETAILS (OBJECT, optional): Organization details to set. This is keyed by the field name and the value is the value to set (either a single value or an array of values)

Returns:

• ID (NUMERIC): The organization ID

• UUID (VARCHAR): The organization UUID

• NAME (VARCHAR): The organization name

• RESULT (OBJECT): The raw result from the Jira API

Examples:

select *
from table(OMNATA_JIRA_PLUGIN.UDFS.CREATE_OR_UPDATE_ORGANIZATION(
                'my-jira-connection',
                'ACME inc',
                [123],
                {}));

FETCH_ALL_ISSUE_FIELDS

Fetches a list of all issue fields, standard and custom.

Parameters:

• CONNECTION_SLUG (VARCHAR): The slug of the connection to query

Returns:

• NAME (VARCHAR): The name of the field

• ID (VARCHAR): The id of the field

• KEY (VARCHAR) The key of the field

• CUSTOM (BOOLEAN): Whether the field is custom or not

• NAVIGATE (BOOLEAN): Whether the field is navigable or not

• ORDERABLE (BOOLEAN): Whether the field is orderable or not

• SCHEMA (OBJECT): The schema of the field

• SEARCHABLE (BOOLEAN): Whether the field is searchable or not

• UNTRANSLATED_NAME (VARCHAR): The untranslated name of the field

• CLAUSE_NAMES: (ARRAY): The clause names of the field

• RAW_METADATA (OBJECT): The raw metadata from the Jira API

Examples:

select RECORD
from table(OMNATA_JIRA_PLUGIN.UDFS.FETCH_ALL_ISSUE_FIELDS(
                'my-jira-connection',));

FETCH_PROJECTS

Fetches a list of all projects.

Parameters:

• CONNECTION_SLUG (VARCHAR): The slug of the connection to query

Returns:

• PROJECT (OBJECT): The project metadata

Examples:

select PROJECT
from table(OMNATA_JIRA_PLUGIN.UDFS.FETCH_PROJECTS(
                'my-jira-connection',));