Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Worklog Reminder User Guide

Owner: Worklog Reminder Team

1. Overview​

1.1 Introduction​

Worklog Reminder enforces worklog policies inside Jira by evaluating time entries against configurable rules, persisting compliance snapshots, and orchestrating follow-up actions when users fall behind on their logging commitments.

1.2 Key Benefits​

  • Automated compliance coverage – Background schedulers and queue consumers keep policies running on a cadence without manual effort, ensuring coverage across days, weeks, or months.
  • Targeted accountability – Policies support user and group audiences, flexible logic, and multiple metrics so you can tailor expectations to each team or project.
  • Actionable escalations – When gaps are detected, the app raises Jira flags, optional redirects, or Jira comment notifications, giving users immediate next steps while tracking acknowledgement history.

1.3 Architecture at a Glance​

Worklog Reminder ships as a Forge app with an administrator project settings page, a personal “My Reminders” global page, and an issue-view background script, all backed by scheduled triggers and queues for long-running work. Persistent storage in Forge KVS keeps policy definitions, compliance entries, and reminder action profiles available to all modules.

2. Getting Started​

2.1 Installation Prerequisites​

Because the app requests Jira configuration and work access scopes, installation must be performed by a Jira administrator who can grant the required permissions. Ensure Forge dependencies are deployed and the app is installed on the desired site before onboarding end users.

2.2 Access & Permissions​

The app reads users, groups, and worklogs, writes worklogs when redirect actions trigger, and stores configuration in app storage. Limit who can administer policies by controlling access to the project settings module in Jira’s global permissions.

2.3 Navigating Entry Points​

  • Project settings – Worklog Reminder adds a dedicated settings page where administrators build policies, manage audiences, and review diagnostics.
  • My Reminders – End users open the global page to review their recent and historic escalations, grouped by timeframe.
  • Inline nudges – A background script runs on the Jira issue view to surface policy breaches at the moment users interact with work items.

3. Core Concepts​

3.1 Policies​

Policies capture the contract between the organisation and its teams: a name, description, labels, status (draft, active, archived), linked rules, and reminder actions, all persisted for auditability.

3.2 Audiences​

Each policy can target specific users or Jira groups in include or exclude mode, and stores descriptive metadata (display names, avatars) for clarity in the UI and reporting. Administrators can add or remove selectors as needs evolve.

3.3 Rules and Constraints​

Rules bundle one or more constraints evaluated with ALL/ANY logic. Constraints compare logged hours (total or per project) over daily, weekly, or monthly windows using numeric thresholds expressed in hours or days, including optional rolling-window sizes and closed-period checks.

3.4 Reminder Actions​

Policies can attach reminder action profiles of type flag, redirect, or Jira email. Redirects store a destination URL, while Jira email actions capture the issue key used to post follow-up comments.

3.5 Compliance Records​

When policies run, the app creates one compliance entry per user and reporting window, recording expected versus actual seconds, comparator metadata, and the current escalation status (new, resolved, ignored, exhausted, compliant). Entries also keep user display details for user-facing summaries. Each record is keyed by policy run and user, seeded with Jira profile information when stored.

3.6 Diagnostics Engine​

The diagnostics service resolves the target audience, evaluates every enabled rule for each account, and compiles constraint-level results so administrators can trace why a policy matched or failed. The engine is reusable across UI and background contexts thanks to dependency injection.

3.7 Policy Execution & Scheduling​

Policy runs are triggered either manually or via queues. The runner logs each execution, updates run metadata, stores compliance entries, and dispatches reminder notifications for failing users. Scheduling derives frequency from constraint windows, finds the right anchor date, and persists the next pending run; queues then advance the cadence after each execution.

3.8 Notification Channels​

Non-compliant entries trigger reminder actions. Jira email actions enqueue a comment that mentions the user and summarises required versus logged hours for the reporting window, while flag and redirect actions are executed inline via the background script.

3.9 Escalation Lifecycle​

Compliance entries track a status lifecycle: new issues appear in user dashboards, action counts cap repeated nudges at five before marking entries as exhausted, and administrators or users can ignore or resolve items when appropriate. Users can request their current escalation via the API, while the reminders controller filters recent views to unresolved items.

4. Representative Use Cases​

  • Daily time tracking compliance – Enforce minimum daily hours and surface immediate flags for missing logs, backed by day-level windows and inline notifications.
  • Weekly or monthly utilisation reviews – Combine weekly and monthly constraints so finance or PMO teams can validate utilisation ahead of billing cycles, with schedules automatically rolling forward.
  • Client billing assurance – Store precise expected versus actual hours per policy run and include those figures in Jira comment reminders for audit trails and stakeholder communication.
  • Employee enablement – Give individuals a personalised reminder centre and allow them to self-resolve or snooze escalations, reducing manager overhead while keeping accountability transparent.

