HERO APP'S Wiki

At a glance

1. How the app is put together

Six ideas explain almost everything the app does. Read this section once and most of the rest becomes predictable.

1.1 Roles come from Jira groups

Five roles, each mapped to a Jira group. The mapping is seeded automatically the first time an administrator opens the console.

Two things surprise people:

• hrms-employees does nothing. Everyone starts at employee already, and hub access is decided by the roster (1.2), not by role.
• hrms-managers does not create managers. Manager surfaces appear for anyone with at least one person under them in the reporting hierarchy, which you set on a profile. The group only affects the leave-balance permission above.

In practice you need hrms-system-admins and nothing else to get started. Add hrms-hr-admins when you have HR staff who need the console but should not be system administrators.

1.2 Being a Jira user is not enough

A Jira user becomes an HRMS member by being added to the roster — from the admin Users section, or by CSV import. Non-members are refused on every user-facing operation.

Administrators bypass the roster check by role. That is what makes the console reachable on a brand-new install, before anyone has been provisioned.

1.3 The organisation is modelled twice

• Reporting hierarchy — each person has a placement (who they report to). A manager's branch is their direct reports plus everyone nested beneath them, transitively. This is what scopes Dashboards and Team Reports.
• Agile structure — Portfolio to Squad to Person, with each person's capacity split across squads. Squads with no live portfolio appear under a Non-Portfolio branch.

Squad membership has exactly one source of truth: the capacity allocations on each person's own profile. The squad members editor and the profile editor write the same data, so they cannot drift apart.

1.4 One approval engine

Timesheet logs, leave requests and manual overtime all route the same way:

1. Resolve the submitter's approver set for that kind of request. Timesheet, leave and overtime each have their own separate list on the person's profile.
2. If that list is empty, use the fallback approvers you configured. If you configured none, any hr or admin role holder may decide.
3. Apply the quorum: All (every approver must decide) or Any (the first decision settles it).
4. Self-approval is off unless enabled on that person's profile.

Every decision is appended to an immutable log. A decision from someone who is not a routed approver does nothing at all.

1.5 Deactivation locks out; it never deletes

Deactivating someone refuses every operation they attempt, shows them a lock screen, and re-routes their pending approvals to the fallback approver. Their history is untouched — timesheets, leave, clock sessions and overtime all survive and keep appearing in reports for past periods.

Two protections: you cannot deactivate yourself, and administrators keep access by their role bypass. Deactivating an administrator is recorded, and the app tells you plainly that they still have access — remove them from the admin group in Jira to actually lock them out.

1.6 The interface holds no authority

Tabs are hidden when they would be useless, but hiding is never the security boundary. Every gate is re-checked on the server:

• Personal reports accept no account identifier in any payload, so "show me someone else's data" cannot be expressed.
• Team reports refuse a caller who manages nobody.
• Admin reports refuse a non-administrator.
• Approval queues filter to your routable items, and each decision re-checks authority.

2. Installation and first run

2.1 Install

Install HRMS Hero from the Atlassian Marketplace. A site administrator approves the requested scopes.

2.2 Create one group

1. In Jira, go to Settings to User management to Groups.
2. Create hrms-system-admins.
3. Add yourself to it.

That is the minimum. Add hrms-hr-admins, hrms-managers later if you need the distinctions in 1.1.

2.3 Open the admin console

Go to Jira Settings to Apps to HRMS Hero Admin.

On the first visit the app seeds its role mapping, runs its database migrations and bootstraps the roster. No configuration is needed to reach this point — if you are in hrms-system-admins, the console opens.

A fresh install replays every database migration from zero. Forge SQL sometimes rate-limits the first burst of schema work. It self-heals. Wait a minute and reload once — repeated reloads re-trigger the work and make it take longer.

2.4 Optional: a Jira project for timesheet periods

A weekly background job creates one Timesheet Period work item per active person, in a project with the key TS. These periods back the timesheet-summary issue panel and the historical fact store that reporting reads.

If you want that machinery running, create a company-managed project with key TS and an issue type named Timesheet Period. If you do not, the weekly job will fail while everything an employee touches day to day — logs, leave, punch, overtime, reports — continues to work.

2.5 Direct links

Open each surface once through the menus and copy the address bar to capture the identifiers.

