Jobs Use Cases

Common Jobs API Use Cases

The list below shows some of the most common API calls used to collect data over the Jobs API.  Click the text on the use case(s) below to see URLs, HTTP Body structure and other information needed for these calls.

Update an MIS application with production information

Description:

One of the main use cases of the PrintOS Jobs application is to get production information from a job to update an MIS/ERP type application.  This method assumes that all jobs in the system have already been queried over the API, and the calling applicaiton is now querying at regular intervals checking for newly updated jobs information.  The properties query parameter should also be provided with all of the necessary properties needed.

Method:

GET

API Endpoint:

/jobs-sdk/jobs/{context}  where {context} equals printrun for near-real time data, or historic for historic print attempt data

Query String:

?startMarker={last marker value}&properties={property set}  where {last marker value} is the previous query's largest marker value incremented by 1 and {property set} is a list of properties needed for tracking of production.

Full URL example

https://printos.api.hp.com/jobs-service/jobs/printrun?startMarker=
1535661050541537&properties=impressions,jobCompleteTime,jobName,marker,substrates

 

Repsonse Sample (shortened):

[
    {
        "jobName": "2 Color Front - 4 Color back.pdf",
        "jobCompleteTime": "2018-08-30T14:27:34.328",
        "marker": 1535661050541537,
        "substrates": {
            "counts": [
                {
                    "name": "MaxPaper",
                    "amountUsed": 8
                }
            ]
        },
        "impressions": 64
    },
    {
        "jobName": "1 Color Black - 1 Page.pdf",
        "jobCompleteTime": "2018-08-30T14:32:56.624",
        "marker": 1535661050541555,
        "substrates": {
            "counts": [
                {
                    "name": "12X18",
                    "amountUsed": 8
                }
            ]
        },
        "impressions": 8
    },
    {
        "jobName": "2 Colors Orange+Green - 1Page .pdf",
        "jobCompleteTime": "2018-08-30T14:33:10.510",
        "marker": 1535661050541567,
        "substrates": {
            "counts": [
                {
                    "name": "12X18",
                    "amountUsed": 8
                }
            ]
        },
        "impressions": 24
    }
]

 

Retrieve Property Specs for a Certain Context

Description:

Much of the data returned from by a Jobs API call depends on the context it was called in. To find the list of properties that will be returned for a specific call you should first call the /jobs/propertyspecs endpoint with the context you are interested in ( i.e. .../jobs/propertyspecs?context=printrun ).

Method:

GET

API Endpoint:

/jobs-sdk/propertyspecs

Query String:

?context=printrun

Full URL example

https://printos.api.hp.com/jobs-service/jobs-sdk/propertyspecs?context=printrun

 

Repsonse Sample (shortened):

