Jira Integration

Table of contents

1. Overview
2. Prerequisites
3. Setup Instructions
   1. Step 1: Create Jira API Token
   2. Step 2: Configure ButterStack Integration
   3. Step 3: Field Mapping
   4. Step 4: Webhook Configuration
   5. Step 5: Custom Fields Setup
4. Advanced Configuration
   1. JQL Filters
   2. Workflow Automation
   3. Status Mapping
5. Integration Features
   1. Asset Linking
   2. Bulk Operations
   3. Reporting
6. Troubleshooting
   1. Common Issues
7. Best Practices
8. API Examples
   1. Create Issue with Asset
9. Next Steps

Overview

ButterStack integrates with Jira to synchronize tasks, track asset assignments, and provide visibility into your development pipeline. This integration enables automatic task updates and two-way synchronization.

Prerequisites

• Jira Cloud or Server instance
• Jira administrator access
• API token or OAuth credentials
• ButterStack project with admin rights

Setup Instructions

Step 1: Create Jira API Token

1. Log in to your Jira account
2. Navigate to Account Settings → Security → API tokens
3. Click Create API token
4. Name it “ButterStack Integration”
5. Copy the generated token

Step 2: Configure ButterStack Integration

1. In ButterStack, go to Settings → Integrations
2. Click Add Integration → Jira
3. Enter your Jira details:

Jira URL: https://your-domain.atlassian.net
Email: your-email@company.com
API Token: [paste your token]
Default Project: PROJ

Copy URL Template

Step 3: Field Mapping

Configure how ButterStack fields map to Jira:

Step 4: Webhook Configuration

Enable real-time updates from Jira:

1. In Jira, go to Settings → System → Webhooks
2. Click Create a webhook
3. Configure:
   • Name: ButterStack Integration
   • URL: https://app.butterstack.com/webhooks/jira/YOUR_PROJECT_ID
   • Events: Select relevant events
     • ✅ Issue created
     • ✅ Issue updated
     • ✅ Issue deleted
     • ✅ Comment added

Step 5: Custom Fields Setup

Create custom fields in Jira for ButterStack data:

1. Go to Settings → Issues → Custom fields
2. Create these fields:
   • ButterStack Asset ID (Text field)
   • Asset Status (Select list)
   • Build Version (Text field)
   • Asset Type (Select list)

Advanced Configuration

JQL Filters

Configure which Jira issues sync with ButterStack:

project = "GAME" AND type in (Task, Bug) AND status != Done

Copy JQL

Workflow Automation

Set up Jira automation rules:

Trigger: Issue transitioned to "In Progress"
Action: Create ButterStack task
Condition: Issue has component "Assets"

Status Mapping

Map Jira statuses to ButterStack asset states:

Jira Status → ButterStack Status
To Do       → Pending
In Progress → Active
In Review   → Under Review
Done        → Completed

Integration Features

Asset Linking

Link assets directly to Jira issues:

1. In ButterStack asset view, click Link to Jira
2. Search for issue by key or summary
3. Select issue to create link
4. Asset status syncs automatically

Bulk Operations

Perform bulk actions on linked issues:

• Update multiple asset statuses
• Bulk assign to Jira users
• Mass comment on issues
• Batch transition workflows

Reporting

Access integrated reports:

• Asset completion by sprint
• Time tracking across assets
• Issue-to-asset mapping
• Team velocity metrics

Troubleshooting

Common Issues

curl -u email@example.com:api_token \
  https://your-domain.atlassian.net/rest/api/2/myself

Best Practices

API Examples

Create Issue with Asset

const createIssueWithAsset = async (assetId, assetName) => {
  const issue = {
    fields: {
      project: { key: 'PROJ' },
      summary: `Asset Review: ${assetName}`,
      description: 'Please review the attached asset',
      issuetype: { name: 'Task' },
      customfield_10100: assetId // ButterStack Asset ID
    }
  };
  
  const response = await fetch('https://your-domain.atlassian.net/rest/api/2/issue', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${btoa('email@example.com:api_token')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(issue)
  });
  
  return response.json();
};

Copy Code

Next Steps

• Set up Linear integration for alternative task tracking
• Configure Slack notifications for updates
• Enable Jenkins CI/CD for automated builds