@sparkerp/plugin-sdk 0.1.0 → 1.1.0

package/bundle/docs/applications/hcm/expenses-self-service.md

@@ -0,0 +1,30 @@
+---
+title: My Expenses, Team Expenses & Approvals
+audience: tenant
+---
+
+# My Expenses, Team Expenses & Approvals (HCM)
+
+This page documents three shipped **Expenses** self-service screens
+(`hcm-expenses`). Not for plugin developers.
+
+## My Expenses
+
+Your own claims — Claim Number, Date, Business Purpose, Total Amount,
+Policy Status, and Status. KPIs: Total, Draft, Pending, Approved, Paid.
+
+## Team Expenses
+
+If you're a manager, the same view scoped to your direct reports, with
+an Employee Name column so you can see whose claim is whose. KPIs:
+Total, Pending, Approved, Paid.
+
+## Approvals
+
+A consolidated inbox of both Expense Claims and Advances waiting for your
+decision, with a real Pending count so you know exactly how much is
+sitting in your queue.
+
+## Related
+
+- [Expense Claims & Advances](./expenses-claims.md)

package/bundle/docs/applications/hcm/expenses-setup.md

@@ -0,0 +1,43 @@
+---
+title: Expense Categories & Expense Policies
+audience: tenant
+---
+
+# Expense Categories & Expense Policies (HCM)
+
+This page documents two shipped **Expenses** setup screens
+(`hcm-expenses`). Not for plugin developers.
+
+**Who this is for:** finance/HR admins setting these up.
+
+## Expense Categories
+
+**New Category** — Category Name/Code, Category Type, Expense Type
+(Reimbursable, or Both — for categories that can be either), a GL Account
+(where this expense posts in your accounting system), Tax Treatment,
+Receipt Mode, a Receipt Threshold (the amount above which a receipt
+becomes mandatory), and whether a **Cost Center** is required on every
+claim in this category. New categories start inactive; **Activate** them
+once configured, **Deactivate** or **Archive** them when retiring one.
+The detail view also shows a real **Expense Count** — how many actual
+claims reference this category.
+
+## Expense Policies
+
+**New Policy** — Policy Name/Code, Policy Type, Priority (for when more
+than one policy could apply — priority decides which one wins), Currency,
+category-specific rules, and Effective From/To dates. **Manager Override**
+controls whether a manager can approve an expense that technically
+violates the policy anyway.
+
+New policies start Draft → **Submit for Review** → **Publish (Go
+Active)**. Once a version is published, you don't edit it in place —
+**Create New Version** starts a fresh version instead, so every claim
+always knows exactly which policy version it was checked against.
+**Deactivate** retires a policy. KPIs: Draft, Pending Review, Active,
+Archived.
+
+## Related
+
+- [Expense Claims & Advances](./expenses-claims.md)
+- [Expense Dashboard & Reports](./expenses-analytics.md)

package/bundle/docs/applications/hcm/health-safety-analytics.md

@@ -0,0 +1,26 @@
+---
+title: Health & Safety Dashboard & Reports
+audience: tenant
+---
+
+# Health & Safety Dashboard & Reports (HCM)
+
+This page documents two shipped **Health & Safety** analytics screens
+(`hcm-health-safety`). Not for plugin developers.
+
+## Health Dashboard
+
+Real-time operational counts: Open Hazards, Open Incidents, Open
+Accidents, Occupational Health cases Open, Exams/Records Pending Review,
+and Training Completed vs. Total — everything currently needing
+attention, on one screen.
+
+## Health & Safety Reports
+
+A trend/summary view over the same data: Total Incidents/Accidents,
+Critical Incidents specifically, Open Hazards, Exams/Records Pending
+Review, and Training Completed vs. Total.
+
+## Related
+
+- [Workplace Safety, Safety Incidents & Workplace Accidents](./health-safety-incidents.md)

package/bundle/docs/applications/hcm/health-safety-incidents.md

