Each Cloud trigger is identified by a unique name. You must reference the unique name in each HTTP request to our Cloud trigger API.

In the example below, replace the “unique_name_of_the_Cloud_trigger” with the actual unique Cloud trigger name defined in your LoftwareAutomation configuration (.MISX file).

Each Cloud trigger defined in your configuration exposes one API method. You use different triggers for each method. One trigger for the PRINT method, another for the PREVIEW method, and yet another for the PRINTERS method, etc. Unique names tell Automation, which trigger it must execute.

When you load and deploy/activate your Automation configuration, Automation registers the Cloud triggers (unique names) in your Loftware Cloud account. You can access the triggers with Cloud trigger APIs. When you execute Cloud trigger APIs, your Loftware Cloud account knows where your registered Automation trigger is running and forwards data to your trigger.

You can have multiple on-premise LoftwareAutomation servers running the same configuration at the same time with automatic round-robin load balancing enabled.

You must include the following custom HTTP header with each request:

You must use the POST method and include the JSON or XML data in your message body.

To execute Cloud trigger APIs, you must register as a developer and get a subscription key. You can complete this self-service operation once you can sign in to your Loftware Cloud account and when you have set up your account in our Developer Portal.

For more information about the registration process, read our user guides:

Our API methods help you test and understand the structures of messages transferred between your business applications and LoftwareAutomation. We include examples and descriptions of inbound requests and LoftwareAutomation feedback structures.

You can use JSON and XML data structures with our API methods.

For more information about incoming data payloads, see the chapter Data structures.

This method retrieves lists of available printers LoftwareAutomation can use. Your lists contain names of printer drivers installed on the computer where LoftwareAutomation 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>

Your API configuration accepts JSON and XML data payloads. Your configuration automatically determines your payload type and responds using the same type.

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 Loftware release will feature JSON responses with error details).

You can see detailed error logs in LoftwareAutomation 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 Automation configuration generates the label catalog using Document API from the Developer Portal (you have to sign in to see the content). The sample uses a small subset of what the Document API provided.

The sample structure that Loftware configuration provides is the following: