JIRA Revenue Assurance Integration

Table of Contents

• Overview
• Configuration
  • What is Required?
    • Blue Triangle Portal 
    • JIRA System Settings 
  • Status Mapping
• Linking a Revenue Assurance Recommendation to JIRA
  • Creating a new ticket
  • Linking to an existing ticket
• Troubleshooting

Overview

Revenue Assurance now integrates directly with Jira, so your team can turn revenue-impacting recommendations into trackable work items without leaving your existing workflow. Link a recommendation to a new or existing JIRA ticket, keep statuses in sync, and see revenue attribution roll in automatically once a fix ships.

Configuration

What is Required? 

1. Blue Triangle Account Admin user with access to Site Settings in the portal. You can also reach out to your BT Representative with all the following info and we would be happy to assist. 
2. JIRA Admin user with access to System Settings
3. JIRA Admin user's email address
4. Your JIRA instance URL (example: https://your-domain.atlassian.net)
5. Atlassian API Token
6. Blue Triangle JIRA webhook URL
7. OPTIONAL: Webhook Signature Secret - used to verify incoming webhook requests from JIRA

Blue Triangle Portal 

1. Under to Site Settings scroll down to JIRA Configuration.
2. Under Atlassian Jira Connection, enter:
   • Instance URL
   • Account Email
   • API Token 
   • Webhook Signature Secret (optional) 
3. Beneath these fields is the Blue Triangle JIRA webhook URL. Copy this URL for your JIRA Admin to use in the JIRA side of the configuration. 
4. Click Test & Save Connection.

JIRA System Settings

This will require a JIRA Admin user with access to System Settings. Until this webhook is configured, status changes made directly in JIRA will not be reflected on the linked recommendation. You will need to update the recommendation status manually to keep the two in sync. 

First, configure the API token. Once configured it will need to be added to the BT Portal configuration. 

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Give it a label, for example Blue Triangle Recommendation Integration 
4. Set an expiration date — anywhere from 1 to 365 days (defaults to 1 year)
5. Click Create, then Copy to clipboard

Next, go to System Settings from the gear icon in the JIRA top toolbar. 

1. Under Advanced, select Webhooks
2. Click the 'Create New Webhook' button
3. Name it, for example Blue Triangle Recommendation Webhook
4. Replace the default URL with the webhook URL from the Site Settings page in BT Portal. 
5. Under JQL Query, enter status CHANGED (or scope it to a project, e.g. project = "YOURPROJECT" AND status CHANGED).
6. Under Issue Events, check only updated.
7. OPTIONAL Copy the secret. This will need to be added to the Portal configuration. 
8. Save

Status Mapping 

Once initial set up is complete, the configuration for Status mapping with appear on the right of the config window in Site Settings.

Recommendations use three statuses, which map to Jira statuses as follows:

If your JIRA workflow doesn't include one of these default statuses, that mapping is left blank — you can set it manually in JIRA Configuration. If a recommendation moves to a status that isn't mapped, you'll see a warning so you can update the mapping or choose the status by hand.

The portal remembers the project, assignee, status, and labels you used last time, so you don't have to reconfigure them on every new ticket.

Linking a recommendation to Jira

Open any recommendation and select Share to Jira. You will have the option to either create a new ticket or link to one that already exists via the tabs at the top of the modal.

Creating a new ticket

1. The recommendation's title becomes the JIRA ticket title.
2. All recommendation fields and metadata are added to the ticket description.
3. Choose the JIRA project, status, assignee, and any other fields available in your schema.
4. You can edit the ticket content before submitting.
5. If the ticket is created successfully, you'll see a confirmation with a link to the new ticket. If it fails for any reason, you'll see the error and can correct it and resubmit.

Linking to an existing ticket

1. Under the 'Link Existing Issue' Tab, paste in the Jira ticket URL directly, or
2. Choose from a suggested list of existing tickets that may match the recommendation.

Once linked, the JIRA ticket URL appears on the recommendation and is clickable. From there you can open the ticket in JIRA, unlink it, or link it to a different ticket instead.

Troubleshooting

A linked Jira ticket shows "We can’t show this space" when I click it.

The ticket was likely deleted or moved in Jira. Unlink the recommendation and, if needed, link it to a new ticket.

I updated a recommendation's status, but the Jira ticket didn't change — or vice versa.

Check that the status mapping in Jira Configuration covers the statuses you're using on both sides. If you're going from Jira to the portal, confirm the reverse webhook is configured (see “Setting up the reverse webhook” above).

I'm not sure which email address to enter in Account Email.

Use the email address of the Atlassian account that generated the API token — not necessarily your own login email, if someone else generated the token for you.