Tabs inside the app have no separate URL. A link always opens on Overview (hub) or Users (admin console). You cannot bookmark a specific tab.

3. The admin console

Jira Settings to Apps to HRMS Hero Admin. Eight sections in the left nav. Your role shows as a badge in the top-right.

Work through them in this order on a new install: Workspace to Skills to Overtime to Admin Actions to Users. The first four create the things the Users section assigns.

3.1 Workspace — roles, portfolios and squads

Three independent lists describing your organisation.

Create an entry

1. Open Workspace.
2. Choose the list: Roles, Portfolios or Squads.
3. Type a name and click the add control.

Names must be unique, case-insensitively, within one list only — a "Payments" portfolio and a "Payments" squad can coexist.

Rename an entry

1. Click the entry's name.
2. Edit it and save.

Every assignment survives a rename. Identifiers are generated and stable — they are never derived from the name.

Link a squad to a portfolio

1. Open the squad.
2. Choose its portfolio from the dropdown.
3. Save.

This is what builds the Agile Map. A squad with no portfolio appears under Non-Portfolio.

Give a portfolio a manager

1. Open the portfolio.
2. Choose a person in the manager picker.
3. Save.

Edit squad members and their capacity

1. Open a squad and choose its members editor.
2. Add people with the picker.
3. Set each member's capacity share as a whole number 0-100.
4. Save.

This writes to each person's profile — the same data the profile editor writes — so both directions always agree. The rule that a person's shares across all their squads must total 100 or less is applied here too. If any member in the batch would break that rule, the whole batch is rejected rather than half-applied, and the message names the person.

Delete an entry

1. Open the entry and choose delete.

If anyone still holds it, the delete is refused and the message names up to five holders and counts the rest. Reassign them first.

If you see "this list changed since you opened it"

Another administrator edited the same list. Reload and reapply your change. Each list is versioned as a whole, so this can happen even when the two of you edited different entries.

3.2 Skills — the catalogue

Create a skill

1. Open Skills.
2. Enter a name and a description.
3. Choose a rarity: na (default), common, rare, epic or legendary.
4. Save.

Edit or delete

1. Open the skill, change it, save.
2. To delete, choose delete. If anyone holds the skill the delete is refused and the message tells you how many hold it.

Skills created here are what you assign to people on their profile. They appear on profile cards, in exports, and in the Users with skills report, which can be filtered by skill or by rarity.

3.3 Overtime — policies

Create a policy

1. Open Overtime.
2. Enter a policy name.
3. Set the working-day base — hours worked on a normal day before overtime starts counting.
4. Set the working-day countable cap — the most overtime that will be counted on a normal day.
5. Set the weekend cap — the most that will be counted on a day that is in the person's weekend.
6. Save.

Assign it

A policy does nothing until it is assigned. Assign it per person from Users to the person's profile to Overtime policy, and switch Overtime enabled on.

Delete

Refused while anyone still has the policy assigned; the message includes the count.

3.4 Admin Actions — leave policies

Create a policy

1. Open Admin Actions.
2. Enter a policy name.
3. Add a leave type row and fill in: Label (what employees will see), Allowance (yearly entitlement), Paid (whether the type is paid), Reason required (whether an employee must give a reason).
4. Add as many type rows as you need.
5. Save.

Rules

• The policy named default is protected and cannot be deleted.
• A policy still assigned to someone cannot be deleted.
• An employee can only ever request a type that exists in their assigned policy.

3.5 Users — the directory and every per-person setting

The section you will return to most.

Find someone

1. Open Users.
2. Type into the search box. The directory lists active Jira users — name and avatar only.
3. Page through with the pagination control.

Each row shows the person's role, their occupied capacity, and their activation switch.

Edit a profile

Click a person to open their profile sheet. Every field, in order:

Approvals

Leave an approver list empty to route that kind of request to the fallback approvers instead.

Working pattern

Overtime

Leave

Reporting placement

Workspace

Skills — a multi-select from the catalogue.

To save: click Save. The remaining-capacity readout and the disabled Save button below 100% are conveniences; the server applies the real rule.

Capacity rules

• Every allocation must name a squad the person actually belongs to. An allocation for a squad they are not in is rejected, not silently dropped.
• Each share is a whole number 0-100.
• The total across their squads must not exceed 100.
• Occupied and free are always derived from the allocations — there is no second figure that can contradict them.

Set the fallback approvers

1. On the Users section, find the fallback approver setting.
2. Add one or more people.
3. Save.

These people receive submissions from anyone whose own approver list is empty. Do this early. If you leave it empty, the app falls back to "any hr or admin role holder", which works but names nobody in particular. The form refuses to save an empty list once you have opened it.

Activate or deactivate someone

1. Click the activation switch on their row.
2. A confirmation dialog names the person and the new state.
3. Click Confirm.

Nothing happens until you confirm. Your own row is disabled. If the person is an administrator, the result line tells you the change was recorded but they keep access — remove them from the admin group in Jira to actually lock them out.

Export one person's history

1. From the person's row actions, open the export dialog.
2. Choose timesheet logs or leave requests.
3. Choose all time or a date range.
4. Choose CSV or JSON.
5. Download.

Add people in bulk

1. Open Bulk actions.
2. Choose one:

3. For Upload, Update or Clear, type the confirmation phrase shown. The confirm button stays disabled until it matches.
4. Confirm. Large files are streamed in chunks and processed in the background.

Three things worth knowing:

• The CSV is parsed in your browser, so large files do not hit a payload limit.
• Email addresses are used only to resolve an existing Jira user's account id, then discarded. They are never stored. If your Jira instance hides email addresses, the import reports that loudly rather than silently matching nothing.
• Clear and Update affect profiles and the roster only. Timesheet, leave and audit history are never touched. Anyone removed is scrubbed from every approver set, so their pending items re-route to the fallback.

3.6 Org map — two read-only views

Open Org map. The screen splits into two trees.

Main Organization map — the reporting hierarchy, built from each person's Parent user.

Agile Map — Organisation to Portfolio to Squad to Person, with each person's occupied capacity.

To use them:

1. Click a node to expand or collapse it.
2. Click a person to open their read-only profile card, which includes their skills and exports as CSV, XLSX or PDF.

Neither map edits anything. Change placement from a person's profile; change portfolios and squads from the Workspace section.

3.7 Reports — organisation-wide

Covered in full in section 6. In short:

1. Open Reports.
2. Click a report card.
3. Set the date range, and optionally narrow by portfolio, squad or master node.
4. Read the chart and table, then export as CSV, XLSX or PDF.

The three full reports run every individual report for one chosen structure. Their structure filter is required — a "portfolio full report" with no portfolio chosen has no meaning.

3.8 Punch-in/out — attendance enforcement

Two independent switches, applied to a list of people.

Turn on force punch

1. Open Punch-in/out.
2. Switch Force punch on.
3. Add the people it applies to.
4. Save.

Those people now see a blurred hub with a punch-in widget until they clock in.

Turn on the session checker

1. With force punch on, switch Session checker on.
2. Set the interval in minutes.
3. Save.

At every wall-clock interval — on the hour, say, regardless of when someone punched in — the app blurs and asks them to renew. They have 10 minutes. Miss it and they are punched out and locked until they clock in again. A short tone plays so they notice while working in another tab.

Use this deliberately. It is visible and interruptive by design. Turn both off to remove it.

4. The employee hub

Open it from Apps to HRMS Hero. The left nav adapts to what you are entitled to see.

A missing tab means you do not qualify. Tabs also stay hidden while their check is loading, so give the page a moment.

4.1 Overview

Your landing page.

The tiles show, where they apply to you: total / this month / this week / today logged hours; your pending submissions; items awaiting your decision (approvers only); leave this year / month / week; and — if overtime is enabled for you — overtime this year / month / week plus today's provisional figure.

To hide tiles you do not care about:

1. Click Customize.
2. Untick any tile.
3. The choice saves to your own preferences immediately.

Below the tiles:

• Requests history — your recent leave and timesheet requests with their status.
• Effort by project — your own logged hours per project, as a bar chart.

Two things to know:

• "This week" follows your weekend. The week starts the first day after your configured weekend and ends the day before it. With a Wednesday + Thursday weekend, your week runs Friday to Tuesday.
• A tile reading "Unavailable" means that one figure could not be computed. It deliberately does not show 0, which would be untrue. The rest of the page still works.

4.2 Punch-in/out

Clock in

1. Open Punch-in/out.
2. Click Punch in.

