Jobs API Documentation

The Documentation below provides a list of Job API endpoints and their capabilities. To view the details of each endpoint click the API endpoint to expand the documentation.

Markers and paging through data:

When polling for data across all existing jobs you will commonly receive more data that what is allowed in the current response size. In this case you will need to "page" through data by making additional API calls with a startMarker query string.

By default PrintOS Jobs sorts jobs from "oldest" to "newest" based on a marker value that was assinged to that record.  The marker of a record can be passed to the API as an anchor to get the next page of records after (or before) that marker.  When paging through the results, the marker value in the last record returned by the previous call should be used as the 'startMarker' parameter in the next request.  

To search from "newest" to "oldest" set the direction query parameter to "backward".  

 

Example response of first page (shortened to 2 records):

[{
		"jobName": "Job Name 1",
		"jobProgress": "AT_PRINT_DEVICE",
		"marker": 1532015644397207,
		"jobSubmitTime": "2018-07-19T09:51:56.005+0000",
		"deviceId": "a30cbfa0-9d0c-469c-9d0d-2937c045c17c"
	}, ...{
		"jobName": "Job Name 1000",
		"jobProgress": "RIPPING",
		"marker": 1533762019094122,
		"jobSubmitTime": "2018-08-08T14:57:50.827+0000",
		"deviceId": "a30cbfa0-9d0c-469c-9d0d-2937c045c17c"
	}
]

The following query to collect the next "page" of data would look like this:

.../jobs-sdk/{context}?startMarker=1533762019094122

The maximum number of items returned in the response can be defined by setting the limit query value. This sets the "page" size of each response.

Method for calling Jobs data:

To keep an up to date view of the current jobs in your environment the following steps are recommended for maintaining a near-real time view of the current state of jobs.

  1. Identify the data you are interested in, and make the appropriate query through the API.  If the job data you are asking for is more than can be returned in a single call (The current limit is 10000 jobs), you will need to make multiple queries.  It will be necessary to make multiple calls (effectively paging through the job data) until all of the data requested is received.
    • This will typically be a query to the base jobs endpoint .../jobs-sdk/jobs/{context} with a larger "page" size (?limit=10000) based on the number of active or recently archived jobs in your environment.  
    • When the last "page" of data is retrieved (number of records returned is less than limit size), the largest marker value should be saved for additional queries
  2. Once you have made the initial set of calls to retrieve the job data, you will need to make regular poling calls to retrieve any updates or newer job data
    • This will be the same API call with the default sorting and limit values (1000 responses sorted from most recently updated to least), but with a startMarker query value set to the previously stored marker value.  This ensures that you are only getting jobs that have been updated since your last query.
    • Regular poling update intervals should be kept relatively infrequent (~ every 1 minute).  Due to the Jobs service design you will not gain much benefit to querying more frequently and you could run into limits on call rates.
    • Based on interval time and number of jobs being processed you will typically not need more than one "page" of data to find updates, but it may be necessary to send additional calls for high volume updates.
    • Again, save off the last marker value from this query to use as the startMarker for the next query.

 

Managing response data with properties:

It is highly recommended that you provide a query string with the properties query set so that you only receive back the relevant properties for your solutions. The default property set is intentionally kept brief to keep down network traffic and API response times. The full list of properties can be obtained by querying the .../jobs-sdk/propertyspecs end point with the context that you are interested in.

A sample API query with a properties query might look like this:

.../jobs-sdk/jobs/dfe?properties=jobName,jobProgress,jobSubmitTime,jobLastEventTime,jobPriority,marker

Giving you a resulting record of:

{
	"jobName": "A Job Name",
	"jobProgress": "AT_PRINT_DEVICE",
	"marker": 1532015644397207,
	"jobSubmitTime": "2018-07-19T09:51:56.005+0000",
	"jobLastEventTime": "2018-07-19T09:51:56.847+0000",
	"jobPriority": 100
}

Times in the Jobs API 

Times Reported by Devices: 

The jobs app receives data from multiple sources. Near real time data about DFE jobs, Press Jobs, and Print Runs are supplied by a Client on the DFE. Historic data is supplied through an event channel originating from the press.  All data sources will report times (submit time, complete time, print start time, print end time, etc.) in an ISO-8601 standard format, but without a time zone.  The date and time represents the device's local time.

Example 

A job finishes printing on a press in the United States on the east coast at 9:00AM local time on Jan 1, 2018 (standard time not daylight savings). The time will be reported by the device as 2018-01-01T09:00:00. There is no indication in the time field as to which time zone this occurred in.  A job that finishes printing at 9:00AM PST on Jan 1, 2018 will report the exact same time (even though they actually occurred three hours apart).  Most programming languages will interpret this as 9:00AM in whichever time zone the application is running in.  

Implications 

The main implication from this treatment of time is that specific moments in time will not adjust into the viewer's time zone, unlike other web applications that people may be accustom to. The following example illustrates one of the major implications. 

   What jobs Printed on 1/1/2018? 

Jobs that were printed on a specific date according the device's clock will be counted independent of what side of the globe the device is on. For a worldwide operation, Jan 1 may last 47 hours. Some jobs printed at the same moment in time in different time zones may not get counted as being printed on the same day.  

Querying Device information:

In order to link certain jobs information to a specific press or dfe it is often necessary to know the deviceId of that device.   The AAA - Authentication and Authorization documentation at the bottom of this page is provided for this purpose.  The same Key/Secret that was generated for Jobs API queries can also be used to query the devices within your PrintOS organization.  Authentication between the two APIs is the same, but the base URL and path is slightly different.

Common Use Cases:

To view more detailed examples of common Jobs API calls visit the Use Cases page. The Uses Cases page provides common examples of API queries and the resulting Job data that is returned.