tFLOW API

tFLOW API

 

Overview

 

Getting API Credentials

To get the tFLOW API credentials, go to the user profile and click on “Show API credentials” link at the bottom of the page. You will see API key and Secret key. Both keys are required to access the tFLOW API.

Note that, when accessing tFLOW API using these credentials, all permissions of current user will be applied. It is recommended to create a dedicated user account to be used to access the API.

Authentication

tFLOW API uses a subset of OAuth2.0 authentication protocol.

First, call the “Get Access token” method by sending POST request to http://<site>/oauth/access_token, sending three parameters: grant_type (must be always client_credentials), client_id, and client_secret. The latter two parameters are the API key and Secret key, respectively, which can be shown in the user profile as described in Getting API Credentials above.

On success, the call will return an access token information like this:

{
    "access_token": "RDdhuIuHyRQKKtLQmJteNT3D0xOzqvYwib01BGLi",
    "token_type": "Bearer",
    "expires_in": 3600
}

Once received, the access token must be specified in the Authorization HTTP header when calling any other API methods, like this:

Authorization: Bearer RDdhuIuHyRQKKtLQmJteNT3D0xOzqvYwib01BGLi

Note that the expiration time of access tokens is 1 hour, so it is not desired to save it for extended period of time. On the other hand, it is not recommended to request access token too often, i.e. before every API call. Instead, use it until you get an authentication error, and then request a new token.

URI structure

When accessing tFLOW API, the URI structure should be as follows:

http://<instance>/api/v2/<entity>/<action_or_additional_params>

So, each API method has own URI. To get a description of all available API methods, browse to

http://<instance>/apidoc

For example, to create a job on tethra.local instance, one should send a POST request to URI

http://tethra.local/api/v2/job/create

To get information about a job with ID = 123, need to send a GET request to URI

http://tethra.local/api/v2/job/123

Parameter passing

Apart parameters included into the URI, each method may accept other parameters, which may be mandatory or optional. The parameters may be passed using several forms:

  1. As a query string according to the RFC 3986. This is convenient for HTTP GET methods.
  2. As JSON code in the request body, like this:
    {
       "param1": "value1",
       "param2": "value2"
    }

    This is useful for HTTP POST methods.

  3. As JSON code assigned to _json parameter:
    _json={"param1":"value1","param2":"value2"}

This works for HTTP GET and POST methods, but especially useful when an HTTP POST method requires uploading a file, thus the requiest must have multipart/form-data encoding.

String encoding

All string parameters passed to the tFLOW API must be in UTF-8 character encoding.

Date and Time encoding

All date/time values must be specified according to ISO 8601 standard, for example:

"2015-10-22T15:12:35+07"

Returning results

Data returned from tFLOW API methods are always in JSON format, except when the API method is supposing to download a file.

The actual set of attributes returned by an API method may depend on the user account permissions which is used to access the API.

Main Entities

 

Users

Each entity of type User represents a user account which is required to access the system. Access to the tFLOW system, either via UI or via API, is always performed under a user account, applying the account's permissions.

Apart obvious attributes, like email or name, each user has a set of more complex attributes:

  • Each user is owned by some client company. The ID of the owning company is stored to client_id attribute. Users owned by instance company are referred to as instance users.
  • Each user has associated list of client companies which the user is able to see. IDs of those companies are stored in visibleClientIds attribute. Note that the owning company is always included to the list.
  • Each user belongs to a particular role, and the ID of that role is stored in role_id attribute.
  • Each user has associated list of email alerts which are allowed to automatically send by the system on various events. Email alerts are described here.

Clients

Each entity of type Client represents a client company account. There is one special company account - instance owner company or simply instance company. Such a company is created when initializing a new tFLOW instance and generally cannot be changed later.

Users owned by the instance company are called instance users. Instance users have more permissions than plain users.

Products

Product is a combination of three automation scripts: * automation script used for production processing (preflight) (mandatory) * automation script used for making proofs (optional, a default automation script of corresponding type is used when not specified) * automation script used for finishing (optional, not used in some configurations)

Each order and job must have a valid reference to a product. When creating job, it by default inherits product from the containing order.

Roles

Role is basically a set of permissions. These statements are about roles: * Roles are belonging to a particular client * Each user can be assigned to one role * User can be assigned only to role which has the same owner company

tFLOW queues

tFLOW production queue is a connection between tFLOW and tBot (or Turbine). When job is sent to a production queue, the production file from last revision of the job is downloaded by tBot (or Turbine) and passed to final processing steps, such as printing or cutting.

tFLOW queues are automatically registered within the system by tBot.

This functionality is not used for No Release workflow.

WebHooks

Webhooks are used to automatically call application's code by tFLOW API when a particular event is happen, so it is implementation of a “Publish/Subscribe” paradigm. The API client application subscribes to event by specifying the event name and URL. After that, tFLOW API publishes events by calling the specified URL.

There is a full list of currently available events:

Internal event name Description
client.create New client has been created.
client.delete Client has been deleted.
client.update Client has been edited.
comment.create New comment has been created.
comment.delete Comment has been deleted.
comment.edit Comment has been edited.
job.clear_rush RUSH status has been cleared for job.
job.complete Job has been completed. (That is, moved to one of terminal states of the workflow).
job.create New job has been created.
job.delete Job has been deleted.
job.request_rush RUSH status has been requested for job.
job.undo_rush RUSH status request has been undone.
job.update Job has been edited.
order.complete All jobs within the order have been completed. (That is, moved to one of terminal states of the workflow).
order.create Order has been created.
order.delete Order has been deleted.
order.update Order has been edited.
revision.create Revision has been created.
revision.create_proof Proof has been created for revision.
revision.delete Revision has been deleted.
revision.upload_proof Proof has been uploaded for revision.
user.create User has been created.
user.delete User has been deleted.
user.update User has been edited.

Note that for jobs, additional events are generated when a transition is executed. The name of the event in this case : “job.” + transitionName, where transitionName has one of values described here.

Orders

Order acts a container for jobs. There are statements about orders:

  • Orders are always belonging to some company. Once order created, the owning company cannot be changed.
  • Most of order properties are inherited by enclosed jobs by default. However, it is possible to override inherited defaults.

Jobs

Job is the main entity in the tFLOW system. It represents a single artwork file which should be tracked, approved (or cancelled), and finally sent to production.

  • Each job belongs to an order. It is not possible to move jobs from one order to another.
  • There could be zero or more Revisions in the job.
  • Each job is assigned to one or more users. The user who initially created the job is assigned automatically.
  • Only assigned users can execute transitions on the job.

Revisions

Revision representing separate versions of an artwork files uploaded to the job. Each job may have zero or more revisions. There is a way to get list of all revisions of a job, but most usual is the last revision.

When uploading an artwork to a job, actually one of the following transitions is executed: upload_first_revision or upload_next_revision, depending on the current job state.

There is no API dedicated method “to create revision” or “to upload an artwork”. Instead, to upload an artwork, it is need to execute upload_first_revision or upload_next_revision transition on the job using the “Execute transition” API method.

Workflows

A comprehensive description of tFLOW Workflows can be found here.