@@ -0,0 +1,44 @@
+---
+title: Workplace Safety, Safety Incidents & Workplace Accidents
+audience: tenant
+---
+
+# Workplace Safety, Safety Incidents & Workplace Accidents (HCM)
+
+This page documents three shipped **Health & Safety** register screens
+(`hcm-health-safety`). Not for plugin developers.
+
+## Workplace Safety
+
+A hazard register. Record what you found — Hazard Type, Location, Work
+Area, Department, who **Identified** it and when, **Existing Controls**
+already in place, and **Additional Controls** needed. Rate it by
+**Likelihood** and **Severity**, assign an **Owner** and **Target Date**
+to fix it. The KPI row includes a real **Open Risk Score Sum** — an
+aggregate risk number across every still-open hazard, not just a count,
+so you can see whether your overall exposure is trending up or down.
+KPIs: Total, Open, Closed, High Risk, Open Risk Score Sum.
+
+## Safety Incidents
+
+Record an incident — Employee, Department, Location, Incident Type,
+Severity, Description, and **Immediate Action** taken. Three real
+compliance flags matter here: **Lost Time** (did it cause missed work),
+**Restricted Work** (light duty), and **Regulatory Reportable** (does
+this need to be reported to a regulator) — plus **Hospitalization** and
+whether an **Investigation** is required. KPIs: Total, Open, Under
+Investigation, Closed, Critical, and a real **Days Away Sum** — total
+lost workdays across all incidents, a genuine safety metric, not a
+vanity count.
+
+## Workplace Accidents
+
+The closely related accident register — same core fields as Safety
+Incidents, plus Accident Type, **Classification**, **Immediate Cause**,
+Work Activity, and whether an **Insurance Claim** is required. Same KPI
+shape (Total, Open, Under Investigation, Closed, Critical, Days Away Sum).
+
+## Related
+
+- [Safety Training & Occupational Health](./health-safety-training.md)
+- [Health & Safety Dashboard & Reports](./health-safety-analytics.md)

package/bundle/docs/applications/hcm/health-safety-medical.md

@@ -0,0 +1,25 @@
+---
+title: Medical Exams & Medical Records
+audience: tenant
+---
+
+# Medical Exams & Medical Records (HCM)
+
+This page documents two shipped **Health & Safety** screens
+(`hcm-health-safety`). Not for plugin developers.
+
+## Medical Exams
+
+Schedule an exam — Employee, Exam Type, Facility, Provider, Priority, and
+Scheduled Date. KPIs: Total, Scheduled, Completed, Pending Review, Follow
+Up (a real, separate count for exams that flagged something needing a
+follow-up), Expired.
+
+## Medical Records
+
+Log a record — Employee, Record Type, Facility, Provider, Record Date.
+KPIs: Total, Active, Pending Review, Review Required, Verified, Expired.
+
+## Related
+
+- [Safety Training & Occupational Health](./health-safety-training.md)

package/bundle/docs/applications/hcm/health-safety-training.md

