Configure and use QuotaLedger

What QuotaLedger does

QuotaLedger turns Jira Service Management worklogs and service-request events into an append-only contract-entitlement ledger. Teams can manage recurring, fixed-term, and prepaid contracts in minutes, tickets, or credits; monitor balances and overage; explain each movement; reconcile delayed events; and export auditable evidence.

The app runs entirely on Atlassian Forge. It is an operational entitlement record and reporting aid, not an invoicing, payment, tax, payroll, or legal-compliance system.

Before you begin

• Install the app on a Jira Cloud site with Jira Service Management.
• Use a Jira site administrator to set global defaults and a Jira or project administrator to configure a project.
• Attach at least one customer organization to the service project before creating organization coverage.
• For worklog-based rules, confirm that agents log time in Jira and that the selected agent groups are correct.

On first installation, QuotaLedger initializes its Forge SQL schema automatically. Keep the page open: it checks readiness every five seconds and continues as soon as initialization finishes.

1. Configure site-wide defaults

1. Open Apps → Manage your apps → QuotaLedger for Jira Service Management.
2. Set the business timezone, data-retention period, fiscal-month start day, default unit, low-balance threshold, rounding mode, increment, and minimum duration.
3. Choose whether aggregate balances may be shown in the customer portal. Each contract must also opt in before a balance is displayed.
4. Optionally map Jira groups to the Manager, Finance, and Auditor roles. Enter a stable group ID or the exact group name.
5. Select Save global settings.

2. Create a project contract

1. Open the Jira Service Management project and select QuotaLedger from the project navigation.
2. Choose the 10 hours/month, 20 tickets/month, or 100 credits/month template, or start with a custom contract.
3. Select an organization attached to the service project. Reuse an entitlement account when several organizations share one commercial account; otherwise create a new one.
4. Set the contract number, public name, contract type, dates, granted quantity, unit, low-balance threshold, overage policy, rollover policy, and optional split allocation.
5. Configure the consumption rule, then create and publish the contract.

Contract types

• Recurring: renews the entitlement period according to the configured cadence and rollover policy.
• Fixed term: covers a defined start and end date.
• Prepaid top-up: starts with a purchased balance and supports audited additional grants.

3. Configure consumption rules

Rules can match request type, priority, labels, an allowlisted selected field, business calendar, and—for worklogs—allowed Jira groups. Selected fields are restricted to Jira custom-field IDs and issue type; QuotaLedger does not read or persist issue descriptions, comments, or worklog bodies.

• Minutes: consume logged minutes using exact, ceiling, floor, nearest, or minimum-then-increment rounding.
• Tickets: consume one unit for the selected issue event.
• Credits: can apply integer priority and after-hours multipliers with configured minimum and maximum values.

When multiple rules match, QuotaLedger uses specificity, contract priority, nearest expiry, and a stable final tie-breaker to make the outcome reproducible.

4. Test before applying

1. Use Historical issue dry run with an existing issue and the intended event basis.
2. Review each event’s allocated, overage, unallocated, no-match, or late-event outcome.
3. Confirm the preview reports zero writes.
4. When the trace is correct, reconcile the issue or generate a new test event.
5. Verify the project balance and Jira issue panel.

Daily use

• The project dashboard shows active accounts, contract balances, alerts, exceptions, and reconciliation health.
• The Jira issue panel explains the current request’s contract, bucket, rule version, balance movement, and reversible ledger entries.
• The JSM organization panel summarizes active coverage for internal users.
• The authenticated customer portal panel shows the public contract name, unit, request-attributed consumption, and period end. Aggregate balance appears only when both site and contract settings allow it and the customer belongs to the bound organization.

Roles and permissions

Group membership does not bypass Jira permissions: a user must also be able to browse the project. Inactive licenses keep data readable but disable configuration changes after the documented integrity window.

Exceptions and reconciliation

• No coverage: correct the organization mapping, contract dates, or rule, then retry.
• Ambiguous account: remove the conflicting active organization mapping, then retry.
• Quota exhausted: approve a different overage policy or grant/adjust entitlement, then retry.
• Late event: a Manager may apply it to the current period; the original occurrence remains in metadata.
• Context changed: a Manager may reassign it to the request’s current organization/account. Existing ledger entries are never silently moved.

Scheduled, paginated reconciliation recovers delayed, updated, deleted, or duplicated Jira events. If an exception remains unresolved, export redacted diagnostics and contact support.

Close, reopen, import, and export

Closing a period expires eligible positive remainder, calculates a deterministic checksum, and increments the close revision. Reopening creates referenced reversal entries and preserves the prior checksum in the audit trail. High-impact actions require a reason.

Export ledger produces a cursor-paginated CSV and a JSON manifest containing contract/version configuration, periods, buckets, rules, exceptions, audit events, and checksums.

For opening balances, Managers can preview and apply a CSV with the header contractNumber,bucketCode,quantityDelta,occurredAt,evidence,reason. Imports are limited to 500 rows and 1 MiB and are idempotent.

Troubleshooting and support

• If the first configuration page is preparing the database, leave it open; it refreshes automatically.
• If access is denied, verify Jira site/project permissions, project browse access, and mapped role groups.
• If an organization is absent, add it to the JSM project first, then reload QuotaLedger.
• If consumption is missing, run the historical dry run and check the event basis, rule dates, organization mapping, and allowed agent group.
• For unresolved failures, download the redacted diagnostics bundle and include the site URL, timestamp, app version, and technical correlation ID—never credentials or customer message bodies.

Email support@callsiq.com or review the support policy for channels, service hours, severity, and response targets.