HR Setup and Configuration Guide

This guide explains the HR setup workspaces, their dependencies, and how setup records feed daily HR operations. Setup records are service-scoped operating configuration; activating a capability does not automatically create them. First read HR Capabilities: Packages, Access, and Administration for the service-package and permission model.

Before configuring HR

Confirm the service context

Confirm the company and active company-service instance before creating configuration. A tenant may have Community Finance & HR and a separate HR & Payroll service; their capability selections and setup data are not interchangeable. Service scope is not the same as selecting a branch or department business unit.

Confirm capability and permissions

The relevant HR capability must be active for the service, and the user must have permission to configure the data. Capability activation does not grant permissions. If a page or tab is missing, check the active service, capability, and user's permission tree before assuming a record or route is absent. See the capability guide for known route/tab mapping exceptions.

Distinguish seed data from tenant setup

Seeds provide stable platform reference records and eligible package defaults. Tenant administrators create configuration for their own organization: jobs, positions, leave types, rosters, salary structures, benefit plans, and policies. Several optional HR seed packs currently have no package-specific seed files; users must configure those operating records in HR Setup.

Do not invent internal IDs or business codes to satisfy a form. System-issued identifiers should come from the relevant ID-template/entity mapping; users should select entities by readable code and name. If a form asks the user to supply a generated code or exposes only a numeric internal ID, verify the entity mapping and treat it as a form defect rather than entering a guess.

Four data layers that must not be confused

Layer	What belongs there	Example	Who normally owns it
Platform reference/seed data	Stable entity definitions, default capability catalogue, permission metadata, ID templates/mappings, standard rule headers/details and tag bindings where defined.	HR_EMPLOYEE entity metadata; a payroll posting-rule header and debit/credit lines.	Product/platform release and seed maintainers.
Service capability configuration	Which optional HR packages are available/active for one company-service and its selected seed-pack boundary.	Enable Leave and Absence for the HR service instance.	Authorized service administrator.
Tenant HR setup	Organization-specific approved grades, jobs, positions, leave rules, shifts, salary structures, benefit plans, travel policies and approval settings.	A tenant's accountant position or leave accrual policy.	Tenant HR/finance administrators.
Operational business records	Employee assignments, requests, approvals, claims, payroll runs, payments, cases and their histories.	One employee's approved leave request.	HR managers, approvers, employees and finance in their roles.

Changing one layer does not substitute for another. An active capability does not create a tenant's approved leave types. A seeded GL rule header does not prove its account tags resolve in this tenant. A configured position does not create an employee assignment, and a completed HR record does not prove that a payment or filing was accepted.

Recommended configuration order

1. Confirm company-service context, active HR capabilities, user access, and approval authority.
2. Configure workforce structure: grades, jobs, positions, and required position exceptions or requisitions.
3. Configure time and absence rules: leave types, shifts, and attendance rules.
4. If enabled, configure pay structures, payroll readiness, and payroll input policy.
5. Configure the optional programmes the tenant will use: onboarding, performance, training, benefits, travel/per-diem, and separation clearance.
6. Create employees and assign approved positions and employment terms; link application access separately when needed.
7. Create operational assignments/enrolments after their prerequisites are approved and effective.
8. Test one complete workflow, including approval and downstream outcome, before loading records in bulk.

Workforce Setup

Tab	Purpose	Used by
Job Grades	Maintain the grade framework used by jobs and positions.	Job definitions, position control, compensation lookup, and employee assignments.
Jobs	Define a type of work and its grade/role attributes.	Positions, recruitment, employee assignment, and reporting.
Positions	Define approved organizational seats and their job/reporting context.	Employee assignment, manager hierarchy, headcount control, and requisitions.
Position Exceptions	Record controlled exceptions to normal position availability or occupancy.	Authorized employee changes and workforce operations.
Position Requisitions	Request staffing capacity against the workforce structure.	Workforce planning and recruitment when those capabilities are enabled.
Clearance Items	Define property, access, or responsibilities to clear at exit.	The employee's separation clearance workflow.

