Krosoft Wiki
Krosoft Wiki
Breadcrumbs

Planning Sync for Jira (Tempo Integration) - User Manual

This guide explains how to install, set up, and operate Planning Sync for Jira (Tempo Integration).
It focuses on the configuration experience and the common happy-path setup.

Audience

This manual is intended for:

  • Jira administrators who install the app and manage access

  • Users who were granted the Jira global permission to administer Planning Sync

  • Project admins who need to understand what the automation does

  • Space admins who need to understand what the automation does

  • Jira users who view the Advanced edition Hours rollup panel on work items they can access

  • Planning Sync administrators who ask the bundled Rovo Agents about retained audit, Compliancy, or Client Work Rate history

What the app does

Planning Sync keeps Jira work item fields aligned with Tempo plan and worklog data. It can:

  • Update Jira date or datetime fields from Tempo plan dates

  • Clear Jira fields when plans are removed

  • Sync assignee fields based on Tempo plan assignees

  • Optionally push Jira fields back to Tempo plan updates

  • Aggregate Tempo worklog hours by selected Tempo work attributes and write totals into Jira custom fields

  • Relay Tempo plan events to Jira Automation and outbound HTTPS destinations

  • Provide operational audit logs and Advanced edition Compliancy cases

  • Show an Advanced edition Hours rollup panel in Jira work item views

  • Answer Rovo questions about retained Planning Sync audit and Compliancy history through Planning Sync Time Machine

  • Provide Client Work Rate reporting and a separate Client Work Rate Reporter Rovo Agent

Installation and setup wizard

After installation, open Planning Sync from Jira app navigation and follow the wizard. The app appears as Planning Sync with the Planning Sync icon in Jira Apps navigation.

If the setup wizard is empty because the app was reinstalled, contact support before saving new configuration. Planning Sync shows a reinstall recovery panel on the first setup step and a compact dashboard card while setup is incomplete. Use Copy support request to collect the site ID, current installation ID, app/environment identifiers, and the support request text Krosoft needs to ask Atlassian to relink Forge-hosted storage.

Prerequisites

Before starting the wizard, make sure you have:

  • Access to Planning Sync through Jira admin rights, site admin rights, or the Jira global permission Administer Planning Sync for Jira (Tempo Integration)

  • Tempo Timesheets or Tempo Capacity Planner installed

  • A Tempo API token or OAuth 2.0 client

Planning Sync requires a Tempo product. Install one of these on your Jira Cloud site before setup:

Create a Tempo API token

These steps are written for Tempo Timesheets administrators.

  1. In Jira, go to Apps -> Tempo -> Settings.

  2. Open API Integration, Data Access, or API tokens, depending on your Tempo version.

  3. Select Create token or Generate token.

  4. Give the token a clear name, for example Planning Sync token.

  5. Copy the token immediately. Tempo shows it only once.

  6. Store the token like a password in a secure vault or password manager.

If you cannot see the API token page, ask a Tempo admin to grant access or generate the token for you.

Wizard steps

Step one: Confirm Tempo

The app checks for Tempo Timesheets or Tempo Capacity Planner on the site. If the check is inconclusive, you can still continue and validate later. If Tempo appears unreachable or temporarily down, the app shows a warning and offers Check again.

If this is a reinstall, use the recovery panel before reconfiguring. Atlassian-hosted storage recovery is not automatic and must be requested by support.

Step two: Authentication

Choose one authentication method:

  • Tempo API token, which is simple and quick

  • OAuth 2.0, which is recommended for longer term use

For a Tempo API token, paste the token into the token field and save.

For OAuth 2.0:

  1. In Planning Sync, copy the Callback URL.

  2. In Jira, go to Apps -> Tempo -> Settings.

  3. Open OAuth 2.0 Applications.

  4. Create a new confidential application and use the Planning Sync Callback URL as the redirect URI.

  5. Copy the Client ID and Client Secret.

  6. Save them in Planning Sync.

  7. Select Authorize and complete the Tempo consent screen.

  8. Confirm that Planning Sync reports an active connection.

Step three: Webhook URL

Generate or refresh the webhook URL from the app when needed. Enable the required listeners in Planning Sync so the app can create or reconcile its Tempo subscriptions. Planning Sync manages both plan and worklog webhook subscriptions from the app.

Step four: License status

The app reads your Marketplace license. Advanced features are available only with the Advanced edition.

Once these steps are complete, move to configuration and turn on the required listeners.

Test instance checklist

Use this checklist to confirm a test or Marketplace review site is ready:

  • Tempo Timesheets is installed and active

  • A Tempo API token or OAuth connection is saved in the app

  • The Planning Sync webhook URL resolves successfully

  • Required Tempo plan and worklog listeners are enabled in the app

  • At least one Jira project has mapped fields

Configuration options

Event listeners

Control which events should be processed:

  • Tempo plan events: plan.created, plan.updated, plan.deleted

  • Tempo worklog events: worklog.created, worklog.updated, worklog.deleted

  • Jira work item events, optional

If a listener is off, the app ignores that event type.

For Tempo plan events, the Handling toggle controls built-in Jira field updates, assignee mapping, and plan approval requests only. Automation webhook forwarding can still run when built-in plan handling is off, as long as the matching Tempo listener is enabled, global scope allows the work item, and Automation webhook forwarding is configured for that event.

Settings: Tempo to Jira

Map Tempo plan data into Jira fields:

  • Latest plan end date -> Jira date or datetime field

  • First plan start date -> Jira date or datetime field

  • Plan assignee -> Jira user picker field

  • Work attribute hour aggregates -> compatible Jira custom field, Advanced edition only

Behavior notes:

  • When no plans remain, mapped date fields are cleared.

  • For first plan start date, choose either upcoming plans only or all plans.

  • Work attribute mappings refresh when an allowed issue view loads, so Jira exports can include stored field values.

  • The Tempo work attribute selector is loaded from configured Tempo work attributes. Select the attribute instead of typing its key.

  • Static-list filters can match Tempo option IDs, keys, names, labels, display names, or primitive tokens returned by Tempo.

  • Work attribute mappings do not support custom JavaScript scripts. Unsupported script fields are discarded on save and never run.

Settings: Jira to Tempo

Enable Jira to Tempo sync if you want Jira field updates to modify Tempo plans:

  • Jira plan start date -> Tempo plan start date

  • Default assignee -> Tempo plan assignee fallback

This sync runs only when the Jira listener is enabled.

Global scope

Limit which work items are eligible for automation:

  • Allowlist by Jira project

  • Allowlist by work item type

When enabled, only allowed projects and work item types are processed.

Plan approvals

Control when plans need approval:

  • Required reviewer

  • Threshold for older plan end dates

  • Optional auto-approval rules

When approval requirements are not met, the plan is skipped and logged.

Advanced settings layout

In Settings -> Advanced settings, child sections start collapsed and are ordered as follows:

  1. Compliance settings

  2. CWR severity thresholds

  3. Audit ingress webhook

  4. Automation webhook

  5. Work attribute sync

  6. Hours rollup issue view

  7. Global scope allowlist

  8. Field availability

  9. Assignee update rules

Expand only the section you need. Collapsed sections do not load their settings. Sections with enable switches show that switch first and reveal detailed controls only after the switch is on.

Automation webhook forwarding

Advanced edition administrators can forward selected Tempo plan events to a native Jira Automation incoming webhook from Settings -> Advanced settings -> Automation webhook.

Setup steps:

  1. Enable Automation webhook forwarding.

  2. Paste the incoming webhook URL generated by the Jira Automation rule.

  3. Select any combination of plan.created, plan.updated, and plan.deleted.

  4. Optionally store a webhook token. Planning Sync sends it as X-Automation-Webhook-Token.

  5. Use Send test webhook to verify the Automation rule receives the structured payload without requiring a sample Jira issue to exist.

  6. Open Automation rule templates to copy transition and Slack-oriented recipes and payload smart values.

The matching Tempo plan listener must also be enabled. For example, forwarding plan.deleted depends on the plan.deleted listener being active.

The Tempo plan Handling toggle does not need to be enabled for Automation forwarding. Leave Handling off when you want Jira Automation to handle the event without Planning Sync updating built-in Jira fields, assignees, or plan approvals.

Planning Sync forwards payloads only. Jira Automation owns transitions, comments, notifications, Slack actions, permissions, and user mapping. Runtime Tempo plan events include Jira Automation's issue query parameter when the related work item key is available. Manual test sends omit that query parameter and mark the payload with test: true.

For admin-ready examples, see Jira Automation Slack planning recipes.

Compliance settings

Advanced edition administrators can use Settings -> Advanced settings -> Compliance settings to:

  • Enable Compliancy before destructive audit, case catalog, and alert controls are shown

  • Enable or disable the Planning Sync Time Machine Rovo Agent

  • Configure destructive audit field selectors and frozen-period governance behavior

  • Configure alert settings such as lookback window and thresholds

  • Configure alert webhook delivery with an HTTPS URL, optional shared secret, resolved toggle, and manual test send

  • Use structured webhook fields such as compliancyCases and ruleCaseBuckets with JSONPath in Jira Automation

Alert results are reviewed in Compliancy -> Alerts.

Work attribute sync

Advanced edition administrators can use Settings -> Advanced settings -> Work attribute sync to aggregate Tempo worklog hours into Jira custom fields by selected work attributes.

Setup steps:

  1. Enable Work attribute sync.

  2. Select a Tempo work attribute discovered from Tempo work attributes.

  3. Optionally filter by a static-list value when Tempo provides values, or type a value for other attribute types.

  4. Select a compatible Jira custom field as the target. Compatible targets currently include Jira number/float custom fields and plain text custom fields.

  5. Choose number or text output.

When an allowed Hours rollup issue view loads for a Jira user who can view the issue, Planning Sync reloads current Tempo worklogs for the issue, sums the hours that match the selected attribute key and optional value filter, and updates the Jira field. Issue-view refresh uses Jira issue visibility, Advanced edition access, and the Hours rollup project allowlist.

Configuration, compatible field lookup, Tempo metadata lookup, and manual sync stay administrator-only.

If no worklogs match, number output writes 0 and text output writes an empty string. When Work attribute sync is disabled, issue-view and webhook refreshes skip Jira field writes while retaining saved mappings. When Tempo reports that the issue worklog scan was truncated, Planning Sync skips the Jira field write and keeps the previous aggregate value instead of storing a partial total.

Outbound destinations

Advanced edition administrators can forward Tempo events to external systems.

  • Add one or more HTTPS destinations

  • Configure an optional shared secret for request verification

  • Choose which Tempo events to forward

  • Pick payload mode: raw Tempo data or custom JSON

If a destination fails, the app attempts retries and records failures in audit logs.

For an admin-ready Microsoft Power Automate and Outlook recipe, see Power Automate Outlook outbound template.

Hours rollup issue view

Advanced edition administrators can use Settings -> Advanced settings -> Hours rollup issue view to:

  • Enable or disable the work item view rollup panel globally

  • Restrict the panel to specific Jira projects with the project allowlist

  • Optionally select a Tempo work attribute, such as Project code, to show a grouped breakdown for the same rolled-up issue scope

  • Add manual label overrides only when Tempo returns static-list IDs that cannot be resolved from metadata, for example d8421f91-c947-49da-9a0a-3190271a2106 = 100%

When enabled and allowlisted, supported parent work item views show an Hours rollup panel with Powered by Planning Sync shown as secondary header text in the collapsed surface. Unsupported work item views stay hidden.

The top row is always Total logged. Parent work items show generation rows such as Children, Grandchildren, and Nested grandchildren, including linked descendants from other Jira projects. Sub-tasks are not shown as separate items except at the lowest non-subtask level, where a Subtasks row can appear. If an attribute breakdown is enabled, the panel also shows grouped worklog totals such as project-code totals.

Users do not need the Planning Sync administrator permission to load this issue details panel. They must be able to view the Jira issue, the site must have Advanced edition access, and the issue project must be allowed by the Hours rollup project allowlist.

When Work attribute sync is enabled, the panel also starts a best-effort refresh of configured Work attribute sync fields under the same issue visibility, Advanced edition, and Hours rollup project gates.

When the feature is disabled, or when the current project is not allowlisted, the work item view panel stays visible but explains why rollup data is unavailable.

Audit logs and Compliancy cases

Advanced edition administrators can review recent actions and webhook activity.

  • Admin page: full operational audit log

  • Admin page: dedicated Compliancy tab for auditable action cases

  • Compliancy cases support free-text search, case-type filtering, acknowledgement filtering, and loading older matching cases with the last applied filters

  • Project tab: project-scoped Planning Log for Planning Sync actions

Compliancy cases cover destructive actions, archived items with cached direct and descendant booked hours, frozen-period governance, and tracked field mapping changes.

Planning Sync Time Machine Rovo Agent

Advanced edition administrators can use Planning Sync Time Machine from Rovo chat/sidebar to ask natural-language questions about retained Planning Sync history, such as:

  • What happened to TEST-123 last week?

  • Show risky compliancy cases in project TEST this month.

  • Why did Planning Sync skip updates recently?

  • Summarize deleted worklog or issue evidence for TEST-123.

Time Machine is read-only. It searches Planning Sync's retained operational audit entries and Advanced Compliancy cases only. It does not search native Jira changelogs, native Tempo history, Slack, email, or external APIs. Results keep Operational audit and Compliancy case source labels visible so you can tell runtime telemetry apart from governance findings.

Access and limits:

  • You need Planning Sync administration access through the app global permission or Jira admin rights.

  • The site needs Advanced edition access, except Forge development environments used for testing.

  • An administrator must enable Settings -> Advanced settings -> Compliance settings -> Enable Planning Sync Time Machine before the agent can query retained history.

  • The action returns compact summaries only, defaults to 10 results, and caps output at 25 entries.

  • Raw request bodies, raw webhook payloads, and oversized body fields are intentionally not exposed to Rovo.

Reporting and Client Work Rate

Advanced edition administrators can use Reporting in the Planning Sync admin navigation to configure and verify manager-facing reports. Client Work Rate is the first report available there, and managers can use the separate Client Work Rate Reporter Rovo Agent after it is enabled.

By default, only Planning Sync administrators can use the CWR Rovo Agent. Administrators can configure one Jira group whose members may read saved CWR snapshots through Rovo without opening Planning Sync admin pages. Group-only users cannot generate or refresh snapshots.

Client Work Rate is calculated as:

CWR = Productive hours / Available hours

Definitions:

  • Productive hours are all hours related to client work.

  • Available hours are scheduled working hours minus leave, non-working holidays, and configured Account-exclusion worklogs.

  • Client work is selected by one source: live Tempo Account Categories or live Tempo Accounts.

  • Account exclusions reduce Available hours without being reported as Leave, Productive, or non-productive time.

  • Leave can come from selected Leave Accounts, Jira Leave JQL matching, issue-field leave, and Tempo holiday schemes.

In payloads, scheduled working hours before reductions map to grossAvailableHours, leave plus non-working holiday reductions map to leaveHours, and final availability maps to availableHours. Report rows can also include grossAvailableFte, leaveFte, and availableFte.

In CWR setup, administrators can:

  • Enable or disable Client Work Rate reporting

  • Set the report name shown in dashboard summaries and Rovo responses

  • Configure a CWR Rovo access group from live Jira group lookup or an exact group name

  • Choose Tempo teams to include from a live Tempo Teams multi-select

  • Add team-specific Rovo Team Name overrides

  • Exclude selected live Tempo team members from calculations without changing Tempo membership

  • Choose whether client work is selected by Account Categories or specific Accounts

  • Choose Account exclusions for Available hours

  • Choose Leave Accounts and Jira Leave JQL rules for Vacation, Sick Leave, and Other Leave

  • Enable Tempo team commitment weighting when split-role users should have Available and Leave hours reduced by team commitment

  • Choose an Automatic snapshots cadence

In Monthly report, administrators can:

  • Choose a month and year without expanding setup

  • Load a saved report when a snapshot exists

  • Generate or refresh a report for the selected period

  • Review Snapshot and Rovo status

  • Watch queued or running refresh progress with current step, progress bar, and estimated remaining time

  • Review formula breakdown, executive exceptions, warning lists, row-level details, and retained source evidence

Below-target exception severity is gradual. With the default target of 75%, CWR below 50% is critical, CWR from 50% to below 75% is warning, and CWR at 75% or higher has no below-target exception. In Settings -> Advanced settings -> CWR severity thresholds, administrators can turn on custom thresholds.

Use Client Work Rate Reporter from Rovo chat/sidebar for prompts such as:

  • Generate CWR for May 2026.

  • Show people below target for May 2026.

  • Generate CWR for Communardo Netherlands for May 2026.

  • Explain why Alex's CWR is low.

The month-scoped starter prompts shown by Rovo are generated during app deployment, not at chat runtime. They point at the previous UTC calendar month in Month YYYY format, so a June 2026 deployment shows May 2026. You can still type a different month when you need another saved CWR snapshot.

Rovo uses saved backend snapshots by default and must not invent CWR calculations. If no saved snapshot exists, ask a Planning Sync administrator to generate or refresh the saved monthly snapshot for the configured Teams to include scope.

Audit ingress receipts

Advanced edition administrators can configure Planning Sync to receive signed callbacks after an external system successfully submits a Jira worklog.

Setup steps:

  1. In Settings -> Advanced settings -> Audit ingress webhook, select Get audit webhook config to generate or fetch the dedicated URL and setup metadata.

  2. Rotate the audit ingress shared secret before setup.

  3. Configure each sender to sign the raw JSON body with HMAC-SHA256.

  4. Send the hex signature in the x-planning-sync-audit-signature header.

  5. Use the dedicated audit ingress webhook URL only for audit ingress senders. Do not use the Tempo webhook URL.

Planning Sync accepts only schema_version: planning-sync.audit_event.v1 and event_type: worklog.submitted.

Accepted requests return receipt_id, event_id, accepted: true, and duplicate. Duplicate event_id deliveries return the same receipt with duplicate: true.

A missing or mismatched HMAC signature returns HTTP 403. Payload/schema validation failures return HTTP 400 with the validation error in the response body. Planning Sync stores only sanitized Jira/worklog claim metadata and rejects payloads containing raw browser, email, calendar, or evidence fields.

Daily usage

After setup, normal usage looks like this:

  • Tempo plans are created or updated.

  • The app updates Jira fields based on your mappings.

  • When an allowed Hours rollup issue view is opened by a Jira user who can view the issue, mapped work attribute aggregates refresh into Jira custom fields for export.

  • Selected Tempo plan events are forwarded to Jira Automation when Automation webhook forwarding is enabled, even if built-in Tempo plan handling is disabled for that event.

  • Tempo worklog events are processed when the related listeners and features are enabled.

  • The audit log records changes and skips.

  • Planning Sync Time Machine can summarize retained audit and Compliancy records for administrators from Rovo when Advanced access is available.

  • Client Work Rate Reporter can answer from saved CWR snapshots when reporting is enabled and access rules allow it.

Troubleshooting tips

No updates in Jira

  • Confirm the Planning Sync webhook URL resolves and app subscriptions were created successfully.

  • Ensure the relevant listener is enabled.

  • Check global scope allowlist settings.

  • Check audit log entries for errors or skips.

Audit log is empty

  • Confirm the site has Advanced edition access.

  • Generate new events after enabling the feature.

Time Machine cannot find an event

  • Confirm Enable Planning Sync Time Machine is on in Advanced settings.

  • Confirm the event exists in retained Planning Sync audit or Compliancy history.

  • Narrow the question with an issue key, project key, date range, or source type.

  • Remember that Time Machine does not crawl native Jira or Tempo history outside Planning Sync storage.

Client Work Rate Reporter cannot produce a report

  • Confirm Client Work Rate is enabled in Reporting.

  • Confirm the user has Planning Sync administration access or belongs to the configured CWR Rovo access group.

  • Confirm a saved monthly snapshot exists for the requested month and configured team scope.

  • Ask a Planning Sync administrator to generate or refresh the saved snapshot if needed.

Webhook verification errors

  • Verify the shared secret in Tempo matches the stored secret.

  • Confirm the webhook URL is current for the environment.

  • For audit ingress receipts, confirm the HMAC is computed over the exact raw JSON body sent to Planning Sync.

Empty setup after reinstall

  • Stop configuration changes until recovery expectations are confirmed.

  • Copy the reinstall recovery support request from the first setup step or dashboard setup-readiness card.

  • Send it to support within 21 days of uninstall so Atlassian can process it before the 28-day Forge-hosted storage retention ends.

Where to find pages

  • Planning Sync admin page: Jira app navigation -> Planning Sync

  • Project log: Jira project navigation -> Planning Log

  • Hours rollup issue view: Jira work item view -> Hours rollup panel, when Advanced edition and project allowlist allow it

  • Rovo Agents: Rovo chat/sidebar -> Planning Sync Time Machine or Client Work Rate Reporter, when enabled and access rules allow it

Access control

Planning Sync access is controlled through the Jira global permission Administer Planning Sync for Jira (Tempo Integration).

  • Jira administrators receive this permission by default on first install.

  • Jira administrators can grant or revoke access for individual users or groups in Jira global permissions.

  • Users without this permission, and who are not Jira admins or site admins, do not see the Planning Sync entry in the left navigation and cannot use admin/configuration screens.

  • Advanced settings, outbound destinations, audit logs, Compliancy, Reporting setup, and Work attribute sync configuration require Planning Sync administration access and Advanced edition access, except in development environments used for testing.

  • Planning Sync Time Machine follows the admin access gate plus Advanced edition gate.

  • Client Work Rate Reporting setup requires Planning Sync administration access and Advanced edition access.

  • Client Work Rate Reporter can allow one configured Jira group to read saved CWR snapshots without granting Planning Sync administration access or refresh rights.

  • Work attribute sync configuration, compatible field lookup, Tempo metadata lookup, and manual sync require Planning Sync administration access.

  • The Jira issue details Hours rollup panel and its best-effort Work attribute field refresh are separate from admin navigation. They can run for non-admin users who can view the issue when Advanced edition access and the configured project allowlist permit it.