6 - Label Request API

Label Request API

If the web application is installed, it supports submitting label data in JSON or XML format over HTTP as POST request.

Workflow of API Label Requests

The label request data is parsed to determine which label profile should be used to print the label, and which printer. Certain properties and values must appear in the label request to match – this is configured in the Profile Map property – see below.
The app may optionally validate the label format against a JSON or XML schema if defined.
Then, values for the search-fields and editable-field variables are extracted, and the label sent to the printer.
To make this work, additional configuration properties are required.
There are two supported scenarios:

• Full label data is submitted (no database query)
• Partial info submitted, requiring database query

If a system such as an ERP is creating the label data, it would normally submit all of the data for a label which can then just be extracted and submitted to the printer.
In some cases, one may want to print labels from a list of codes or IDs and require a database query for each label to obtain the necessary full information for the label.

URL for API Calls

URL for a full label data request submission (no database query):
POST <server-name>/labels/printqueue</server-name>

URL for a label request submission requiring a database query:
POST <server-name>/labels/dataqueue</server-name>

Advanced Profile Configuration - JSON and XML API

Profile and printer configuration is always done through the desktop app, also if the web application is installed, since the web app contains no configuration pages.
Additional configuration properties exist to enable API submissions.

Configuration of the API is done directly in a profile – thus, you cannot have more than one type of XML request and one type of JSON request. If you do need support multiple types of label requests for the same label type, define multiple profiles using the same label template.
For JSON requests, the configuration specifies a mapping between the field names defined in the label profile and the corresponding JSON properties in the request. For XML, you specify an XPath expression to retrieve values from the XML request.

JSON Label Request Configuration

Property	Description
JSON Schema	Path to JSON schema file. The file should follow the syntax defined at https://json-schema.org/. This file is only used when “JSON Schema Option” is set to “UseProfileSchema”.
JSON Schema Option	You can choose to skip validation (DoNotValidate), to use a fixed file defined in the above ”JSON Schema“ property (UseProfileSchema), or to use the schema specified in the label request $schema property (in this case this is a relative URL – the file must be in the configuration directory)
JSON Profile Map	List of JSON properties and respective values which must appear in the label request for this profile to be selected
JSON Search Field Map	List of field names (identical to Search Field list) and corresponding JSON properties. LabelCast will use the values of those JSON properties to assign to the Search Field variables. If such fields are detected in the label request, this triggers a database query.
JSON Data Field Map	List of field names (identical to Data Field list) and corresponding JSON properties. Data Field Map only needs to be configured for label data request which contain full label data, including fields which “normally” would come from a database query result.
JSON Edit Field Map	List of field names (identical to Editable Field list) and corresponding JSON properties.

XML Label Request Configuration

Property	Description
XML Schema	Path to XML DTD file. XSD is not currently supported – it must be a Document Type Definition (DTD). This file is only used when “XML Schema Option” is set to “UseProfileSchema”.
XML Schema Option	You can choose to skip validation (DoNotValidate), to use a fixed file defined in the above XML Schema property (UseProfileSchema), or to use the schema specified in the label request $schema property (in this case this is a relative URL – the file must be in the configuration directory)
XML Profile Map List of	XPath expressions and respective values which must appear in the label request for this profile to be selected
XML Search Field Map	List of field names (identical to Search Field list) and corresponding XPath expressions to locate the values in the XML. LabelCast will use these values to assign to the Search Field variables. If such fields are detected in the label request, this triggers a database query.
XML Data Field Map	List of field names (identical to Data Field list) and corresponding XPath expressions to locate the values in the XML. Data Field Map only needs to be configured for label data request which contain full label data, including fields which “normally” would come from a database query result.
XML Edit Field Map	List of field names (identical to Editable Field list) and corresponding XPath expressions, as above.

[4 - Configuration]