The badge turns green, an elapsed counter starts, and the session appears in today's list marked Still open.

Clock out

1. Click Punch out.

If you have punched time today that you have not logged yet, a prompt opens offering to log it:

1. The date is pre-filled and the hours are capped at the outstanding balance.
2. Fill in the rest of the log and save — or cancel, which is a perfectly valid skip.

Through the day

• Punch in and out as many times as you need. Your day total is the sum of all sessions.
• Today's total session hours counts every session including the one running.
• A session left open at the end of your local day is closed automatically by the server and badged Auto-closed, so a system-generated end time is never mistaken for a real punch-out.
• If your state changes in another tab, the screen refreshes and explains rather than getting stuck.

Review your history

1. Scroll to History.
2. Set From and To to narrow the range.
3. Click Load more to fetch older days.

Each day card shows its total and every session within it.

Export

1. Set the date range you want.
2. Click Export CSV.

The file contains your own sessions for that range.

If enforcement is on

• Force punch — the hub is blurred until you clock in. Click the punch-in button in the centre widget.
• Session checker — at each interval the screen blurs and asks you to renew. Click Renew punch within 10 minutes. Miss it and you are punched out; punch in again to continue.

4.3 Timesheet

Your logging home.

Read the week strip

Seven days with the hours logged against each day's target, drawn from your Official Working Hours. Weekend targets are 0, but the days still appear. Today is highlighted. The week total sits alongside.

There is no "submit week" — submission is per log.

Create a log

1. Click New log.
2. Choose the Log Category: Non-Portfolio (go to step 4) or Portfolio (go to step 3).
3. Choose the Portfolio Type: Feature, Support or Agile Ceremony.
4. Fill in the Date and Work Hours. Both are required.
5. Description is optional.
6. For a Feature log only, choose the linked Jira work item. Type two or three characters to search; results cover anything you can access, not just items assigned to you. This field is required for Feature logs.
7. Save as draft, or submit for approval.

Limits

• No single log may exceed 24 hours.
• No single day may total more than 24 hours across all your logs.

The log lifecycle

draft to pending to approved | rejected | withdrawn

• draft — yours to edit freely
• pending — awaiting a decision; it cannot be edited
• approved — terminal and read-only
• rejected or withdrawn — editable again, so you can correct and resubmit

Edit, submit or withdraw

1. Find the log in My logs.
2. Use its row action: Edit (draft, rejected or withdrawn only), Submit, or Withdraw (pending only).

Filter your logs

1. In My logs, choose one or more status filters.
2. Set a date range.

The breakdown

The card beside your logs totals the current week by type — Feature, Support, Agile Ceremony and Non-Portfolio — against your weekly target.

What happens on approval

An approved Feature log mirrors its hours once onto the linked Jira work item as a worklog. The mirror is tagged so the app never double-counts it. All approved logs feed the reporting fact store and trigger an overtime recalculation.

4.4 Admin Actions to Leaves

Despite the name, this is your own leave view. Approvals live in the Requests tab.

What you see

• My Leave Balance — one card per leave type in your policy, showing available against entitled
• Your calendar — your own leave, marked by day
• My Leave Requests — type, dates, days and status, with row actions

Request leave

1. Click New request.
2. Choose the Leave Type. The list comes only from your assigned policy.
3. Set Start and End dates.
4. For each boundary day, choose Full day or Partial: Partial reveals From and To times, bounded by your Official Working Hours windows.
5. If the type requires it, fill in the Reason field. It only appears for types that need one.
6. Save as draft, or submit.

Duration and balance are previewed as you type. The server re-validates everything on submit — the preview is a convenience, not the rule.

Manage a request

From its row: Edit (draft, rejected or withdrawn), Submit, Withdraw (pending), or Cancel.

4.5 Overtime

Visible only when overtime is enabled on your profile.

What you see

Four tiles: today (provisional), plus finalised week, month and year. Every figure is HH:MM. Below is the day-by-day history with each day's status.

How to read it

• Today is provisional and still accruing. It is not a fact until the hourly finaliser closes your day.
• Everything else is finalised, with one of four statuses:

You cannot request overtime. It is computed from your logged time against your assigned policy, with your configured weekend deciding which days count as weekend days. To change the numbers, change the underlying time logs.

4.6 Workspace

