Introduction and concepts:
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:
-
As a query string according to the
RFC 3986. This is convenient for HTTP
GET
methods.
-
As JSON code in the request body, like this:
{
"param1": "value1",
"param2": "value2"
}
This is useful for HTTP POST
methods.
-
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.