@@ -0,0 +1,29 @@
+---
+title: Safety Training & Occupational Health
+audience: tenant
+---
+
+# Safety Training & Occupational Health (HCM)
+
+This page documents two shipped **Health & Safety** screens
+(`hcm-health-safety`). Not for plugin developers.
+
+## Safety Training
+
+Assign a course to an employee — Course Code/Name, Category, Training
+Type, Delivery Method, Instructor, Assigned/Due Date, whether it's
+**Mandatory**, whether it needs a **Certification** on completion, and
+whether an **Assessment** with a real **Passing Score** is required. KPIs:
+Total, Assigned, Completed, Overdue, Expired — so you can catch someone
+whose mandatory training has lapsed, not just track completions.
+
+## Occupational Health
+
+Open a case — Employee, Case Type, Facility, Priority, Exposure Notes,
+Opened/Scheduled Date, and who it's **Assigned To**. KPIs: Total, Open,
+Pending Review, Restricted (a case that's resulted in work restrictions),
+Closed.
+
+## Related
+
+- [Medical Exams & Medical Records](./health-safety-medical.md)

package/bundle/docs/applications/hcm/helpdesk.md

@@ -0,0 +1,28 @@
+---
+title: HR Helpdesk
+audience: tenant
+---
+
+# HR Helpdesk (HCM)
+
+This page documents the shipped **HR Helpdesk** screen (`hcm-helpdesk`).
+Not for plugin developers.
+
+## What it does
+
+Submit a real support ticket — Category, Subject, Description, Priority —
+and see your own ticket list with real status tracking.
+
+## Known gaps
+
+- **No ticket conversation/messages, internal HR notes, or attachments**
+  yet — a ticket is created and tracked, but there's no back-and-forth
+  thread on it.
+- **No knowledge base/search, SLA tracking, assignment/routing/
+  escalation, rating, or reopen/cancel actions.**
+- **Ticket numbers are a plain auto-incrementing ID**, not a formatted
+  reference like `HR-2026-0001`.
+
+## Related
+
+- [Employee Relations Dashboard & Case Reports](./employee-relations-analytics.md)

package/bundle/docs/applications/hcm/holiday-calendar.md

@@ -0,0 +1,69 @@
+---
+title: Holiday Calendar
+audience: tenant
+---
+
+# Holiday Calendar (HCM)
+
+This page documents the shipped **Holiday Calendar** screen
+(`hcm-foundation`) — where HR sets up one or more holiday calendars (e.g.
+one per country or office location) and the holidays on them. Not for
+plugin developers.
+
+**Who this is for:** HR staff setting up and maintaining company holidays.
+
+## Getting there
+
+Under Core HR / Administration in the HCM menu.
+
+## What you see
+
+- **KPI cards** at the top with real counts for your tenant.
+- A **month calendar grid**, with each holiday shown as a colored event by
+  type.
+- A **Holiday Summary** donut chart.
+- **Upcoming Holidays** and **Calendar List** panels.
+
+On mobile, KPI cards go to 2-across (4-across on tablet/desktop) and the
+calendar/summary and upcoming/list panels stack full-width instead of
+sitting side by side. It's the same underlying data on web, Studio, and the
+mobile app — not a cut-down mobile version.
+
+## Adding holidays
+
+- **Add Holiday** — add one holiday by hand: name, date, type, and which
+  calendar it belongs to.
+- **Create New Calendar** — set up a new calendar (e.g. for a new country
+  or office).
+- **Import Holidays** — upload a real Excel file. It's saved into your
+  tenant's document storage (a "HR Imports" folder, created automatically
+  the first time you use this) and then read on the server to create real
+  holiday entries — this isn't a preview or a template, it actually adds
+  the holidays from your file.
+
+## Exporting
+
+A real **Export** button downloads the calendar as an Excel file you can
+open, print, or share.
+
+## Navigating months
+
+Use the month grid's own built-in Previous/Next/Today controls (there's no
+separate toolbar for this — just the calendar itself).
+
+## Known gaps
+
+- **No Location or Status filter in the toolbar** — only Calendar and Type
+  filters are wired up.
+- **Holidays can't yet be scoped to a specific employee group** — a holiday
+  applies calendar-wide, not to a subset of employees.
+- **"Calendar List" has no separate management screen** — you can see the
+  list of calendars here, but there's no dedicated page yet to edit or
+  organize them beyond what Create New Calendar and Add Holiday already
+  cover.
+- **Imported files always land in a fixed "HR Imports" folder** — you can't
+  choose a different destination.
+
+## Related
+
+- [HR Policies](./hr-policies.md)

package/bundle/docs/applications/hcm/hr-policies.md

