Working with the Data Model — Production

Use Production to turn a customer's order into a printing job: describe what must be made, prepare the artwork, plan the press and finishing work, and record what actually happened on the shop floor. The job brings those records together so you can follow the work from specification to completion.

Use IaC for infrastructure and provisioning. Use the API for runtime data. Provision work centres, production cells, capabilities, shifts, device assignments, substrate catalogues and reusable templates through IaC. Use the API to work with jobs, components, artwork, production steps, schedules, tasks and production reports.

This guide covers production work in jobs and the full productTemplates topic, with template definition and publication routed to IaC. Artwork preparation, imposition and related print.prepress operations are covered in the Prepress guide; the reference links to their new home. JMF device connectivity belongs to the separate print.jmf topic. The Production API reference lists the arguments, result types, input fields and enums; the sections here explain how they fit into a printing job.

Choose where to start

Read and change records safely

A query reads information. A mutation usually changes it; some production mutations calculate or preview a result. Check the operation's purpose before calling it. Send the operation and variables separately to your environment's GraphQL API using an authenticated account. Permissions still apply to related records selected inside a result.

The examples follow a brochure order for 5,000 finished copies, with a 4-page cover and a 32-page text section, finished to A4 and saddle stitched. They are recipes, not a complete production plan. The actual sheet layout, paper, press, spoilage allowance and finishing route must be agreed for your job. Replace the illustrative identifiers and dates with your own records. Keep each returned ID for later requests.

Check top-level GraphQL errors and any errors { path message } inside a result. Continue only when the expected record is present and errors are empty. A successful HTTP response alone does not confirm that work was saved. If a response is lost, read the job before repeating a creation request.

Start with create… for a new record and update… for changes to an existing record. These are the recommended operations for everyday work: the request makes your intention clear, and an update lets you supply the fields you want to change. Check each input’s treatment of omitted fields, nulls and nested values.

Treat upsert… as an advanced option. Use it when you deliberately need its create-or-update behaviour and understand how it identifies records, which fields it requires and whether it replaces child collections. It is not a general shortcut for a partial update or a promise to match an external reference.

Some resources expose only an upsert operation. Where that is the available route, this guide explains how to use it; do not invent a create or update operation that the API does not provide. A description or a name helps people recognise the work; it does not replace the structured specification needed for planning.

Start the printing job

An order records what the customer is buying. A job records the work needed to produce it. Keep both when the work comes from a sale, so production remains connected to the commercial commitment.

Bring an order into production

If the order already exists, use createJobsFromOrder. The same handover is described in the ERP guide:

mutation CreateCommerceProductionJobs($input: CreateJobsFromOrderInput!) {
  createJobsFromOrder(input: $input) {
    order { id status }
    jobs { id name }
    errors { path message }
  }
}

Variables:

{
  "input": {
    "orderId": "ord_01h455vb4pex5vsknk084sn02q",
    "jobs": [
      {
        "orderLineId": "oln_01h455vb4pex5vsknk084sn02q",
        "jobName": "Northstar packaging sleeves",
        "quantity": 500
      }
    ]
  }
}

Read the returned job IDs before adding specifications or operations. acceptEstimateAndCreateJobs is another handover when accepting an estimate is the starting point. These are alternative starting routes; do not also create a duplicate job by hand.

Open a job directly

For work that needs a job directly, create its header:

mutation CreatePrintingJob($input: CreateJobInput!) {
  createJob(input: $input) {
    job { id jobNumber name quantity status }
    errors { path message }
  }
}

Variables:

{
  "input": {
    "name": "Autumn brochure — 5,000 copies",
    "jobNumber": "PRINT-2026-1042",
    "quantity": 5000,
    "status": "DRAFT",
    "description": "A4 brochure: 4-page cover and 32-page text, saddle stitched. Print specification and routing to be confirmed.",
    "dueAt": "2026-11-06T16:00:00Z"
  }
}

quantity is the finished job quantity: 5,000 brochures in this example. It is not automatically the number of press sheets, impressions or signatures. Keep jobNumber as the recognisable production reference and use the returned id for relationships.

Job statuses available in the API are:

DRAFT, RFQ, CONFIRMED, PREPRESS, PRESS, POSTPRESS, PACKING, SHIPPED, COMPLETED, WAITING, CANCELLED, EXCEPTION

A job's overall status and an individual operation's execution status answer different questions. Do not treat changing the job status as a substitute for recording press or finishing progress.

Use a job group when several jobs need to be considered together. Removing a job from a group is different from deleting it. In particular, destroyJobGroupAndJobs deletes the jobs as well as the group; it is not a routine way to close completed work.

For repeat products, find a configured product template and inspect its published version before creating the job.

Find product templates and published versions

A product template describes a repeatable product, such as a brochure with a cover and text section. Use a configured template when you want a new printing job to start from that agreed structure. The template is reusable configuration; the job created from it is a particular piece of production work.

Define, change and publish product templates through IaC. The steps here read configured templates and their published versions. If the product you need is missing, or its structure needs changing, update the IaC configuration before using it for production.

Browse the configured templates

Start with active templates:

query BrowsePrintingTemplates($first: Int!, $after: String) {
  listProductTemplates(isActive: true, first: $first, after: $after) {
    edges {
      node { id name sku category isActive status version publishedVersion }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables:

{
  "first": 20
}

Check the name, SKU, category and publishedVersion before choosing a template. The query can also filter by exact SKU or category. Continue with endCursor as after while hasNextPage is true, keeping the filters unchanged.

The available status values are DRAFT, PUBLISHED. Status and published version answer different questions. A template can be DRAFT because someone has changed its definition while an earlier version remains published. Filtering only for PUBLISHED would hide that template. This example therefore browses active templates and asks for both fields.

A null publishedVersion means there is no published version to use. Do not treat an active flag or a familiar SKU as proof that a template is ready for job creation.

Read the selected template

Keep the selected template ID:

query ReadPrintingTemplate($id: ProductTemplateID!) {
  getProductTemplate(id: $id) {
    id name description sku category tags isActive status version publishedVersion
  }
}

Variables:

{
  "id": "ptl_00000000008008000000000281"
}

The returned version is the current definition's version. publishedVersion identifies the most recently published snapshot. For example, version 4 may be a draft while published version 3 remains the production starting point.

Read the published snapshot when checking what will be used. The current template record may contain changes that have not yet been published.

Browse the published versions

query BrowsePrintingTemplateVersions($templateId: ProductTemplateID!, $first: Int!, $after: String) {
  listProductTemplateVersions(templateId: $templateId, first: $first, after: $after) {
    edges { node { id productTemplateId version publishedBy createdAt } }
    pageInfo { hasNextPage endCursor }
  }
}

Variables:

{
  "templateId": "ptl_00000000008008000000000281",
  "first": 20
}

This query lists published versions, newest first. It does not list every draft edit. Each entry has a version number, publication time and publisher, when recorded. Follow the pagination cursor to inspect older publications.

Keep the parent template ID and version number together. A version record also has its own id, but the single-version lookup below takes templateId and an integer version.

Inspect a published snapshot

Use the version number returned by publishedVersion to inspect the current published definition, or a version from the history to review an earlier publication:

query ReadPrintingTemplateVersion($templateId: ProductTemplateID!, $version: Int!) {
  getProductTemplateVersion(templateId: $templateId, version: $version) {
    id productTemplateId version publishedBy createdAt
    snapshot { name description sku category tags isActive }
  }
}

Variables:

{
  "templateId": "ptl_00000000008008000000000281",
  "version": 3
}

Version 3 is illustrative; replace it with the version you intend to inspect. The snapshot preserves the definition at publication time, so its name, SKU and active flag can differ from the current template record. A missing result means that this template/version pair did not resolve; check both values before continuing.

For a fuller print specification, the snapshot also exposes components, operations, configSchema and print settings. Request those fields when checking the parts, production steps and configuration choices for the job. Their field shapes are listed in the Production API reference.

Create the printing job from the published template

Use instantiateProductTemplate once the template and the customer's requirements agree. Supply the template ID and the job's configuration as described in the reference. Its configuration choices depend on the published template; there is no single set of options that suits every product.

Instantiation uses the template's current publishedVersion. The operation does not accept a version number to pin. Reading an older snapshot does not select it for job creation, and another publication between inspection and creation can change which version is used.

Read the returned templateVersion, job, components, operationCount and errors before continuing. Keep the job ID and confirm the result against the order. This is an alternative to creating the same job manually; do not run both paths for the same piece of work.

The operation list includes definition and publication methods for discoverability. Those writes remain IaC work, as does installing a canonical template. Creating an individual job from a published template is runtime work.

Describe the parts to produce

A component is a part of the finished product with its own production requirements. For the brochure, use one component for the cover and another for the text section. An insert would be a further component. Components can have different paper, colours, artwork and production routes while belonging to the same job.

Add the cover component

mutation AddPrintingCover($input: CreateComponentInput!) {
  createComponent(input: $input) {
    component { id jobId name kind quantity }
    errors { path message }
  }
}

Variables:

{
  "input": {
    "jobId": "job_0h248h248h848r248h248h248h",
    "componentNumber": "COVER",
    "name": "4-page cover",
    "kind": "COVER",
    "quantity": 5000,
    "description": "Cover component for the autumn brochure. Add the print specification before planning."
  }
}

Create the text component separately with its own name and the TEXT kind. Here, each finished brochure needs one cover and one text section, so each component starts at 5,000. That does not mean each requires 5,000 press sheets: the imposition and production route determine sheet and operation quantities.

Component kinds available in the API are:

CONTENT, COVER, INSERT, MAIN, TEXT, DUST_JACKET, ENDPAPER, OUTSERT, OTHER

Complete the print specification

createComponent accepts the complete print specification when you create a part: pages, colours, layout, material, finished size, finishing and substrate choices. You can supply these fields alongside the cover details shown above.

To revise an existing part, call updateComponent with its id and only the fields you want to change. It accepts the same print specification fields as createComponent. Omitted print fields keep their current values; an explicit null clears that print field. A supplied colour, layout, material or finishing object replaces that whole field, so include the details you want to retain within it.

Advanced: upsertComponent. Prefer create/update for the steps above. If you deliberately use upsert, include the existing component id together with the required jobId, name, kind and quantity. Omitting the ID describes a new component, not an update to one you already created.

media and finishedSize are JSON inputs, not plain strings such as “A4”. Use the dimension structure accepted by your print configuration. The reference lists the structured colour, layout and finishing inputs. A component's finishing details do not replace the operation route: saddle stitching, folding and trimming still need their production steps.

A component group lets you associate related components within the job. Use it where the route works on a group of parts, rather than creating an artificial extra finished product.

Hand artwork over to Prepress

Use the Prepress guide to receive files, associate artwork with a component, check preflight results, inspect separations and prepare imposition. It also explains running configured prepress workflows; define and deploy those workflows through IaC.

Before planning the press run, confirm that the artwork and saved imposition match the component specification. Use their resulting production requirements to review the route, quantities and finishing steps below. A file preview alone does not establish that the job is ready to print.

Plan the production steps

An operation describes a step of production. For the brochure, the route may include platemaking, cover printing, text printing, folding, saddle stitching, trimming and packing. The appropriate steps depend on the specification and the equipment used.

Associate a step with its component when it acts on that part. A finishing operation that combines the cover and text may need job or component-group context. Use dependency links to express what must happen first; a list's display order is not a substitute for those dependencies.

Add a press operation

mutation AddPrintingPressOperation($input: CreateOperationInput!) {
  createOperation(input: $input) {
    operation { id jobId componentId name kind status productionQuantity }
    errors { path message }
  }
}

Variables:

{
  "input": {
    "jobId": "job_0h248h248h848r248h248h248h",
    "componentId": "cmp_1248h248h288h848h248h248h2",
    "name": "Print brochure covers",
    "kind": "PRINTING",
    "status": "PENDING",
    "requestedWorkCenterId": "wcr_248h248h248h288h248h248h24"
  }
}

The work centre ID must refer to an already configured press. requestedWorkCenterId expresses the requested resource; it does not reserve a time slot. Select a suitable capability where needed, and use getOperationParameterSchema to discover the parameters for the operation kind.

This example deliberately leaves productionQuantity unset. Determine it from the agreed imposition, count basis and allowances before scheduling the actual run. Finished brochures, press sheets and impressions are different quantities.

Connect the route and its work items

inferOperations suggests the required production steps from either an existing component or a supplied specification. Review the result before relying on it as the route. Use listOperationEdges to inspect dependencies, and createOperationEdge or updateOperationEdge for individual links. For an advanced whole-graph change, upsertOperationGraph replaces the job's dependency edges and work centre preferences together, so supply the intended complete graph.

Operation items break a step into smaller pieces of work, such as separate batches or passes. Their links express dependencies at that finer level. Start with createOperationItem and updateOperationItem for individual items, and createOperationItemEdge and updateOperationItemEdge for individual links. Use the following bulk upserts only when you intend to replace the selected collection. upsertOperationItemEdges replaces the edges within the supplied job and optional source/target operation scope; inspect that scope before replacing links. upsertOperationItems replaces all existing items for the operation; use the individual create or update operations for a smaller change.

Production plans hold planned work. Start with createProductionPlan for a new plan and updateProductionPlan for revisions. Review the replacement rules for any child collections you supply, even in an update. The advanced upsertProductionPlan operation replaces its child records rather than appending to them. updatePlannedOperationQuantities adjusts quantities while retaining planned operation identities, allocations and durations; review the timing separately if the new quantities change how long the work will take.

Schedule the work

A schedule scenario is a proposed or published arrangement of work. An allocation puts an operation on a work centre between a start and end time. The route describes what needs to happen; the schedule describes when and where it is expected to happen.

Prepare a draft scenario

mutation CreatePrintingSchedule($input: CreateScheduleScenarioInput!) {
  createScheduleScenario(input: $input) {
    scheduleScenario { id name status planningHorizonStart planningHorizonEnd }
    errors { path message }
  }
}

Variables:

{
  "input": {
    "name": "Brochure production — proposed week 45",
    "status": "DRAFT",
    "planningHorizonStart": "2026-11-02T06:00:00Z",
    "planningHorizonEnd": "2026-11-07T18:00:00Z"
  }
}

Schedule statuses available in the API are:

DRAFT, PUBLISHED, ARCHIVED, SIMULATION

A draft is useful for planning before committing to the production schedule. Keep the scenario's scope, planning horizon and any production cell consistent with the work you are arranging.

Allocate the cover press run

mutation AllocatePrintingPress($input: CreateScheduleAllocationInput!) {
  createScheduleAllocation(input: $input) {
    scheduleAllocation { id scheduleScenarioId operationId workCenterId startAt endAt }
    errors { path message }
  }
}

Variables:

{
  "input": {
    "scheduleScenarioId": "sch_2nanananan8naranananananan",
    "workCenterId": "wcr_248h248h248h288h248h248h24",
    "operationId": "opr_1k6csk6csk8csr6csk6csk6csk",
    "startAt": "2026-11-03T08:00:00Z",
    "endAt": "2026-11-03T10:00:00Z"
  }
}

Use the IDs returned for your scenario and press operation, and the configured press ID. The example's two-hour slot is illustrative; it does not calculate production time from the brochure quantity. Review setup, running time, cleanup, shifts, dependencies and other allocations before publishing the schedule.

Use scenario locking and allocation locking deliberately: they apply at different levels. Read the current scenario and allocations before changing a published plan.

Compare alternatives and follow the day

simulateScheduleScenario runs a forecast for a scenario. Follow it through scenarioSimulationRun, scenarioSimulationRuns and scenarioSimulationProgress; cancel it with cancelScenarioSimulation when necessary. simulateWorkload explores a workload without saving changes.

startScheduleOptimization starts a search for a schedule against the supplied objectives. Read the run with getOptimizationRun or listOptimizationRuns, follow scheduleOptimizationProgress, and use cancelScheduleOptimization to stop it. A forecast or optimisation result needs review before it becomes your operating plan.

Work centre behaviour profiles describe expected production behaviour. The twin queries expose a work centre's represented state, events and projections. Use these to compare expectations with recorded progress; a forecast is not a production report. Configuration of the work centre and its twin remains an IaC concern.

For the current day, productionDay brings together status history, the published plan and shifts for up to 100 active work centres in a cell, over a window of at most 36 hours. productionSnapshot provides a broader current view. Keep date-time offsets explicit when planning across shifts.

Record progress on the shop floor

The plan describes what should happen. Production reports record what did happen: the operation, work centre, time, count and any material consumption. Preserve the count unit and meaning so the figures can be interpreted correctly later.

Record a press run

mutation RecordPrintingPressRun($input: CreateProductionReportInput!) {
  createProductionReport(input: $input) {
    productionReport { id operationId goodCount totalPlanned countUnit runKind }
    errors { path message }
  }
}

Variables:

{
  "input": {
    "name": "Cover press run — first report",
    "jobId": "job_0h248h248h848r248h248h248h",
    "componentId": "cmp_1248h248h288h848h248h248h2",
    "operationId": "opr_1k6csk6csk8csr6csk6csk6csk",
    "workCenterId": "wcr_248h248h248h288h248h248h24",
    "startedAt": "2026-11-03T08:00:00Z",
    "endedAt": "2026-11-03T09:30:00Z",
    "goodCount": 2500,
    "totalPlanned": 2500,
    "countUnit": "COUNT",
    "runKind": "PRODUCTION",
    "actualPrintingDurationSeconds": 3600
  }
}

This report illustrates 2,500 good press sheets against a plan of 2,500 sheets, using COUNT as the counting unit. It assumes that sheet quantity was established for this operation; it is not a calculation of the sheets needed for 5,000 brochures. The report covers 90 elapsed minutes, with 60 minutes recorded as actual printing time. These are deliberately separate measures.

Use consumption when reporting material use as part of the production report. Keep material use and warehouse movements consistent with your process; recording a count is not a substitute for issuing stock. Avoid submitting a second report simply because the first response was lost: read the saved reports first.

Track execution and completion

Use transitionOperation to request an execution status change, and inspect any returned errors. The current state and execution rules determine whether the transition is allowed. transitionOperationItem addresses an individual item. Operation statuses are:

PENDING, AVAILABLE, SETUP, RUNNING, CLEANUP, COMPLETED, FAILED, STOPPED, CANCELLED, RESTARTING

Work centre status events describe the equipment's state and history. Use recordWorkCenterStatusEvent to record an event and correctWorkCenterStatusEvent to correct a previous one. These events are different from a job's overall status or a report of good production.

After completion, read the recorded completion summary:

query ReadPrintingCompletion($operationId: OperationID!) {
  getOperationCompletionByOperation(operationId: $operationId) {
    id operationId startedAt completedAt actualDurationMinutes
    goodCount wasteCount totalPlanned countUnit
  }
}

Variables:

{
  "operationId": "opr_1k6csk6csk8csr6csk6csk6csk"
}

A missing completion result is not a zero quantity or zero duration. Check the operation and its reports before treating the job as reconciled. The summary keeps good count, waste, planned count and unit together.

Use statusEvents to receive production changes, then read the relevant records when you need their current detail.

Coordinate people and milestones

Use a task for work a person needs to carry out, such as reviewing the cover proof or investigating a press stoppage. Read assigned work with myTasks, take responsibility with claimTask, and use task transitions to record progress. getTaskEvents supplies the task history.

A milestone marks an important point in the job, such as artwork approved, printing complete or ready for dispatch. Give it due dates and associate it with the job or a component. Starting, completing and cancelling are distinct actions; the corresponding undo operations correct those actions when appropriate.

A task, a milestone and a production operation are separate records. Completing an approval task does not by itself report press output or prove that every finishing operation is complete.

Review production and costs

Read the job as a whole

query ReadPrintingJob($id: JobID!) {
  getJob(id: $id) {
    id jobNumber name quantity status dueAt
    components { id name kind quantity }
    operations { id name kind status componentId }
    milestones { id name dueAt completedAt }
  }
}

Variables:

{
  "id": "job_0h248h248h848r248h248h248h"
}

Review the components, operations and milestones together. The job may have reached the press while a later finishing step is still pending. productionBoard provides a wider view of active jobs with order context.

Use evaluateProducibility and producibilityIntelligence to assess production choices and constraints. previewPlannedOperationAudit previews an audit without saving changes; auditProduction and auditProductionEnriched support a broader review against the plan.

issueStockToProduction issues warehouse material, creates transfers and reduces stock quantities. Coordinate it with the warehouse process so the same material is not issued twice. Material receipts, purchasing and customer invoicing are covered in the Warehousing and Logistics and ERP guides.

Compare the job's costs

For entering and correcting actual costs, follow the ERP guide.

query ReviewPrintingCosts($jobId: JobID!) {
  jobCostingSummary(jobId: $jobId) {
    job { id name }
    totalMaterialCost totalOperationCost totalCost
    recordedCostsAvailable totalRecordedCost recordedCostCurrency
    sellingPrice sellingPriceCurrency recordedCostMargin
    errors { path message }
  }
}

Variables:

{
  "jobId": "job_0h248h248h848r248h248h248h"
}

Distinguish the summary's material and operation cost figures from its recorded cost totals. Check recordedCostsAvailable and the associated currency fields before interpreting a margin. A missing recorded total does not mean production was free. Do not combine amounts in different currencies as though they were one total.

Before treating the printing job as complete, reconcile required operations, production counts, material use and outstanding milestones. Packing and dispatch remain real steps in delivering the customer's order; completion of one press run does not establish fulfilment of the sale.

Read the configured production resources

A work centre is a resource that can perform work, such as a press or finishing station. A production cell groups work centres. Capabilities describe what they can do, and shifts describe availability. Device assignments connect configured equipment to the production resource.

Read these records to choose suitable resources for the job. Manage their definitions and relationships through IaC. Read the configured paper choices and their provisioning guidance in the Prepress guide. Selecting an existing paper for a component remains runtime work.

installCanonicalTemplate installs a reusable product template and belongs with provisioning. instantiateProductTemplate, described earlier, creates a particular printing job from a published template.

Shared paper-weight and imposing settings are covered in Prepress as administrative configuration.

Keep instructions with the work

Use entity notes to keep instructions and decisions with the appropriate record. Link production instructions to the relevant job or component rather than relying on a detached message. Keep structured quantities, dates and statuses in their fields; a note should explain them, not replace them.

At the commercial handover, a note on the source order can record an instruction that production needs to see. This shared example uses an order target:

mutation AddCommerceOrderNote($input: CreateEntityNoteInput!) {
  createEntityNote(input: $input) {
    entityNote { id targetId body version }
    errors { path message }
  }
}

Variables:

{
  "input": {
    "targetId": "ord_01h455vb4pex5vsknk084sn02q",
    "body": "Customer requested delivery after 10:00. Confirm the delivery appointment before dispatch."
  }
}

Use the target type and ID appropriate to the record you are annotating. Read existing notes and their versions before updating them. reindexEntityNotes supports note search maintenance; it is not required for each new instruction.

Discover the API and get help

The shared discovery operations expose schema information, available tools and help. Use them to find the precise inputs and capabilities available in your environment. They support working with Production; they do not create a printing route on their own.

The examples in this guide are also available through topicExamples(names: [...]), using names such as production.create-job, production.add-cover and production.record-press-run. The returned operation and variables belong together. Replace the illustrative IDs before using them for your own job.