# Job API

Introduction
Core Concepts

# Introduction

The Job is the core of Zaikio and the production part of the Zaikio Platform. Without a Job, no planning or manufacturing can be done - after all, what would there be to plan or manufacture!

Our definition of Job is simple - a unique type of item manufactured inside a print shop. A book, a business card, a flyer - the what is not important, simply that it is a kind of product that is made. Services, such as preflight of files, or colour correction, are not Jobs.

# Core Concepts

# Object graph

┌─────────────┐
│  Products   │
└─────────────┘
       │
       │  ┌─────────────┐
       │  │    Parts    │
       ├─▶│[with layout]│
       │  └─────────────┘
       │         │
       │         │   ┌─────────────┐
       │         ├──▶│  Substrate  │
       │         │   └─────────────┘
       │         │   ┌─────────────┐
       │         ├──▶│   Colors    │
       │         │   └─────────────┘
       │         │   ┌─────────────┐
       │         ├──▶│ Finishings  │
       │         │   └─────────────┘
       │         │          │
       │         │          │  ┌─────────────┐
       │         │          ├─▶│Raw Materials│
       │         │          │  └─────────────┘
       │         │          │  ┌──────────────────────┐
       │         └──────────┴─▶│  Artwork References  │
       │                       └──────────────────────┘
       │                                   │
       │         ┌──────────────────────┐  │
       │         │   Artwork Actions    │◀─┤
       │         └──────────────────────┘  │
       │         ┌──────────────────────┐  │
       │         │   Artwork Remarks    │◀─┘
       │         └──────────────────────┘
       │
       │  ┌─────────────┐
       ├─▶│ Packagings  │
       │  └─────────────┘
       │  ┌─────────────┐
       ├─▶│ Assignments │
       │  └─────────────┘
       │         │
       │         │
       │         │
       │         │  ┌─────────────┐
       │         └─▶│Zaikio/Person│
       │            └─────────────┘
       │ ┌──────────────────────┐
       └▶│   Product Actions    │
         └──────────────────────┘

# Parts

A Job is made from one or many parts. These parts represent well-known segments of a particular type of Job, such as the cover or endpaper of a Book. Each of these Parts is manufactured independently (or could be batched for more complex workflows) and ultimately assembled into the completed, finished product.

Each Part has a comprehensive layout describing in machine-readable detail the specifics of how it is printed, finished and assembled. Parts also record their colour configuration and the desired substrates for printing upon (if known).

This allows complex products - for example books with some pages printed on photo paper and some on normal stock

to be built up by providing multiple Parts. Each of these then has its own production lifecycle, fully trackable through Zaikio, feeding realtime data back to all connected applications as well as the Zaikio user interface.

There is a full table of all of the kinds of Job and the available Parts they can contain available here. Compared to some platforms, this might seem inconvenient, as the Zaikio API requires and validates that the provided part-data is semantically valid for the type of Job, but it provides more valuable data for applications to act upon.

# No Templates

Zaikio has a very simple design decision - we do not store, attempt to store or handle any concept of templating. Each Job is a unique, discrete piece of data that is free to exist by itself. We absolutely can envision people creating Apps to handle simple Job creation from predefined templates, and the Job API makes that simple to achieve, but we aren't best placed to decide how that should work for each print shop.

It's simplest for each Job to be created discretely, either through the easy interface batch creation endpoint, or with the more granular endpoints to provision each component of data separately.

# State

Jobs have a state, representing their readiness for print and acting as a guide for applications within the Zaikio ecosystem to decide when to act upon them.

We recommend that a Job is left in draft state until as late as possible. It is entirely conceivable that a job might be part of a confirmed Order but still draft from a printing point of view as details such as substrate or scheduling might not be locked. Once it is ready for production, it can be transitioned into pending state.

The full list of states, in sequence, is:

Name	Description
`draft`	not yet produceable
`pending`	ready for production
`prepress`	in prepress
`press`	in press
`postpress`	in postpress
`packaging`	in packaging
`completed`	production of job done
`canceled`	the production of this job was canceled

# Transitioning to a new state

You can transition a Job to a new state by making an explicit call to create a JobStateTransition.

POST /jobs/:id/state_transitions

The payload required is as follows

{
  "state": {
    "next_state": "prepress"
  }
}

