Job allocation start and end times

How a job allocation’s start and end times are determined, and when they differ from the job’s.

Overview

A job allocation records one resource being assigned to one job. It has its own Start and End fields, and those are what that resource is actually scheduled for: they are what appears in their agenda on the mobile app, and what notifications about their work are based on.

By default, a job allocation’s times mirror its job’s, but they do not have to. A job allocation can instead take its times from the resource requirement it belongs to, or hold times of its own that are unrelated to the job’s.

Time source for a job allocation

Both Jobs and ResourceRequirements have a JobAllocationTimeSource field. Together they decide which record a job allocation’s times follow. For any given job allocation, the first matching rule below applies.

Order Condition Result
1 The job allocation belongs to a resource requirement whose JobAllocationTimeSource is true The resource requirement controls the times
2 Otherwise, the job’s JobAllocationTimeSource is true The job controls the times
3 Otherwise The times are held on the job allocation itself

The platform default for JobAllocationTimeSource is true on jobs and false on resource requirements, so the job controls the times and every job allocation on a job shares that job’s schedule. Some interfaces create work with the job’s field set to false, and existing work keeps the value it was created with.

Effect of rescheduling a job

The effect of changing a job’s start or duration depends on which record controls the times.

Job allocation Controlled by Effect of changing the job’s start or duration
No resource requirement, job is the time source (the default) Job The job allocation moves with the job
Belongs to a resource requirement that is not the time source, job is the time source (the default) Job The job allocation moves with the job
Belongs to a resource requirement that is the time source Resource requirement The requirement’s ScheduledStart is re-derived as the job’s new start plus the requirement’s relative start, and its job allocations follow
Neither the job nor the resource requirement is the time source The job allocation itself Nothing changes; the job allocation keeps its own times

These details matter if you are reconciling scheduling data:

  • A resource requirement that is the time source always holds its own Duration, so changing only the job’s duration does not move its job allocations, although changing the job’s start does.
  • Job allocations with the status Deleted are not updated. Job allocations with every other status, including Pending Dispatch, are updated.
  • Changing JobAllocationTimeSource from false to true does not realign existing job allocations. They align the next time the controlling record’s start or duration changes.
  • A job allocation must start and end within its job. The platform checks this only when the job allocation’s own times are written, and not when the job moves. In the last row of the table, a job allocation can therefore end up outside its job, and the next write to its times then fails.

Duration and end time

When a job allocation’s Start and End are set, its End is its Start plus its Duration. End is derived rather than set independently, and the platform keeps the three values consistent.

While a job or a resource requirement controls a job allocation’s times, those times belong to the controlling record: writing Start or End directly onto the job allocation is rejected. The times change when the controlling record’s times change.