# Shop floor API

Introduction
Status
Core Concepts

# Introduction

The Shop floor API covers the practicalities of day-to-day operations on the floor of a print shop.

# Status

This API has reduced public availability at the moment. Contact your Partner Manager for access to pre-release features.

# Core Concepts

# Machines

A Machine represents a physical device used in the production of print jobs. This could be a printer, or a folder or any other device - automated or manual - that needs to be scheduled and planned for.

Zaikio loads this data in from Zaikio Hub - Machines API where it is configured for use across the Zaikio Platform.

# Specialists

A Specialist represent a skilled worker who performs tasks in the process of the production of print jobs.

Zaikio loads this data in from Zaikio Hub - Specialists API where it is configured for use across the Zaikio Platform.

# Production Slots

A ProductionSlot represents an allocated time period for a Machine or Specialist to work upon completing a Workstep. A ProductionSlot must always be contiguous - do not, for example, leave a slot open overnight if production should span two days but nobody will work on it overnight.

Multiple ProductionSlots might be required to complete a Workstep. These could be sequential or parallel, and it is for the production scheduler to decide the best approach here. Zaikio does not do any scheduling by itself, although the app store will have many applications to help solve these challenges.

# Executions

An Execution represents a block of time in which a Machine or a Specialist worked on a Workstep. We would expect all Executions to occur as part of a ProductionSlot, however that is not essential. There is no hard link between the two concepts, we use heuristic matching to discover the likely schedule if needed.

An execution can be created using a payload similar to the below - indicating what is being worked upon, whom is operating and the machine being used. quantity represents the processed number of iterations - e.g. sheets printed or folds performed. waste allows incrementing of discarded items. These will then be tallied against the expectations for the Workstep and relevant progress indicators updated. Read more in the docs

// POST /executions

{
  "execution": {
    "operator_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "machine_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "workstep_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "quantity": 0,
    "waste": 0,
    "started_at": "2023-01-15T11:10:40.649Z",
    "ended_at": null
  }
}

Once you have created an Execution, you should ideally update it on a regular basis so that realtime progress can be communicated. In the case of an automated machine, this should be simple, if building a tool for specialists to use then it might only be relevant to request an update each hour.

Consider how granular these updates need to be. There is little to be gained in updating the API every time a single sheet is printed, but maybe groups of 1000s, or percentage completion markers might be more meaningful.

An update is as simple as making a RESTful request to PATCH the Execution docs

// PATCH /executions/${execution_id}

{
  "execution": {
    "quantity": 100,
    "waste": 10
  }
}

Finally, once the Execution has concluded, send one more PATCH to update the ended_at attribute, signalling that no further progress will be made in this block of time. Future work can start a new Execution and progress continue to be reported there. A good scenarios for closing-and-reopening an Execution include:

changing the operator of a Machine
lunch breaks
maintenance of a machine
resupplying materials

//PATCH /executions/${execution_id}

{
  "execution": {
    "quantity": 1000,
    "waste": 14,
    "ended_at": "2023-01-15T12:00:00Z"
  }
}

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

Name	Fired by
`execution_opened`	fired whenever a new `Execution` is added (opened) to Zaikio
`execution_changed`	fired whenever a `Execution` is amended
`execution_closed`	fired whenever a `Execution` is closed
`execution_removed`	fired whenever an `Execution` is removed

Full details are available here in the API documentation.

Data Platform

Reference