5. Administrator Workflows​

5.1 Create and Publish a Policy​

Supply a name, optional labels, target selectors, and rule definitions; optionally publish immediately to activate the schedule. Each creation request accepts audiences, multiple rules, and an optional default reminder action. Policy records are stored with status metadata for later editing or archival.

5.2 Configure Reminder Actions​

Administrators can assign or update action profiles, including redirects (validated for URLs) and Jira emails (validated for issue keys). The resolver persists the chosen action type along with destination metadata for subsequent executions.

5.3 Manage Audiences​

Add or remove user and group selectors through the policy APIs, which accept both single-value and multi-value inputs plus descriptive metadata to keep summaries legible. Audience resolution later expands these selectors into concrete account IDs at run time.

5.4 Run Manual Checks & Monitor Progress​

Use the diagnostics endpoints to trigger immediate worklog evaluations or queue manual policy checks; results appear in the same repositories and schedules used by automation.

5.5 Review Compliance & Scheduling Data​

List stored compliance entries, inspect past check runs, and fetch pending schedules via the diagnostics API surface to understand historical performance and upcoming executions.

5.6 Maintain Automation Cadence​

After each successful execution the app automatically enqueues the next scheduled check, but administrators can reschedule pending runs or review cadence logic through the exposed endpoints if business needs change.

5.7 Perform Data Hygiene​

Diagnostics tooling includes a bulk delete endpoint to clear stored compliance entries when resetting pilots or responding to data retention requests.

6. End-User Experience​

6.1 Personal Reminders Workspace​

The global page surfaces unresolved escalations first, capped at the most recent 25 entries, while the “All” tab exposes the full history sorted by most recent activity. Entries include policy names, time windows, and logged-versus-expected totals for context.

6.2 Inline Jira Prompts​

When a user with an outstanding escalation views an issue, the background script shows a persistent flag (or performs a redirect) describing the gap, provides a shortcut to the reminders page, and records each invocation to avoid spamming beyond five attempts.

6.3 Jira Email Nudges​

If a policy’s action includes Jira email, the queue posts a comment to the configured issue, mentions the affected user, and lists required, logged, and outstanding hours for the reporting window, creating an auditable trail of reminders.

6.4 Self-Service Resolution​

Users (or admins on their behalf) can ignore or resolve escalations, which updates the stored status, suppresses future flags, and keeps the audit trail intact. Increment endpoints track how often actions fire so support teams can intervene when attention wanes.

7. Data Handling & Security​

7.1 Stored Information​

The app stores policy metadata (names, labels, statuses), reminder actions, compliance entries, and action counters in Forge storage, each keyed for efficient lookups per policy run and user.

7.2 Permission Scope​

Forge permissions include reading users, groups, and worklogs, writing worklogs, and managing configuration. Review these scopes regularly to ensure they align with organisational governance standards.

7.3 Notification Content & Privacy​

Reminder copy is generated from stored compliance entries and includes only necessary policy details, reporting windows, and aggregate time values to avoid exposing sensitive worklog narratives. Background flags reuse the same computed metrics without storing additional personal data.

8. Troubleshooting & Support​

8.1 Diagnostics Toolbox​

Use the diagnostics endpoints to rerun policies on demand, inspect stored compliance entries, view scheduled checks, or purge stale data. These tools expose the same services the automation layer uses, making it easier to compare expected versus actual behaviour.

8.2 Common Causes of Missing Alerts​

If a policy run returns no results, confirm that the audience resolver produced account IDs and that at least one constraint is enabled; the diagnostics service logs when no users are in scope and skips evaluation in that case.

8.3 Operational Tips​

Policy runs log success and error outcomes, capturing messages when storage updates fail or when reminder notifications cannot be enqueued. Monitor Forge logs for entries from the policy runner or reminder dispatcher when troubleshooting escalations.

9. Frequently Asked Questions​

How often will policies run automatically?
Policy cadence is derived from the tightest constraint window (daily, weekly, or monthly) and the scheduler automatically advances the next run after each execution.

What happens if a user keeps ignoring reminders?
Each escalation tracks how many actions have fired; after five invocations the status flips to “exhausted” to prevent repeated prompts, while the entry remains visible in dashboards for follow-up conversations.

Where can I review my past compliance history?
The “All Reminders” tab in the global page lists every compliance entry in reverse chronological order, including resolved or ignored items for full transparency.