{
    "context": "Job.PrintRunInfo",
    "list": [
        {
            "name": "deviceId",
            "type": "String",
            "caseSensitive": true
        },
        {
            "name": "duplex",
            "type": "Boolean",
            "caseSensitive": true
        },
        {
            "name": "impressions",
            "type": "Integer",
            "caseSensitive": true
        },
        {
            "name": "impressions1Color",
            "type": "Integer",
            "caseSensitive": true
        },
        {
            "name": "impressions2Colors",
            "type": "Integer",
            "caseSensitive": true
        },
        {
            "name": "impressionsNColors",
            "type": "Integer",
            "caseSensitive": true
        },
        {
            "name": "impressionsType",
            "type": "Enum",
            "caseSensitive": true,
            "values": [
                {
                    "id": "A3",
                    "description": "Value that represents the type of impressions shown are A3 impressions."
                },
                {
                    "id": "B2",
                    "description": "Value that represents the type of impressions shown are B2 impressions."
                }
            ]
        },
        {
            "name": "inks",
            "type": "JSON",
            "caseSensitive": true
        },
        {
            "name": "inkUnits",
            "type": "Enum",
            "caseSensitive": true,
            "values": [
                {
                    "id": "IMPRESSIONS",
                    "description": "Indicates that the <count> values represent the number of impressions printed with that <name> color."
                }
            ]
        },
        {
            "name": "jobCompleteTime",
            "type": "Date",
            "caseSensitive": true
        },
        {
            "name": "jobCopies",
            "type": "Integer",
            "caseSensitive": true
        },
        {
            "name": "jobElapseTime",
            "type": "Duration",
            "caseSensitive": true
        },
        {
            "name": "jobId",
            "type": "String",
            "caseSensitive": true
        },
        {
            "name": "jobLastEventTime",
            "type": "Date",
            "caseSensitive": true
        },
        {
            "name": "jobName",
            "type": "String",
            "caseSensitive": false
        },
        {
            "name": "jobProgress",
            "type": "Enum",
            "caseSensitive": true,
            "values": [
                {
                    "id": "PRE_RIP",
                    "description": "The job has arrived and is getting ready to RIP."
                },
                {
                    "id": "RIPPING",
                    "description": "The job is currently RIPping."
                },
                {
                    "id": "RIPPED",
                    "description": "The job has completed RIPping at the DFE, but has not been loaded on a Press Controller yet (it may have been assigned to a Press)."
                },
                {
                    "id": "LOADING",
                    "description": "The DFE job has completed RIPping and is loading onto the Press Controller."
                },
                {
                    "id": "AT_PRINT_DEVICE",
                    "description": "The DFE job has been sent to a Press."
                },
                {
                    "id": "HELD",
                    "description": "The Press job is in the Held queue."
                },
                {
                    "id": "QUEUED",
                    "description": "The Press job is in the Print Queue, but is not the job currently being printed."
                },
                {
                    "id": "RETAINED",
                    "description": "The Press job is in the Retained queue.  Normally, a Press job is placed in the Retained queue when it has finished printing.  In this case, the value would normally be 'PRINTED'. However, if connectivity was lost during the time the job was placed in the Retain queue, and all the Jobs Data Collector knows is that the job is now in the Retained queue (but it does not know how it got there), then the value will be 'RETAINED'."
                },
                {
                    "id": "PRINTING",
                    "description": "The Press job is currently being printed."
                },
                {
                    "id": "PRINTED",
                    "description": "The Press job has successfully completed printing.  It may be in the Retained queue or have been deleted (see LocationType for how to deterime which it is).  This state can apply to DFE, Press, and Print Run jobs."
                },
                {
                    "id": "COMPLETED",
                    "description": "The job is considered to be completed.  Complete is a terminal state (meaning no more actions can be performed on the job other than 'delete'."
                },
                {
                    "id": "ABORTED",
                    "description": "The job was aborted.  It may or may not have had any successful Print Runs before being aborted.  It may have been aborted in the middle of a Print Run.  If this was a Print Run job, the Print Run job data can be used to determine how much printing was done before the job was aborted.  It may still be in the Retained queue (allowing for possible additional prints), or it may have been deleted (see LocationType for how to determine which it is)."
                },
                {
                    "id": "UNKNOWN",
                    "description": "The job state is unknown.  This occurs when a device loses connection to the cloud and needs to resync.  At the start of a resync, all jobs on the device are set to 'UNKNOWN'. If the device still knows about this job, then a job-specific resync event will overwrite this state with the current value (otherwise, the job will be left in the 'UNKNWON' state)."
                }
            ]
        },
        {
            "name": "jobSubmitTime",
            "type": "Date",
            "caseSensitive": true
        },
        {
            "name": "jobType",
            "type": "Enum",
            "caseSensitive": true,
            "values": [
                {
                    "id": "DFE",
                    "description": "The entry represents a job on a DFE."
                },
                {
                    "id": "PRESS",
                    "description": "The entry represents a job on a Press."
                },
                {
                    "id": "PRINT_RUN",
                    "description": "The entry represents and individual print of the Press job on a Press.  A single job can be printed multiple times and each time generates a new Print Run job."
                }
            ]
        },
        {
            "name": "marker",
            "type": "Long",
            "caseSensitive": true
        },
        {
            "name": "parentJobId",
            "type": "String",
            "caseSensitive": true
        },
        {
            "name": "substrates",
            "type": "JSON",
            "caseSensitive": true
        },
        {
            "name": "substrateUnits",
            "type": "Enum",
            "caseSensitive": true,
            "values": [
                {
                    "id": "SHEETS",
                    "description": "Substrate value represents the number of sheets of paper printed."
                }
            ]
        }
    ]
}
All jobs on a specific press device

Description:

To narrow query results down to a specific press a query string must be included with the devices parameter set to the deviceId value of that press.

Since these jobs will be on press the {context} will be set to "press".

Method:

GET

API Endpoint:

/jobs-sdk/jobs/press

Query String:

?devices=ec63127a-d8e4-4f37-9f87-6903a8ee9fa1

Response Sample:

[{
"jobName": "Historic buildings of San Antonio 2",
"jobProgress": "PRINTED",
"marker": 1532015644397207,
"jobSubmitTime": "2018-07-19T09:51:56.005+0000",
"deviceId": "ec63127a-d8e4-4f37-9f87-6903a8ee9fa1"
}, {
"jobName": "Dollar Dental Reminder Mailer 2",
"jobProgress": "PRINTING",
"marker": 1533762019094122,
"jobSubmitTime": "2018-08-08T14:57:50.649+0000",
"deviceId": "ec63127a-d8e4-4f37-9f87-6903a8ee9fa1"
}, {
"jobName": "Complete Idiots Guide to Euclidean Tensor Fields 3",
"jobProgress": "HELD",
"marker": 1533762019094122,
"jobSubmitTime": "2018-08-08T14:57:50.659+0000",
"deviceId": "ec63127a-d8e4-4f37-9f87-6903a8ee9fa1"
}]
Jobs in the print queue of a specific press

Description: 

The query for this information is the same as the query above.  Finding information about jobs in this state involves processing the response data to find the information you need.

To find jobs in the Print Queue of the press,  you need to look at two property values in the response:

  1. "locationType": "QUEUE"  meaning the job is queued on the press.
  2. "location": "QUEUED"  meaning the job is currently queued in the print queue vs "HELD" for the held queue or "RETAINED" for the retained queue. 

Note that the location and locationType properties are not returned by default.  They will need to be added to the query string in the properties parameter.

Method:

GET

API Endpoint:

/jobs-sdk/jobs/press

Query String:

?devices=ec63127a-d8e4-4f37-9f87-6903a8ee9fa1&properties=jobName,location,locationType,marker

Full URL:

https://printos.api.hp.com/jobs-sdk/jobs/press?devices=ec63127a-d8e4-4f37-9f87-6903a8ee9fa1&properties=jobName,location,locationType,marker

Sample Response:  (press jobs that are in the print queue are highlighted)

[{
"jobName": "Classic Cars 1996 2",
"marker": 1532020852420883,
"locationType": "QUEUE",
"location": "RETAINED"
}, {
"jobName": "Historic buildings of San Antonio 3",
"marker": 1532020852420883,
"locationType": "QUEUE",
"location": "HELD"
}, {
"jobName": "AOL Mailer 1",
"marker": 1532020852420883,
"locationType": "DELETED"
}, {
"jobName": "Yahoo Prospectus 2",
"marker": 1532020852420883,
"locationType": "QUEUE",
"location": "QUEUED"
}, {
"jobName": "Personalized Bookmarks 3",
"marker": 1532021858826781,
"locationType": "QUEUE",
"location": "HELD"
}, {
"jobName": "Ferrari 1950-2010 2",
"marker": 1532021858826781,
"locationType": "QUEUE",
"location": "QUEUED"
}, {
"jobName": "Historic buildings of San Antonio 2",
"marker": 1532021858826781,
"locationType": "DELETED"
}, {
"jobName": "Bar Coasters 2",
"marker": 1532021858826781,
"locationType": "QUEUE",
"location": "RETAINED"
}, {
"jobName": "DSCOOP Poster 11 2",
"marker": 1532022223513023,
"locationType": "QUEUE",
"location": "QUEUED"
}, {
"jobName": "QSL Cards 2",
"marker": 1532022223513023,
"locationType": "QUEUE",
"location": "RETAINED"
}, {
"jobName": "Classic Cars 1996 3",
"marker": 1532022223513023,
"locationType": "QUEUE",
"location": "HELD"
}, {
"jobName": "Bio 101 Lab Notebook,4colorsIsv 2",
"marker": 1532022223513023,
"locationType": "QUEUE",
"location": "RETAINED"
}]
Find the current Work Time Estimate for a specific press

