Working with the Data Model — Prepress

Use Prepress to prepare customer artwork for the printing job: receive the files, connect them to the correct components, check their suitability, inspect previews and separations, and prepare the imposition and production output. Keep the original artwork, its checks and its derived files connected so everyone can identify what is ready to print.

The examples follow the brochure in the Production guide: 5,000 finished copies with a 4-page cover and a 32-page text section. The cover and text have their own artwork and specifications. This guide prepares that artwork; the Production guide explains creating the job, specifying its components, planning the route and recording press and finishing work.

Use IaC for infrastructure and provisioning. Use the API for runtime data. Define folders, storage connections, reusable workflows, workflow versions, triggers and supporting templates through your IaC stack. Use the API to work with files, artwork associations, preflight results, imposition and executions of those configured workflows.

This guide covers files, print.prepress and the relevant workflows operations. The full workflow operation list is included for discovery, with authoring, advanced-format and administrative operations clearly identified. Job creation from product templates and the production snapshot remain in Production; the reference links to their home. The Prepress API reference supplies arguments, result types and field tables.

Choose where to start

Read and change records safely

Start with create for a new record and update for changes to an existing one. Inspect each input's required fields and handling of omitted values. Upsert is an advanced option: it can require a complete record or replace collections. Where an artwork or imposition record only exposes upsert, use that documented operation and supply its existing ID when revising it.

Send each operation and its variables separately to your authenticated GraphQL API. Check top-level errors and any errors { path message } in the result. Keep the returned IDs, and read saved records before repeating a creation request after a lost response. A successful HTTP response does not by itself establish that every item in a batch succeeded.

Replace the illustrative IDs, dates, names and file sizes with your own values. The examples are individual recipes. Registering an external file and uploading a managed file are alternative ways to obtain a file record; do not create both for the same upload.

Keep a file's identity separate from its storage address and its artwork association. A file ID identifies the stored file record. An artwork association identifies that file's use on a component. A temporary download URL is neither of those identities.

Choose configured folders and storage

A folder defines a named storage location and its connection. It may use managed cloud storage, a configured storage backend or a controller. It is part of the environment you provision through IaC, rather than a new folder to create for every artwork revision.

Browse the available folders before receiving the cover PDF:

query BrowsePrepressFolders($first: Int!) {
  folders(first: $first) {
    edges { node { id name kind rootPath isDefault } }
    pageInfo { hasNextPage endCursor }
  }
}

Variables:

{
  "first": 20
}

Read kind and the configured default as well as the name. The upload recipe below requires a managed-cloud folder, identified by the CONTROL_CLOUD kind. Other bindings have their own access methods; choosing a different folder does not make it compatible with the browser-upload operation.

Use folder to read a known folder and testFolder for a read-only reachability check. That check does not prove write permission. For a managed-cloud folder it can report an unknown result, so do not interpret it as verification of the whole upload path.

The storage queries expose the configured connection and its kind. A kind-specific lookup can return null when a connection exists but has a different kind. storageCapabilities lists the connection kinds supported by the environment; testStorageBackend probes an existing connection without writing files.

Manage folder and storage definitions through IaC. A folder already referenced by files cannot simply have its binding or root path changed, and a referenced or default folder cannot be deleted. Those restrictions protect the addresses of existing files. Provider consent for Google Drive or Dropbox is an interactive connection-setup step alongside provisioning; it is not part of the artwork-processing recipe.

Receive and organise production files

A file record describes the document, its category and status, and its relationships to the job or component. It can represent customer artwork, a proof, an imposed PDF or another production document. File categories are:

ARTWORK, PREPRESS, IMPOSITION, PROOF, PRODUCTION_OUTPUT, QUALITY_REPORT, INVOICE, DELIVERY_NOTE, PURCHASE_ORDER, SUBSTRATE, OTHER

Allocate an upload

For a managed-cloud folder, request an upload address:

mutation RequestPrepressUpload($inputs: [RequestFileUploadInput!]!) {
  requestFileUploads(inputs: $inputs) {
    grants { fileId uploadUrl expiresAt }
    errors { path message }
  }
}

Variables:

{
  "inputs": [
    {
      "name": "Autumn brochure cover",
      "originalFilename": "autumn-cover-v1.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 1048576,
      "category": "ARTWORK",
      "usageRole": "ARTWORK",
      "jobId": "job_000000648h848r248h248h248h",
      "componentId": "cmp_000000448h848r248h248h248h",
      "folderId": "fld_000000848h848r248h248h248h"
    }
  ]
}

Supply the actual byte size and MIME type. The illustrative size is not a recommended size or an upload limit. Keep the returned fileId and transfer the PDF bytes to the returned uploadUrl using the upload service's required method. That transfer happens outside GraphQL; requesting an address does not upload the document. Respect the expiry time and inspect errors for each batch item.

Confirm that the upload finished

After transferring the bytes, complete the upload:

mutation CompletePrepressUpload($inputs: [CompleteFileUploadInput!]!) {
  completeFileUploads(inputs: $inputs) {
    files { id name status folderId componentId }
    errors { path message }
  }
}

Variables:

{
  "inputs": [
    {
      "fileId": "fil_000000248h848r248h248h248h"
    }
  ]
}

The operation verifies the uploaded object before marking its file ready. Do not use updateFile to force a managed upload into a ready state. If completion fails, inspect the error and the saved file status before proceeding to preflight.

File statuses are:

UPLOADING, PROCESSING, READY, FAILED, ARCHIVED

Register a file held elsewhere

createFile registers an externally stored file using its externalStorageKey and the required metadata. It does not upload the bytes into managed cloud storage. Use it only for the external storage path your environment supports. upsertFile is the advanced create-or-update form; it is not an alternative upload-completion mechanism.

Read and revise the file record

query ReadPrepressFile($id: FileID!) {
  getFile(id: $id) {
    id name originalFilename mimeType sizeBytes status category
    jobId componentId folderId usageRole parentFileId versionNumber
  }
}

Variables:

{
  "id": "fil_000000248h848r248h248h248h"
}

Use listFiles to browse or filter files, following the returned pagination cursor when there are more results. Check the job, component, category and usage role before selecting artwork merely because its filename looks right.

Use update for a metadata correction:

mutation UpdatePrepressFile($id: FileID!, $input: UpdateFileInput!) {
  updateFile(id: $id, input: $input) {
    file { id name componentId usageRole status }
    errors { path message }
  }
}

Variables:

{
  "id": "fil_000000248h848r248h248h248h",
  "input": {
    "name": "Autumn brochure cover — customer revision 1",
    "componentId": "cmp_000000448h848r248h248h248h",
    "usageRole": "ARTWORK"
  }
}

This changes the record's name and component relationship; it does not change the PDF bytes or establish that the artwork is approved. Keep revisions identifiable. parentFileId and versionNumber can describe their relationship, but changing those fields does not itself create a new document or an approval process.

Obtain a download address

mutation DownloadPrepressFile($id: FileID!) {
  fileDownloadUrl(id: $id) { url expiresAt kind }
}

Variables:

{
  "id": "fil_000000248h848r248h248h248h"
}

Inspect the grant's kind and expiry. Managed-cloud addresses may be signed and time-limited. External addresses pass through without a new platform signature or expiry guarantee, and some document endpoints still require authentication when retrieved. Obtain a fresh grant when needed rather than treating a temporary URL as the permanent artwork reference.

Connect artwork to the component

Keep the cover artwork with the cover component and the text artwork with the text component. A file's component metadata helps organise it; the component artwork association records how that file is used in the print preparation process.

Use upsertComponentArtworkFile with the componentId and a file reference. Supply fileId for a platform file or the supported externalUri for external artwork. The association also carries its usage role, description, page information and sort order. Use the returned artwork-association ID for operations such as preflight and artwork previews; they do not take the ordinary file ID.

There is no separate create/update pair for these associations. Omit the association ID when creating one and supply it when revising that association. Review the required fields in the reference instead of assuming an upsert is a partial patch. Read the result through getComponentArtworkFile or list the component's associations with listComponentArtworkFiles.

Use the prepress-operation records to describe preparation work associated with the component. These records are distinct from the press and finishing operations in Production. Removing an artwork association or a prepress-operation record is not a way to undo work already performed on a physical job.

Check artwork and inspect separations

A preview lets someone inspect the document. Preflight checks it against a selected profile. Neither should be confused with customer approval or a complete decision that the job is ready to manufacture.

Run a saved preflight check

Call runPreflight with the component artwork association's artworkFileId and the intended profile. It reads that artwork and saves a preflight report. Read the returned report and errors; use getPreflightReport or listPreflightReports to review the saved checks later.

Available profiles are:

COMMERCIAL_OFFSET, PDF_X_1A, PDF_X_3, PDF_X_4, PDF_X_CLAIMED

Choose the profile required for your production process and inspect its findings. Do not interpret a filename containing “print-ready” as a substitute for the report. The lower-level upsertPreflightReport records supplied results; it does not ask the platform to run the checks.

For an inline check without saving a report, use preflightCheck with the supplied PDF bytes and its documented input. Inline checks and saved checks serve different purposes. If artwork changes, review the new artwork rather than relying on a report for the previous file.

Inspect the page and its inks

renderArtworkPreview produces a page preview from an artwork association. renderPreview works with supplied PDF bytes. These return image data for inspection rather than a new proof approval record.

Use renderPlateSeparation to inspect an ink separation from associated artwork, and renderSeparation for supplied PDF bytes. Review the appropriate pages and separations for the job; a composite preview alone does not show every production concern.

Read production instructions in the artwork

extractProduction reads production-step information from supplied PDF bytes without saving it. extractProductionOperations reads associated artwork and can optionally persist the derived operations. Inspect the extracted instructions against the agreed component specification before choosing to save them. Extraction does not replace planning the production route.

Prepare imposition and production output

Imposition arranges the component's pages into sheet layouts and signatures. Begin with the component's agreed finished dimensions, bleed, pagination, quantity and paper choices. The Production guide explains setting those specifications through component create/update operations.

Explore and save the layout

Use previewImposition to explore a proposed layout without creating records, including before there is a component. listFoldPatterns exposes the available patterns.

For a component that already exists, calculateImposition reads its specification and saves imposition records. Review the supplied options, particularly any choice to replace existing results, before recalculating a layout that people are already using. Read the saved records with getImpositionSpec or listImpositionSpecs.

upsertImpositionSpec records an explicitly supplied specification; it is different from asking the platform to calculate the layout. This advanced route needs the intended complete input. Use it only when you are deliberately managing those details.

Inspect the layout and finishing requirements

Use renderImpositionSVG to inspect a saved specification or supplied layout. consolidateImpositionFinishing derives the finishing view from that layout without saving changes. Review the folding, cutting and other relevant finishing requirements against the route planned for the job.

Create imposed output

imposePdfInline composes source PDF pages using an already calculated signature plan. It returns PDF bytes without saving a file or calculating new geometry. It does not repeat the forms into the full job quantity. Store the resulting document through the appropriate file process if it needs to be retained, and identify its relationship to the artwork and imposition used to create it.

Recheck the layout and production quantities when pagination, finished size, paper or artwork changes. Finished brochures, signatures, press sheets and impressions are different count bases. Hand the agreed imposition and output back to Production for routing, scheduling and execution.

Run configured prepress workflows

A workflow can connect steps such as receiving artwork, checking a PDF, creating a preview and reporting the result. Provision its definition, versions and triggers through IaC. A workflow execution is one run of that configured automation for particular input data.

Select the configured workflow

query ReadPrepressWorkflow($id: WorkflowID!) {
  getWorkflow(id: $id) {
    id name description isActive currentVersionId
  }
}

Variables:

{
  "id": "wfl_000000a48h848r248h248h248h"
}

Use listWorkflows when finding the configured workflow. Read its active state and current version, and inspect the version's input contract with getWorkflowVersion before starting it. Read the configured triggers if you need to understand whether uploading artwork will already start a run; do not add an extra manual run unintentionally.

Start a run with the expected input

mutation RunPrepressWorkflow($input: ExecuteWorkflowInput!) {
  executeWorkflow(input: $input) {
    execution { id workflowId versionId status }
    errors { path message }
  }
}

