stopParamsObject

The stopParams object defines properties for stop types — fundamental to Spiral’s operation. Stop types can be modified during execution via update, enabling accurate modelling of stop states. Attribute names and types are links; sub-object fields and the Helix extension block are documented below.

{

"key": <string>,

"clone": <stopParamsKey>,

"minTravelTime": <timeInterval>,

"roundTimes": <timeInterval>,

"compulsory": <bool>,

"position": ANY | ONTIMEONLY | FIRST | LAST,

"defaultDuration": <timeInterval>,

"defaultContingency": <timeInterval>,

"deployMode": ALWAYS | NEVER | LATE | AUTO_HEAD | AUTO_ARV,

"earlyDeploy": <timeInterval>,

"reliable": <bool>,

"nonProductive": <bool>,

"exclusive": <bool>,

"areaExempt": <bool>,

"isBreak": <bool>,

"payUnits": <real>,

"failureFactor": <real>,

"useStby": <useCondition>,

"useVoluntary": <useCondition>,

"useExtended": <useCondition>,

"useSurge": <useCondition>,

"useCloserMargin": <distance>,

"useEarlierMargin": <timeInterval>,

"useLateMargin": <timeInterval>,

"useStbyTravelFactor": <real>,

"quality": ANY | RELIABLE | IDLE | DARK_RELIABLE | DARK_IDLE,

"positionQuality": ANY | RELIABLE | IDLE,

"reassignQuality": ANY | RELIABLE | IDLE,

"arrivalIs": STOP | LOCATION,

"commitMode": SPIRAL | HOST,

"commitWithinTime": <timeInterval>,

"uncommitWithinTime": <timeInterval>,

"headDelay": <timeInterval>,

"clockResolution": <timeInterval>,

"sensitivity": <timeInterval>,

"canBreak": <bool>,

"necessary": <bool>,

"noCall": <bool>,

"noOsrc": <bool>,

"onlyRestrictionSubsidy": <real>,

"optionsLimit": <integer> | null,

"contextMargin": <real>,

"idleSurgeLimit": <integer> | null,

"voluntaryConfirmWithin": <timeInterval>,

"latest": <dynamicLatestObject> | null,

"noSoln": <noSolnObject>,

"init": <initObject>,

"delay": <delayObject>,

"handover": <handoverObject>,

"parts": <partsObject> | null,

"illegalActions": <illegalActionsObject>,

"helix": <helixObject>,

}