Configure grades before jobs that depend on them, then create approved positions before assigning employees. A job is the type of work; a position is an approved seat. Creating a job does not itself make a position available. Use a requisition for a staffing request rather than creating a duplicate position to represent an unapproved hire.

Review reporting relationships and effective dates before using positions in employee records; those relationships affect manager views and team-work scope. Keep exceptions as explicit, justified records rather than changing an approved position to accommodate one case. Clearance-item setup defines what must be returned, revoked, handed over, or reconciled; it does not itself record that a specific employee has cleared it.

Workforce master-data dependency chain

Job grade -> Job -> Approved position -> Position allocation/headcount
                                      -> Requisition (when new capacity is needed)
Approved position + employee -> Current employment assignment -> Manager scope

Validate the full chain before using a position in recruitment or employee creation. Check active state, approval state, grade/job compatibility, root service scope, reporting hierarchy, position allocation and headcount. A requisition follows its own approval path; it does not create a position until the position workflow creates and approves one. The current frontend maps requisitions under Workforce Core rather than an isolated Workforce Planning gate; see Implementation Coverage.

Time and Attendance Setup

Tab	Purpose	Used by
Leave Types	Configure leave categories and applicable request/eligibility handling.	Leave requests, balances, accruals, approvals, and possibly payroll inputs.
Shifts	Configure named shift patterns and working-time boundaries.	Rosters, planned coverage, availability, and attendance comparison.
Attendance Rules	Configure rules for attendance capture, review, corrections, and exceptions.	Attendance records, approvals, overtime, coverage, and possibly payroll.

Configure the rule/type before transactions that refer to it. Keep planned shift, actual attendance, leave entitlement, and absence reason distinct: they describe different facts and reconcile through explicit workflows. Where a shift crosses midnight, confirm local service time and date handling; user screens should not expose unnecessary backend precision such as 07:30:00.000000.

Payroll and Compensation Setup

Payroll Setup

Payroll Setup is the accounting and payment-readiness area for HR payroll. Review required payroll posting rules/accounts and available payment methods before processing a period. Cash and bank are distinct methods and must resolve to their distinct configured accounts; do not reuse one account mapping for both.

Readiness is not enrollment, calculation, posting, payment settlement, or filing acceptance. Those are operational steps in Payroll Processing. A configured payroll account also does not prove that the account is valid for a particular payment batch or that the resulting transaction was posted.

Payroll Input Policy

The input policy determines which approved source records may enter future payroll snapshots. Sources include attendance, paid/unpaid leave, overtime, absence deductions, benefits, salary revisions, suspensions, loans/advances, arrears, one-off adjustments, and recovery deductions. It is not a way to repair inaccurate source records or import arbitrary amounts.

For each source, decide whether it is enabled and required, and which calculation settings apply. A required source means a run must not silently proceed without the expected approved input; an enabled but optional source may contribute when qualifying records exist. Review the effective policy and snapshot version before generating a run so the run retains which policy governed its inputs.

Loan repayments and arrears remain owned by their source-of-truth workflows. Payroll may consume an eligible approved recovery amount; it must not rewrite a loan schedule or invent previous-period arrears. See Payroll for run generation, reconciliation, GL posting, settlement, and statutory remittance.

Salary Structures

Salary structures define the compensation basis available to employees and payroll. Confirm currency, frequency, effective interval, and any approved ranges/components before assigning a structure. Where configured, make sure the employee's position/job/grade is eligible for that structure.

The shared structure is not an individual employee's salary history. Enter employee compensation changes through the dated lifecycle/revision workflow with its approval history; do not edit a shared structure to rewrite past terms for every employee.

Talent and Benefits Setup

