Cellario OS Event Service — Event Reference

56 min

A companion to Subscribing to Cellario OS Event Service: the event types you can subscribe to, and the schema of each event's payload

Before you read this: this reference assumes you already have a subscriber and know how to create subscriptions and filters. If not, start with the subscription guide (Subscribing to Cellario OS Event Service) — Section 3 covers subscriptions and filters, and Appendix A is the full filter reference.

1. Introduction

As workflow orders, Guided Tasks, scripts, and lab devices execute work in Cellario OS, the platform publishes structured events to the Event Service. This reference catalogs the Workflow, ManualTask (Guided Task), CellarioEdge, CloudScheduler, and Scripting job event families and documents the payload schema of each event so you can filter on them and parse them in your own systems.

Terminology: Guided Tasks are called ManualTask on the wire — in the envelope type, the payload_type, and payload property names. The prose below says "Guided Task"; the JSON values remain ManualTask.

How to identify an event

Every delivered event carries the common envelope described in the subscription guide (snake_case fields such as type, state, payload_type, payload_json). For the events in this reference:

The envelope type is the event family: Workflow, ManualTask, CellarioEdge (device events), or CloudScheduler. The exception is scripting job events, where type names the specific event directly (seven values prefixed ScriptingJob — see section 13).

The envelope payload_type identifies the specific event within the family. For the Workflow and ManualTask families it is a dotted, fully-qualified name — match it with a contains or ends_with string filter rather than exact equality. Other families use bare or derived names, called out in their sections.

The event-specific data is in payload_json, carried as a JSON string that you parse into the schemas documented below.

Events triggered by a person also carry a user_id field on the envelope — the GUID of the user who made the change. Each event section below notes when it is populated.

Event	type	payload_type ends with
Workflow operation started	Workflow	WorkflowOperationStartedMessage
Workflow order canceled	Workflow	WorkflowOrderCancelledMessage
Workflow order internal error	Workflow	WorkflowOrderInternalError
Workflow order state updated	Workflow	WorkflowOrderStateUpdated
Workflow order step state updated	Workflow	WorkflowOrderStepStateUpdated
Guided task instance updated	ManualTask	ManualTaskInstanceUpdated
CellarioEdge device event	CellarioEdge	DriverHostEvent
CellarioEdge file uploaded	CellarioEdge	DriverHostFileUploadedEvent (exact)
Cellario Scheduler events (CellarioEdge passthrough)	CellarioEdge	varies — see section
Cloud Scheduler events	CloudScheduler	Cellario.Client.<EventName> — see section
Scripting job events	ScriptingJob… (7 types — see section)	Script or ScriptResult (exact)

Payload conventions

The payload schemas below share these conventions:

Property names are PascalCase (e.g. WorkflowOrderId, NewState) — unlike the snake_case envelope. Remember that payload filters are case-sensitive (see Appendix A of the subscription guide). Exception: the scheduler event documents in section 11 and section 12 (the CellarioEdge passthrough and CloudScheduler families) are camelCase by default — eventType, orderAssetId, not EventType, OrderAssetId — and can be flipped to PascalCase by a scheduler config switch. See §11.1.

State values inside payloads are integers. Each event section includes a value → meaning table. Note the contrast with the envelope's state field, which carries the state name as a string (e.g. envelope state: "InProgress" alongside payload "NewState": 2). Filter on whichever is more convenient — but don't mix them up.

Cancel-state spelling varies by event family. Workflow order lifecycle states spell it with two l's — Cancelling / Cancelled (§6) — but workflow order step states (§7), Guided Tasks (§8) use one l in uppercase: CANCELED; scheduler events (§11 / §12) use one l as Canceled. Because matching is case- and spelling-sensitive, filter on the exact form emitted by the service — a Canceled filter will not match a workflow order lifecycle state's Cancelled.

IDs are GUIDs rendered as strings, e.g. "3fa85f64-5717-4562-b3fc-2c963f66afa6".

Timestamps are ISO 8601 with offset, e.g. "2026-08-07T12:00:00+00:00".

2. Quick-start filter recipes

Create these as complex filters (subscription guide, Section 3, Option B).

All workflow order state changes:

{
  "type": { "in": ["Workflow"] },
  "payload_type": { "ends_with": "WorkflowOrderStateUpdated" }
}

