Recording Production Progress

Applies to CoCoCo platform v1.0.0-rc.31. Every statement below was checked on that version, against the schema and against points already recorded.

Progress points are how CoCoCo learns what is actually happening on the shop floor: how many good copies an operation has produced, how much waste, which phase the machine is in, how fast it is running.

Before you write the first one, there is one property worth knowing.

Progress points are append-only

A recorded point cannot be edited or deleted — only followed by another one. That is what makes the production history trustworthy, and it has three practical consequences:

• Get the timestamp right. latestProgress returns the most recent point of an operation, and a point that was recorded with the wrong time cannot be moved afterwards.
• Mark test data. While you are building an integration, put something recognisable in the free-text status field, so a later reader can tell a trial run from real production.
• Correct forward. If a wrong quantity was recorded, record the correct one afterwards rather than looking for a way to fix the old row.

What one point carries

Field	Meaning
goodCount / wasteCount	Good production and waste. The field does not say whether it is a running total or an increment — see the note below the table
phase	SETUP, RUNNING, CLEANUP, IDLE, MAINTENANCE, STOPPED
speed	Current production speed
percentComplete	Completion, if your source knows it
errorCode / errorMessage / errorSeverity	Why a machine stopped
timestamp	When this was true — defaults to server time if omitted
source	Where the number came from
status	Free text for anything your source carries that has no field

Running total or increment? The input does not define it. Choose one for your integration and keep to it. Keep in mind that latestProgress returns one single point as the operation’s current state — that only reads correctly if each point carries the total so far.

Set source honestly

JMF means a machine reported it. MANUAL means a person entered it — at a terminal, in a kiosk app, or through a MIS feedback screen.

A measured number and a typed number deserve different levels of trust, and source is how anyone reading the data can tell them apart. Do not label a MIS import as JMF because the data originally came from a machine three systems ago.

Units for print

Sheets and impressions are recorded with countUnit: CUSTOM plus a customCountUnit string:

countUnit       = "CUSTOM",
customCountUnit = "SHEETS",

Take the spelling from verticalProductionUnits rather than typing it from memory — the field is free text, so "SHEET" and "SHEETS" become two separate series to anything that groups by unit, and nothing warns you.

Addressing the right operation

Two ways, and the second is the one integrations want:

By id — operationId, when your code already holds it.

By external reference — when your source system knows its own numbers but not CoCoCo’s:

externalRef = {
  jobExternalId       = "MIS:26-04711",
  operationExternalId = "MIS:26-04711:20",
}

Resolution walks top-down (job → component → operation → item), so partial coordinates work. No lookup, no mapping table. See Mapping MIS Data onto the CoCoCo Data Model.

Batching

One request takes up to 10,000 points, and a batch is the right shape for an importer: read everything new since your last watermark, build the points, send them once, and only then advance the watermark.

A point has no deduplication key — the input carries no external id — so a point that is sent twice is stored twice, and it cannot be deleted afterwards. The answer tells you how many points were recorded and lists errors for the rest. If a call reports errors, work out which points were stored before you send anything again; never re-send a whole batch just because part of it failed.

Reading it back

• latestProgress(operationId) — the most recent state of one operation.
• queryProgressPoints(filter) — the history, filterable by operation, job or work center, for timelines and analysis.
• MicroSQL over the progress_points reporting table — for aggregates across many operations. See Build reports and export your data.

The platform also derives metrics from recorded points — good and waste production and production speed appear as time series without you creating them.

Where to go next

• Mapping MIS Data onto the CoCoCo Data Model — progress from a MIS database
• Protocols Explained: MQTT, HTTP, JMF, SQL — progress straight from a machine
• Job Is Stuck in a Status — when the numbers arrive but the job does not move