key string: Unique identifier for stop-type reference.
clone stopParamsKey: Inherit values from another stop type.
minTravelTime timeInterval default 0 s: Minimum travel time allocated to the stop.
roundTimes timeInterval default 5 min: Rounding interval for proposed arrival / departure times.
compulsory bool default false: Whether a resource can refuse during voluntary periods.
position ANY | ONTIMEONLY | FIRST | LAST default ANY: Placement restriction: ANY (no restriction), ONTIMEONLY (arrival ≤ latest), FIRST (first stop of the working period), LAST (last stop before period end).
defaultDuration timeInterval default 10 min: Default stop time when not supplied.
defaultContingency timeInterval default 0 s: Default contingency buffer.
deployMode ALWAYS | NEVER | LATE | AUTO_HEAD | AUTO_ARV default ALWAYS: Deployment messaging to the host: ALWAYS (standard), NEVER (host manages), LATE (only to prevent lateness), AUTO_HEAD / AUTO_ARV (transition straight to that state).
earlyDeploy timeInterval default 20 min: Early-deployment window for idle resources.
reliable bool default false: Whether the finish time is considered reliable.
nonProductive bool default false: Non-working-time activity.
exclusive bool default false: Requires no concurrent activities.
areaExempt bool default false: Exempt from working-area restrictions.
isBreak bool default false: Contributes to break-time allocation.
payUnits real default 1.0: Pay units for pay-per-job compensation.
failureFactor real default 0.0: Risk factor (0.0–1.0) for completion failure.
useStby useCondition: Accessibility condition under which the standby solution tier may be used.
useVoluntary useCondition: Accessibility condition under which the voluntary solution tier may be used.
useExtended useCondition: Accessibility condition under which the extended solution tier may be used.
useSurge useCondition: Accessibility condition under which surge de-prioritisation applies (e.g. NOSOLN, LATE, APPT, CLOSER).
useCloserMargin distance: Distance margin allowed when using a closer alternative.
useEarlierMargin timeInterval: Time margin allowed when using an earlier alternative.
useLateMargin timeInterval: Time margin allowed when using a later alternative.
useStbyTravelFactor real default 1.0: Travel-time multiplier applied when evaluating standby use.
quality ANY | RELIABLE | IDLE | DARK_RELIABLE | DARK_IDLE default ANY: Resource quality required to service this stop type. DARK_ variants are reliability sub-classes (signed-off but reachable).
positionQuality ANY | RELIABLE | IDLE default ANY: Controls where in the schedule this stop may be positioned.
reassignQuality ANY | RELIABLE | IDLE default ANY: Resource quality required before this stop may be reassigned.
arrivalIs STOP | LOCATION default STOP: Whether arrival timing references the stop or the location.
commitMode SPIRAL | HOST default SPIRAL: Whether Spiral commits the stop automatically (per commitWithinTime) or the host controls commit.
commitWithinTime timeInterval default 0 s: Spiral transitions to CMTD when predicted arrival is within this window.
uncommitWithinTime timeInterval: Window within which a committed stop may still be uncommitted.
headDelay timeInterval default 0 s: Time allowed for a resource to respond to deployment before heading.
clockResolution timeInterval default 60 s: Resolution of the estimated-arrival clock when heading to the stop.
sensitivity timeInterval default 5 min: Advanced — the smallest time interval treated as significant.
canBreak bool default false: A break may be taken within this stop type (though the stop is not itself a break).
necessary bool default true: Whether the stop is essential to its containing activity.
noCall bool default false: The stop should not trigger callout of resources in the STBY state.
noOsrc bool default false: Prevents the stop from entering the OSRC (outsource) state.
onlyRestrictionSubsidy real default 0.0: Subsidy applied when the stop is restricted to specific resources (an "only" restriction).
optionsLimit integer default null: Maximum number of skill options considered (null = unlimited).
contextMargin real: Cost / scoring margin applied to the stop’s surrounding scheduling context.
idleSurgeLimit integer default null: Count limit on the idle-surge effect for this stop type.
voluntaryConfirmWithin timeInterval default FOREVER: Timeframe within which voluntary deployment must be confirmed.
latest dynamicLatestObject: Controls generation of latest values for stops with dependencies.
noSoln noSolnObject: Cost and consequences of not scheduling (outsourcing) this stop type.
init initObject: How Spiral responds when a stop of this type enters the INIT state (immediate solutions / appointments).
delay delayObject: How predicted arrival times generate lateness costs.
handover handoverObject: Appointment / handover retrieval parameters.
parts partsObject: Parts-ordering lead-time configuration.
illegalActions illegalActionsObject: How rule violations for this stop type are handled.
helix helixObject: Helix-specific presentation and stop-building configuration (see below).

Helix extensions

The helix block is a Helix addition to the Spiral stopParams (it is ignored by Spiral itself). It controls how a stop type is presented and built in the Helix client, plus server-side validation and state-change hooks. check and the onState cells are "fnName()" specs resolved against the client crud module — see Backend hooks.

{

"icon": <string>,

"locationType": [string] | null,

"lineColor": <string> | null,

"mapVisibility": spec | null,

"listText": spec | null,

"planText": spec | null,

"planTitle": spec | null,

"highlight": spec | null,

"warning": { [code]: string } | null,

"roster": <bool> | null,

"messageIn": { actionee, urgency, text } | null,

"messageOut": { actionee, urgency, text } | null,

"actions": <object> | null,

"delayColors": [object] | null,

"nextStateColors": [object] | null,

"[STATE]": stateObject | null,

"addStop": <addStopObject>,

"mandatoryStop": { "to": stopParamsKey },

"morphStop": [stopParamsKey],

"templates": <object> | null,

"lineLetter": <string> | null,

"check": spec | null,

"onState": { [from]: { [to]: spec } } | null,

}

