Customer Portal Toolkit for JSM — User Guide

Documentation map

Quick start

1. Open the builder. Use global administration as a Jira administrator, or open the app from the target service project's settings as a project administrator.
2. Choose the configuration target. Select global, project or request-type scope and one active portal area.
3. Start with a layout. Run the five-step Quick setup, apply a starter template, or add an empty section.
4. Add and configure widgets. Drag a compatible widget into the preview or use Add, then edit it in the Widget, Visibility and Style inspector tabs.
5. Preview deliberately. Choose a controlled request, customer/agent/project-admin simulation, language and device. Preview never proves real Jira permission.
6. Resolve validation errors. Review capability, privacy, query, content and action warnings; test any warning you accept.
7. Publish the complete scope. The Publish dialog lists every changed portal area. Confirm it, then verify the result in the real customer portal with controlled accounts.

Install and open the app

Before installation

• Use Jira Service Management Cloud; Server and Data Center are not supported.
• Have an organization or site administrator who may install Marketplace apps and review permissions.
• Prepare at least one controlled JSM project, synthetic request and test customer account.
• Review the Privacy Policy, Security Practices, Data Residency and Customer Terms.

Marketplace installation

1. Open the approved Customer Portal Toolkit listing in Atlassian Marketplace and confirm the app name, vendor and Cloud hosting.
2. Select Get it now or Try it free, select the intended site and review the requested access.
3. Complete installation, then confirm the app appears under Atlassian administration's Connected apps.
4. Open the app's global administration page, or open the target JSM service project and choose its settings/apps area.

Atlassian's current administrator flow is documented in Install and manage app access. Atlassian may rename navigation items; use its current Connected Apps instructions if labels differ.

Roles and permissions

Configuration scopes and inheritance

Effective configuration resolves from broad to narrow:

GLOBAL → PROJECT → REQUEST TYPE → CURRENT CONTEXT

• Global provides a consistent installation-wide base.
• Project adapts that base to one authorized service project.
• Request type applies only genuine differences for one request type.

At a narrower scope you can inherit, override an allowed property, hide an inherited widget, restore the parent value, or make an independent copy. Use the narrowest change that solves the requirement; copying a full layout makes future parent updates harder to govern.

Supported portal areas

Other logical locations remain dormant when Forge does not provide an approved safe surface. Their presence in internal types is not a promise that administrators can activate them.

Understand the builder workspace

1. Widget library: search compatible widgets, browse recommendations or choose a customer task. Capability-dependent widgets are disabled with a reason when the current project cannot support them.
2. Portal preview: arrange sections, columns, groups and widget order while seeing a full customer-page context or only the edited area.
3. Properties inspector: use the sticky Widget, Visibility and Style tabs for the selected item and complete panel.

On desktop, the three work areas scroll independently and their separators can be dragged or controlled by keyboard. Narrow layouts stack the areas and use normal page scrolling. The header shows draft save state, validation readiness, Quick start, Help, Versions, installation settings and Publish.

Add and select widgets

1. Select the intended portal area and configuration scope first.
2. Use Recommended, a task group, or Browse all widgets. Search checks every compatible widget.
3. Drag a widget into the canvas or select its Add button.
4. Select the rendered widget to open its properties. Use drag/drop or the move controls to change order.
5. Review the cost label: Fast, Standard, May load later or Prepared periodically.

The registry contains 62 definitions. The builder exposes 61 portal/customer widgets; Admin AI Configuration Assistant is the 62nd admin-only contract and never renders in the customer portal. Read the complete widget reference before using capability-dependent, aggregate, AI or action widgets.

Layout, sections and starter templates

Quick setup has five steps: portal area, starting layout, panel visibility, preview context, and review/publish. The available starter layouts are IT Help Desk, Customer Support, HR, Facilities, Access Requests and Incident Management.

• Templates create editable drafts and never publish automatically.
• Replacing a non-empty draft requires confirmation.
• A template may include SLA, Assets, organization, workflow or other widgets that are unavailable in a particular project.
• Configure desktop, tablet and mobile behavior; keep narrow areas readable and avoid excessive multi-column layouts.
• If a published location has no effective widgets, Jira can hide the complete app module chrome for that location.

Panel visibility

Visibility belongs to the complete location panel, not individual widgets. Choose at least one audience and one device. Selected audiences are combined with OR; audience, status, device, request access, license, account type, capability and action checks still combine with AND at runtime.

• Customer — authenticated JSM customer.
• Agent in this project — licensed user with the current project's service-desk agent permission.
• Project administrator — user with project administration permission, or a global Jira administrator.

If a role lookup fails, a role-restricted panel fails closed. A hidden action cannot be invoked by forging its widget ID because execution repeats the panel and widget policy checks.

Content, Jira fields and localization

• Write a reviewed English base label, description, fallback and configured content.
• Add reviewed Polish content where your audience needs it. Preview both languages before publishing.
• Select fields from current-project metadata. Do not assume a field ID copied from another site has the same meaning.
• Use a customer-friendly label without changing the underlying Jira field or value.
• Choose a safe missing-value or unavailable-capability message. Never simulate data that Jira did not provide.
• Links use restricted protocols and configured labels; arbitrary HTML, CSS, JavaScript, templates, endpoints or payloads are not accepted.

Locale matching follows the exact tag, its base language and then English. Administrators remain responsible for the accuracy of customer-facing, legal, safety and workflow wording.

Widget appearance

New widgets use the compact borderless JSM native treatment by default. In the Style tab, choose a preset and then combine validated tokens.

Surface, spacing, stacked/inline layout, label separator, emphasis, alignment, label/icon/description visibility and separators remain a closed validated token set. Custom CSS, remote assets and arbitrary colors are not accepted.

Privacy-treated metrics and charts

• Every query is compiled, bounded and tied to the current project.
• Use presets or the visual query editor where possible. Advanced JQL accepts only supported variables and must pass validation.
• The privacy minimum is at least five. Small cohorts can be suppressed, generalized or shown as a range/qualitative value.
• Exact values require the configured higher threshold, with a baseline of at least twenty.
• Historical charts use stored snapshots and include a text equivalent, sample/freshness context and an honest no-data state.
• Response, resolution, percentile, trend and SLA history are contextual estimates, not a guarantee for the current request.

Permission-checked customer actions

Actions never extend Jira/JSM permission. Configure only fields, transitions, participant candidates and closed safe operations offered by the installed app for the current project.

• Add Public Comment always creates a customer-visible comment, never an internal note.
• Add Attachment accepts a supported local file from 1 to 256 KiB through this app path.
• Edit Allowed Fields accepts only administrator-selected allowlisted fields and bounded values.
• Participant and transition actions use server-issued choices intersected with current Jira options.
• Confirmation, validation, rate limits, atomic idempotency and content-free audit protect every mutation.

Test both a permitted customer and a customer without permission after any workflow, field, request-type or permission change. See the action widget reference.

Preview the customer experience

Preview controls

• Request: use the newest authorized request, Previous/Next, or enter an explicitly authorized request key.
• Preview as: simulate customer, project agent or project administrator; anonymous appears only for a global portal header.
• Language: switch between English and Polish.
• Device: inspect desktop, tablet and mobile.
• Detail: use Full portal for context or Edited area for focused layout work.
• Zoom: changes the preview only and never saves configuration.

Validate, save and publish

Draft changes autosave with optimistic revision checks. The header reports Saving, Saved, Error or Conflict. Undo and redo affect the current editing session.

1. Select Review issues and open each affected widget/field.
2. Fix every blocking error. Understand warnings before proceeding.
3. Select Publish. If a save is still pending, the app saves the draft first.
4. Review the publishing scope and every changed portal area. Publication covers the whole selected global/project/request-type scope, not only the area currently previewed.
5. Confirm publication and refresh the real portal request.

