> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hr-easy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Contracts

> Templates, placeholder variables, generation, and electronic signature.

Contracts are generated from **DOCX templates** you upload, filled with data the
platform already holds, and sent for signature. Nobody retypes a salary into Word.

## Templates

A contract template is a `.docx` (or normalised `.dotx`) file containing
`{{placeholder}}` markers. Templates are **versioned**: editing one creates a new
version, and contracts already issued stay pinned to the version they were generated
from.

Templates can be scoped to a legal entity, so a multi-entity installation issues each
Rechtsträger's own paper.

| Capability                  | Role        |
| --------------------------- | ----------- |
| `contract-templates:view`   | `HR_STAFF`+ |
| `contract-templates:create` | `ADMIN`+    |
| `contract-templates:edit`   | `ADMIN`+    |
| `contract-templates:delete` | `ADMIN`+    |

## The placeholder taxonomy

Every placeholder falls into exactly one of four classes, decided by **who supplies the
value**. This is the part that makes contract generation predictable.

<AccordionGroup>
  <Accordion title="employmentTerms — from the structured terms section">
    `start_date`, `end_date`, `salary`, `salary_monthly`, `employment_level`,
    `hours_per_week`, `vacation_days`, `location` — with their German idioms
    (`eintrittsdatum`, `monatslohn`, `pensum`, `ferientage`, `arbeitsort`, …).

    These are captured **once** in the structured Anstellungsbedingungen section. The
    manual input is hidden on the contract form, and a template `defaultValue` for them
    is ignored. There is exactly one place a Pensum is entered.
  </Accordion>

  <Accordion title="profile — prefilled from the person and the position">
    Name, contact, birth date, nationality, marital status, number of children, the
    full address broken into street / house number / PLZ / city / canton, and the
    position data.

    The input is rendered and **seeded** from the Personalstammblatt, the employee
    master data, or the application — and HR can still edit it.
  </Accordion>

  <Accordion title="system — injected by the platform">
    `contract_number` is generated; `contract_date` is seeded and guaranteed at
    generation time. HR never types these.
  </Accordion>

  <Accordion title="author — genuinely template-supplied">
    Anything else, including your own custom names. The input renders empty and HR fills
    it per contract, unless the template carries a `defaultValue` — this is the only
    class where a default actually matters.
  </Accordion>
</AccordionGroup>

Precedence when a name could match more than one class is
`employmentTerms` > `system` > `profile` > `author`. Matching is case-insensitive,
because the DOCX extractor lowercases names. An unrecognised placeholder is `author` by
definition, so a typo in a template surfaces as an empty field to fill rather than a
silently wrong value.

<Card title="Full taxonomy" icon="table-list" href="/development/project-structure">
  The canonical machine-readable sets live in `src/lib/contracts/variable-classification.ts`, kept
  in lockstep with the prefill mappers by tests.
</Card>

## Generating a contract

<Steps>
  <Step title="Pick template and language">
    The contract locale follows the employee, so a French-speaking hire gets the French template.
  </Step>

  <Step title="Structured terms">
    Fill the Anstellungsbedingungen section: start date, Pensum, salary, hours, vacation
    entitlement, work location, notice period.
  </Step>

  <Step title="Remaining fields">
    Profile placeholders arrive prefilled; author placeholders are yours to complete.
  </Step>

  <Step title="Preview">
    The DOCX is rendered and converted to PDF for review before anything is sent. The conversion
    runs through a LibreOffice sidecar service.
  </Step>

  <Step title="Send for signature">See below.</Step>
</Steps>

## Signature

Three signing paths are supported behind one interface:

| Path          | Use                                                                  |
| ------------- | -------------------------------------------------------------------- |
| **DocuSign**  | Server-to-server via JWT grant. Webhook callbacks are HMAC-verified. |
| **SwissSign** | Swiss qualified electronic signature, for contracts that need it.    |
| **Manual**    | Print, sign, scan, upload. The state machine is the same.            |

Whichever path is used, signature completion emits an event. The pre-boarding
orchestrator listens for it, and the contract-to-employment bridge opens the
employment period from the agreed start date — the terms captured on the contract
become the terms on the record, without a second data entry.

## Contract access

Employees see their own contracts in the [portal](/guides/portal). Access is
token-scoped and checked per request; a contract PDF is never served from a
guessable URL.

## Numbering

Contract numbers are generated by the platform in a configurable format, unique per
installation, and are stable once issued.