icon string: Name of the map-marker icon rendered for this stop type (e.g. "Car"). Resolves to a canvas-rendered icon in the client. A null icon draws a small dot rather than a full marker.
locationType string: Which location modes the stop editor offers, any of "any" | "derived" | "area" | "precise" (see the location object). Controls the location-mode rotation UI. Defaults to ["any","derived","area"] when unset; destination / incident stops typically use ["derived","precise"].
lineColor string: CSS colour of the schedule line drawn into this stop on the map. When unset the line takes the stop's own (state) colour; set null to override a colour inherited from a cloned type.
mapVisibility spec: Expression (with `this` = the stop) deciding whether the marker is drawn. Defaults to helixMapVisibility(): drawn if the stop is in the current plan, on a watched/active desk, a child of a plan stop, or shares the current selection; "anywhere" (no location) stops are never drawn.
listText spec: Expression producing the stop’s row text in the entity lists (default helixListText()). Returning null hides the stop from the lists.
planText spec: Expression producing the stop’s row text in the plan window (default helixPlanText()). Returning null hides it from the plan.
planTitle spec: Expression producing the plan-window title when this stop heads the plan (default helixPlanTitle(): the resource summary, falling back to the owning desk’s name).
highlight spec: Expression producing the row / marker highlight badge (e.g. helixHighlight("Lock") shows a lock icon while the stop is locked).
warning { [code]: string }: Map of Spiral illegal-action code → operator-facing message template shown when a mutation is refused. Templates may interpolate stop attributes with {attr|format} placeholders.
roster bool: Marks a roster stop type (NOW / REST / STBY). Roster stops are presentation shells for the resource’s shift rather than jobs, and are skipped when deriving the resource’s active work.
messageIn { actionee, urgency, text }: Resource → dispatch messaging facility for this stop type (action format). `text` is the enable gate: true = always available, an expression = per-stop, absent = hidden. See the Actions guide.
messageOut { actionee, urgency, text }: Dispatch → resource messaging facility (the "Message resource" button in the stop editor). Same shape and gating as messageIn. See the Actions guide.
actions object: Per-stop-type action definitions raised into the dispatch Actions queue (messages to acknowledge, questions to resolve, automatic classed actions). Fully described in the Actions guide.
delayColors object: Colour bands keyed by lateness threshold (seconds), used by helixColorDelay() to colour the stop by how far ahead of / behind schedule it is.
nextStateColors object: Colour bands by time-to-next-state, used to colour the stop as its next transition approaches.
[STATE] stateObject: Per-state presentation keyed by stop state (PLAN, DPLY, HEAD, …) — colour, status text and icon. See below.
addStop addStopObject: Default child-stop types offered when an operator adds a stop of this type (see below).
mandatoryStop { "to": stopParamsKey }: Child stops automatically attached to a stop of this type.
morphStop stopParamsKey: Stop types this stop may be morphed into.
templates object: Predefined stop templates available for this type.
lineLetter string: Single-letter code used in the line / roster display.
check spec: Server-side validation run on the crud add/update path with `this` = the stop. Return a non-empty string to reject the mutation, or null/undefined to pass.
onState { [from]: { [to]: spec } }: Stop state-transition matrix. The cell [fromState][toState] is called (with `this` = the stop) on that transition; the string "null" marks the pre-create (null→first) and post-delete (last→null) edges. Cells are independent.

addStop

Each relation maps to the stop type(s) offered when the operator extends a stop of this type along that relation (an array of stopParamsKey, or null). The relations mirror the stopObject links of the same name.

{

"to": [stopParamsKey] | null,

"and": [stopParamsKey] | null,

"with": [stopParamsKey] | null,

"then": [stopParamsKey] | null,

"asset": [stopParamsKey] | null,

}

to stopParamsKey: Stop types offered for a sequential delivery (`to`) child.
and stopParamsKey: Stop types offered for an unrelated concurrent (`and`) child.
with stopParamsKey: Stop types offered for a concurrent (`with`) child.
then stopParamsKey: Stop types offered for a sequential follow-up (`then`) child.
asset stopParamsKey: Stop types offered for an asset (`asset`) child.

State presentation

Keys named after a stop state (PLAN, OSRC, CALL, DPLY, HEAD, CMTD, ARVD, DONE) carry the look and label for the stop while it is in that state:

{

"color": <string>,

"status": <string> | null,

"icon": <string> | null,

}

color string: Colour name (resolved via the client colour map) or expression (e.g. helixColorDelay()) for the marker in this state; "transparent" hides the dot.
status string: Domain text shown for this state in the lists, the stop editor and the map — e.g. an UNLOAD stop showing "RECY" for HEAD/CMTD. Falls back to the raw state code when unset.
icon string: Override the marker icon while the stop is in this state.

stopParamsObject

Helix extensions

addStop

State presentation

Related