A specific workflow order reaching Completed (NewState 3 — unquoted, because it's a JSON number):

{
  "type": { "in": ["Workflow"] },
  "payload_type": { "ends_with": "WorkflowOrderStateUpdated" },
  "payload_matches": {
    "WorkflowOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "NewState": 3
  }
}

Critical workflow errors:

{
  "type": { "in": ["Workflow"] },
  "severity": { "in": ["critical"] }
}

Guided tasks finishing:

{
  "type": { "in": ["ManualTask"] },
  "state": { "in": ["FINISHED"] }
}

Device errors from a CellarioEdge (device state changes are subtype 5; see CellarioEdge device event):

{
  "type": { "in": ["CellarioEdge"] },
  "payload_type": { "ends_with": "DriverHostEvent" },
  "payload_matches": { "Type": 5, "State": "Error" }
}

Scripting job failures:

{
  "type": { "in": ["ScriptingJobError"] }
}

3. Workflow operation started

Published when an operation (an instrument or protocol operation) begins executing for a workflow order step.

This event is emitted only for orders whose protocol uses workflow-order-engine thread operations. For other protocols the step simply moves to InProgress without this event — rely on Workflow order step state updated for universal step-start coverage.

Envelope

Field	Value
type	Workflow
source_category	integration
source_name	WorkflowOperationsService
source_id	The workflow order step ID
payload_type	ends with WorkflowOperationStartedMessage
state, severity, user_id	not set

Payload schema (parse payload_json)

Field	Type	Description
WorkflowOrderId	GUID string	The workflow order the operation belongs to
ProtocolStepId	integer	The protocol step being executed
OperationId	integer	The sample operation identifier
InputParameterValues	array of { Name, Value }	Operation input parameters; both Name and Value are strings (Value is the stringified parameter value)
OperationHints	object (string → string)	Hint key/value pairs applied to the step (e.g. elementType)
Summary	string	Human-readable summary of the event, e.g. "WorkflowOperationStartedMessage (ProtocolStepId 12, OperationId 34)"

Example payload

{
  "WorkflowOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ProtocolStepId": 12,
  "OperationId": 34,
  "InputParameterValues": [
    { "Name": "Volume", "Value": "50" }
  ],
  "OperationHints": { "elementType": "instrument" },
  "Summary": "WorkflowOperationStartedMessage (ProtocolStepId 12, OperationId 34)"
}

4. Workflow order canceled

Published when a workflow order is canceled. This event has two possible triggers, and subscribers should treat them the same way:

Explicit cancellation — the scheduler reports that the order reached a canceled state.

Assumed cancellation — the underlying scheduler order can no longer be found, so the platform concludes it was canceled. This means a cancellation event does not always correspond to an explicit cancel action.

Envelope

Field	Value
type	Workflow
source_category	integration
source_name	WorkflowEngine
source_id	The workflow order ID
payload_type	ends with WorkflowOrderCancelledMessage
state, severity, user_id	not set

Payload schema

Field	Type	Description
WorkflowOrderId	GUID string	The canceled workflow order
Summary	string	Always "WorkflowOrderCancelledMessage"

The payload carries no cancellation reason and no previous state. If you need those, subscribe to Workflow order state updated instead (or as well) — its payload includes OldState, NewState, and CancellationReason.

Example payload

{
  "WorkflowOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Summary": "WorkflowOrderCancelledMessage"
}

5. Workflow order internal error

Published when an unexpected platform error prevents a workflow order from starting. When this occurs, the order is automatically returned to the Pending state. It is delivered with envelope severity: critical, which makes it easy to route to alerting (the only other events that can carry critical are caller-authored step messages — see section 7):

{ "type": { "in": ["Workflow"] }, "severity": { "in": ["critical"] } }

Envelope

Field	Value
type	Workflow
source_category	integration
source_name	WorkflowEngine
source_id	The workflow order ID
severity	critical
payload_type	ends with WorkflowOrderInternalError
state, user_id	not set

Payload schema

Field	Type	Description
WorkflowOrderId	GUID string	The workflow order that failed to start
ErrorMessage	string	Description of the failure, e.g. "Failed to ExpressStart order: Timed out"

Example payload

{
  "WorkflowOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ErrorMessage": "Failed to ExpressStart order: Timed out"
}

6. Workflow order state updated

Published on every workflow order state transition (Pending → Starting → InProgress → Completed, cancellations, etc.). This is the primary event for tracking order lifecycle.

Envelope

Field	Value
type	Workflow
source_category	integration
source_name	WorkflowOrderRepository
source_id	The workflow order ID
state	The new state's name, e.g. "InProgress" (see table below)
user_id	GUID of the requesting user, when the transition was user-initiated (e.g. a manual cancel); otherwise not set
payload_type	ends with WorkflowOrderStateUpdated
severity	not set

Payload schema

Field	Type	Description
WorkflowOrderId	GUID string	The workflow order
OldState	integer	State before the transition (see table)
NewState	integer	State after the transition (see table)
CancellationReason	string or null	Populated when the order was canceled with a reason; otherwise null. Read from the order's persisted field, so once set it repeats on every subsequent event for that order (both the Cancelling and Cancelled transitions), not only the first

Workflow order state values

Payload value (integer)	Envelope state (string)	Meaning
1	Pending	Created, not yet started
2	InProgress	Actively executing
3	Completed	Finished successfully
4	Cancelled	Cancelled
5	Starting	Start requested, spinning up
6	Cancelling	Cancel requested, winding down

Example payload (order moved from Starting to InProgress)

{
  "WorkflowOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "OldState": 5,
  "NewState": 2,
  "CancellationReason": null
}

7. Workflow order step state updated

Published when a workflow order step changes state — steps move through Pending → InProgress → Completed (or Skipped / Canceled / Error, and back to Pending on retry). Use this event to track progress through a workflow at step granularity.

Envelope

Field	Value
type	Workflow
source_category	integration
source_name	WorkflowOrderStepRepository
source_id	The workflow order step ID
state	The step's current state name, e.g. "InProgress" (see table below)
severity / description	Populated only on annotation updates: display-only error annotations arrive with severity: "error" and the error text in description; step messages carry a sender-chosen severity and the message text. A genuine step failure — the transition into the Error state — arrives with both unset; its failure message is in the payload's StepHints.errorMessage. To catch failing steps, filter on the state (payload NewState: 5 or envelope state: "Error"), not on severity
user_id	GUID of the acting user on user-driven updates (retrying or skipping a step); otherwise not set
payload_type	ends with WorkflowOrderStepStateUpdated

Payload schema

Field	Type	Description
WorkflowOrderId	GUID string	The parent workflow order
WorkflowOrderStepId	GUID string	The step being updated
OldState	integer	State before the update (see table)
NewState	integer	State after the update (see table)
StepHints	object (string → string)	The step's hint key/value pairs (e.g. elementType)
RunOrderIds	array of integers	Scheduler run orders currently associated with the step

Well-known StepHints keys (all values are strings; nested structures are JSON encoded as strings — parse them separately):

Key	Contents
elementType	The step's element type
errorMessage	The failure message, when the step entered the Error state
warnings	JSON array of warning strings
errors	JSON array of { timestamp, message } display-only error annotations
iterationCount	The loop step's iteration counter
taskInstanceId	The Guided Task instance bound to the step, when applicable

Workflow step state values

Payload value (integer)	Envelope state (string)	Meaning
0	Pending	Not yet started (also set on retry)
1	InProgress	Actively executing
2	Completed	Finished successfully
3	Skipped	Skipped by a user or the workflow
4	Canceled	Cancelled
5	Error	Failed

Not every event is a state transition. This event is also published with OldState equal to NewState when other step data changes: a run order is attached to the step (watch RunOrderIds grow), a warning is added to an in-progress step, a display-only error annotation is added (arrives with severity: "error" — see the envelope table), a step message is published (message and severity on the envelope), or a new loop iteration starts on a step already in progress. Do not assume OldState != NewState; compare the two fields if you only care about genuine transitions.

Example payload (step started)

{
  "WorkflowOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "WorkflowOrderStepId": "8c1d2e3f-1234-4562-b3fc-2c963f66afa6",
  "OldState": 0,
  "NewState": 1,
  "StepHints": { "elementType": "instrument" },
  "RunOrderIds": [101, 102]
}

8. Guided task instance updated

Published at each Guided Task lifecycle point: when a task instance is created (READY), started (STARTED), finished (FINISHED — including its output parameter values), or reaches another terminal state (FAILED, CANCELED, SKIPPED).

This is the same ManualTask event described in Appendix A of the subscription guide ("Common event values"). The filter guidance there applies: to match a specific order's task events, filter on payload_matches.OrderAssetId (always populated) rather than WorkflowOrderId (populated only for workflow-driven tasks).

Envelope

Field	Value
type	ManualTask
source_category	integration
source_name	manual-task-service
source_id	The task instance ID
state	Uppercase state name, e.g. "STARTED" (see table below)
user_id	GUID of the user whose action produced the update (e.g. the operator starting or finishing the task), when available
payload_type	ends with ManualTaskInstanceUpdated
severity	not set

Payload schema

Field	Type	Description
State	integer or null	The task's new state (see table)
TaskId	GUID string	The Guided Task instance
OrderAssetId	GUID string	The order the task belongs to. Sentinel: the all-zeros GUID (00000000-0000-0000-0000-000000000000) means the task has no order — treat it as absent
SampleOperationId	string	The task's runtime identifier. Sentinel: "0" means no runtime ID — treat it as absent
ParameterValues	array of { ParameterId, Value }	All parameter values; ParameterId is a GUID string, Value a string. Contains output values on FINISHED and later state updates; empty on READY and STARTED
GeneratedDate	timestamp	When the event was generated (UTC)
WorkflowOrderId	GUID string or null	The owning workflow order — null for tasks created outside a workflow
WorkflowOrderStepId	GUID string or null	The owning workflow order step — null for tasks created outside a workflow
LabwareSets	array of { ParameterId, Value }	The subset of ParameterValues that are labware-set outputs, duplicated here so you don't need to inspect parameter types
MoveOperations	array of { ParameterId, Value }	The subset of ParameterValues that are move-operation outputs, duplicated likewise

Guided task state values

Payload value (integer)	Envelope state (string)	Meaning
0	READY	Instantiated, awaiting an operator
1	STARTED	An operator has begun the task
2	FINISHED	Completed successfully
3	FAILED	Failed
4	CANCELED	Cancelled
5	SKIPPED	Skipped

Example payload (task finished, one labware-set output)

{
  "State": 2,
  "TaskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "OrderAssetId": "9b2f4c11-aaaa-4562-b3fc-2c963f66afa6",
  "SampleOperationId": "42",
  "ParameterValues": [
    { "ParameterId": "1a2b3c4d-5717-4562-b3fc-2c963f66afa6", "Value": "PlateSet-7" }
  ],
  "GeneratedDate": "2026-08-07T12:00:00+00:00",
  "WorkflowOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "WorkflowOrderStepId": "8c1d2e3f-1234-4562-b3fc-2c963f66afa6",
  "LabwareSets": [
    { "ParameterId": "1a2b3c4d-5717-4562-b3fc-2c963f66afa6", "Value": "PlateSet-7" }
  ],
  "MoveOperations": []
}

9. CellarioEdge device event

Published as lab devices connected through a CellarioEdge do work: producing data, running operations, logging, warning, changing device state, and as device resources are added, updated, or removed from the CellarioEdge.

All eight variants share one payload schema and one payload_type. The variant is identified by the numeric Type field inside the payload:

Type	Variant	Meaning
1	Data	The device produced result data
2	Operation	A device operation changed disposition (queued, in progress, completed, …)
3	Log	The device emitted a log message
4	Warning	The device raised a warning
5	DeviceStateChange	The device transitioned to a new state
6	ResourceAdded	A device resource was added to the CellarioEdge
7	ResourceUpdated	A device resource's definition was updated
8	ResourceDeleted	A device resource was removed from the CellarioEdge

Envelope

Field	Value
type	CellarioEdge
source_category	integration
source_name	CellarioEdgeEventService
source_id	The CellarioEdge ID
severity	Set for Log events whose level maps to a recognized severity: debug, info, warning, error. Other log levels (state, internal, exception, data) arrive with no severity — read the true level from the payload's Metadata.Severity / Metadata.Level instead. Warning events arrive with warning. Otherwise not set
payload_type	ends with DriverHostEvent
state, user_id	not set (state information is inside the payload)

Payload schema

Field	Type	Description
Id	GUID string	Unique event ID
DateCreated	timestamp	When the event was generated (UTC)
CorrelationId	GUID string or null	Correlates the event with the operation/action that caused it
ResourceName	string	The device resource's name
ResourceReferenceId	GUID string	The resource's reference ID on the CellarioEdge
ResourceId	GUID string	The resource's platform ID
DriverHostReferenceId	GUID string	The CellarioEdge's reference ID
DriverHostId	GUID string	The CellarioEdge's platform ID
Type	integer	The event variant (table above)
State	string	Variant-specific state (see below); empty string when not applicable
Description	string	Human-readable description of what happened (for Operation and DeviceStateChange failures this carries the error message)
Metadata	object or null	Variant-specific details (see below)
OperationMetadata	object or null	Metadata attached to the originating action, when the event stems from a tracked operation
WorkflowOrderId	GUID string or null	The owning workflow order, when the device work was initiated by a workflow
WorkflowOrderStepId	GUID string or null	The owning workflow order step, likewise

State values by variant

Operation (2): the operation disposition — Queued, InProgress, CompletedNormally, CompletedWithErrors, Aborted, Unknown

DeviceStateChange (5): the device state — Error, Idle, Connecting, Connected, Initializing, Ready, DoingOp

All other variants: empty string

Metadata contents by variant

Variant	Metadata shape
Data (1)	{ "Name": string, "ResultDataString": string, "FilePaths": [string] }
Operation (2)	{ "OperationName": string, "DeviceState": <device state> }
Log (3)	{ "Level": integer, "Severity": string }
Warning (4)	not set
DeviceStateChange (5)	{ "CurrentCommand": string }
ResourceAdded / ResourceUpdated (6, 7)	{ "Operations": [...] } — the driver-defined operations the resource supports
ResourceDeleted (8)	not set

Example payload (a device going into error)

{
  "Id": "5e8d3a21-9f47-4b06-8f7a-2c963f66afa6",
  "DateCreated": "2026-08-07T12:00:00+00:00",
  "CorrelationId": "7a1b2c3d-5717-4562-b3fc-2c963f66afa6",
  "ResourceName": "Centrifuge-1",
  "ResourceReferenceId": "0f9e8d7c-5717-4562-b3fc-2c963f66afa6",
  "ResourceId": "1c2d3e4f-5717-4562-b3fc-2c963f66afa6",
  "DriverHostReferenceId": "2d3e4f5a-5717-4562-b3fc-2c963f66afa6",
  "DriverHostId": "3e4f5a6b-5717-4562-b3fc-2c963f66afa6",
  "Type": 5,
  "State": "Error",
  "Description": "Rotor imbalance detected",
  "Metadata": { "CurrentCommand": "Spin" },
  "OperationMetadata": null,
  "WorkflowOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "WorkflowOrderStepId": "8c1d2e3f-1234-4562-b3fc-2c963f66afa6"
}

10. CellarioEdge file uploaded

Published when a file produced on a CellarioEdge (e.g. a device result file) has been uploaded to Cellario OS blob storage and is available for download.

Filtering note: unlike most events, this event's payload_type is the exact string DriverHostFileUploadedEvent (no dotted prefix), so an in (exact-match) filter works: "payload_type": { "in": ["DriverHostFileUploadedEvent"] }.

Envelope

Field	Value
type	CellarioEdge
source_category	integration
source_name	CellarioEdgeEventService
source_id	The CellarioEdge ID
payload_type	DriverHostFileUploadedEvent (exact)
state, severity, user_id	not set

Payload schema

Field	Type	Description
FileUploadId	GUID string	The file-upload record
CorrelationId	GUID string or null	Correlates the upload with the operation that produced the file
DriverHostId	GUID string	The CellarioEdge the file came from
BlobStorageBucketName	string	Blob-storage bucket holding the file
BlobStorageFileId	GUID string	The file's ID in blob storage — use with the Blob Storage API to download
BlobStorageFileName	string	The stored file name
EdgeFilePath	string	The file's original path on the CellarioEdge
Metadata	object or null	Metadata attached to the upload. When it contains a WorkflowStepId, Cellario OS binds the uploaded file to that workflow step (creating the file reference shown on the step); uploads without it are not linked to any step

Example payload

{
  "FileUploadId": "4f5a6b7c-5717-4562-b3fc-2c963f66afa6",
  "CorrelationId": "7a1b2c3d-5717-4562-b3fc-2c963f66afa6",
  "DriverHostId": "3e4f5a6b-5717-4562-b3fc-2c963f66afa6",
  "BlobStorageBucketName": "driver-host-files",
  "BlobStorageFileId": "5a6b7c8d-5717-4562-b3fc-2c963f66afa6",
  "BlobStorageFileName": "results_2026-08-07.csv",
  "EdgeFilePath": "C:\\Data\\results_2026-08-07.csv",
  "Metadata": null
}

11. Cellario Scheduler events (passthrough)

CellarioEdges can forward events from an attached Cellario Scheduler through to the Event Service. These arrive with envelope type: CellarioEdge (same source_name / source_category as the other CellarioEdge events), and a payload_type derived from the forwarded message:

payload_type	Meaning
A forwarded message name, e.g. OrderStateChange	A named CellarioEdge-adapter message
RpcResponse	The result of a remote procedure call to the scheduler
SchedulerEvent	Fallback when the message carries no recognizable name

The forwarded message is delivered as-is, wrapped in a small CellarioEdge envelope. When the payload is a scheduler event, the envelope's DataJson field carries the scheduler event document — a JSON document encoded as a string — plus routing fields such as Name, ResourceName, and ResourceId. Parse payload_json, then parse the DataJson string inside it to get the event document described below.

The envelope source_id of a passthrough event is the originating scheduler resource's ID when the forwarded message carries one; otherwise it falls back to the CellarioEdge's reference ID. Note this differs from the CellarioEdge events in sections 9–10, whose source_id is the CellarioEdge's platform ID — don't assume one source_id value spans both.

Also published elsewhere. The same scheduler event may be published directly by the Cloud Scheduler family (section 12) without this passthrough wrapping — a subscriber to both families receives both copies, keyed to different orders. See the warning in section 12.

11.1 The scheduler event document

Every scheduler event is one JSON document discriminated by its eventType field. Ten event types exist: System, Order, Operation, Driver, Data, Inventory, StorageInventory, Audit, Generic, and Deadlock.

Scheduler event documents follow different serialization conventions from the cloud-published payloads in sections 3–10:

Property names are camelCase by default (eventType, orderAssetId). A scheduler configuration switch can flip the entire document to PascalCase, so tolerant parsers should match property names case-insensitively.

Enums are strings, not integers: "state": "Finished", not "state": 2.

Timestamps are ISO 8601.

Common envelope (all scheduler event types):

Field	Type	Description
id	integer	Unique event ID, assigned sequentially by the scheduler
date	timestamp	When the event occurred
description	string or null	Human-readable description
version	string	Event schema version; currently always "3.0"
systemName	string	The scheduler system that produced the event
systemAssetId	string	The producing system's global asset ID
eventType	string	The discriminator — one of the ten types below
additionalInfo	array or null	Reserved; currently never populated

11.2 eventType: "System" — system state change

Emitted when the scheduler system changes state.

Field	Type	Description
name	string	The system name (duplicates systemName)
state	string	One of InError, UnInitialized, Initializing, Initialized, Running, Pausing, Paused

{
  "id": 1041, "date": "2026-08-07T12:00:00+00:00", "version": "3.0",
  "systemName": "Cell-1", "systemAssetId": "SYS-0001",
  "eventType": "System",
  "name": "Cell-1", "state": "Running",
  "description": "System started"
}

11.3 eventType: "Order" — order state change

Emitted when a run order changes state. A synthetic Starting event is also emitted when a new order begins execution.

Field	Type	Description
orderId	integer	The scheduler order
orderAssetId	string or null	The order's global asset ID
state	string	One of Created, Submitted, Started, Finished, Removed, Pausing, Paused, Scanning, Scripting, Starting, Canceled
protocolId	integer	The protocol the order runs
protocolName	string or null
protocolAssetId	string or null

{
  "id": 1042, "date": "2026-08-07T12:01:00+00:00", "version": "3.0",
  "systemName": "Cell-1", "systemAssetId": "SYS-0001",
  "eventType": "Order",
  "orderId": 512, "orderAssetId": "1f7e9c3a-bbbb-4562-b3fc-2c963f66afa6", "state": "Started",
  "protocolId": 77, "protocolName": "Compound Screen", "protocolAssetId": "PROT-0077"
}

11.4 eventType: "Operation" — sample operation change

Emitted as each sample operation (a plate/labware step such as a move or a liquid transfer) starts, finishes, or fails. This is the highest-volume scheduler event type.

Field	Type	Description
name	string or null	Operation name, e.g. LiquidTransfer, Move, OpenDoor, Script
barcode	string or null	The labware barcode
labwareType / labwareTypeAssetId	string or null
plateProtocolName / plateProtocolId	string or null / integer	The thread (plate protocol) within the order
state	string	One of None, Started, Finished, Accept, Repeat, Failed
currentResource / currentResourceAssetId	string or null	Where the labware currently is
destinationResource / destinationResourceAssetId	string or null	Where it's headed ("None" when not applicable)
operationResource / operationResourceAssetId / operationResourceType	string or null	The device performing the operation
sampleOperationId	integer
orderSampleId	integer
orderId / orderAssetId	integer / string or null	The owning order
protocolStepId	integer
notes	string or null	Device error message, when the operation failed
parameters	array of { name, value, description }	The operation's parameters (description is never populated on Operation events). For Guided Tasks, includes positioning entries (ResourcePositionId, Column, Row, DestinationResourcePositionId, DestinationColumn, DestinationRow, ManualLidAction, ManualScanBarcodeRequired). On Finished, may include a Results entry carrying raw driver output
isManualTask	boolean	true when the operation is a Guided Task
isDeviceSimulated	boolean	Whether the device was simulated

11.5 eventType: "Driver" — device state change

Emitted when a device (resource) attached to the scheduler changes state.

Field	Type	Description
resourceName	string	The device
resourceAssetId	string
state	string	One of Unavailable, Error, Idle, Connecting, Connected, Initializing, Ready, DoingOp
errorMessage	string	The device error text when state is "Error"; empty string otherwise
isDeviceSimulated	boolean

11.6 eventType: "Data" — result data available

Emitted after an operation or order finishes and produced data: device result files, script output, or an order-level data package. The context field says what the data belongs to.

Data events carry no state field — filters on state never match them; filter on eventType and context instead.

Field	Type	Description
context	string	"Operation" (device files or script data) or "Order" (order data package)
name	string	Name of the data produced by the device; empty when not applicable
files	array of { path, checkSum: { name, format, value } }	Produced files; checksums are md5 in hexadecimal
data	object or null	Two possible shapes: script output as { name, value } (known issue: name is currently always null; the output is in value), or raw device data — arbitrary JSON passed through from the device as-is
order	object	Order detail (see below)
operation	object or null	Operation detail (see below); only present when context is "Operation"

Order detail: id, orderAssetId, protocolId, protocolAssetId, protocolVersion, startTime, endTime (local time), startTimeUtc, endTimeUtc (UTC equivalents — prefer these), parameters (array of { name, description, value, dataType }), properties (array of { name, description, value }).

Operation detail: eventId, orderSampleId, sampleOperationId, barcode, plateProtocolId. Note eventId means different things per family: on Data events it is the event's own ID; on Inventory events it is the triggering event's ID (0 when absent).

11.7 eventType: "Inventory" — liquid transfer results

Emitted when a finished operation reports liquid-transfer results.

Inventory events carry neither a state nor a context field — the presence of the operation detail tells you the results belong to an operation.

Field	Type	Description
inventoryType	string	The result type reported by the device, verbatim. Only the exact value "LiquidTransferResult" produces entries in metadata; any other value yields an empty metadata array
metadata	array	One entry per well transfer (schema below)
order	object	Order detail (as in Data events)
operation	object or null	Operation detail (as in Data events)

Each metadata entry (a LiquidTransferResult):

Field	Type	Description
liquidTransferId	string or null
timeStamp	timestamp	When the transfer occurred
expectedTransferVolume	decimal	Volume in µL
sourceDecrementVolume	decimal	Volume removed from the source well
destinationIncrementVolume	decimal	Volume added to the destination well
failureMessage	string or null	Set when the transfer failed
sourcePlateSampleId / destinationPlateSampleId	integer
sourceBarcode / destinationBarcode	string or null
sourceWell / destinationWell	string or null	e.g. "A1"
properties	object	Additional key/value details

11.8 eventType: "StorageInventory" — storage position contents changed

Emitted when the contents of a storage position (e.g. an incubator or hotel slot) change.

Field	Type	Description
resourceName / resourceAssetId	string	The storage device
resourcePositionId	integer	The position within the device
row / column	integer	The position's coordinates
itemType	string	What now occupies the position: Empty, BarcodeOnly, LabwareOnly, or LabwareAndBarcode
barcode	string or null	The labware barcode, when present
labwareType / labwareTypeAssetId	string or null	The labware type, when present
orderSampleId	integer	The occupying sample, when the position is held by an order

An event with no barcode, no labware type, and no order sample means the position is now empty.

11.9 eventType: "Audit" — order & protocol audit trail

Emitted when orders or protocols are created, updated, or deleted.

Field	Type	Description
auditContext	string	"Order" or "Protocol" (the only values currently produced)
state	string	One of Create, Read, Update, Delete
metadata	object	Shape depends on auditContext (below)

auditContext: "Order" → metadata = { orderId, orderAssetId, protocolId, protocolName, protocolAssetId }

auditContext: "Protocol" → metadata = { protocolId, protocolName, protocolAssetId }

11.10 eventType: "Generic" — customer-defined events

Not raised by the scheduler itself: callers post arbitrary events to the scheduler's own API, and the scheduler re-broadcasts them. Useful for injecting your own signals into the same event stream.

Field	Type	Description
details	object	Arbitrary JSON supplied by the caller
orderId	integer	Optional order association (0 when absent)
orderAssetId	string or null

Generic events have no state field, so state-based filters never match them.

11.11 eventType: "Deadlock"

Emitted when the scheduler detects a scheduling deadlock. The payload carries only the common envelope fields — description reads "<systemName> experienced a deadlock." and no further detail (affected samples, system state) is included in the event.

12. Cloud Scheduler events

The Cloud Scheduler is the internal Workflow Engine for OS. It publishes the same scheduler event documents described in sections 11.1–11.11 straight to the Event Service — no CellarioEdge envelope and no DataJson double-parse: the payload_json is the scheduler event document. These represent some internal workings of OS and can be ignored for most use cases.

⚠️ You may receive the same underlying event twice — once per family. A single scheduler event (for example a Data event for a produced result file) can be delivered both as a CloudScheduler event (this section — direct payload_json, no dataJson double-parse) and as a CellarioEdge passthrough event (section 11 — wrapped, with the event document inside the dataJson string). The two copies describe the same data but are keyed to different orders: the CloudScheduler copy carries the OS workflow order's orderId/orderAssetId, while the passthrough copy carries the underlying scheduler ("celld") order's ids. Their property casing can also differ (see the camelCase/PascalCase switch in §11.1). If you subscribe to both families, de-duplicate or pick one family per integration — which family you subscribe to determines which correlation id you can filter on.

Envelope

Field	Value
type	CloudScheduler
source_category	integration
source_name	cloud-scheduler
source_id	The scheduler system's asset ID
payload_type	Cellario.Client.<EventName>, where <EventName> is one of SystemEvent, OrderEvent, OperationEvent, DriverEvent, DataEvent, InventoryEvent, StorageInventoryEvent, AuditEvent, GenericEvent, DeadlockEvent
state	Set only for OrderEvent (the order state name, e.g. "Started"); absent on every other type
user_id	not set

The payload document schemas are identical to the CellarioEdge-passthrough ones — see sections 11.1 (common envelope and serialization conventions) through 11.11.

Example filter — cloud scheduler order events for a specific order:

{
  "type": { "in": ["CloudScheduler"] },
  "payload_type": { "ends_with": "OrderEvent" },
  "payload_matches": { "orderAssetId": "1f7e9c3a-bbbb-4562-b3fc-2c963f66afa6" }
}

13. Scripting job events

Published as cloud script jobs (Python or C# scripts run by workflow script steps) move through their lifecycle: fetching the script, installing dependencies, running, and finishing with a result or an error.

This family works differently from the others: the envelope type names the specific event (there are seven), while payload_type is one of just two exact values — Script while the job is progressing, ScriptResult when it finishes. Filter on type, and use the payload_type to know which payload schema to parse.

type	When	state	severity	payload_type
ScriptingJobRunning	The job has started	—	info	Script
ScriptingJobFetching	Fetching the script's files	—	info	Script
ScriptingJobFetched	Script files retrieved	—	info	Script
ScriptingJobInstalling	Installing Python dependencies (only when the script has a requirements file)	—	info	Script
ScriptingJobDependenciesInstalled	Dependencies installed	—	info	Script
ScriptingJobCompleted	The script ran successfully	completed	info	ScriptResult
ScriptingJobError	The job failed at any stage	error	error	ScriptResult when the script produced output (execution failures); Script for earlier failures (fetch/install errors, unsupported script type)

Envelope (all seven types)

Field	Value
type	One of the seven values above
source_category / source_component	other / other
source_name	The script's name
source_id	The scripting job ID
description	Human-readable progress or error message (for errors, the extracted script error)
state / severity	Per the table above
payload_type	Script or ScriptResult (exact values)
user_id	not set

Payload schema — Script (progress events and pre-execution errors)

Field	Type	Description
WorkflowOrderId	GUID string or null	The workflow order that launched the script
WorkflowOrderStepId	GUID string or null	The script step within that order

Payload schema — ScriptResult (completion and execution errors)

Field	Type	Description
stdout	string	The script's standard output
stderr	string	The script's standard error (populated on failures)
returncode	integer	The script process exit code (0 on success)
output_parameters	string	The script's output parameters as a JSON string — parse it separately; empty when the script produced none
WorkflowOrderId	GUID string or null	The workflow order that launched the script
WorkflowOrderStepId	GUID string or null	The script step within that order

Example payload (ScriptingJobCompleted)

{
  "stdout": "Processed 96 wells\n",
  "stderr": "",
  "returncode": 0,
  "output_parameters": "{\"hitCount\": 12}",
  "WorkflowOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "WorkflowOrderStepId": "8c1d2e3f-1234-4562-b3fc-2c963f66afa6"
}

Tracking a job end-to-end: all events for one job share the same source_id (the job ID). A job always ends with exactly one ScriptingJobCompleted or ScriptingJobError; the progress events (Running, Fetching, Fetched, Installing, DependenciesInstalled) vary by script type and whether dependencies needed installing.