Skip to main content

Jira Integration

Clarative can integrate with Atlassian Jira to automatically sync your JSM Assets as vendors and track Jira issues as vendor incidents. This integration supports both Jira Service Management (JSM) Assets for vendor management and Jira Issues for incident tracking.

Step 1: Connect Jira​

Permissions

You must be an admin to access this feature.

  1. Go to the Integrations page in Clarative by clicking the profile menu, clicking Settings and then clicking Integrations in the navigation bar.
  2. Click "Add Jira Integration."
  3. Click "Continue" to authorize Clarative's access to your Atlassian account.
  4. Review and accept the requested permissions, which include:
    • read:jira-work - View Jira issues
    • read:jira-user - Access user profiles and team information
    • read:servicedesk-request - See Jira Service Management tickets
    • read:servicemanagement-insight-objects - Access IT assets and configuration data
    • offline_access - Sync data without manual re-authorization
  5. Return to the integrations page and click "Finish Setup".
  6. Select your Atlassian instance from the list and click "Connect".

Your Jira instance is now connected to Clarative.

Step 2: Configure JSM Assets Integration​

Asset Filtering​

  1. From the Integrations page, click "Configure" on your Jira Integration and click "Jira Service Management Assets Ingest".
  2. Create an Asset Query Language (AQL) filter to ingest only the relevant assets. A common approach is to select a specific schema with a query like objectSchema = "ITAsset". You can find more information on AQL in the official documentation.
  3. Test your query by clicking "Test AQL Query" and verifying that relevant assets appear.

Asset Schema Mapping​

  1. Select your Asset Schema (e.g., "ITAsset").
  2. Map the required fields:
    • Name: Maps to vendor name in Clarative, select the corresponding Jira Asset field.
    • Domain: Maps to vendor domain in Clarative, select the corresponding Jira Asset field.

Custom Metadata Fields​

You can map additional JSM Asset fields to use as metadata in other integrations:

  1. In the Custom Metadata section, click "Add Metadata Field."
  2. Enter a Custom Metadata Field ID (e.g., "external_id"), this will be the field you can reference on the vendor object in Clarative.
  3. Select the corresponding JSM Asset Field from the dropdown.
  4. Click "Save" to apply your configuration.
Asset Sync

If you are using JSM Asset Metadata fields in the Issues integration, the JSM Assets integration must complete successfully before configuring the Jira Issues integration, as issue mapping may depend on asset metadata.

Step 3: Configure Jira Issues Integration​

SLA Mapping​

Map Jira issues to your vendor SLAs using Jira Query Language (JQL) queries to filter issues for each SLA. You can find more information on JQL in the official documentation.

  1. From the Integrations page, click "Configure" on your Jira Integration and click "Jira Issues Ingest".
  2. For each vendor SLA, choose your mapping approach:

Option 1: Custom JQL Filter​

Define a specific JQL query for each SLA.

For example to include issues in a project called "INCIDENT" that have a Root Cause field set to "External" and contain the vendor "GitHub" in the title, you would use the following query:

project = "INCIDENT" AND "Root Cause" = "External" AND summary ~ "GitHub"

Option 2: Templated JQL with Metadata​

Use JSM Asset metadata in your JQL filters with handlebar syntax. This will allow you to have a global default filter that uses specific vendor metadata, like a domain or external ID, to attach issues to each vendor's SLA.

For example, if you imported vendors via the JSM Asset integration and included a domain metadata field, and if your issues have a "Vendor" field that links to the appropriate asset, you could use the following default query:

vendor in aqlFunction("Domain LIKE {{ domain }}")

Option 3: Mixed Approach​

You can use templated queries with vendor-specific values. You may want to do this if a single vendor has multiple SLAs.

For example, if you want to use a similar filter to the default filter but separate SLAs for Atlassian BitBucket vs Atlassian Jira, you could use the following queries to additionally filter by title:

project = "INCIDENT" AND vendor in aqlFunction("Domain LIKE {{ domain }}") AND summary ~ "BitBucket"
project = "INCIDENT" AND vendor in aqlFunction("Domain LIKE {{ domain }}") AND summary ~ "Jira"

Incident Field Mapping​

Configure how Jira issue fields map to Clarative incident properties:

  • Start Date: Select the Jira field for incident start time
  • End Date: Select the Jira field for incident resolution time
  • Incident Level: Choose how to map Jira priority/severity to Clarative incident levels
  • Additional Query Fields: Add extra fields for filtering in JQL queries

Incident Level Mapping​

Map Jira field values to Clarative incident severity levels. For example, if using the Jira system field "Priority", you might use the following mapping:

Clarative ValueJira Level
CriticalHighest
MajorHigh
MinorLow
MaintenanceLowest

Test Your Configuration​

  1. Use the "Test" button next to each SLA mapping to validate your JQL queries.
  2. Review the test results to ensure data is mapping correctly.
Vendor Metadata Templates

You can reference JSM Asset metadata in JQL queries using the syntax {{ field_name }}. These templates are populated with actual values when the integration runs. Be sure to include the spaces between the handlebars like {{ field_name }}, not {{field_name}}.

Data Sync​

  • JSM Assets are synced as vendors and will populate your vendor database
  • Jira Issues matching your SLA JQL queries are tracked as incidents
  • Data syncs automatically without requiring manual re-authorization
  • Initial sync may take some time depending on the volume of assets and issues
Sync Dependencies

The Jira Issues integration requires JSM Assets to sync successfully first if you're using asset metadata in your JQL templates.

Questions?​

If you need help or have questions, contact us anytime at support@clarative.ai.