Appendix B: Cloud trigger API

This method retrieves lists of available printers NiceLabel Automation can use. Your lists contain names of printer drivers installed on the computer where NiceLabel Automation runs.

You must send an empty data payload for the API to determine which type of response you need.

Request URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/CloudTrigger/Api-CloudIntegrationDemo-Printers

JSON data payload

{}

XML data payload

<?xml version="1.0" encoding="utf-8"?>

This method prints your labels. In data payloads, you provide:

Request URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-Print

JSON data payload

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
    "Quantity": “1”,
    "Printer": " ZEBRA R-402",
    "PrinterSettings": "",
    "PrintJobName": "",
    "Variables": [
        {
            "Name": "FIELD1",
            "Value": "Value1"
        },
        {
            "Name": "FIELD2",
            "Value": "Value2"
        }
    ]
}

XML data payload

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion></FileVersion>
    <Quantity>1</Quantity>
    <Printer>ZEBRA R-402</Printer>
    <PrinterSettings></PrinterSettings>
    <PrintJobName></PrintJobName>
    <Variables>
        <Variable Name="FIELD1">Value1</Variable>
        <Variable Name="FIELD2">Value2</Variable>
    </Variables>
</PrintData>

This method returns lists of available label templates in specific folders (and subfolders) from your DMS.

Request URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-LabelCatalog

JSON data payload

{
    "CatalogRoot": "/folder/subfolder",
    "SubscriptionKey": "your_subscription_key"
}

XML data payload

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <CatalogRoot>/folder/subfolder</CatalogRoot>
    <SubscriptionKey>your_subscription_key</SubscriptionKey>
</PrintData>

This method returns label previews in your required format. Like the PRINT method, you provide label names, versions, and data values. Supported preview formats include PDF, JPG, and PNG.

Request URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-Preview

JSON data payload

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
    "Quantity": “1”,
    "Printer": "",
    "PrinterSettings": "",
    "PreviewFormat": "",
    "Variables": [
        {
            "FIELD1": "Value1",
            "FIELD2": "Value2"
        }
    ]
}

XML data payload

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion></FileVersion>
    <Quantity>1</Quantity>
    <Printer></Printer>
    <PrinterSettings></PrinterSettings>
    <PreviewFormat></PreviewFormat>
    <Variables>
        <Variable Name="FIELD1">Value1</Variable>
        <Variable Name="FIELD2">Value2</Variable>
    </Variables>
</PrintData>

This method returns your labels converted to print jobs for target printers. For example, if your target printer is Zebra, your content returns in ZPL (Zebra Programming Language). You provide label names, versions, and data values like the PRINT method.

Request URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-PrintJob

JSON data payload

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
    "Quantity": "1",
    "Printer": "",
    "PrinterSettings": "",
} "Variables": [
    {
        "FIELD1": "Value1",
        "FIELD2": "Value2"
    }
]

XML data payload

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion></FileVersion>
    <Quantity>1</Quantity>
    <Printer></Printer>
    <PrinterSettings></PrinterSettings>
    <Variables>
        <Variable Name="FIELD1">Value1</Variable>
        <Variable Name="FIELD2">Value2</Variable>
    </Variables>
</PrintData>

This method returns lists of the variables defined in your specified labels. You may need to know the variables defined in your label so you can assign them values when you execute the PRINT method.

Request URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-Variables

JSON data payload

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
}

XML data payload

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion></FileVersion>
</PrintData>

This method returns live printer statuses reported by your printers. Not all printers are capable of reporting their statuses.

Request URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/Api-CloudIntegrationDemo-PrinterStatus

JSON data payload

{
    "Printer": "ZEBRA ZD420-300dpi ZPL",
}

XML data payload

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <Printer>ZEBRA ZD420-300dpi ZPL</Printer>
</PrintData>

The data structures below include all possible fields. Fields you use depend on your API method. See the chapter API Methods for a list of fields applicable to your particular API method.

JSON payload structure

{
    "FilePath": "/folder/label.nlbl",
    "FileVersion": "",
    "Quantity": "1",
    "Printer": "",
    "PrinterSettings": "",
    "PrintJobName": "",
    "PreviewFormat": "",
    "CatalogRoot": "",
    "SubscriptionKey": "",
    "Variables": [
        {
            "Variable1": "Value1",
            "Variable2": "Value2"
        }
    ],
    "Report": [
        {
            "Pos": "01",
            "Code": "100"
            "Name": "Product 1"
        },
        {
            "Pos": "02",
            "Code": "200"
            "Name": "Product 2"
        }
    ]
}

You can use the optional JSON Report object when you print shipping documents like packing slips and delivery notes.

Items within JSON Report objects are converted into structures suitable for Report objects on your label templates. For example, the variables “Pos”, “Code” and “Name” from the example are used in the Report object with the same names. You can also use your own variable names. If you don’t intent to use Report objects in your label template, you can skip the JSON Report object.

XML payload structure

<?xml version="1.0" encoding="utf-8"?>
<PrintData>
    <FilePath>/folder/label.nlbl</FilePath>
    <FileVersion>1</FileVersion>
    <Quantity>1</Quantity>
    <Printer></Printer>
    <PrinterSettings></PrinterSettings>
    <PrintJobName></PrintJobName>
    <PreviewFormat></PreviewFormat>
    <CatalogRoot></CatalogRoot>
    <SubScriptionKey></SubscriptionKey>
    <Variables>
        <Variable Name="Variable1">Value1</Variable>
        <Variable Name="Variable2">Value2</Variable>
    </Variables>
    <Report>
        <Item>
             <Pos>01</Pos>
             <Code>100</Code>
             <Name>Product 1</Name>
        </Item>
        <Item>
             <Pos>02</Pos>
             <Code>200</Code>
             <Name>Product 2</Name>
        </Item>
    </Report>
</PrintData>

Field descriptions

Automation provides data processing results to business applications in synchronous responses. Responses always match incoming data payload structures. When you send JSON-formatted requests, you receive JSON responses. When you send XML-formatted requests, you receive XML responses.

For XML data payloads, the API provides feedback in the HTTP header and in the message body. For JSON data payloads, responses contain HTML messages without error details (An upcoming NiceLabel release will feature JSON responses with error details).

You can see detailed error logs in NiceLabel Automation Manager for each response type.

PrinterList Structures

Each printer has Printer elements.

Variable Structures

Each variable on your label contains Variable elements.

For more information, read our user guide:

LabelCatalog Structures

Below is just a sample structure returned for the Label Catalog.

The sample structure that NiceLabel 10 configuration provides is the following:

The structure that NiceLabel 2019 configuration provides is the following: