Skip to content

Lifecycles

This page shows the states of the records that drive the product and what moves each one. The states are the values the database accepts for the status column of each table (a CHECK constraint), and the transitions are the ones the code performs. Each section names the service that owns the transitions: no other code changes that status.

The tables are described in Domain model. The same states, as a user sees them on screen, are in Record states.

Table applications, column status. An application is created by the lead intake (apps/api/src/modules/recruit/lead-intake/lead-intake.service.ts). After that, only the move service changes its stage or status (apps/api/src/modules/recruit/funnel/application-move.service.ts).

stateDiagram-v2
  [*] --> active: Lead arrives
  [*] --> not_qualified: Knockout answer
  active --> active: Move stage
  active --> hired: Hire
  hired --> active: Undo hire
  active --> not_qualified: Mark not qualified
  active --> withdrawn: Mark withdrawn
  active --> closed: System closes
  state "Out of the pipeline" as out {
    not_qualified
    withdrawn
    closed
  }
  out --> active: Reopen
Transition Who triggers it Notes
Created as active A lead from the careers form, the lead API, an import, a referral link or a recruiter Placed in an open stage of the pipeline. Emits application.created.
Created as not_qualified The lead intake, when an answer fails a knockout rule Placed in the system stage “Not qualified” with the reason knockout. A job can instead send knockouts to review, and then the application is created active.
active to active A recruiter with recruit.applications.move, or an automation action The stage changes, the status does not. Emits application.stage_changed.
active to not_qualified A recruiter, with a reason Moves to the system stage “Not qualified”. Emits application.rejected.
active to withdrawn A recruiter, with a reason Keeps its stage, for conversion analysis. Emits application.withdrawn.
active to closed The system only Reason merged when two candidates are merged, or hired_elsewhere when the candidate is hired through another application. Keeps its stage. Emits no event.
active to hired The Hire action only (recruit.applications.hire and people.directory.manage) Moves to the Hired stage and creates or links the person. Emits application.hired.
not_qualified, withdrawn or closed to active A recruiter (“Reopen”), or a new lead whose answers now pass the knockout rules Refused when the candidate has another active application for the same job. Emits application.reopened.
hired to active “Undo hire” only, up to 7 days after the hire The person created by the hire is archived. Emits application.reopened.

An arrow that leaves the box “Out of the pipeline” applies to the three states inside it.

The status and the kind of the stage always agree: active only in an open stage, hired only in the Hired stage, not_qualified only in the system stage. withdrawn and closed keep the stage the application was in.

Table driver_applications, column status. This is the complete employment application the candidate fills in and signs on a public link. The transitions are in apps/api/src/modules/recruit/full-application.

stateDiagram-v2
  [*] --> sent: Send full application
  sent --> in_progress: First answer saved
  in_progress --> signed: Candidate signs
  signed --> changes_requested: Request changes
  changes_requested --> signed: Candidate signs again
Transition Who triggers it Notes
Created as sent A recruiter (“Send full application”) or the automation action send_full_application One per application of the pipeline. Emits full_application.sent on the first link.
sent to in_progress The candidate, on the public page On the first step saved, document uploaded or consent accepted.
in_progress to signed The candidate, by signing Happens in the transaction that completes the signing envelope. The application becomes read only. Emits full_application.signed.
signed to changes_requested A recruiter (“Request changes”), with a note The earlier signature is kept and marked as superseded. A new signature is required.
changes_requested to signed The candidate, by signing again A new envelope and a new signed PDF.

“Resend” and “Cancel link” replace or disable the link and do not change the status. The constraint also accepts canceled, but no code path writes it.

Table offers, column status. The transitions are in apps/api/src/modules/recruit/offers. An offer is signed through a signing envelope, and the end of the envelope is what closes the offer.

stateDiagram-v2
  [*] --> sent: Send offer
  sent --> accepted: Candidate signs
  sent --> declined: Candidate declines
  sent --> expired: Limit date passes
  sent --> withdrawn: Withdraw
  accepted --> [*]
  declined --> [*]
  expired --> [*]
  withdrawn --> [*]
