JSON Response

Please refer to the following for setting the response from the server to a POST request from the client in CloudPRNT.

Response header

Response Body

HTTP Status Code

JSON data defined in CloudPRNT
The server will respond with a JSON encoded reply, based on the following template:
{
    "jobReady": true|false,
    "mediaTypes": [ "<content media type>" ],
    "jobToken": "<string token>",
    "deleteMethod": "DELETE"|"GET",
    "clientAction": [ {"request": "<request type>", "options": "<request parameters>"} ],
    "claimBarcodeReader": [ "<device name>" ],
    "claimKeyboard": [ "<device name>" ],
    "display": [ { "name": "<device name>", "message": "<message markup>" } ],
    "jobGetUrl": "<alternative URL for job GET>",
    "jobConfirmationUrl": "<alternative URL for job confirmation>"
}
The server response informs the client of any pending print data, and also allows the server to pass Client Action requests to the client.
Some JSON parameters are supported from certain firmware versions, depending on the supported models:

Key Name

IFBD-HI01X/HI02X

mC-Print2/3

TSP100IV

TSP100IV SK

mC-Label3

jobToken

1.8 or later

3.2 or later

1.0 or later

2.0 or later

1.0 or later

claimBarcodeReader

1.4 or later

1.2 or later

1.0 or later

2.0 or later

1.0 or later

claimKeyboard

1.4 or later

n/a

n/a

n/a

n/a

display

1.4 or later

1.2 or later

1.0 or later

2.0 or later

1.0 or later

jobGetUrl

1.8 or later

3.5 or later

1.0 or later

2.0 or later

1.0 or later

jobGetjobConfirmationUrl

1.8 or later

3.5 or later

1.0 or later

2.0 or later

1.0 or later

Note

JSON parameters and supported models not listed in the table are supported by all firmware versions.

  • “jobReady”
    If “true” then the server has data for the client which should be printed, it can be retrieved using a http GET request.

    Note

    While the printer is offline, a GET request will not be issued and POST request will continue to be issued.
    After the printer is online, a GET request will be issued by receiving a response from the server with jobReady set to true.
  • “mediaTypes”
    A list media (MIME) types that available print data may be provided in by the server.
    For example a server may be able to serve a document as a PNG image, or convert to Star Raster. The client will choose it’s preferred format from those available.
    Note that this can vary between print jobs, for example a server may handle printing bit image and text data types differently.
  • “jobToken”
    An optional string parameter(Some models are supported from specific firmware versions).
    When setting jobReady to true, to begin printing a job, the server may specify a string token that will then be used by the client in all communication relating to that job.
    Specifying a jobToken value can help servers synchronise GET and DELETE requests to a particular job and is especially useful over highly distributed systems, or where the network connection can be unreliable.
    Servers can freely assign the jobToken value in whichever way best suits their application.
    For example it may be a UUID, job name, job hash, queue sequence number, etc.

    Note

    The specified value of the jobToken is set by the client only when jobReady is set to true and a string is specified in the jobToken, the printer ASB status is online and the printer is ready(printingInProgress is false).
    And the jobToken specified by the server is deleted from the client after the DELETE request is processed in the client.
    If an error occurs in the printer ASB status during printing (paper empty, cover open), a POST request with the printer status is generated(no DELETE request is generated).
    Therefore the specified jobToken will not be deleted and will be reflected in the POST request until the next jobReady:true is received from the server.
  • “deleteMethod”
    Ask the printer to confirm print job completion with either an http DELETE or GET request.
    This field is optional, and the printer will default to using a DELETE.
    Generally, supporting DELETE is recommended, as the standard way to remove a resource from a web server.
    However, some web servers are unable to pass DELETE request to CGI scripts, and so the printer will optionally send an http GET, with specific query string parameter instead.
  • “clientAction”
    An array of requests for a special action from the client
    See Client Action section.
  • “claimBarcodeReader”
    An array of strings, each string is the logical device name of a Barcode Reader device to be claimed for input.
    Alternatively, a Boolean response of ‘true’ can be sent to claim the ‘default’ barcode reader.
    Claiming a barcode reader means that scanned barcodes will be reported to the server.
    The claim lasts only until the next poll, therefore the server should set this field every time if it wishes to receive barcode scans continuously.
  • “claimKeyboard”
    Some models are supported from specific firmware versions.
    An array of strings, each string is the logical device name of a Keyboard device to be claimed for input.
    Alternatively, a Boolean response of ‘true’ can be sent to claim the ‘default’ keyboard.
    Claiming a keyboard means that key presses will be reported to the server. The claim lasts only until the next poll, therefore the server should set this field every time if it wishes to receive keyboard activity continuously.
  • “display”
    A string containing a message for the default display, or an array of display messages.
    Each message should contain two string fields:
    • “name”
      The name of the display device to send the message to.
    • “message”
      The message to be sent to the display, this can be plain text with CloudPRNT display markup messages.
      Refer to the Display for details.
  • “jobGetUrl”
    An optional URL string parameter(Some models are supported from specific firmware versions).
    When jobReady is set to true, then this field may be provided to specify an alternative URL to perform the job GET. This allows easy distribution to a different server for managing the print job file downloads such as a data ‘blob’ service.
    And the information of the specified URL in printer will be deleted after the GET request is issued.
  • “jobConfirmationUrl”
    An optional URL string parameter(Some models are supported from specific firmware versions).
    When jobReady is set to true, then this field may be provided to specify al alternative URL to perform the print confirmation DELETE (or GET, if “deleteMethod” is set to “GET”) operation.
    And the information of the specified URL in printer will be deleted after the DELETE request is issued.
To simplify the client<–>server rules, a server should not set a clientAction request and expect printing at the same time.
If “jobReady” is set to true, and one or more clientActions are requested, the client will handle the clientAction requests only.
It is expected that the printing can wait for the next poll. This does not usually cause any visible performance penalty, because the client will issue the next poll immediately after handling the clientAction requests instead of after the usual polling interval.
Below is an example of how the printer operates after receiving each HTTP response status code related to the POST response from the server.

Status Code

Printer action

200
Analyze the response from the server and issue various requests according to the content.
If there is no print request, if there is a print request but the printer is offline:
Continue Polling the server (POST) without any special processing.
If there is a print request and the printer is online:
Issue Print job requests (GET) .
If there is a clientAction request:
Performs a clientAction request and issue Polling the server (POST) with the results.

Other than 200

Continue Polling the server (POST) without parsing the response from the server.

Server POST response sample

A typical server response, when no printing is required

{
    "jobReady": false
}
A typical server response when printing is required.
The server is able to make the job available as either plain text, or png data.
{
    "jobReady": true,
    "mediaTypes": ["text/plain", "image/png"]
}
A typical server response when PNG image printing is required by using a specified job token string.
This job token string will be used at GET request, DELETE request, and POST request(during printing) which are related that job.
{
    "jobReady": true,
    "mediaTypes": ["image/png"],
    "jobToken": "PrintJob1"
}
A server response, with request for the printer to report its polling interval and list of supported job encodings
{
    "jobReady": false,
    "clientAction": [
        {"request": "GetPollInterval", "options": ""},
        {"request": "Encodings", "options": ""}
    ]
}