Variables:

{
  "input": {
    "workflowId": "wfl_000000a48h848r248h248h248h",
    "input": "{\"fileId\":\"fil_000000248h848r248h248h248h\",\"componentId\":\"cmp_000000448h848r248h248h248h\"}"
  }
}

This recipe assumes a workflow provisioned to accept an object containing fileId and componentId. Those names are an example contract, not built-in inputs for every workflow. Adapt them to the deployed workflow's input schema. The GraphQL input field contains a JSON string, so the inner object is encoded inside that string.

Omitting versionId selects the workflow's configured current version. Use an explicit version only when you intend to run that version. Keep the returned execution ID; starting a workflow is not a promise that all its steps completed, and repeating the request can start another run.

Follow the run and inspect the results

query ReadPrepressExecution($id: WorkflowExecutionID!) {
  getExecution(id: $id) {
    id workflowId versionId status cancellationRequested
    startedAt completedAt output waitingNodeId
    steps { nodeId nodeName status output error }
  }
}

Variables:

{
  "id": "wfx_000000c48h848r248h248h248h"
}

Execution statuses are:

PENDING, RUNNING, COMPLETED, FAILED, WAITING, CANCELLED

Read the execution's status and step results together. A completed workflow means its configured steps completed; inspect the preflight findings or other output before deciding whether the artwork is acceptable. A workflow can successfully report that a PDF has problems.

Use getExecutionSteps for step detail and listExecutions for previous runs. listExecutionLogs and executionLogStream provide log history and live updates for a selected context, subject to their permissions. Avoid copying sensitive document data from logs into unrelated notes or records.

cancelExecution requests cancellation. resumeWorkflowExecution is for a run waiting for an external signal, not a general retry of any failed run. Read the current state and the workflow's expected next action first. Administrative recovery operations are listed separately; they require stronger checks and are not part of an ordinary artwork retry.

Progress-point operations record or read production progress associated with automation. They are not proof approval records. The production-wide snapshot belongs in the Production guide.

Manage reusable automation through IaC

IaC is the authoring surface for workflows. Define the workflow, its version and triggers in your stack, review the proposed changes, and apply them through your normal IaC process. The workflow and template resources exposed by the schema describe what can be provisioned. Keep environment-specific configuration in that stack and runtime artwork IDs in each execution's input.

Use the same approach for supporting reusable text templates. These templates can produce text from runtime context; they are different from the product templates that create printing jobs. renderTemplate uses an already configured text template with supplied data.

XML is an underlying workflow engine format. Source inspection, format validation, import and export operations appear in the reference for advanced tooling and compatibility, but this guide does not teach editing or submitting XML as the normal way to author automation. Those format details do not change the IaC ownership of reusable definitions.

Changing an active version, enabling a trigger or publishing a reusable template changes shared automation. Treat those as IaC changes rather than steps to repeat for each brochure. Reading a definition and starting an execution remain runtime activities.

The reference distinguishes IaC authoring, advanced-format inspection and administrative recovery. Interactive storage-provider consent is labelled setup. These labels make the complete operation list discoverable without turning it into a checklist of actions required for prepress.

Read configured paper and print settings

Read substrates to select suitable paper for the component and imposition. getSubstrate, getSubstrateBy and listSubstrates expose those choices. Substrate template lines describe configured paper choices associated with product templates.

Provision substrate definitions and template lines through IaC. Selecting existing paper for this job is runtime work; changing the shared catalogue affects later jobs too. Creating a job from a published product template is covered in Production.

Paper-weight and imposing settings are shared print configuration. Their update operations appear for completeness and are marked administrative. They are not steps for preparing each individual PDF.

Discover the API and get help

Use the shared discovery operations to inspect supported fields, find related tools and read help. The generated reference accounts for all operations in this guide's topics, including the explicitly linked operations covered in Production.

Retrieve examples with topicExamples(names: [...]), using names such as prepress.request-upload, prepress.complete-upload and prepress.run-workflow. Use each operation with its variables, substituting actual record IDs and the input contract of the selected workflow.