AI Prompt Step

What this is

A new step type for approval paths that runs a chosen AI provider against the approval and writes the answer onto the step. Admins point the step at a prompt template (built-in or custom); when the approval reaches the step, the AI produces a short analysis — a summary, a risk assessment, a compliance check, a decision recommendation, or an external-reviewer briefing.

The output shows on the approval timeline as a one-line "key insight", opens a richer dialog on click, and is available as a template variable downstream Automation / HTTP / Email steps can quote.

Why

Approvers spend a lot of time scrolling through Jira issues, Confluence pages, and approval history before deciding. The interesting signal — a dissenting comment, precedent from a similar past approval, a policy gap — is usually there but easy to miss. AI Prompt surfaces it automatically. It also unblocks workflows the product can't do today: external-reviewer briefings, dynamic risk scoring, policy summaries, automated context for downstream automation.

Supported providers

• Anthropic — Claude Opus 4.7 / Sonnet 4.6 / Haiku 4.5.

• OpenAI — GPT-5.5 / 5.5 Pro / 5.4 / 5.4 Pro / 5.4 mini / 5.4 nano / 4.1.

• Groq — Llama 3.3 70B / 3.1 8B / GPT-OSS 120B / GPT-OSS 20B (free / low-cost option — perfect for testing and less demanding customers).

• OpenRouter — multi-model gateway giving access to Anthropic / OpenAI / Google Gemini / Meta Llama / DeepSeek / Mistral / xAI through a single key

How a prompt run works

Each run sends a single request to the provider, composed of:

1. System prompt (we generate). Tells the model: it's an approval workflow analyst, respond concisely in plain text, personal data is anonymised (<user-1>, <user-2> tokens; <email> placeholders; watcher names dropped); the locale to respond in; if the approval is JSM customer-facing, avoid internal jargon; if the PII-toggle is on, free-text has been scrubbed of phone/card/IBAN.

2. User prompt — the admin's prompt body, with {{ … }} variables interpolated against the approval context.

3. Structured data appendix — two JSON blocks appended after the user prompt:

   • Work Item / Content Data: full Jira issue or Confluence page record, filtered to custom fields the template references; comments included with author tokenised; ADF flattened to plain text.

   • Approval Data: approval header (status, deadlines, originator, restart info), all four step phases (steps / successSteps / rejectionSteps / expirationSteps) with each step's decision and comment, active user / action, watcher count, up to 3 cross-approvals on the same reference, prior prompt-step outputs, definition metadata (name + description + deadline policy), tenant settings.

Hard cap: ~200 000 chars combined; over that, the step skips with a clear "trim the template" message rather than burning tokens.

Context cleaning / pruning

Before any data leaves the tenant, the assembled context is pruned:

• Null / empty fields and empty arrays/maps dropped

• Atlassian Document Format → plain text — descriptions, comment bodies, rich-text custom fields are converted before sending.

• Comments bounded — per-step comment length truncated, count capped.

• Custom fields filtered to template-referenced ones only — admins must explicitly mention customfield_XXXXX to include it.

• Watcher list → count only.

• Cross-approvals capped at 3.

• Internal / opaque fields stripped — workflow scheme IDs, ancestors, audit metadata, residual HTML.

• Definition trimmed to name, description, decision-deadline policy, validity-expiration policy. Operational metadata (id, status, version, condition IDs, work-item-type IDs) is dropped.

Result is typically a small fraction of what the raw Jira / Confluence APIs would return. Admins see exactly what the AI gets via the template preview in Settings > AI.

Configuration (admin) — Settings > AI

Three tabs, all global-admin only:

General — provider dropdown (with link to the provider's API-key page) · masked API-key field (encrypted at rest, only last-4 fingerprint shown) · model select (suggestions per provider + custom) · Test connection button (tiny probe) · Enable AI Prompt steps toggle · Strip free-text PII toggle · Monthly token budget · unsaved-changes warning.

Prompt templates — list / create / edit / delete custom templates (max 50 per tenant; name ≤ 120 chars, description ≤ 500, body ≤ 4000). Live preview against a real approval shows the exact prompt the AI would see and an estimated token cost (warning at ~8K).

Usage — current-month dashboard: tokens used / budget / % consumed (coloured bar), status lozenge, total executions, sortable per-approval-path table. Banner across all tabs when at or near the cap.

Adding the step (definition editor)

Step picker has a new "Prompt" tile (with "New" badge). Form fields:

• Name — also the variable key for downstream interpolation.

• Template chooser — blank / built-in / custom. Picking a non-blank template confirms before overwriting an in-progress body.

• Prompt body — 4 000 char limit, character counter, {{ … }} variable syntax with a "Syntax guide" link.

• Optional condition + label condition (same as other steps).

If AI isn't configured / enabled / over budget, the form shows an explanatory panel pointing to AI Settings.

Variables admins can use

Standard {{ … }} syntax. The same data the structured tail exposes is available for inline interpolation:

• {{ issue.fields.summary }}, {{ issue.fields.description }}, {{ issue.fields.customfield_XXXXX }}, {{ issue.fields.status.name }}, etc.

• {{ page.title }}, {{ page.body }}, {{ page.version }} (Confluence).

• {{ approval.name }}, {{ approval.status }}, {{ approval.steps }}, etc.

• {{ definition.name }}, {{ definition.description }}.

• {{ activeUser }}, {{ approvalOriginator }}, {{ action }}, {{ watchers.count }}, {{ crossApprovals }}, {{ tenantSettings }}.

• {{ promptSteps["Step Name"].result }} — full text of an earlier prompt-step output in the same approval.

Built-in templates (5)

Each is designed to drive a distinct value AND match the result-dialog UI shape:

1. Summary for approver — surfaces non-obvious signals an approver would miss. Output: HEADLINE + "Watch for" bullets + "Blind spots".

2. Risk assessment — overall LOW / MEDIUM / HIGH plus 4-dimension breakdown (Financial / Compliance / Operational / Reputational) + top unmitigated concern.

3. Policy compliance check — admin pastes their numbered rules; output is COMPLIANT / PARTIALLY_COMPLIANT / NON_COMPLIANT plus per-requirement evidence + Gaps + Remediation.

4. Decision recommendation — APPROVE / REJECT / NEEDS_MORE_INFO + key reason + non-obvious signal + precedent.

5. External reviewer briefing — for offline approve/reject email flows. Plain-English translation, no internal IDs, refers to people by role.

All five are aware of the <user-N> tokens.

What approvers see

Timeline — AI icon, step name, one-line "key insight" parsed from the result. Keyboard-accessible.

Result dialog (click-through) — coloured headline card (verdict / risk / compliance, tone-coloured) · dimensions grid (4 risk dimensions or per-requirement compliance lozenges) · full prose body · "Copy result" button · "Previous runs" history.

Failure panels — actionable per-error guidance:

• Monthly budget reached — points to AI Settings, notes monthly reset.

• AI not configured / disabled — points to AI Settings.

• Provider key invalid — instructs to rotate.

• Other failures show one-liners (rate limit, timeout, content filter, output truncated, empty response).

Downstream interop

A successful Prompt step exposes its output as {{ promptSteps["Step Name"].result }} (also .executedAt, .provider, .model). Variables are scoped — a step in parallel group N can only read from earlier groups, never itself or later. Unlocks compositions like Risk → Automation comment, Summary → Email watcher group, Compliance → Decision recommendation that quotes the compliance verdict.

External API access (Web API v2)

For customer dashboards / audit pipelines / integrations:

• /webapi/v2/approvals/{id} now includes the Prompt step with id, name, status, executedAt, resultTeaser, providerUsed, modelUsed, errorCode, errorMessage, tokensIn, tokensOut.

• New /webapi/v2/approvals/{approvalId}/prompt-steps/{stepId}/executions returns full execution history (every run, with timestamps, tokens, latency, error code, full PII-scrubbed prompt sent + full response).

• /webapi/v2/definitions/{id} includes Prompt step config.

Privacy

Two layers.

Always on (no toggle, every tenant):

• Email addresses stripped (field values + free-text patterns) → <email>.

• Account IDs / opaque user identifiers removed.

• Real names of reporters, assignees, watchers, approvers, delegates, page authors etc. replaced with stable per-execution <user-N> tokens. Same person → same token, so the AI can still reason about who-did-what across steps.

• Watcher lists reduced to count only.

Opt-in toggle "Strip free-text PII" (for GDPR / HIPAA / PCI):

• Phone / credit-card / IBAN patterns in any free text replaced with <phone> / <cc> / <iban>.

• Custom fields whose key contains a PII keyword (email, phone, address, dob, ssn, passport, tax, iban, card, credit, national, personal) dropped wholesale.

Default off — for most tenants, comment text is the signal the AI should reason over.

Cost & safety controls

• Monthly token budget per tenant — warning at 90 %, hard skip at 100 %.

• Deduplication — 1-hour content-version cache; same-input rerun is free, marked "cached" in audit.

• Hard prompt-size cap — pathological inputs trip a clear error instead of burning tokens.

• Test-connection rate limit + settings-save rate limit — no provider hammering or rapid-fire saves.

• Audit log of every call — provider, model, tokens in/out, latency, finish reason, error code, full PII-scrubbed prompt + response, content version, "cached" flag. Visible per step in the dialog and per tenant in the usage dashboard.

Error codes: INVALID_KEY, RATE_LIMITED, BUDGET_EXHAUSTED, TIMEOUT, CONTENT_BLOCKED, OUTPUT_TRUNCATED, EMPTY_RESPONSE, UNAVAILABLE, MISCONFIGURED, PROMPT_TOO_LARGE, OTHER.

Permissions & provider security

• All AI configuration (settings, templates, usage) — global-admin only.

• Result-dialog endpoint requires the caller to have access to the underlying approval and the step must belong to that approval (no IDOR via guessed step IDs).

• API keys encrypted at rest, never returned to clients (only last-4 fingerprint), never logged.

• Provider URLs are fixed in code — tenants can't redirect to a custom endpoint, so a stolen key can't be combined with a custom URL to exfiltrate data elsewhere.

• Provider error responses are not echoed back to end users — some providers include the original prompt inside their error envelope; we strip that path.