Tab	What it configures	Downstream use
Onboarding Checklists	Reusable task/evidence templates for joining or changing role.	Assigned onboarding tasks, owners, completion, and probation handoff.
Performance Cycles	Review periods and the performance process.	Goal setting, reviews, feedback, calibration, and outcome history.
Training Programmes	Learning offerings and configuration for enrolment/completion.	Employee development, completion evidence, and skills reporting.
Benefit Plans	Benefit products and plan terms that may be offered to employees.	Eligibility, enrolment, provider invoices, contributions, and total rewards.
Eligibility Rules	Conditions used to determine benefit qualification and required evidence.	Enrollment decisions, reassessment, waivers, and audit explanations.

Onboarding templates do not create employee tasks until applied to an individual's onboarding. Configure performance cycles and training programmes before assigning employees to them. Configure benefit plans before eligibility rules and enrollments; confirm effective dates, evidence requirements, waiver policy, contribution treatment, and provider reconciliation.

An eligibility rule expresses decision logic; an enrollment or waiver records the individual's outcome and evidence. Editing a rule should not silently create retroactive enrollments or contribution changes. Reassess affected employees through an auditable life-event or enrollment workflow.

Travel Expense Policies

Configure service-scoped travel and per-diem policy separately from requests and claims. Define who/what qualifies, the allowance basis and limits, applicable dates/locations, and required approvals or evidence. Per diem is an allowance policy and may support qualifying assignments beyond conventional travel; it is not itself a paid claim.

Before the first claim, confirm the approval workflow, expense and employee-payable accounts, cash/bank mappings, and GL posting rules. Claim approval recognizes an expense and payable; later settlement debits that payable and credits the actual payment account. See Travel and Expenses for processing and reconciliation.

Approval, effective-date, and audit principles

• Distinguish draft, submitted, approved, rejected, returned, suspended, and effective states; approval status is not the same as current employment status.
• Use effective-from/effective-to dates to say when configuration applies. Do not overwrite history to make a future change look as though it was always in force.
• Separate maker and checker duties for sensitive configuration and financial changes where policy requires it.
• Preserve the actor, time, reason, and prior/new values for material setup changes.
• Keep tenant setup service-scoped and do not use custom-field values as a substitute for typed HR configuration records.
• Use platform ID templates and entity mappings for generated employee, requisition, rule, and transaction references. Users should select business entities by readable names; generated identifiers are not user inputs.

Generated identifiers and ID-template coverage

The backend calls the platform entity-ID generator for generated references; the form should capture descriptive business fields, not ask users to type the identifier. The current backend seed mapping includes the HR entities below. Patterns are source-seed reference formats as reviewed and are never values to type manually. They do not prove the tenant installed the entity, template and mapping successfully.

Entity	Seeded display pattern	Typical record
HR_EMPLOYEE	EMP-######	Employee number
HR_JOB / HR_JOB_GRADE / HR_POSITION	HRJ-#### / HJG-#### / HPO-####	Job, grade, position
HR_LEAVE_TYPE / HR_SHIFT / HR_ATTENDANCE_RULE	HLT-#### / HSH-#### / HAT-####	Leave type, shift, attendance rule
HR_CLEARANCE_ITEM	HCI-####	Clearance setup item
HR_WORKFORCE_REQUISITION	HWR-####	Workforce capacity request
HR_RECRUITMENT_REQUISITION / HR_RECRUITMENT_CANDIDATE	HRQ-#### / HRC-####	Hiring request, candidate
HR_RECRUITMENT_APPLICATION / HR_RECRUITMENT_OFFER	HRA-#### / HRO-####	Application, offer
HR_PAY_STRUCTURE / HR_PAYROLL_PERIOD / HR_PAYROLL_RUN	HPS-#### / HPP-#### / HPR-####	Pay structure, period, run
HR_PAYROLL_PAYMENT_BATCH / HR_PAYROLL_ADJUSTMENT	HPB-#### / HPA-####	Payment batch, payroll adjustment
HR_SALARY_REVISION / HR_STATUTORY_REMITTANCE	HSR-#### / HRM-####	Employee pay change, remittance
HR_PERFORMANCE_CYCLE	HPF-####	Review cycle
HR_TARGET_CATEGORY / HR_TARGET_CYCLE / HR_TARGET_DEFINITION	HTC-#### / HTY-#### / HTD-####	Goal/target configuration
HR_TRAINING_PROGRAM	HTP-####	Training programme
HR_BENEFIT_ELIGIBILITY_RULE	HBE-####	Benefit eligibility rule
HR_TRAVEL_PER_DIEM_POLICY / HR_TRAVEL_REQUEST / HR_TRAVEL_CLAIM	HDP-#### / HTR-#### / HCLM-####	Allowance policy, trip request, claim
HR_FINAL_SETTLEMENT / HR_SEPARATION	HFS-#### / HSP-####	Final settlement, separation
HR_GRIEVANCE / HR_DISCIPLINARY_ACTION	HGR-#### / HDA-####	Employee relations case