Transition Who triggers it Notes
Created as sent A recruiter with recruit.offers.manage (“Send offer”) The row is inserted as draft and becomes sent in the same transaction, once its envelope exists. An application has at most one open offer.
sent to accepted The candidate, by signing the offer The envelope reaches completed. Emits offer.accepted.
sent to declined The candidate, on the signing page The reason typed is copied to the offer. Emits offer.declined.
sent to expired The worker, once a minute The envelope passed its limit date. Emits offer.expired.
sent to withdrawn A recruiter (“Withdraw”) Cancels the envelope. Refused when the candidate has just answered.

The constraint also accepts viewed, but the row never takes it. When the candidate opens the document, offers.viewed_at is written and the screen reads “Viewed” from the signer of the envelope.

Table signing_envelopes, column status. Every signed document uses the signing service (apps/api/src/modules/platform-signing/signing.service.ts): offers, full applications, contracts and policies, road test certificates and the answers of previous employers. The module that owns the document creates the envelope and reacts to its end.

stateDiagram-v2
  [*] --> draft: Module creates it
  draft --> sent: Worker stores the PDF
  state "Open for signature" as open {
    sent --> partially_signed: A signer signs
  }
  open --> completed: Last signer signs
  open --> declined: A signer declines
  open --> expired: Limit date passes
  open --> canceled: Module cancels
  draft --> canceled: Module cancels
Transition Who triggers it Notes
Created as draft The module that owns the document The content is frozen, with its variables replaced, and a job is queued for the PDF.
draft to sent The worker (queue platform-signing, job render-document) The PDF is stored and its SHA-256 hash recorded. Each signer who signs by link and has an email address gets the signing request.
sent to partially_signed A signer Signers sign in the order given. The database refuses a signature out of order, on an expired or closed envelope, or over a different document hash.
sent or partially_signed to completed The last signer The worker then stores the final PDF, with the proof pages (job store-final-pdf). Emits signing.completed.
sent or partially_signed to declined A signer, on the signing page Emits signing.declined.
sent or partially_signed to expired The worker, once a minute Emits signing.expired.
draft, sent or partially_signed to canceled The module that owns the document For example “Withdraw” on an offer, or a document replaced before it was signed.

An arrow that leaves the box “Open for signature” applies to both states inside it. A completed envelope never changes status. When a signed full application is reopened with “Request changes”, the envelope stays completed and gets a superseded entry in its audit trail (signing_events).

Each signer has its own status in signing_signers: pending, viewed when the document is first opened, then signed or declined.

Table driver_files. A driver file has three stored facts, all written by the compliance engine (apps/api/src/modules/compliance/engine) and by nothing else:

  • phase: where the driver is in the relationship with the company.
  • status: compliant, pending or expired, a summary of its items.
  • eligible: whether the driver may be dispatched, with the reasons in ineligible_reasons when not.
stateDiagram-v2
  [*] --> hiring: Opened for an application
  [*] --> active: Opened for a person
  hiring --> active: Hire
  active --> hiring: Undo hire
  active --> terminated: Termination
  terminated --> active: Termination undone
Transition Who triggers it Notes
Created as hiring “Start pre-hire screening”, the candidate signing the full application, or the Hire action when neither happened before The file belongs to the application and gets the required items of its driver type.
Created as active A driver registered directly in People > Directory The file belongs to the person.
hiring to active The Hire action The same row moves from the application to the person. Items, documents and history go with it; nothing is copied.
active to hiring “Undo hire” The file goes back to the application.
active to terminated People, when the status of the person becomes terminated The file is recalculated one last time, becomes read only and gets the end date of its retention.
terminated to active People, when the termination is undone The file is writable again.
stateDiagram-v2
  [*] --> not_eligible: Opened, an item blocks
  [*] --> eligible: Opened, nothing blocks
  not_eligible --> eligible: Nothing blocks any more
  eligible --> not_eligible: Item blocks, hold or termination