If module visibility metadata has not synchronized to Jira, the builder shows a red pending-sync banner with a retry action. The configuration may be published, but do not accept empty-module behavior until the banner clears.

Optional two-person approval

When enabled installation-wide, the first eligible administrator requests approval for the exact revision. A different eligible administrator must approve that unchanged revision within 24 hours. A revision change or expiry requires a new request.

Versions, conflicts and rollback

• Versions shows publication history for the current scope.
• A save conflict means another administrator changed the same draft. Reload and reconcile intentionally; do not overwrite blindly.
• Rollback restores an earlier published version into a new draft. It does not rewrite history in place.
• Validate the restored draft against current fields, workflow, capabilities, privacy settings and parent configuration before publishing.
• Version 1.0 does not provide file-based configuration export/import, cross-site migration or a customer-restorable backup.

Post-publication acceptance checklist

• Test a Jira administrator and in-scope/out-of-scope project administrator.
• Test a customer with request access and a customer without access.
• For the public header, test authenticated, generic unlicensed and anonymous states separately.
• Check English and Polish on desktop, tablet, mobile and the narrow side panel.
• Check projects with and without optional SLA, Assets, organization, service, knowledge, field and workflow capabilities.
• Verify suppressed, generalized, exact and stale metric states without exposing rows.
• Test every configured action for success, denial, double submission, retry and changed workflow.
• Test AI disabled; if enabled, also test unavailable, timeout, budget and invalid-output fallback.
• Confirm one slow or failing widget does not make sibling content unusable.

What customers need to know

Customers may see different content by request type, project, status, request access, project capabilities, language, device and administrator configuration. A local unavailable state does not mean the complete portal has failed.

• Not available can mean a missing field/capability, empty value, timeout or insufficient access.
• Privacy suppression means a small or unsafe aggregate is intentionally hidden or generalized.
• Cached or stale content includes freshness context; it should not be read as current live state.
• Historical metrics provide context, not a personal SLA or prediction.
• An action appears only when the current customer, request, workflow and published policy allow it.
• Optional AI text is an identified plain-language aid, not authoritative Jira state or professional advice.

Installation settings: analytics, AI and approval

Enable an optional setting only after organizational review and acceptance on the installed version. See AI Transparency and Privacy Policy.

Accessibility and responsive use

• The builder and runtime support keyboard navigation, visible focus, reduced motion and responsive reflow.
• Resizable desktop separators support arrow keys, Home/End and double-click reset.
• Charts provide a text equivalent; color is not the only status cue.
• Interactive controls require a visible or programmatic accessible name.
• Keep customer copy short, use meaningful link labels and test browser zoom and narrow layouts.

Report lost focus, clipped content, horizontal overflow, missing labels, unreadable contrast or a chart without an equivalent summary as a defect.

Troubleshooting and support

Start with the Troubleshooting Guide. For product support, use the Mederak Apps Service Desk.

Include the app version/environment, site hostname, UTC timestamp, portal area, actor class, project/request-type name, locale/device/browser, configuration revision, safe error or correlation code and synthetic reproduction steps.

Glossary

Capability

A field, API, plan, workflow or project feature that a widget needs to operate.

Configuration scope

The global, project or request-type level being edited and published.

Effective configuration

The result after inheritance, local overrides, locks and current context are resolved.

Panel

The complete app content in one portal location. Audience/status/device visibility applies to this whole unit.

Privacy-treated aggregate

A count, range, label, percentage, duration or short series that passed cohort and disclosure controls without returning matching request rows.

Published version

The validated configuration revision used by the customer portal runtime.

Safe fallback

A deterministic or unavailable state used when a field, capability, AI call or data source cannot safely return content.

Trusted context

Site, actor, project, request, module and license information derived from Forge/Jira rather than accepted from a browser payload.