A read-only view of where you sit in the organisation.

What you see

Your role, your portfolios, your squads, and your capacity split — including how much is free.

Below that, two trees:

• Main Organization map — your reporting branch
• Agile Map — your branch through Portfolio to Squad to Person

To view someone

1. Click a person in either map.
2. Their read-only profile card opens, including their skills.
3. Export it as CSV, XLSX or PDF if you need it.

Who you may open is decided on the server: administrators may view anyone; everyone else may view themselves and people in their own reporting branch.

This route takes no input and changes nothing. It can only ever show your own data.

Your own profile card

Click the profile button in the hub's top-right corner at any time. Same card, same three export formats.

5. Approving work

The Requests tab appears if you are a named approver for anyone — including yourself, when self-approval is on.

5.1 The inbox

One surface covers leave, timesheet logs and overtime.

1. Open Requests.
2. Choose a filter tab: Pending, Approved, Rejected or All. Pending carries a live count.
3. Click an item in the left list.
4. The right pane shows its full detail and the approval-chain timeline — who has decided, when, and with what comment.

5.2 Decide

1. With an item selected, click Approve or Reject.
2. Add a comment where one is required.

5.3 How a decision settles

• Under Any, your decision settles the item.
• Under All, every named approver must decide before it settles.
• A decision from someone who is not a routed approver does nothing — no state change, and no error that would confirm the item exists.

5.4 What approving does

Known limitation. The queues read the first page of globally pending items and then filter to you. In a very large organisation with many simultaneously pending items, an approver could miss items beyond that first page. This is tracked as a follow-up.

6. Reports

6.1 Three tiers

self subset branch subset organisation.

6.2 Run a report

1. Open the tier's section.
2. Click a report card.
3. Set the date range.
4. Apply any filters the report offers: Administrator reports add portfolio, squad and master node; The skills report adds skill and skill rarity.
5. Read the chart and the table.
6. Click the export control and choose CSV, Excel (XLSX) or PDF.

Filters intersect — they narrow, never widen. A filter naming something outside your reach, or something that does not exist, returns an empty report rather than an error, because an error would confirm that out-of-reach data exists.

6.3 The catalogue

Personal — 4

Team and administrator — the same nine, over different populations

Declared once and offered at both tiers, so a manager and an administrator see the same columns and the same metric definitions.

Plus Users with skills at both tiers — person, role, skills, count, rarest — filterable by skill or rarity.

Administrator only — three full reports

Portfolio, Squad and Master node full reports each run every individual report for one chosen structure and return them as titled sections. Their structure filter is required. The skills report is excluded from them — it is a snapshot, not an operational metric.

That is 27 definitions: 4 personal, 10 team, 13 administrator.

6.4 Two metric definitions to read carefully

"Not filling timesheets" counts only expected working days. A day is expected only if it is not the person's weekend, not approved leave, and not an organisation non-working day. Both compliance reports use this rule, so only genuine gaps are counted.

"Average clock in/out" is an arithmetic mean, not a circular one. It averages each day's first clock-in and last clock-out as a time of day. A shift crossing midnight will skew it. This is documented rather than silently corrected.

6.5 About the exports

• Export and screen always agree. The export runs the identical scoped query as the view, so it can never contain a row the screen would not show.
• XLSX cannot carry a formula-injection payload. A cell is a formula in that file format only when it explicitly says so, and the writer emits inline strings and numbers only. CSV, being typeless, uses prefix quoting instead.

All three writers run on the server with no third-party dependency.

7. Surfaces inside Jira

7.1 Log time from a work item

1. Open any Jira work item.
2. Open the actions menu (...).
3. Choose Log timesheet (HRMS Hero).
4. Enter Work Hours and an optional description.
5. Submit.

This files a Feature log against that item, dated today. Category, date and the linked item are fixed from context. All the usual validation and approval routing applies. Someone who is not a provisioned member sees an explanation and no form.

7.2 Issue panels

Four panels are available on work items.

Each shows only what the server decides you may see.

7.3 Dashboard gadgets

To add one:

1. Open a Jira dashboard and choose to add a gadget.
2. Pick from the three HRMS gadgets.

Each is permission-scoped on the server, so two people looking at the same gadget may correctly see different numbers.

7.4 Workflow extensions

Available when editing a Jira workflow:

• HRMS approval validator — requires a comment on reject or return, and re-checks balance and overlap
• HRMS timesheet submission validator — blocks submission below the minimum hours, or with any uncategorised worklog
• HRMS approval post-function — routes to the next level, applies balance effects, appends the trail and audit entry, and notifies

Approver authority is enforced in the post-function, which is the sole authority regardless of what the workflow permits.

7.5 Export endpoint

An authenticated, scope-narrowed inbound pull endpoint for payroll or BI systems. Your system calls the app; the app never calls out. The token is app-issued and administrator-provisioned — end users never supply a credential.

8. What runs automatically

Two triggers react to Jira itself: work item created or transitioned (a routing backstop), and worklog created, updated or deleted (timesheet reconciliation).

Reconciliation recomputes from source. On every worklog change the app re-derives the period's totals from the full current worklog set rather than applying a delta. That makes it idempotent and convergent: replaying an event, or receiving events out of order, still lands on the correct total and can never double-count or go negative.

9. Security and data protection

9.1 Architecture

• No network egress. The app declares no external hosts, enforced by the Forge platform and by a lint rule in the build pipeline. It cannot reach an outside service even if asked to.
• Data stays in your tenancy. Configuration in Forge KVS; facts, history and audit in Forge SQL. Both are Atlassian-hosted app storage inside your site.
• Identity is delegated. No app login, no password, no separate account. The signed-in Jira user is the identity, always taken from the platform — never from a request payload.
• The server is the sole authority. Every visible gate is re-checked server-side. Forcing a hidden route open exposes nothing.
• Scoping narrows only. Filters intersect with your scope and can never widen it. An empty intersection is an authorised-empty result, not an error.
• Audit is immutable and free of personal data. Configuration changes and administrative actions append to a log recording what changed. Reports are reads and are not audited.

9.2 What is stored about people

9.3 The one CSP relaxation

The app's iframes permit inline styles, which the charting, animation and accessible-primitive libraries require. Scripts stay locked. This is a style allowance inside a sandboxed iframe — not network access, and not a permission.

9.4 Documents

Privacy Policy, Terms of Use, DPA (an Article 28(3) data processing agreement) and Security. Atlassian is the sole sub-processor, which follows directly from the no-egress architecture.

10. Licensing

HRMS Hero is a paid Marketplace app. Atlassian resolves a licence for each installation and delivers it to the app on every call.

Enforcement is the app's own and it is total: every operation is licence-gated by construction. Three keys are exempt — the two status calls and the health ping — because making the calls that explain why the app is unusable depend on the app being usable would be circular.

An unlicensed site sees this on both the hub and the admin console:

Subscription required
HRMS Hero is not licensed for this site. Please ask a Jira administrator to start a trial or subscribe from the Atlassian Marketplace.

A deactivated person sees:

Account deactivated
Your account has been deactivated. Please contact your administrator.

When both apply, deactivation is shown — it is the more specific and more actionable answer.

For developers: the licence requirement applies to the production environment only. A development deployment reports no requirement by design, which is why development testing needs the CLI's licence-simulation flag.

11. Operations

For whoever maintains the app.

11.1 Quality gates

npm ci                    # install exactly the locked dependency tree
npm run typecheck         # backend + UI TypeScript
npm run lint              # ESLint
npm run sast              # security lint, including the no-egress tripwire
npm run format            # Prettier check
npm test                  # unit tests
npm run test:integration  # integration tests
npm run test:ui           # UI tests (jsdom — a bare vitest run fails here)
npm run size-check        # per-surface gzipped bundle budget

11.2 Build and deploy

npm run build:ui          # builds each Custom UI surface into static/<surface>/
forge deploy

predeploy runs the UI build and the size check automatically, so a plain forge deploy always ships a fresh, budget-checked build.

11.3 The bundle budget

Every UI surface must stay at or under 300 KB gzipped JavaScript, and the check sums all chunks per surface — so code-splitting improves load time but does not lower the total. The hub runs close to the ceiling. If a change would breach it, surface the "relocate or raise the budget" decision. Never silently breach it, and never disable the gate.

11.4 Environments

11.5 Installing and upgrading

