# n8n ↔ Jira Integration Guide

**Objective:** Create n8n workflows to integrate Jira with Slack, Email, and BigBlueButton

---

## Setup Overview

### Architecture
```
Jira Issue Event
    ↓ (Webhook)
n8n Webhook Receiver
    ↓ (Process & Route)
├─→ Slack Channel (Notification)
├─→ Email Handler (Create issue)
└─→ BigBlueButton (Generate meeting link)
```

### Prerequisites
1. n8n instance running: `https://n8n.ai-impress.com`
2. Jira API token configured
3. Slack workspace with bot permissions
4. Access to n8n (via Authentik SSO)

---

## Step 1: Create n8n Webhook for Jira Events

### In n8n UI:
1. Go to `https://n8n.ai-impress.com`
2. Create new workflow: **Jira Event Handler**
3. Add "Webhook" node:
   - Method: POST
   - Path: `/jira/events`
   - Copy the **Webhook URL**
   - Example: `https://n8n.ai-impress.com/webhook/jira/events`

4. Save the node

---

## Step 2: Register Webhook in Jira

### Option A: Via Bash Script
```bash
#!/bin/bash
JIRA_AUTH="di5zYW1vaWxlbmtvQGFpLWltcHJlc3MuY29tOkFUQVRUM3hGZkdGMEFCbEppNE1PUkoxTWx5YjZaaFItSTk4NFRZQ3JVaG9HSDN5SGYwYmpoWktrSl9wazI3czZtcmItR1ZvVnRyMGJYbVhXdFlEeVF0MUFFMMFV0NkJOcG1mcnoxQVRKbklicUFzV1Z1V2VLSHhxeUtKOGdaVkFwc2k4T0JjLWpDMkJWb0c5VFVFQkRQRE1XbUdfMEpHM3pGVTZidjhqVG1HZWN3ZTJ4bFp6VGlKbz1FMDA5MzE0MA=="

curl -X POST \
  "https://ai-impress.atlassian.net/rest/api/3/webhook" \
  -H "Authorization: Basic $JIRA_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://n8n.ai-impress.com/webhook/jira/events",
    "webhooks": [
      {
        "events": ["jira:issue_created", "jira:issue_updated"],
        "jqlFilter": "project in (PROD, MARK, SUPP, OPS)"
      }
    ]
  }'
```

### Option B: Manual via Jira UI
1. Go to https://ai-impress.atlassian.net → Settings → System → Webhooks
2. Create Webhook:
   - URL: `https://n8n.ai-impress.com/webhook/jira/events`
   - Events: Issue created, Issue updated
   - JQL Filter: `project in (PROD, MARK, SUPP, OPS)`

---

## Step 3: Create Slack Integration Workflow

### In n8n:
1. Add nodes after Webhook:

**Node 2: Switch**
- Route based on `body.webhookEvent`:
  - `jira:issue_created` → Channel 1
  - `jira:issue_updated` → Channel 2

**Node 3a: Set Slack Message (Created)**
```javascript
{
  "text": `🆕 New Issue: ${body.issue.key}`,
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": `*${body.issue.fields.summary}*\nProject: ${body.issue.fields.project.name}\nAssignee: ${body.issue.fields.assignee?.displayName || 'Unassigned'}`
      }
    }
  ]
}
```

**Node 3b: Set Slack Message (Updated)**
```javascript
{
  "text": `📝 Updated: ${body.issue.key}`,
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": `*${body.issue.fields.summary}*\nStatus: ${body.issue.fields.status.name}\nAssignee: ${body.issue.fields.assignee?.displayName || 'Unassigned'}`
      }
    }
  ]
}
```

**Node 4: Slack Send Message**
- Bot Token: `xoxb-...` (from Slack workspace)
- Channel: Select based on project
  - PROD → `#prod-jira`
  - MARK → `#mark-jira`
  - SUPP → `#supp-jira`
  - OPS → `#ops-jira`
- Message: Use data from Set message nodes

---

## Step 4: Create Email Integration Workflow

### For incoming emails → Create Jira issue:

**Node 1: Email Trigger** (if using IMAP)
- Mailbox: `support@ai-impress.com`
- Check for new emails every 1 minute

**Node 2: Extract Email Data**
```javascript
{
  "summary": `[Email] ${email.subject}`,
  "description": email.body,
  "issueType": "Task",
  "project": "SUPP"
}
```

**Node 3: Create Jira Issue**
- Use Jira node with "Create" action
- Map extracted data to issue fields

---

## Step 5: Create BigBlueButton Integration

### For meeting link generation:

**Node 1: BigBlueButton Create Meeting**
- Meeting ID: `${issue.key}-${timestamp}`
- Meeting Name: `${issue.key}: ${issue.summary}`
- Attendee Password: `attendee123`
- Moderator Password: `moderator123`

**Node 2: Store URL in Jira**
- Update issue custom field with meeting URL
- Use Jira "Update" node

**Node 3: Notify via Slack**
- Send message with meeting link to appropriate channel

---

## Testing the Workflow

### Test Jira Webhook:
```bash
# Create a test issue in PROD
curl -X POST \
  "https://ai-impress.atlassian.net/rest/api/3/issues" \
  -H "Authorization: Basic $JIRA_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "project": {"key": "PROD"},
      "summary": "Test n8n integration",
      "issuetype": {"name": "Task"}
    }
  }'
```

### Verify in n8n:
1. Go to workflow
2. Click "Execute Workflow"
3. Check execution logs
4. Verify Slack message appears

---

## Error Handling

Add error handlers in n8n for:
1. Webhook validation failures
2. Jira API rate limits
3. Slack message delivery failures
4. Email parsing errors

Use n8n "Error Handler" nodes to log and retry.

---

## Monitoring & Maintenance

### Check webhook status:
```bash
curl -X GET \
  "https://ai-impress.atlassian.net/rest/api/3/webhook" \
  -H "Authorization: Basic $JIRA_AUTH"
```

### Check failed webhooks:
```bash
curl -X GET \
  "https://ai-impress.atlassian.net/rest/api/3/webhook/failed" \
  -H "Authorization: Basic $JIRA_AUTH"
```

### Extend webhook life (30 days expiry):
```bash
curl -X POST \
  "https://ai-impress.atlassian.net/rest/api/3/webhook/refresh" \
  -H "Authorization: Basic $JIRA_AUTH" \
  -d '{
    "webhookIds": [10000, 10001, 10002]
  }'
```

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Webhook not firing | Check JQL filter in Jira webhook settings |
| Message not in Slack | Verify bot token and channel name |
| Rate limit errors | Add delays between n8n operations |
| Meeting link not stored | Check custom field ID in Jira |

---

## Success Criteria

✅ Issue created in Jira → Appears in Slack within 5 seconds
✅ Email received → Creates SUPP ticket automatically
✅ BBB meeting link generated and stored in issue
✅ No API rate limit errors
✅ All workflows handle errors gracefully

---

## Resources

- n8n Docs: https://docs.n8n.io
- Jira Webhook API: https://developer.atlassian.com/cloud/jira/platform/webhooks/
- Slack Bot API: https://api.slack.com/bot-users

---

**Next:** Execute this guide to create working integrations