The engine recalculates a driver file inside every transaction that changes one of its items, and once a day for dates: a pass of the worker runs every hour and takes the driver files not yet recalculated since the start of the day of their company. After each recalculation, eligible is true only when all three hold:

  1. No required item is blocking. A required item blocks when it is expired; when it is missing or rejected and has no due date or is past it; when a document was sent, was never reviewed and the due date has passed; or when a new document was sent over an approved one whose validity has already passed.
  2. compliance_hold is off. The hold is turned on by a database trigger of the drug and alcohol vault: a pre-employment test that is positive or refused, a full Clearinghouse query that returns “prohibited”, or a record marked “Not cleared”. The engine reads only the flag, never a result. See Sensitive data.
  3. The phase is not terminated.

A change of eligible emits compliance.eligibility_changed, and a change of status emits compliance.status_changed. The stored status is expired when any item is expired, otherwise pending when any item is missing, sent, rejected or expiring, otherwise compliant.

Table compliance_items, column status. The diagram shows the usual path of a document; the table below it is complete.

stateDiagram-v2
  [*] --> missing: Engine creates the item
  missing --> submitted: Document sent
  submitted --> valid: Approve
  submitted --> rejected: Reject
  rejected --> submitted: Document sent again
  valid --> expiring: Validity is near
  expiring --> expired: Validity passed
  expiring --> submitted: New document sent
  expired --> submitted: New document sent
Operation Allowed from Result Who
Submit a document missing, rejected submitted The driver or candidate (public link), or a user
Replace the document submitted, valid, expiring, expired submitted The driver, or a user
Approve missing, submitted, valid, expiring, expired valid A user, or the system when a screening is reviewed or an envelope is completed
Reject, with a reason missing, submitted rejected A user
Waive, with a reason missing, submitted, valid, expiring, expired, rejected waived A user
Reopen submitted, valid, expiring, expired, rejected, waived missing A user
Date passes valid expiring, when the validity is within the company setting (30 days by default) The engine, once a day
Date passes expiring expired, the day after the validity The engine, once a day
Rule stops applying Any not_applicable The engine. The item returns to its earlier status if the rule applies again.

A periodic item of a driver already hired is created as valid, with its first cycle counted from the hire date. Items of the drug and alcohol file are never reviewed by these operations: they are valid while the vault answers that a record that fulfills the rule is on file.

Table safety_history_requests, column status. One request per previous employer, under 49 CFR 391.23. The transitions are in apps/api/src/modules/compliance/safety-history.

stateDiagram-v2
  [*] --> sent: Request safety history
  state "Waiting for the employer" as waiting {
    sent --> reminded: Reminder
    reminded --> reminded: Next reminder
    sent --> no_response: 30 days pass
    reminded --> no_response: 30 days pass
  }
  waiting --> answered: Employer answers
  waiting --> no_record: Employer has no record
  waiting --> canceled: Cancel

The three states in the box are the ones in which the request still waits for the employer. An arrow that leaves the box applies to all three.

Transition Who triggers it Notes
Created as sent A user with compliance.screenings.manage (“Request safety history”) Requires the authorization the candidate signed in the full application. The email to the employer and the first attempt are written in the same transaction.
sent to reminded The worker, every 10 minutes Reminder emails 7, 14 and 21 days after the request, each recorded as an attempt.
sent or reminded to no_response The worker, every 10 minutes The day after the 30-day deadline. With two attempts recorded, the item of the driver file is met as “No response documented”.
sent, reminded or no_response to answered or no_record The previous employer, on the public page The answer is signed through a signing envelope. Drug and alcohol answers go straight to the vault.
sent, reminded or no_response to canceled A user (“Cancel”) The link stops working.

Logging an attempt by hand (“Log attempt”: a call, a fax, a letter) adds a row to safety_history_attempts and does not change the status.