Building a module out of other modules. Starters & leavers (4.6.0) is deliberately small: it owns four tables and one service class, and everything else - the work, the kit, the account, the documents, the automation, the person's page - belongs to a module that already existed. This page is the worked example: what it reuses, how, the rules that make it safe, and the list of every place a new module has to be registered.

User guide: Starters & leavers.

It owns only what nothing else holds - who, which kind, which date, which template:

Everything else is borrowed:

The result: no task table, no custody table, no notification code, no file storage, no email sending. Each of those already has its rules - company scope, permissions, history, events - and they all still apply, because the module goes through the front door every time.

final class StartersService, plus two enums (JmlKind, JmlStatus). Pages and endpoints are thin: they authorise and call it.

1. Validate the kind and date; resolve the person (analystCanAccessUser first - out of reach reads as "not found").
2. Insert the jml_cases row first.
3. TasksService::saveTask for the parent task (due on the date), then store its id as parent_task_id.
4. For each template step: saveTask a subtask (parent_task_id, team, analyst, due = date + offset), then attachTemplateToTask if it has a checklist.
5. WorkflowEngine::dispatch('jml.case_created', ...).

🔑 No outer transaction, on purpose. saveTask and the checklist service fire their own workflow events as they go. Wrapping them in a transaction would let a workflow act on a task that is then rolled back. Writing the case row first means a failure part-way leaves a case that says what it has - never tasks that belong to nothing. A step that fails is written to the case's history and returned in $warnings; the rest still go in, and the case id is still returned so nobody opens it twice.

A step can be raised as a ticket instead of a subtask; tickets with the same name are one ticket, linked in jml_case_tickets. Its own page: Steps as tickets - Developer Guide.

getCase() lists the parent task's subtasks with their status; listCases() and casesForPerson() count them in the same query:

(SELECT COUNT(*) FROM tasks s WHERE s.parent_task_id = c.parent_task_id) AS steps_total,
(SELECT COUNT(*) FROM tasks s JOIN task_statuses ss ON ss.id = s.status_id
  WHERE s.parent_task_id = c.parent_task_id AND ss.is_closed = 1) AS steps_done

A step closed on the Tasks board is ticked on the case with no code in between - there is no second copy to fall out of step. A subtask added by hand in Tasks counts too.

A template may name a form (jml_templates.form_id), a rule that picks it (match_rule) and an "only if" per step (jml_template_steps.condition_rule). Rules are JSON {match: all|any, rules: [{question, op, value}]}, tested by StartersService::ruleMet(), which hands each comparison to the Forms module's own formLogicTestRule() (plus any_of, which is equals for each comma-separated value).

🔑 Rules are kept by question LABEL, not field id. Every form version is a new forms row with new form_fields ids, so a rule written against an id would silently stop matching the day someone edits the form. rawAnswers() keys the stored answers by lower-cased label; formRoot() walks parent_form_id so "the same form" means any version of it.

applyTemplate() is the one place steps are made, from three callers:

If the template has a form and the case has no answers yet, applyTemplate() puts the form on the parent task (TaskForms::add, required, blocking), sets steps_pending = 1 and stops. Otherwise each step is skipped unless ruleMet(), has {Question} filled by fillAnswers() - including transforms such as {First name|initial|upper} (5.2.0, Text transforms - Developer Guide) - and the parent task's description gains the answers table.

openFromSubmission() is the workflow action's body: it reads name / email / date / job title from the answers by question type and wording (or the action's own args), matches a mover or leaver to Users by email, takes the company from the requester (a company-guarded workflow may act only for its own), and picks the template with chooseTemplate(). It runs as nobody (actor 0): TasksService::saveTask credits such tasks to the first active administrator, as the workflow Create a task action always has (tasks.created_by_id is NOT NULL).

The parent task's title and description and the custody note on issued kit are saved text that everybody reads, so they are written once in the case's language - writeLocale(): the owner's saved interface_language, else the acting analyst's, else English - through I18n::tFor() and the starters.written.* strings. A workflow or portal opening has no language of its own. The date uses IntlDateFormatter where intl is installed and an ISO date where it is not.

setStatus() changes the case only. A step still open is someone's job; closing it silently would hide that. The UI says how many are open before Done.

issueKit() / recoverKit() check analystCanAccessAsset (the custody methods do not check scope themselves) and then call Assets. markLeft() refuses a directory-managed person (users.is_managed) - the next sync would undo it - and otherwise runs UPDATE users SET + userActiveSets(false).

Every endpoint starts with includes/starters/api_bootstrap.php (signed in, requireModuleAccessJson('starters'), JSON, $conn/$ctx/$analystId, schema ready), then one call into the service inside startersApiRun(), which turns a ServiceError into {success:false, error}. Writes call startersApiRequirePost(). The bootstrap is listed in tests/module-access-coverage.php's guard pattern.

The checklist for the next module. Each is one line or one entry.

Two tests catch a missed one: tests/analyst-lifecycle.php fails for an analyst column not in the map, and tests/module-access-coverage.php fails for an endpoint without the module guard.

Plain JS, no build. assets/js/starters.js is shared (Jml.api, the renderers, a type-ahead searchBox, the New case dialog JmlNew); starters-list.js, starters-view.js and starters-settings.js are one per page. The dialogs are the shared .modal from inbox.css; the confirmations are showConfirm(); the documents panel is FreeITSMDocuments.mount(el, {parentType: 'jml_case', ...}). CSRF is added to every request by csrf.js, which the waffle menu injects.

The demo (database/demo-data/starters.json) follows the same rule as the module: it owns only its own tables. A demo import clears every is_demo row of each table it writes, so two demo modules must never write the same table - Starters writing tasks would delete the Tasks demo on every re-import, and the other way round. So:

Another file's refs are not visible to an import, so demoAfterStarters() in includes/demo_data.php joins them up afterwards: each case finds its parent task by ": <name>" in the title (any language - a re-import finds it already rewritten), its answers by the submission whose Full name is the person, and the starter templates are pointed at the demo form by id (an older install's untagged "New Starter Request" would win a case-insensitive title match). Then StartersService::refreshTaskText() writes the title and description opening the case would have written, with the date of the import.

The steps in the demo were produced by evaluating each template's "only if" rules against that case's answers, so a demo case never has a step its answers would not have made.

tests/starters.php (45 checks) - writes, so it needs both FREEITSM_TEST_DATABASE and FREEITSM_BASE_URL pointing at a throwaway install, and removes everything it makes. It checks that steps become subtasks due on the right days, that progress follows a step closed in Tasks, that kit goes through Assets custody and a Retired status retires it, that Left switches the person off (and is refused for a directory-managed one), that the People page lists the cases, that a form's answers choose the template, skip the steps whose "only if" fails and fill {Question}, that a template with questions waits for answers given on the task, and that a GET cannot change a case.

• The REST API (/api/v1) - cases are not exposed there yet.
• A Watchtower card and Report Pack blocks.
• The other locales - German and Spanish arrived with 4.6.0; the rest follow through the i18n pipeline.