wxcc-ai

Node/Express service that wires Webex Contact Center summaries, Jira tickets (core + JSM Store Support), and xAI Grok summarization into a single set of internal HTTP endpoints.

Setup

npm install
cp .env.example .env
# fill in JIRA_*, XAI_*, and optionally the Assets values
npm run dev

The server listens on PORT (default 1866).

Environment variables

See .env.example for the full list. The important ones:

Var	Purpose
JIRA_CLOUD_ID	If set, requests use https://api.atlassian.com/ex/jira/{cloudId}.
JIRA_BASE_URL	Fallback for legacy site URLs (https://your-site.atlassian.net).
JIRA_EMAIL, JIRA_API_TOKEN	Basic auth to Jira. JIRA_AUTH_TYPE=bearer switches to bearer.
JIRA_SERVICE_DESK_ID	Numeric JSM service desk id for Store Support.
JIRA_ASSETS_WORKSPACE_ID	Assets workspace id (auto-discovered if omitted).
JIRA_ASSETS_STORE_SCHEMA_ID, _OBJECT_TYPE_ID	Locate the Store schema/type.
JIRA_ASSETS_STORE_NUMBER_ATTRIBUTE[_ID]	Attribute name (or id) holding the store number in Assets.
JIRA_STORE_CUSTOM_FIELD_ID	Custom field on the JSM request that holds the Store Assets reference.
XAI_API_KEY, XAI_BASE_URL	Grok credentials for summary generation.

Endpoints

Base path: /api/wxccai.

Read

• GET /getticket?jiraKey=CS-1234 — Grok-summarized single ticket.
• GET /open-tickets-by-reporter?email=user@example.com — Grok-summarized list of open tickets a person reported.
• GET /ticket/:key/status — raw status fields (no Grok).
• GET /ticket/:key/transitions — available workflow transitions.

Write

• PATCH /ticket/:key — body: { summary?, description?, priority?, labels?, assigneeAccountId?, additional? }
• POST /ticket/:key/comment — body: { text, internal? }
• POST /ticket/:key/close — body: { transitionName?, resolution?, comment?, internal?, component?, businessService?, system?, cause?, subType?, preserveExistingClassification?, skipValidatorFields? }. Auto-picks the first "done" transition when transitionName is omitted. When the chosen transition is done-category, the four SS workflow-validator fields (components, Business Service, System, Cause) are populated first (see "Closing SS tickets" below). Non-done transitions skip the resolution field (fixes issue #9).
• POST /ticket/:key/confirmFixed — CC-agent convenience. Body: { subType?, comment?, component?, businessService?, system?, cause?, internal? }. Closes with resolution=Done.
• POST /ticket/:key/customerCancelled — CC-agent convenience. Body: { subType?, reason?, component?, businessService?, system?, cause?, internal? }. Closes with resolution=Won't Do.
• POST /ticket/:key/duplicate — CC-agent convenience. Body: { primaryKey (required), subType?, comment?, component?, businessService?, system?, cause?, internal? }. Creates a formal Duplicate issue link to primaryKey, then closes with resolution=Duplicate.

Store Support (JSM requests)

• GET /ssRequestTypes — supported subType values + Assets config summary.
• POST /createSSRequest — body includes subType, summary, storeNumber (auto-resolved via Assets), onBehalfOf, description, additional.

Webex webhook

• POST /issueTranscript/:jiraKey — attaches audio + JSON transcript + human-readable transcript, then posts a restricted-visibility summary comment.

Admin

• GET /admin/caches — snapshot of all four Assets object caches (stores, businessServices, systems, causes): { caches: [{ name, count, lastSyncAt, ageSeconds, syncing, assetsSyncConfigured, ... }] }. Safe for health checks.
• GET /admin/caches/:name/status — same shape, one cache.
• POST /admin/caches/:name/refresh — force an immediate resync of one cache via the personal PAT (see below). Takes a few seconds.
• POST /admin/caches/refreshAll — refresh every cache in parallel.
• GET /admin/storesCache/status and POST /admin/storesCache/refresh — backward-compat aliases for the stores cache endpoints above.

Debug (non-production only)

• GET /debug/assetsProbe?storeNumber=305 — runs several AQL variants against Jira Assets and returns visible schemas + object-type detail + a computed diagnosis. Returns 404 when NODE_ENV=production.

Assets object caches (Assets workaround)

Several parts of the SS lifecycle need to translate a human-readable name (a store number, a Business Service name, a System name, a Cause code) into a Jira Assets object id before the value can be written to a CMDB custom field. The shared service account is silently filtered out of the underlying object schema (68), so the app maintains four local caches that are populated from a personal Atlassian PAT (a real human account with the right Assets role):

Cache	Object type	Used for
stores	109	customfield_10261 Store Number on new SS tickets
businessServices	100	customfield_10224 Business Service workflow validator on close
systems	103	customfield_10225 System workflow validator on close
causes	107	customfield_10233 Cause workflow validator on close

All four are backed by the same shared factory (services/jira/assetsObjectCache.js) and use the same PAT credentials. The service account is still used for everything else (creating tickets, comments, attachments, transitions).

Both storage patterns end up in the same place — process.env.ASSETS_SYNC_TOKEN — so the runtime code path is identical. Pick whichever fits the host.

Setup A — production / Linux host (.env)

Put the values directly in .env (which is gitignored) and lock the file down:

cat >> .env <<'EOF'
ASSETS_SYNC_EMAIL=you@ae.com
ASSETS_SYNC_TOKEN=<paste-your-atlassian-api-token>
EOF

chmod 600 .env    # only the bot user can read it

Then start normally:

npm start

Rotate the token in Atlassian → Account → Security → API tokens whenever the trust boundary on the host changes (new operator, offboarding, suspected leak). The app reloads it on the next process start.

Setup B — local dev on macOS (Keychain)

If you're running the app on a Mac and would rather not keep the PAT in .env, use the wrapper script — it pulls the token from Keychain into ASSETS_SYNC_TOKEN before exec'ing the process:

security add-generic-password \
    -s jira-assets-sync \
    -a you@ae.com \
    -w '<paste-your-atlassian-api-token>' \
    -U

echo 'ASSETS_SYNC_EMAIL=you@ae.com' >> .env   # email in .env, token stays in Keychain

./bin/load-assets-sync-secret.sh npm start

If ASSETS_SYNC_TOKEN is already in the process env (Setup A above), the wrapper is a no-op and skips the Keychain lookup.

Runtime behavior

On boot the app loads each on-disk cache from $CACHES_DIR/{name}.json (default ./data/), kicks off a background refresh for any snapshot missing or older than CACHES_STALE_AFTER_HOURS, and schedules a periodic full resync every CACHES_REFRESH_HOURS. resolveStoreAssetReference serves lookups from memory (sub-ms) with a live PAT lookup as fallback for brand-new stores. The three close-time caches (business services, systems, causes) are much smaller (dozens to a few hundred entries) and rarely change.

Force a refresh at any time:

curl -X POST http://localhost:1866/api/wxccai/admin/caches/stores/refresh
curl -X POST http://localhost:1866/api/wxccai/admin/caches/refreshAll

Closing SS tickets

The Resolved transition on SS tickets fires a workflow validator that requires four fields to be populated:

• components — Jira native (63 options in the SS project)
• customfield_10224 Business Service — Assets CMDB
• customfield_10225 System — Assets CMDB
• customfield_10233 Cause — Assets CMDB (the value "Unknown" exists as a designed catch-all)

closeTicket fills these in before calling the Resolved transition. Resolution order per field:

1. Explicit value in the request body (component, businessService, system, cause)
2. Whatever is already on the ticket (if preserveExistingClassification is true, the default — respects human triage)
3. The per-subType default from src/config/ssCloseDefaults.js
4. The __default__ entry (Help Desk / Store Technology / I can't find my option - Misc / Unknown)

For CC-agent-driven closes, the shortest path is to send just subType and comment; everything else is defaulted. Use the convenience routes:

# Caller confirms the issue is resolved
curl -X POST http://localhost:1866/api/wxccai/ticket/SS-20948/confirmFixed \
  -H 'Content-Type: application/json' \
  -d '{"subType":"Report a Technology issue"}'

# Caller wants to cancel
curl -X POST http://localhost:1866/api/wxccai/ticket/SS-20949/customerCancelled \
  -H 'Content-Type: application/json' \
  -d '{"subType":"Broken device / hardware","reason":"changed their mind"}'

# Duplicate of an earlier ticket (creates a formal Duplicate issueLink)
curl -X POST http://localhost:1866/api/wxccai/ticket/SS-20950/duplicate \
  -H 'Content-Type: application/json' \
  -d '{"primaryKey":"SS-20948"}'

To override the auto-detected classification (for a subType not in the defaults map, or when the caller volunteers specific context), pass any of the four fields explicitly. CMDB names are matched case-insensitively; you can also pass a raw Assets objectId as a shortcut for businessService / system / cause:

curl -X POST http://localhost:1866/api/wxccai/ticket/SS-XXXXX/confirmFixed \
  -H 'Content-Type: application/json' \
  -d '{"subType":"Broken device / hardware","system":"Printer","cause":"Broken Equipment"}'

Jira Assets gotcha

createSSRequest resolves a store number to an Assets object reference (customfield_10261). Two independent permission layers must both grant access, or every AQL query silently returns total: 0:

1. OAuth scopes on the API token: read:cmdb-schema:jira, read:cmdb-type:jira, read:cmdb-object:jira, read:cmdb-attribute:jira (and the write: equivalents for updates).
2. Object Schema role membership in Jira Assets itself — the underlying user needs to be added to a role on the Store schema in Jira → Assets → Object schemas → Configure → Roles.

If AQL keeps returning total: 0 with HTTP 200, run the probe endpoint above; the diagnosis field will tell you exactly which layer is missing.

Docker

npm run docker:build
npm run docker:run

The image runs as a non-root user and exposes 1866. HEALTHCHECK pings GET /health.

Repo hygiene

• Secrets live only in .env, which is .gitignored.
• The two discover-ss-*.js helper scripts read from .env — never hardcode credentials in them.
• The debug logger no longer echoes the outbound Authorization header. Rotate any token that appears in older logs/*.log files.