Description:

jobWorkTimeEstimate is a property returned for jobs in the press context.  It shows the estimated amount of time that job will take to print in seconds.

To calculate the current work time estimate of jobs loaded on a press you will need to query the current list of jobs on that device, then parse the response for all jobs you want to include in the work time estimate calculation based on their state (e.g. jobs in print queue, print + held queue etc.) Once this set of jobs has been found the work time estimate can be calcualted by adding the values of each jobWorkTimeEstimate.

Note that the jobWorkTimeEstimate property is not returned by default.  It will need to be added to the query string in the properties parameter.

In the example response below the work time estimate for that device will be calculated for all jobs in the held and print queue (location = "QUEUED" or "HELD")

Method:

GET

API Endpoint:

/jobs-sdk/jobs/press

Query String:

?devices=ec63127a-d8e4-4f37-9f87-6903a8ee9fa1&properties=jobName,location,locationType,marker,jobWorkTimeEstimate

Full URL:

https://printos.api.hp.com/jobs-sdk/jobs/press?devices=ec63127a-d8e4-4f37-9f87-6903a8ee9fa1&properties=jobName,location,locationType,jobWorkTimeEstimate

Sample Response: (highlighted jobWorkTimeEstimate values will be included in calculation)

The calculated work time estimate for this set of data should be (33 + 64 + 50 + 28 + 293) or 468 seconds

{
		"marker": 1532020549465316,
		"queueOrderIndex": 1532018620968,
		"locationType": "QUEUE",
		"location": "QUEUED",
		"jobWorkTimeEstimate": 33
	}, {
		"marker": 1532020549465316,
		"queueOrderIndex": 1532020390741,
		"locationType": "QUEUE",
		"location": "HELD",
		"jobWorkTimeEstimate": 64
	}, {
		"marker": 1532020549465316,
		"queueOrderIndex": 1532014066425,
		"locationType": "DELETED",
		"jobWorkTimeEstimate": 99
	}, {
		"marker": 1532020852420883,
		"queueOrderIndex": 1532016992484,
		"locationType": "QUEUE",
		"location": "RETAINED",
		"jobWorkTimeEstimate": 112
	}, {
		"marker": 1532020852420883,
		"queueOrderIndex": 1532020716498,
		"locationType": "QUEUE",
		"location": "HELD",
		"jobWorkTimeEstimate": 50
	}, {
		"marker": 1532020852420883,
		"queueOrderIndex": 1532014426060,
		"locationType": "DELETED",
		"jobWorkTimeEstimate": 84
	}, {
		"marker": 1532020852420883,
		"queueOrderIndex": 1532019162884,
		"locationType": "QUEUE",
		"location": "QUEUED",
		"jobWorkTimeEstimate": 28
	}, {
		"marker": 1532021858826781,
		"queueOrderIndex": 1532021720996,
		"locationType": "QUEUE",
		"location": "HELD",
		"jobWorkTimeEstimate": 293
	}
Tracking jobs submitted from upstream application

Description: 

Often a 3rd party application (MIS / ERP / Web-2-Print etc.) submitted a job to the Digital Front End and the progress of the job needs to be relayed back to that application.  The status of these jobs can be queried over the Jobs API based on a number of fields depending on how the job was submitted to the the Digital Front End.

Hotfolder Submision:

Submission of jobs through a hotfolder limits the amount of data that can be tracked through the jobs application.  Information is typically limited to the name of the submitted file, or any trackable properties that were defined in a ticket template associated with that hotfolder.  Any information set in a ticket template (i.e. customer information) will apply to all jobs submitted against that ticket template, and therefore are not unique to one job.

Jobs APP Property DFE Job Property Comment
customerName Company Name If Customer Information was defined in the associated ticket template then this will be relayed to the Jobs App
jobName Job Name The Job Name is usually generated based on the PDL file name that was dropped in the hotfolder.  Note that jobName is not necessarily unique.  If the same file name was submitted multiple times then that jobName will appear in multiple job entries.

JDF Submission:

Submission of jobs via JDF provide much more control of individual job information.  The table below shows properties in the jobs application that can be driven through a JDF ticket.

Jobs APP Property

JDF Property (XPath) Comment
jobName JDF/@DescriptiveName Not necessarily unique
jobId JMF/Response/QueueEntry/@QueueEntryID Will be contained in the ResponseSubmitQueueEntry message if the job was submitted via JMF
jdfJobId JDF/@JobID JDF/@JobID and JDF/@JobPartID together should be unique according to the CIP4 specification
jdfJobPartId JDF/@JobPartID JDF/@JobID and JDF/@JobPartID together should be unique according to the CIP4 specification
hpTrackingId JDF/ResourcePool/NodeInfo/GeneralID[@IDUsage="hpTrackingId"]/@IDValue A custom property supported by HP to drive barcodes from upstream applications such as MIS

Jobs API Call:

In the API call below we assume that an upstream application submitted a job to the DFE using a JDF ticket.  Inside that JDF ticket the JDF/@JobID and JDF/@JobPartID values were defined by the submitting application.  The resulting API call to the Jobs application will reference these two values to query the associated job.  

Method:

GET

API Endpoint:

/jobs-sdk/jobs/press  (for near real-time data)

/jobs-sdk/jobs/historic

Query String:

You should set the properties query to only respond with the relevant properties to your query

?properties=jobName,jobProgress,marker,jdfJobId,jdfJobPartId  or

?properties=jobName,jobProgress,marker,jobCompleteTime,printedSheets,impressions

Full URL
Example:

https://printos.api.hp.com/jobs-service/jobs-sdk/jobs/press?properties=jobName,jobProgress,marker,jdfJobId,jdfJobPartId  or

https://printos.api.hp.com/jobs-service/jobs-sdk/jobs/historic?properties=jobName,jobProgress,marker,jobCompleteTime,printedSheets,impressions

Note: you may need to page through multiple responses to find the individual jobs that you are looking for.  It is recommend to monitor only jobs that have changed since your last query interval and keep a working set of your current jobs in memory, or in an external database application to make querying easier.  See the Method for calling Jobs data section on the documentation page for more details.

 

Sample Response (press context):

[
        {
        "jobName": "9e514b81-e68f-47b1-83f9-bce88f7693d6",
        "jobProgress": "QUEUED",
        "marker": 1532021229621638,
        "jdfJobPartId": "660164e6423fd881c0e052df88e2d8e9",
        "jdfJobId": "6223d7fb9f39970606a2b524a686941f"
    },
    {
        "jobName": "bae75abb-1306-4eef-b213-b4a389fe9e57",
        "jobProgress": "HELD",
        "marker": 1532021410621638,
        "jdfJobPartId": "c0cf2d3fe26b8cc48f1f9c537fd074aa",
        "jdfJobId": "562f5c3608dc974979c12adc7904d41c"
    },
    {
        "jobName": "044ad8e4-91bb-4ee6-87f1-386408f101ed",
        "jobProgress": "RETAINED",
        "marker": 1532021591621638,
        "jdfJobId": "99dc6d570c5a525c5e4208bf66503013"
    },
    {
        "jobName": "285fe76a-96a0-481e-b669-3d4d74d644ba",
        "jobProgress": "HELD",
        "marker": 1532021772621638,
        "jdfJobPartId": "84ec6dfb792706ba71bff7c9c3d66c06",
        "jdfJobId": "77618ba805f842d1a98e04a8e924b96d"
    }
]

