CustomerGauge -> JIRA


This is a guide to integration using CustomerGauge’s theme outputs (topics, volumes, sentiment/NPS, exemplar comments) as evidence that drives and tracks Jira work. Consider this as a "sketch" - to ensure it works perfectly configuration will be needed on both sides. 


1) What to send (data contract)


From CustomerGauge, expose the data in API, using compact JSON “Theme Evidence” object:


{  "themeId": "CG-THEME-123",  "themeName": "Onboarding delays",  "windowStart": "2025-08-01",  "windowEnd": "2025-09-30",  "volumeTotal": 142,  "volumeBySegment": {"Enterprise": 41, "Mid": 74, "SMB": 27},  "npsImpact": {"delta": -8.4, "detractorRate": 0.31},  "topDrivers": ["Slow kickoff", "Data migration", "Role clarity"],  "accountsAffected": [{"accountId":"A-778","name":"Quintain"}, {"accountId":"A-992","name":"Kerry"}],  "revenueAtRisk": 1_250_000,  "examples": [    {"commentId":"c1","account":"Quintain","score":3,"verbatim":"Kickoff took 3 weeks."},    {"commentId":"c2","account":"Kerry","score":4,"verbatim":"Data not ready; unclear owners."}  ],  "evidencePackUrl": "https://app.customergauge.com/themes/CG-THEME-123" }

This becomes the single payload you POST to Jira (real-time on threshold breach, or scheduled weekly).


2) How it lands in Jira (design patterns)


A) Create/Update a Jira 

Epic

 per theme (recommended)

  • Create Epic (POST /rest/api/3/issue) with:

    • Summary: Theme: Onboarding delays (Vol: 142, NPS Δ −8.4)

    • Description: paste key metrics, table of segments, and top 5 exemplar comments (truncate safely). Link “View full evidence” → evidencePackUrl.

    • Labels/Components: cg-theme, onboarding, voice-of-customer.

    • Custom fields (highly useful):

      • cg_theme_id = CG-THEME-123 (for idempotency)

      • cg_volume_total (number)

      • cg_nps_delta (number)

      • cg_rev_at_risk (currency/number)

  • Idempotent upsert: search by cg_theme_id; if found, update fields and add a comment “Theme refreshed (week of …)”.


B) Spawn 

Stories/Sub-tasks

 for workstreams

  • Auto-create linked issues for work packages (e.g., “Define onboarding playbook,” “Data migration checklist,” “RACI for roles”).

  • Copy the subset of metrics relevant to each story; keep the Epic as the single source of truth.


C) Attach “evidence packs”

  • If you generate a PDF/CSV pack, upload via POST /issue/{id}/attachments (Jira requires the X-Atlassian-Token: no-check header). Name files like CG_Onboarding_Delays_2025-09-30.pdf.


D) Ongoing updates as 

comments

 or 

field refresh

  • Weekly (or on material change): POST /issue/{id}/comment with a short digest:

    • “Vol +17 WoW (142→159), NPS Δ −8.4→−7.1; Top new driver: ‘handover gaps’. 3 new exemplar comments added.”

  • Also refresh numeric custom fields so PMs can sort/filter without opening the issue.


3) Automation inside Jira (so PMs see & act)

  • Auto routing: Use Jira Automation: When issue created with label cg-theme → set assignee = VOC lead, add watchers, add due date.

  • Quality gates: If cg_rev_at_risk > threshold → auto-create a “Risk” issue linked to the Epic.

  • Dashboards:

    • Filter: project = OPS AND labels = cg-theme ORDER BY cg_rev_at_risk DESC

    • Gadgets: Filter Results (show Volume, NPS Δ), Two-Dimensional Filter (Theme vs Status), Created vs Resolved (trend of theme work).


4) Example API calls (minimal, illustrative)


Create/Upsert Epic

  1. Search by themeId (custom field cf[12345]):

GET /rest/api/3/search?jql=cf[12345] ~ "CG-THEME-123"&fields=summary

  1. Create if not found:

POST /rest/api/3/issue {  "fields": {    "project": {"key": "OPS"},    "issuetype": {"name": "Epic"},    "summary": "Theme: Onboarding delays (Vol: 142, NPS Δ −8.4)",    "description": "Evidence: https://app.customergauge.com/themes/CG-THEME-123\n\nVolume: 142\nNPS Δ: -8.4\nRevenue at risk: 1.25M\nTop drivers: Slow kickoff; Data migration; Role clarity\nAccounts: Quintain, Kerry\n\nTop examples:\n• [3] Quintain: \"Kickoff took 3 weeks.\"\n• [4] Kerry: \"Data not ready; unclear owners.\"",    "labels": ["cg-theme","voice-of-customer","onboarding"],    "customfield_12345": "CG-THEME-123",    "customfield_12346": 142,    "customfield_12347": -8.4,    "customfield_12348": 1250000  } }

  1. Update if found:

PUT /rest/api/3/issue/{issueIdOrKey} {  "fields": {    "customfield_12346": 159,    "customfield_12347": -7.1  } }

Add weekly digest comment

POST /rest/api/3/issue/{issueIdOrKey}/comment {  "body": "CG Theme refresh (2025-10-02): Vol +17 WoW to 159; NPS Δ −7.1; New driver: handover gaps. Evidence: https://app.customergauge.com/themes/CG-THEME-123" }

Attach evidence pack


POST /rest/api/3/issue/{issueId}/attachments with multipart file CG_Onboarding_Delays_2025-09-30.pdf.


5) Governance & privacy

  • PII: Don’t paste raw customer names or emails in public projects; use account aliases or link back to CustomerGauge (permission-gated).

  • Quotas: Truncate exemplar comments (e.g., first 300 chars). Keep a maximum (e.g., 5 per refresh).

  • Idempotency: themeId + windowEnd as your unique key for each update cycle to avoid duplicate epics/comments.


6) Nice extras

  • Bi-directional link: store Jira Epic key back in CustomerGauge so your VoC theme page shows “Remediation Epic: OPS-1234 (Open).”

  • Threshold webhooks: Trigger creation/updates only when volume or NPS delta moves by >X% or revenue-at-risk crosses a line.

  • Segment slices: For big themes, create child issues per segment (Enterprise/Mid/SMB) with their own metrics to parallelize work.

This is a "sketch" as to how to make it work. There will be some configuration needed on both applications to perfect the flow. 


[Submitted by AD 6 October 2025]