@@ -0,0 +1,64 @@
+---
+title: HR Policies
+audience: tenant
+---
+
+# HR Policies (HCM)
+
+This page documents the shipped **HR Policies** screen (`hcm-foundation`) —
+where HR publishes company policies and tracks which employees have
+acknowledged them. Not for plugin developers.
+
+**Who this is for:** HR staff who create and publish policies, and anyone
+whose permissions include policy management (view/create/update/delete/
+publish/archive/manage-category/view-acknowledgement/export).
+
+## Getting there
+
+Under Core HR in the HCM menu.
+
+## What you see
+
+- A row of **KPI numbers** at the top (e.g. total policies, published,
+  pending acknowledgement — the real counts for your tenant).
+- A **filter bar** to narrow the list.
+- The main **grid** of policies, with row actions: **View**, **Submit**,
+  **Publish**, **Archive**.
+
+## Creating and publishing a policy
+
+**Create** opens a form: pick a category, write the policy content, and
+save it as a draft. Use **Submit** to move it toward publication, then
+**Publish** to make it live. Once a version is published, it's locked —
+you can't silently edit it. To change a published policy, you create a new
+version instead, so employees always know exactly what they acknowledged
+and when.
+
+**Archive** retires a policy that's no longer in effect.
+
+**Manage Categories** lets you set up and edit the categories policies are
+organized under (e.g. Code of Conduct, Leave Policy, IT Usage) — configure
+these before creating policies so each one has somewhere to belong.
+
+## Policy detail
+
+Click a policy to open its detail view, with three tabs:
+
+- **Overview** — the policy's own details.
+- **Versions** — every published version of this policy, since publishing
+  never overwrites a previous version.
+- **Acknowledgements** — which employees this policy applies to, and who
+  has (and hasn't) acknowledged it yet.
+
+## Known gaps
+
+- **Publish and Archive don't go through an approval workflow** — they take
+  effect immediately for anyone with the right permission, unlike some
+  other HCM change types that route through a manager/HR approval step
+  first. If your organization expects policy publication to need sign-off
+  from someone else, that's not enforced here yet — it relies on only
+  giving the Publish permission to people who should have final say.
+
+## Related
+
+- [Holiday Calendar](./holiday-calendar.md)

package/bundle/docs/applications/hcm/hr-settings.md

@@ -0,0 +1,98 @@
+---
+title: HR Settings
+audience: tenant
+---
+
+# HR Settings (HCM)
+
+This page documents the shipped **HR Settings** area (`hcm-foundation`) —
+the central place an HR administrator configures how HCM behaves for their
+company. Not for plugin developers; if you're adding a new settings group
+of your own, treat this as a working example to copy, not a guide to read
+first.
+
+**Who this is for:** the **HR Settings Administrator** role. Everyday
+settings you can just save yourself; a few sensitive ones need a second
+person to approve the change before it takes effect (see
+[Approvals for sensitive settings](#approvals-for-sensitive-settings)
+below).
+
+## Getting there
+
+`/app/hcm/administration/hcm-foundation/hr-settings` — the **Overview**
+page, a grid of 12 setting-category cards.
+
+## The Overview page
+
+Nine tabs across the top — **Overview**, **Policies**, **Workflows**,
+**Notifications**, **Integrations**, **Security**, **Compliance**,
+**Custom Fields**, **System** — switch between them instantly, no page
+reload. Overview shows all 12 category cards together; each other tab
+zooms into one category at a time.
+
+Not every category is fully built yet. Click **Manage** on a card and
+you'll land on that category's real settings screen; click a card that
+still says **Coming soon** and there's nothing there yet:
+
+| Works today (Manage) | Not yet (Coming soon) |
+|---|---|
+| Organization | HR Policies |
+| Compensation | Workflows |
+| Attendance | Notifications |
+| Employee | Integrations |
+| Compliance | Security |
+| System | Custom Fields |
+
+## Managing a settings group
+
+Clicking **Manage** on any working category opens a real settings screen
+for that group — every actual setting HCM ships for that category, each
+with its current value and a way to change it.
+
+Settings come in three tiers, and the tier changes what happens when you
+save:
+
+- **Safe settings** (tier 1) — save immediately, no approval needed.
+- **Sensitive settings** (tier 2/3) — saving doesn't apply the change right
+  away. Instead it's held as a **pending value** until someone with the
+  right authority approves it. Only once approved does the new value
+  actually take effect.
+
+This means you might change a sensitive setting and not see it "stick"
+immediately — that's expected, not a bug. Check for a pending approval if a
+setting you changed doesn't seem to have updated.
+
+## Country Configuration
+
+A separate screen for turning on **Country Packs** — bundles of
+country-specific settings (statutory requirements, tax rules, social
+security, leave rules, payroll rules, working-time rules, holidays,
+compliance requirements, and employee ID formats) for a specific country.
+
+- **Activate** a country once its pack is installed, and its settings
+  become available through the same settings screens as everything else.
+- **Retire** a country to turn it back off.
+
+At the time of writing, only **India** has a Country Pack installed and
+available to activate here — this isn't a general "pick any country in the
+world" list, only whatever packs your tenant actually has installed show
+up.
+
+## Approvals for sensitive settings
+
+If you're the one approving a pending settings change (rather than the one
+who proposed it), you'll see it come through the normal HCM approvals
+inbox, the same place any other approval request in HCM shows up.
+
+## Known gaps
+
+- **Six of the 12 categories aren't built yet**: HR Policies, Workflows,
+  Notifications, Integrations, Security, and Custom Fields all still say
+  "Coming soon" — there's no settings screen behind them yet.
+- **Country Configuration only lists India** today, not a general list of
+  every country in the world — more countries appear here as their packs
+  get installed.
+
+## Related
+
+- [Add your own app-owned roles & permissions](../../guides/add-app-owned-roles-and-permissions.md)