Not every HR entity has a seeded human-readable code. Some child rows use an internal primary key and are displayed through their parent/name/date context. Do not infer that a code is missing merely because an entity uses an internal key; the form should still show readable business metadata rather than requiring the user to enter a database ID.

When adding or auditing a generated code, verify the whole chain:

1. the entity is present in entity.yaml;
2. its pattern is in entity-id-template.yaml;
3. entity-id-template-mapping.yaml connects that template to the entity;
4. the create procedure calls generate_entity_id_json and rejects a missing generated value;
5. the form has no user-entered field for that generated code; and
6. the tenant has the required seed/release data and a readback confirms the generated value.

The repository defines intended source, not tenant installation state. If a form asks the operator to type an identifier that should be generated, or displays only a numeric internal ID for a business lookup, report a source/UI-or-tenant-release mismatch and repair the owning layer; never type a fabricated value to get past it.

Seeded rule and account metadata

For accounting-bound HR operations, a posting-rule header alone is not enough. Verify the header, every required debit/credit detail, rule-to-entity binding, account resolver metadata, service/root-business-unit applicability, and required approved tag bindings. Resolve those tags to actual active approved COAs in the same service. Payroll and travel cash/bank settlement must resolve through distinct CASH_AT_HAND and CASH_BANK paths; one does not imply the other.

Platform-wide GL rules and stable entity, permission, and ID metadata belong in the canonical backend seed files. Tenant-specific COA tags and organizational configuration still need tenant readbacks. Do not put one tenant's operating rows into a release step as ad hoc inserts: release steps are for schema/object compatibility, canonical seed loaders own repeatable reference-data seeding, and tenant administrators own their operating records.

Setup troubleshooting

Symptom	Checks
Page or tab is missing	Active company-service, capability status, route/tab mapping, and the user's view/setup permission.
Lookup is empty	Service scope, approval/current state, effective dates, filters, upstream setup dependency, and readable lookup metadata. Do not substitute an internal ID.
Only some tabs are available	Each tab may require a different capability inside a shared workspace.
A configured item is not selectable	Approval status, effective dates, service scope, job/grade/position relation, and any required Party/role relationship.
Seed sync did not create a policy	Check the capability-to-pack mapping and actual seed files. Most optional HR packs currently declare no reference-data files; tenant-owned setup must be created in HR Setup.
Form requests a code or displays an integer ID	Check form metadata, entity definition, template, mapping, procedure generator call and tenant seed readback. Do not enter a guessed identifier.
GL readiness says account/rule missing	Check header, required details, entity/rule binding, service scope, resolver metadata, approved tag binding and resolved active COA.
Employee is approved but remains Inactive	Employee approval and employment activation are separate. Check the approved current employment and active approved position, then use the lifecycle activation action.
Capability is enabled but a feature has no setup rows	Capability enables product availability; it is not tenant operating configuration. Create and approve the required setup first.
A change appears to affect old records	Check effective dates, version/snapshot behavior, approval history, and whether the action changed configuration or created a new dated transaction.

Related guides

• Capabilities and Access
• HR Overview
• Employees
• Leave and Attendance
• Payroll
• Travel and Expenses
• Benefits and Total Rewards