How a task is given to an outside firm (3.3.0): a supplier from Contracts, and optionally one person there, held on the task beside the analyst who owns it. The feature crosses four modules - Tasks (where it is stored and chosen), Projects (where it is planned, counted and chased), People (where a supplier's page lists its tasks) and Contracts (where suppliers and contacts live) - so it has a page of its own.

The user guide is Projects - Contractors.

Pages in this series: 1 Architecture · 2 Schema · 3 Services and API · 4 Plan, Timeline and dependencies · 5 Health and charts · 6 Governance · 7 Alerts, reports and AI · 8 Connections, templates, people · 9 Demo data, testing and traps · 10 Contractors

A contractor is who does the work, not who owns it. tasks.assigned_analyst_id stays the person here who owns the task and chases the firm; tasks.assigned_supplier_id (and assigned_contact_id) say which firm, and which person there, is doing it. So a contractor task normally has both. Everything else follows from that split: Capacity counts the hours against the firm, never against the analyst; the overdue digest and the AI say "contractor X" next to the owner; the email (when switched on) tells the contact who to reply to - the analyst. Suppliers and contacts are install-wide (Contracts has no companies), so a task in any company may name any supplier.

-- tasks (3.3.0)
`assigned_supplier_id` INT NULL,   -- the supplier doing the work
`assigned_contact_id`  INT NULL,   -- the person there (a contacts row of that supplier)
KEY `ix_tasks_supplier` (`assigned_supplier_id`),
CONSTRAINT `fk_tasks_supplier` FOREIGN KEY (`assigned_supplier_id`) REFERENCES `suppliers` (`id`) ON DELETE SET NULL,
CONSTRAINT `fk_tasks_contact`  FOREIGN KEY (`assigned_contact_id`)  REFERENCES `contacts` (`id`)  ON DELETE SET NULL,

-- project_members (3.3.0): a firm, or one person there, on a project team
`supplier_id` INT NULL,
`contact_id`  INT NULL,
CONSTRAINT `fk_pmem_supplier` FOREIGN KEY (`supplier_id`) REFERENCES `suppliers` (`id`) ON DELETE CASCADE,
CONSTRAINT `fk_pmem_contact`  FOREIGN KEY (`contact_id`)  REFERENCES `contacts` (`id`)  ON DELETE CASCADE,

• Deleting a supplier or contact takes it off its tasks (SET NULL - the task stays) and takes the member row off the team (CASCADE - a member with nobody behind it means nothing).
• The task FKs are added by an inline block in api/system/db_verify.php (next to the recurrence ones); the member FKs are in the $projectFks list. Both column pairs are in includes/db_verify_schema.php.
• tasks is created before suppliers in database/freeitsm.sql; that works because the file runs with FOREIGN_KEY_CHECKS = 0.
• A member row has exactly one of analyst_id, team_id, user_id, supplier_id; contact_id only ever goes with supplier_id. members() reports its kind as contractor.

The guard. Code must work on an install that has the new code but has not run Database Verification:

function tasksContractorReady(PDO $conn): bool
{
    static $ready = null;
    if ($ready === null) {
        try { $conn->query("SELECT assigned_supplier_id, assigned_contact_id FROM tasks LIMIT 0"); $ready = true; }
        catch (Throwable $e) { $ready = false; }
    }
    return $ready;
}

Every reader checks it (or, for the member columns, contractorMemberSql() does its own probe and returns NULL AS ... columns).

Create and update both go through the same validation, and both check the Contracts rule only when a contractor is set or changed, so a client that sends back an unchanged task body is never refused:

// updateTask() - a supplier change drops a contact who works for the old one
$sIn = array_key_exists('assigned_supplier_id', $in) ? $in['assigned_supplier_id'] : $curS;
$cIn = array_key_exists('assigned_contact_id', $in) ? $in['assigned_contact_id']
      : (($sIn === '' || $sIn === null || (int)$sIn !== $curS) ? null : $curC);
[$newS, $newC] = tasksContractorValidate($conn, $sIn, $cIn);
if ($newS !== $curS || $newC !== $curC) {
    self::contractorAllowed($conn, $ctx);          // 403 without Contracts
    $updates[] = 'assigned_supplier_id = ?'; $args[] = $newS;
    $updates[] = 'assigned_contact_id = ?';  $args[] = $newC;
    $emailContractor = $newC !== null && $newC !== $curC;
}

private static function contractorAllowed(PDO $conn, ActorContext $ctx): void
{
    if ($ctx->actorId > 0 && !analystCanAccessModule($conn, $ctx->actorId, 'contracts')) {
        throw new ServiceError('forbidden', 'forbidden', 'Choosing a contractor needs access to Contracts.');
    }
}

The rule lives in the service, not the endpoint, because three callers reach it: the Tasks board (api/tasks/save.php), the REST API (api/v1/resources/tasks.php) and Ask AI (projectChatApplyOne()). The system (actorId 0) may always.

createTask() validates before anything is written and sets the pair with an UPDATE after the insert, next to the estimate. ProjectsService::createTaskInProject() strips the pair from the create, sets the project, then saves the pair as an update - so the assignment email can name the project.

Seeing a contractor needs nothing beyond seeing the task, like a team or project name. Choosing one needs Contracts. api/tasks/contractors.php returns {allowed: false} without it, and the task window then shows the firm as read-only text.

• contractorChoices is loaded once per page by loadContractorChoices() (alongside loadProjectChoices() in openDetailPanel()): null = not loaded, false = may not choose, otherwise the list.
• contractorFieldHtml(task) draws Contractor and Contact there under the assignee row; contacts without an email say no email. Changing the supplier calls setTaskContractor(id, supplierId, null), which clears the contact.
• The card chip (.task-card-contractor) shows the firm and, after a dot, the person.
• The filter mirrors the Project filter: currentContractorFilter ('', any, none or a supplier id), taskMatchesContractor() in the three places that filter the board and list, refreshContractorFilter() after each load - the section is hidden until a loaded task has a contractor.

Plan and Timeline. projectRead() passes its tasks through tasksWithContractors(); a Plan row adds <span class="prj-task-ctr"> before the due date (the avatar stays the owner); the Timeline adds the firm to the bar's tooltip.

Members. addMember() hands any body with supplier_id or contact_id to addContractorMember(), which checks readiness, the Contracts rule, validates the pair (wrapping the error as a ServiceError), refuses a duplicate (supplier_id = ? AND contact_id <=> ?) and inserts. A contractor member's name is the contact's name, or the supplier's when it is the firm as a whole; supplier_name and the contact's job_title come with it. RACI letters and the stakeholder map key on the member id, so they work unchanged. The Add someone dialog shows the Contractor kind only when api/tasks/contractors.php says allowed.

Capacity. projectCapacity() selects t.assigned_supplier_id and the supplier name (when ready), includes tasks that have only a supplier, and takes them out before the analyst branch:

if ($t['assigned_supplier_id'] !== null) {
    $sid = (int)$t['assigned_supplier_id'];
    $c = &$out['contractors'][$sid];
    $c ??= ['supplier_id' => $sid, 'name' => (string)$t['supplier_name'], 'tasks' => 0, 'hours' => 0.0, 'late' => 0, 'no_estimate' => 0];
    $c['tasks']++;
    if ($remaining !== null) $c['hours'] += $remaining; else $c['no_estimate']++;
    if ($t['due_date'] !== null && $t['due_date'] < $today) $c['late']++;
    unset($c);
    continue;                     // never in an analyst's load
}

$out['contractors'] is a list sorted by name; the page draws it as a table under the people.

Digest, facts and Ask AI. The overdue digest payload gains tasks[].contractor_name. projectAiFacts() appends contractor <name> to each task line and names a contractor stakeholder by its supplier. Ask AI (part 7):

The run closure validates the pair and looks up the names (_supplier, _label) when the proposal is made; projectChatApplyOne() checks Contracts again when it is applied, because with shared memory the person applying may not be the one who asked. The apply rank puts task_contractor with task_dates, after new tasks.

project_contractor_email (off / on) is a Projects setting because the reminders run on the Projects scan, but it covers every task with a contractor, in a project or not.

The body is built in tasksContractorEmail(): a greeting by first name, the task, the project, the firm, start and due dates, the description as plain text, and "Your contact at is (). Please reply to them, not to this email." It is sent with ssSendSystemEmail(..., 'task_contractor'), so a failure (no mailbox, a bad token) is a send-log row, not an error.

Each reminder is claimed in the ledger before it is sent, so it goes once per due date:

$claim = $conn->prepare("INSERT IGNORE INTO workflow_scheduled_emissions (trigger_event, entity_key, fingerprint, emitted_datetime)
                         VALUES ('task.contractor_reminder', ?, ?, UTC_TIMESTAMP())");
$claim->execute(['task_contractor:' . $taskId . ':' . $kind, $dueDate]);   // moving the date re-arms both

projectAlertsScan() calls tasksContractorReminders() on the full scan only ($projectId === null) - the reminders are install-wide, and the per-project scan after a save would otherwise run them for everybody.

supplierDetail() and supplierContactDetail() add sections['tasks'] from peopleContractorTasks($conn, $analystId, ['supplier' => id]) or ['contact' => id] - when the reader can open Tasks. Rows are scoped to the reader's companies (t.tenant_id) and leave out tasks in a members-only project the reader cannot see; open first, then by due date. pplSectionContractorTasks() draws the card (Task, Status, Due, Project, Person there, Chased by), and pplStats() adds an open of total tile.

Every task in REST API: Tasks carries:

"contractor": { "id": 3, "name": "Nexus IT" },
"contractor_contact": { "id": 5, "name": "Mark Evans" }

(both null when there is none). Create and update accept assigned_supplier_id and assigned_contact_id with the rules in section 4; the catalogue (api/v1/spec.json) lists the 422 and 403 cases, and api/v1/lib/openapi_schemas.php has both properties on the Task schema. That file was edited by hand: openapi_fix.php rewrites it without its comments (see the TRAP in part 9).

scripts/gen_projects_demo.php gives the Bradford move's cabling, Wi-Fi and internet line to Nexus IT (Mark Evans on two of them), the switch order to TechDirect (Rachel Green), and puts Nexus on the team with Mark as the contact. The suppliers and contacts are Contracts' demo rows, matched by name and email (_skip_insert).

Contracts' demo data may not be imported, and a demo task must not vanish because of that, so the importer gained a per-field opt-out:

{ "_ref": "po_cabling", "title": "Cabling installed and tested on every floor",
  "assigned_supplier_id": "@suppliers.sup_nexus", "assigned_contact_id": "@contacts.con_mark",
  "_optional_fields": ["assigned_supplier_id", "assigned_contact_id"] }

// api/system/import_demo_data.php
foreach ((array)($record['_optional_fields'] ?? []) as $f) {
    $v = $record[$f] ?? null;
    if (is_string($v) && strpos($v, '@') === 0 && !isset($idMap[substr($v, 1)])) unset($record[$f]);
}
unset($record['_optional_fields']);

_optional (the whole record goes) is still right for the member row: a contractor member with no supplier is nothing.

• Never send a real email. Test the email path on a scratch database with no mailbox: with the setting on, ssSendSystemEmail() logs a failed row with route task_contractor, which proves the gate, the route and the ledger without anything leaving the machine. Remember projectSettings() caches per request - pass true to refresh it after writing the setting in a test.
• Test the Contracts rule as an analyst without Contracts (the scratch demo's analysts 2 and 3).
• The checks that ran for 3.3.0: validation (wrong supplier's contact, contact alone, supplier change clears the contact, clearing), the rule (create and update refused, unchanged body allowed), the REST serializer, members (name, duplicate), Ask AI apply and take-back, the FK SET NULL when a supplier is deleted, Capacity (only open tasks, out of the load), the People sections, the facts and list_* tools, and the demo import with and without Contracts' demo data.

Contractors cannot sign in or update their own tasks (there is no supplier portal); the REST API cannot filter tasks by contractor; Capacity has no hours-per-week for a firm, so it lists their work rather than a load; the Tasks table and timeline views do not have a contractor column or filter; the email is English only (the contact has no language), and its wording is fixed; a contractor member cannot be the owner of a RAID entry or a benefit; templates do not carry contractors.