This will return a payload showing the transition.

{
  "previous_state": "draft",
  "next_state": "pending",
  "triggered_by": "Organization/9573196a-ccc4-43a7-9c74-6699e5bd122c",
  "user_id": null,
  "created_at": "2023-01-11T13:44:03.349Z",
  "updated_at": "2023-01-11T13:44:03.349Z"
}

We fire events describing the current status of a Job and the transitions it goes through to make it simpler for applications to decide when to act.

Name	Fired by
`job_added`	fired whenever a new `Job` is added to Zaikio
`job_changed`	fired whenever a `Job` is amended
`job_state_is_now_pending`	fired whenever a `Job` enters `pending` state
`job_state_is_now_prepress`	fired whenever a `Job` enters `prepress` state
`job_state_is_now_press`	fired whenever a `Job` enters `press` state
`job_state_is_now_postpress`	fired whenever a `Job` enters `postpress` state
`job_state_is_now_packaging`	fired whenever a `Job` enters `packaging` state
`job_state_is_now_completed`	fired whenever a `Job` enters `completed` state
`job_state_is_now_canceled`	fired whenever a `Job` enters `canceled` state
`job_ready_for_produciton`	fired when a `Job` leaves `draft` status for any state other than `completed` or `canceled`

# Sample Payload

{
  "id": "17670184-b15c-4e83-a513-d5879f75f2cb",
  "timestamp": "2020-06-03T15:02:30.359Z",
  "name": "zaikio.job_added",
  "version": "1",
  "payload": {
    "meta": {
      "origin": {
        "triggered_by": null
      }
    },
    "job_id": "47670184-b15c-4e83-a513-d5879f75f2cb"
  },
  "link": "https://mc.sandbox.zaikio.com/api/v1/jobs/47670184-b15c-4e83-a513-d5879f75f2cb",
  "received_at": "2020-06-04T15:02:30.364Z",
  "subject": "Org/383663bc-149a-5b76-b50d-ee039046c12e"
}

# No Co-ordination

An important concept to understand is that Zaikio does not provide co-ordination of when connected applications should act upon a Job. The weakness of co-ordination engines is that they must be configured based on the requirements of each user. Zaikio exists to be a universally appropriate solution, and our approach here is to pass the burden of decision making onto the applications themselves about whether they should act.

This might end up with connected applications doing work just in case it is required, however that's a small price to pay for dramatically simpler, configuration-less operation for printers. Complicated workflows might require additional, external co-ordination which we would recommend as an excellent opportunity for partners to build apps to provide.

# How does this work in practice?

Each connected application should subscribe to at least the job_added and job_changed events. Whenever a Job is added or changed, the application will receive a webhook informing them of the change, and enabling them to load the current state of that Job through the Job API. The entirety of Job specification is available through the API giving access to all of the data that might be needed to decide whether to act.

Depending on the kind of connected application, attributes of the Job can be used to decide whether the Job is of interest.

# Suggested checks

checking the job.state to see if the current state of the job is semantic for the application - e.g. an estimation app probably is not interested in jobs during their prepress, press or postpress phases, but might be interested in a completed Job to see how the estimate mapped to production reality.
checking there are any FileReferences if files are needed for the applications actions
checking job.parts has been provided with any information yet

Additionally, as a courtesy, if an application triggered a change in a Job, we provide a meta object as part of the event payload field, which contains the application which triggered the change. This means that you can potentially ignore updates which stem from your own write requests. Checking payload.meta.origin.triggered_by will provide this information for you.

# Substrates, Finishings & More

# Colours

Each Part specifies the colours required to produce it. When we talk about colours, we have a two-step approach to identifying them: the colour system (CMYK, Pantone, HKS) and the colour name inside that system. We also can provide a print standard for reference.

Each colour is attached to either the front or back of a page and a coverage can be supplied to allow cost calculation and production optimisation. An example payload is below.

The order of colours within the list is important. Colours are intended to be applied in sequence through the array, so the first declarations should be applied closest to the substrate.

{
  "colors": [
    {
      "name": "Black",
      "system": "CMYK",
      "coverage": 0.9,
      "surface": "front"
    },
    {
      "name": "Black",
      "system": "CMYK",
      "coverage": 0.1,
      "surface": "back"
    }
  ]
}

# Substrates

The desired substrate for a Job to be printed upon can be specified as part of the Job's specification. We have taken the decision to only record the desire here as the reality might change due to properties of the Job (a customer's preference would not work upon a given substrate) or production (a substrate might be unavailable within the production deadline) or for other reasons. This could be left blank if there is no preference expressed for a given Job, in which case either an estimation application or production planning application should make a best-guess of what to use given the context.

We would recommend investigating Zaikio Procurement (opens new window) for a simple, effective way to access and purchase substrates and more from a wide range of industry suppliers. The consumer documentation (opens new window) is a good place to start!

# Data Model

{
  "unique_material_identifier": null,
  "category": "coated",
  "coating": [true, false],
  "grain": "short",
  "paper_weight": 200,
  "paper_weight_unit": "gsm",
}

# Finishings

We have an extensive list of available finishings, which can be expressed as part of the Part definition, and placed on the Part through its Layout (documentation).

If there are finishings missing from the list, please contact your partner manager (opens new window) to setup a discussion with our product team, and we will aim to assist.

name
Comb Binding
Embossing
Engraving
Foil Stamping
Gluing
Head Band
Hole
Lamination
Perfect Binding
Perforation
Ring Binding
Saddle Stitching
Spiral Binding
Strip Binding
Thread Sewing

# Job vs Production

An important distinction within Zaikio is that Job data is distinct from production data about how a Job should be produced. Please see the Production API for further information on production.

This differentiation acknowledges that for the majority of Jobs there are many different ways to produce the product, which may require many different approaches. Separating the data away from the Job allows planning or replanning not to affect the core data describing the Job itself.

Our interest whilst specifying the Job is to understand the product by itself, without any details about its production, unless such details are required to ensure a certain outcome. For example you do not need to select a substrate, but need to provide boundaries in which the production process might be allowed to select the substrate at a later time. Another example would be content sections with many folded pages. For Zaikio it is unimportant how and even if those pages are folded when looking at the product specification in the beginning. These decisions are up to the connected apps that generate the production information later on. However if a certain fold is required to ensure the product is made in the right way, say for a zig-zag folded flyer, then that information needs to be provided in the specification (here in the Part's layout) as well.

# Files

# Introduction

Zaikio does not store files, but allows you to attach references to Jobs to provide the data. This could point to a file stored on a local computer or storage array, DropBox, or any other service that you use to store and distribute files. We call these FileReferences.

We would always recommend that you use a secure, online storage solution to enable the full power of Zaikio. Seamless interoperability with all of the apps, such as imposing or colour correction tools, that you might wish to deploy would require those applications to be able to simply access the underlying files.

FileReferences can be attached to a Part, providing the content of what to print, or to a Finishing - providing paths or other content to describe a finishing such as foiling or lamination.

Zaikio provides a best-in-class service for storing the underlying files which integrates perfectly into Zaikio. This new product is called Zaikio Vault. Zaikio Vault provides secure, encrypted, cloud-based storage of files. We use military-grade encryption to protect data and can offer advanced levels of provenance and security for clients with specific requirements. Features such as granular access controls and full auditing are standard.

Contact your partner manager (opens new window) or sales (opens new window) for more information.

# File Actions & Remarks

Many print workflows require files to be assessed, either using automated tools or manually inspected. Zaikio offers a comprehensive model for capturing that feedback. Our Action and Remark APIs provide all of the features required to model even advanced workflows.

We would recommend that workflow apps interacting with files should create Action resources to model the operations that will take place on a FileReference. This could include tasks such as preflighting or colour-correction.

A Action has a state and progress information, allowing simple updating of the current status of progress through the Zaikio API. Potentially when complete, or if problems are found, a Remark can be created, pointing to the Action that ran, explaining what happened. This information can then be passed back to interested parties.

Data Platform

Reference

# Job API

# Introduction

# Core Concepts

# Object graph

# Parts

# No Templates

# State

# Transitioning to a new state

# Sample Payload

# No Co-ordination

# How does this work in practice?

# Suggested checks

# Substrates, Finishings & More

# Colours

# Substrates

# Data Model

# Finishings

# Job vs Production

# Files

# Introduction

# File Actions & Remarks