First checks
- Confirm the exact app version, Forge environment and Jira Cloud site.
- Confirm the actor role: Jira administrator, project administrator, agent, customer, generic unlicensed or anonymous.
- Confirm the global/project/request-type scope and portal area currently published.
- Open the same request directly in Jira/JSM as the affected user and confirm the underlying value or action is available.
- Check the builder's validation overview, capability warnings and pending module-visibility synchronization banner.
- Reproduce with a synthetic request in development or staging where possible.
Do not “fix” a symptom by broadening scopes, adding egress, lowering privacy thresholds, switching a customer read/mutation to app authority or disabling validation.
Capture a safe incident envelope
Record only:
- app version, environment and site hostname;
- UTC timestamp and timezone;
- portal area and actor class;
- project/request-type name or synthetic identifier;
- configuration revision, locale, device/viewport and browser;
- safe app error code/correlation ID and HTTP status class if shown;
- expected behavior, actual behavior and synthetic reproduction steps.
Do not collect request summaries/descriptions/keys unless an approved process requires one, comments, field values, organization/people names, email/account IDs, attachments, JQL containing customer values, full portal URLs, prompts/completions, storage values, tokens, credentials, raw Jira response bodies or browser secrets.
Administration and builder
| Symptom | Safe checks | Resolution |
|---|---|---|
| Global admin page is missing | Confirm the app is installed on this site and the actor has Jira ADMINISTER permission. | Use an eligible Jira administrator and the approved installation. Do not copy another app identity or URL. |
| Project settings access is denied | Confirm the current project context and ADMINISTER_PROJECTS permission. | Use an eligible project/global administrator. A submitted project ID cannot grant access. |
| Wrong project or request type is shown | Read the “Editing” scope summary and trusted project context. | Use Change to select an authorized target; stop if the host context itself is wrong. |
| Template contains unavailable widgets | Check plan, project type, field, SLA, Assets, organization, service, knowledge and workflow capabilities. | Map, replace or locally hide the widget. A template is a starting draft, not a capability guarantee. |
| Draft save reports a conflict | Check the current revision, publication history and another administrator's change. | Reload and reconcile intentionally. Do not overwrite through payload or browser manipulation. |
| Publish is blocked | Select Review issues and inspect every blocking field-level error. | Fix all errors. Warnings require an understood and tested decision, not a blanket waiver. |
| Publish asks for approval | Check the global two-person setting, requester, unchanged revision and request age. | A different eligible administrator approves within 24 hours; otherwise create a new request. |
| Published but module chrome is stale | Look for the red pending visibility-sync banner. | Use Retry visibility sync, then refresh the customer request. Authorization is unchanged while sync is pending. |
Portal content and visibility
| Symptom | Safe checks | Resolution |
|---|---|---|
| Complete panel is hidden | Check enablement, effective empty layout, audience, request status, device, account class, request access and license. | Correct the complete panel policy and republish. Preview simulation alone is not permission evidence. |
| One widget says Not available | Check its selected field/source, current request access, required capability and fallback. | Keep the local safe state or repair the source/configuration. Never substitute privileged or unrelated data. |
| Portal header is empty for anonymous visitors | Confirm global portal-header scope, published public configuration, supported public page and public widget class. | Keep it empty unless every public-safety condition is met; request data, metrics, actions and AI are forbidden. |
| Wrong language appears | Check exact locale, base-language content, English fallback and published revision. | Add reviewed localized content and republish. Do not rely on unreviewed machine translation for critical copy. |
| Desktop looks correct but mobile is crowded | Use the mobile preview and check columns, widths, long labels, tables and action controls. | Use a single-column narrow layout, concise copy and compatible appearance tokens. |
| Related item is missing | Open the target directly as the current user and confirm the relation is customer-visible. | Accept omission when the target is unauthorized; the app does not disclose that a hidden target exists. |
| SLA, Assets, service or knowledge widget is missing | Confirm the project plan, field/configuration and current-user API capability. | Use a safe fallback/replacement or keep the widget unavailable until the real capability exists. |
Metrics and charts
| Symptom | Safe checks | Resolution |
|---|---|---|
| Counter is suppressed or qualitative | Check cohort size, privacy minimum, exact threshold, time window, query dimensions, freshness and differencing policy. | Use a broader legitimate cohort or accept the safe presentation. Do not lower controls merely to reveal a value. |
| Historical duration or SLA value is absent | Confirm the semantic metric engine, compatible definition and enough privacy-safe samples. | Leave unavailable until the specific metric can be computed; do not relabel a count. |
| Chart has no points | Check publication time, snapshot schedule, stable metric definition, sample, timestamps and sibling state. | Allow the honest no-data state while snapshots build; investigate jobs without exposing raw rows. |
| Value appears stale | Check displayed freshness, cache age, refresh state and safe correlation ID. | A safe stale value may remain after refresh failure. Repair the source/job rather than removing freshness disclosure. |
| Metric differs from Jira search | Compare project binding, current-customer/organization cohort, supported query definition and privacy treatment. | Expect generalized output. Customer metrics intentionally do not reproduce a raw Jira issue search. |
Customer actions
| Symptom | Safe checks | Resolution |
|---|---|---|
| Action is disabled | Check authenticated customer, active license, exact portal location, panel visibility, published policy, request access, capability and workflow. | Configure only server-attested choices and retest as the customer. Never elevate with app authority. |
| Public comment is rejected | Confirm text is present, at most 10,000 characters and permitted by the current customer API. | Correct the input/permission. Never fall back to an internal comment. |
| Attachment is rejected | Check decoded size 1–256 KiB, filename, MIME type, encoding and customer permission. | Use a supported smaller file or the service team's approved alternative. |
| Participant is unavailable | Check the published participant policy, server-issued token/label and current Jira permission. | Reconfigure the approved participant. Never submit a raw account ID from the portal. |
| Transition disappeared | Check the live current-customer transitions and published allowlist after workflow/status changes. | Update policy and retest. A transition absent from the current workflow must stay disabled. |
| Duplicate or Processing response | Check whether the first submission is running or already succeeded. | Wait and refresh request state before retrying; use the same UI retry flow. |
Optional AI
| Symptom | Safe checks | Resolution |
|---|---|---|
| AI widget uses fallback | Check global opt-in, per-widget opt-in, actor class, Forge LLM availability, budget, timeout/circuit and output validation. | Use deterministic content. Core portal behavior must not depend on AI. |
| AI output is rejected | Check bounded input/output, required schema, prohibited content and customer-safe projection. | Keep the validated deterministic fallback; do not bypass validation or send more customer data. |
| Admin AI assistant does not appear in the portal | Confirm the selected registry contract. | This is expected: Admin AI Configuration Assistant is admin-only and has no customer portal location. |
Performance, cache and partial failures
- A five-second client batch deadline can leave one slow widget unavailable while siblings continue.
- Fast widgets use configured content or the current request; Standard widgets use an additional source/action; high-cost widgets may load later; historical widgets are prepared periodically.
- Cached customer-shared data contains only an already privacy-treated presentation.
- A failed refresh can preserve a safe stale presentation with freshness context.
- Do not lengthen the whole page timeout to hide one slow source. Repair, replace or move the expensive widget.
Escalation and support
Use the Mederak Apps Service Desk. Include the safe incident envelope, affected version/environment, impact and actor classes, first/last observed time, reproducibility and redacted evidence.
For suspected vulnerabilities, choose a private security report and follow Security Incident Response. Do not open a public issue with exploit details, tenant data, credentials or customer content.