• Deploying does not wipe data. A deploy updates code; storage is untouched.
• Installations auto-track minor versions, so forge install --upgrade usually reports "already at the latest version".
• Only forge uninstall destroys data.
• The licence-simulation flag applies only on a fresh install, not an upgrade.
• A licensed app cannot be CLI-installed to production — production installs come through the Marketplace.

12. Troubleshooting

"Subscription required" on a licensed site

Reload once, then check the subscription in the Marketplace admin. A development deployment never requires a licence, so seeing this there means the licence simulation is set to inactive.

"Could not determine your permissions"

The console could not resolve your role. Usually you are not in hrms-system-admins or hrms-hr-admins — or the app is mid-bootstrap on a fresh install, in which case wait a minute and reload once.

A fresh install shows failing tiles or empty data

Migrations are replaying from zero and Forge SQL may rate-limit the first burst. It self-heals. Repeated reloads prolong it.

Deactivating someone had no effect

They are an administrator or HR. Those roles keep access by design as an anti-lockout measure, and the confirmation says so. Remove them from the admin group in Jira.

A hub tab is missing

Tabs also stay hidden while their check is loading.

The task picker says tasks could not be loaded

It searches everything you can access in Jira. A failure means a Jira API error, which is recorded in the app's logs with the status and response.

A report is empty with no error

That is an authorised-empty result and it is deliberate. A filter naming something outside your reach — or something that does not exist — returns an empty population rather than an error, because an error would confirm out-of-reach data exists.

A role, portfolio, squad, policy or skill will not delete

Something still references it. The message names up to five holders and counts the rest. Reassign them first.

"This list changed since you opened it"

Another administrator edited the same taxonomy list. Reload and reapply. Lists are versioned as a whole, so this happens even when you edited different entries.

Someone's hours or overtime look wrong

Check three things on their profile, in this order:

1. Weekend days — decides which days count as weekend for overtime and for expected-day maths
2. Local UTC offset — decides where their local day boundary falls, and so which day overtime lands on
3. Official Working Hours/Day — sets their daily target

Timesheet periods are not being generated

The weekly job creates Timesheet Period items in a project with key TS. If that project or issue type does not exist, the job fails. See section 2.4.

13. FAQ

Does any of our data leave Atlassian?

No. The app declares no external hosts and cannot make outbound calls.

Do users need a separate account or password?

No. Identity is the signed-in Jira user.

Does updating the app wipe our data?

No. Only forge uninstall destroys data.

Which groups do we actually have to create?

Only hrms-system-admins. See section 1.1.

How do I make someone a manager?

Set other people's Parent user to point at them. Group membership does not do it.

Can someone see another person's data?

Only within their scope: yourself always; your branch if you manage people; the organisation if you are an administrator or HR. Personal reports accept no account identifier at all.

What happens to someone's history when we deactivate them?

Nothing. It is preserved in full and keeps appearing in reports for past periods. Only their access stops, and pending approvals re-route to the fallback.

Can I approve my own requests?

Only if an administrator enabled self-approval on your profile. It is off by default.

What if someone has no approvers configured?

Their submissions go to the fallback approvers you set. If you set none, any HR or admin role holder can decide.

Why is today's overtime "provisional"?

The day is not over. The hourly finaliser closes each person's just-ended local day and snapshots the value, so the finalised figure can never differ from what they were shown.

Is overtime requested or calculated?

Calculated, from logged time against the person's policy. There is no overtime request form.

Can I change the leave types available to someone?

Yes — edit their assigned leave policy, or assign them a different one from their profile.

Why do exports match the screen exactly?

The export runs the same scoped query as the view. It is not a separate code path that could drift.

14. Glossary

15. Limits and defaults

Defaults for an unconfigured person

Hard limits

Lifecycles

Timesheet log:    draft to pending to approved | rejected | withdrawn
                  (approved is terminal and read-only)

Leave request:    draft to pending to approved | rejected | withdrawn | cancelled

Overtime day:     auto_approved | pending to approved | rejected

Report identifiers

personal.<name>     e.g. personal.timesheet, personal.punch
team.<name>         e.g. team.missing-timesheet, team.users-with-skills
admin.<name>        e.g. admin.overtime, admin.full-portfolio

A requested identifier is resolved against the registry before anything else runs. Anything not declared there is a validation failure, never a query.

HRMS Hero is developed by HEROSAPPS. For support, see the contact details on the Marketplace listing.