diff --git a/opt/00-infrastructure/atlassian/scripts/11-n8n-jira-integration-guide.md b/opt/00-infrastructure/atlassian/scripts/11-n8n-jira-integration-guide.md new file mode 100644 index 0000000..d476287 --- /dev/null +++ b/opt/00-infrastructure/atlassian/scripts/11-n8n-jira-integration-guide.md @@ -0,0 +1,266 @@ +# 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 + diff --git a/opt/00-infrastructure/atlassian/scripts/11-register-n8n-webhook.sh b/opt/00-infrastructure/atlassian/scripts/11-register-n8n-webhook.sh new file mode 100755 index 0000000..32c2a0f --- /dev/null +++ b/opt/00-infrastructure/atlassian/scripts/11-register-n8n-webhook.sh @@ -0,0 +1,79 @@ +#!/bin/bash + +# Week 4: Register n8n Webhook in Jira +# Creates webhook to send Jira events to n8n for processing + +ATLASSIAN_SITE_URL="https://ai-impress.atlassian.net" +ATLASSIAN_EMAIL="v.samoilenko@ai-impress.com" +ATLASSIAN_API_TOKEN="ATATT3xFfGF0ABlJi4MORJ1Mlyb6ZhR-I984TYCrUhoGH3yHf0bjhZKkJ_pk27s6mrb-GVoVtr0bXmXWtYDyQt0QL0Ut6BNpmfrz1ATJnIbqAsWVuWeKHxqyKJ8gZVApsi8OBc-jC2BVoG9TUEBDPDMWmG_0JG3zFU6bv8jTmGecwe2xlZzTiJo=E0093140" +JIRA_AUTH=$(echo -n "${ATLASSIAN_EMAIL}:${ATLASSIAN_API_TOKEN}" | base64) + +# n8n webhook URL +N8N_WEBHOOK_URL="https://n8n.ai-impress.com/webhook/jira/events" + +echo "=== Week 4: Registering n8n Webhook in Jira ===" +echo "" +echo "Webhook URL: $N8N_WEBHOOK_URL" +echo "" + +# Create webhook payload +echo "Creating webhook for Jira events..." + +JSON_DATA='{ + "url": "'$N8N_WEBHOOK_URL'", + "webhooks": [ + { + "events": [ + "jira:issue_created", + "jira:issue_updated" + ], + "jqlFilter": "project in (PROD, MARK, SUPP, OPS)" + } + ] +}' + +echo "Webhook configuration:" +echo "$JSON_DATA" | python3 -m json.tool +echo "" + +# Register webhook +echo "Registering webhook in Jira..." +RESPONSE=$(curl -s -X POST \ + "${ATLASSIAN_SITE_URL}/rest/api/3/webhook" \ + -H "Authorization: Basic ${JIRA_AUTH}" \ + -H "Content-Type: application/json" \ + -d "$JSON_DATA") + +echo "Response:" +echo "$RESPONSE" | python3 -m json.tool + +# Check if successful +if echo "$RESPONSE" | grep -q '"webhookIds"'; then + WEBHOOK_IDS=$(echo "$RESPONSE" | python3 -c "import sys, json; data=json.load(sys.stdin); print([w['id'] for w in data['webhookIds']])") + echo "" + echo "✓ Webhook registered successfully!" + echo "Webhook IDs: $WEBHOOK_IDS" + echo "" + echo "Next steps:" + echo "1. Test by creating an issue in Jira:" + echo " - Project: PROD" + echo " - Watch for webhook event in n8n" + echo "" + echo "2. Monitor webhook status:" + echo " - Check n8n webhook logs: $N8N_WEBHOOK_URL" + echo "" + echo "3. View failed webhooks (if any):" + echo " - Endpoint: /rest/api/3/webhook/failed" +else + ERROR=$(echo "$RESPONSE" | python3 -c "import sys, json; data=json.load(sys.stdin); print(data.get('errorMessages', [data]))" 2>/dev/null) + echo "" + echo "❌ Error: $ERROR" + echo "" + echo "Troubleshooting:" + echo "1. Check n8n webhook URL is accessible: $N8N_WEBHOOK_URL" + echo "2. Verify Jira authentication token is valid" + echo "3. Check JQL filter syntax: project in (PROD, MARK, SUPP, OPS)" +fi + +echo "" +echo "=== Webhook Registration Complete ==="