Sample Response (historic context):

[
    {
        "jobName": "299941f5-9468-41e5-9723-6e111d468926",
        "jobProgress": "PRINTED",
        "jobCompleteTime": "2018-08-10T20:14:06.621",
        "marker": 1525388156,
        "impressions": 145,
        "printedSheets": 29
    },
    {
        "jobName": "8c8c9636-5413-4d9a-bc59-7b7f664877fd",
        "jobProgress": "PRINTED",
        "jobCompleteTime": "2018-08-10T20:17:07.621",
        "marker": 1525388157,
        "impressions": 24,
        "printedSheets": 3
    },
    {
        "jobName": "1fe5f797-32d1-40f2-8eb2-c90310b267ca",
        "jobProgress": "PRINTED",
        "jobCompleteTime": "2018-08-10T20:20:08.621",
        "marker": 1525388158,
        "impressions": 180,
        "printedSheets": 45
    },
    {
        "jobName": "cab8519f-72ed-421d-8a61-a13db9a8edd6",
        "jobProgress": "PRINTED",
        "jobCompleteTime": "2018-08-10T20:23:09.621",
        "marker": 1525388159,
        "impressions": 152,
        "printedSheets": 19
    },
    {
        "jobName": "257bfebc-1046-4ab1-bc91-7deec37f847f",
        "jobProgress": "PRINTED",
        "jobCompleteTime": "2018-08-10T20:26:10.621",
        "marker": 1525388160,
        "impressions": 125,
        "printedSheets": 25
    }
]
Query the devices in your organization

Description:

In order to find jobs specific to a specific device, or to find out which device a set of jobs is on you will need the deviceId value of that device.  You can query the list of devices in your organization through the AAA API /organization/devices endpoint.

Note that the base URL and path are different from the Jobs API, but authentication method is the same.

The response below shows two devices.  The top device is a digital front end, and the bottom device is a digital press.

Method:

GET

API Endpoint:

/organizations/devices

Full URL Example:

https://www.printos.com/api/aaa/v4/organizations/devices

Response Sample:

{
            "active": true,
            "locked": false,
            "deviceId": "51c9b6e3-4da1-4641-be12-bb012a32cf92",
            "name": "hppro-sm1-DFE",
            "description": "HP SmartStream Production Pro Print Server",
            "serialNumber": "GB4048008J",
            "model": "CloudEnabledIndigoDFEV1",
            "type": "IndigoDFE",
            "group": "Indigo",
            "organizationId": "2fd5431d-0bfe-48s0-b354-162cdf357vb8",
            "jobDestination": {
                "agentId": "9e5206f0-de4b-11f7-b09c-eb40a311a43c",
                "jobDeliveryType": "JMF",
                "jmfURL": "http://hppro-sm1/prodflow/jmf/hppro-sm1"
            },
            "anonymous": false,
            "createdTime": 1512987073000,
            "lastLoggedInTime": 1540224596000
        },
        {
            "active": true,
            "locked": false,
            "deviceId": "42d36da1-79cd-41eb-8b3e-405fd7nb2593",
            "name": "HP7500",
            "serialNumber": "30000981",
            "model": "HP Indigo 7500 Digital Press",
            "type": "IndigoPress",
            "group": "Indigo",
            "organizationId": "4fd6431d-0efe-48e0-b345-161cdf357eb9",
            "site": {
               "siteId": "b1aa4794-1efa-4131-96c5-c9605ed565db",
                "name": "Main",
                "primaryAddress": {
                    "addressLine1": "1234 Main St.",
                    "locality": "Town",
                    "region": "AB",
                    "country": "US",
                    "postalCode": "22891",
                    "addressId": "1837",
                    "name": "Acme"
                },
                "timezone": "Africa/Lagos",
                "organizationId": "2fd5431d-0bfe-48s0-b354-162cdf357vb8",
                "hpRegion": "AMERICAS"
            },
            "anonymous": false,
            "createdTime": 1474462483000
        }