app.engagements
TableRow level security on
A person or an external organization working one project of an org in one external role (Section 4.4.4, engagement contract, decision D16). Role, classification, pay basis and arrangement identify the canon rate card, which is never repeated. External users read engagements only through api_external projections, never this table (Section 8.7).
Primary key: id
| Column | Type | Nullable | Description |
|---|---|---|---|
| id | uuid | No | Primary key, UUID v7. |
| org_id | uuid | No | Owning org, derived from app.projects on insert; never accepted from the caller and never changed.References app.organizations.id |
| project_id | uuid | No | Project the engagement works.References app.projects.id |
| person_id | uuid | Yes | Engaged person. With a counterparty, the person the vendor or agency supplies.References app.people.id |
| counterparty_id | uuid | Yes | Engaged external organization (the external account), as the org-side counterparty row. Required for vendor-supplied labor (XOS-ENG-4).References app.counterparties.id |
| role_type | app.external_role_type | No | External role type (Section 4.4.2): Client, Vendor, Contractor, Crew, Staff, Artist, Artist Representative or Sponsor. |
| role_code | text | Yes | Canon role (Roles Library, decision D12). NULL exactly for Client and Sponsor engagements, which carry no work terms (1624).References xpms.rate_card.role_code |
| worker_classification | text | Yes | Canon worker classification (decision D16). NULL exactly for Client and Sponsor engagements (1624).References xpms.rate_card.worker_classification |
| pay_basis | text | Yes | Canon pay basis; NULL for an unpaid classification (XOS-ENG-1) and for Client and Sponsor engagements (1624).References xpms.pay_basis.label |
| arrangement | text | Yes | Canon arrangement; NULL exactly when the pay basis is NULL.References xpms.arrangement.label |
| agreed_rate_minor | bigint | Yes | Agreed rate in minor units per pay basis unit, when it differs from the rate card; NULL reads the rate card, and is always NULL for Client and Sponsor engagements (1624). Restricted (data.restricted.read.payroll). |
| currency_code | character(3) | Yes | ISO 4217 currency of the agreed rate.References private.currencies.currency_code |
| employment_status | text | Yes | Employment status; employees only (XOS-ENG-2, XOS-ENG-3).References private.employment_statuses.label |
| flsa_status | text | Yes | FLSA status; employees only (XOS-ENG-2, XOS-ENG-3).References private.flsa_statuses.label |
| labor_agreement_id | uuid | Yes | Labor agreement the employee works under; employees only (XOS-ENG-3).References app.labor_agreements.id |
| start_date | date | No | First day of the engagement. |
| end_date | date | Yes | Last day of the engagement; NULL while open-ended. |
| engagement_state | app.engagement_state | No | Engagement state. Changes only through app.transition_engagement. |
| internal_note | text | Yes | Internal org note. Never visible externally (Section 4.4.1). |
| deleted_at | timestamp with time zone | Yes | Soft delete time. A row with deleted_at set is ignored by every access helper. |
| created_at | timestamp with time zone | No | When the row was inserted. Set by the database. |
| created_by | uuid | Yes | Person who inserted the row, or null for a platform process. Set by the database.References app.people.id |
| updated_at | timestamp with time zone | No | When the row last changed. Set by the database. |
| updated_by | uuid | Yes | Person who last changed the row, or null for a platform process. Set by the database.References app.people.id |
| application_id | uuid | Yes | Accepted application the engagement came from (Section 4.4.4 stage 5), when it came from the marketplace.References app.applications.id |