Official translation unavailable. Translate this page with Google:

To enable Cloud trigger printing, you use an integration system (NiceLabel Automation) installed on-premise to receive and process data from your business systems. NiceLabel Automation exposes APIs you can connect to using Cloud trigger APIs from your cloud business applications.

In addition to label printing, with APIs you can:

  • Get label previews (PDF, PNG or JPEG)

  • Report live statuses of label printers

  • Generate lists of all labels in your Document Management System (DMS)

  • Get lists of available printers

  • Get lists of variables defined in your label

  • Provide print jobs (binary)

Important

You are not required to use or follow these samples. These instructions are based on the sample NiceLabel Automation configuration provided in your integration package. You are free to modify your configuration or create your own from scratch.

Executing Cloud trigger APIs

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 NiceLabel Automation 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 NiceLabel Cloud account. You can access the triggers with Cloud trigger APIs. When you execute Cloud trigger APIs, your NiceLabel Cloud account knows where your registered Automation trigger is running and forwards data to your trigger.

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

URL

https://labelcloudapi.onnicelabel.com/Trigger/v1/CloudTrigger/<unique_Cloud_Trigger_name>

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

Ocp-Apim-Subscription-Key

<Subscription key is generated on the Developer Portal when you register "Clound Integration" developer from the Control Center>

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

Registering as integrators

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 NiceLabel 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:

API methods

Our API methods help you test and understand the structures of messages transferred between your business applications and NiceLabel Automation. We include examples and descriptions of inbound requests and NiceLabel Automation 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.

PRINTERS method

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"?>

PRINT method

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

  • Label names

  • Label versions

  • Printer names

  • All label data to print

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>

LABELCATALOG method

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>

Note

The SubscriptionKey field is necessary for NiceLabel Cloud Data Integration Pack developed for NiceLabel 10. When you use version for NiceLabel 2019, you do not need to provide a subscription key.

PREVIEW method

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>

PRINTJOB method

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>

VARIABLES method

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>

PRINTERSTATUS method

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>

Data structures

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

Incoming data payloads

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

NAME

DESCRIPTION

FilePath

Full path name and label name from Document Storage.

FileVersion

Label file version. If you use major/minor versioning, type your version as “0.1” or “1.1”. If you use major versioning, type your version as “1” or “2”.

When you do not type values, the latest available revision is used. If you use approval workflows, the latest approved label version is used.

Quantity

Number of labels to print.

Printer

Printer name where your labels print. This must be the exact printer name installed on your Windows computer with NiceLabel Automation.

PrinterSettings

Base64-encoded DEVMODE structure. Use to override printer settings saved in your label template or recalled from your printer driver.

Note

You can create PowerForms applications to configure printer settings and export settings to DEVMODE. You can also export settings to DEVMODE from your printer driver with an application you can download from our website (Downloads > Utilities and Support Software).

PrintJobName

Job file names that display in Windows Spooler. If omitted, your job name is the name of your label file by default.

PreviewFormat

Label preview format. Available formats include PDF, PNG, and JPEG. If not specified, PDF is your default format.

CatalogRoot

Starting folder where you create your label catalog. Your catalog also includes labels from all subfolders.

Note

If you request label catalogs from large Document Storage repositories, it may take several moments to complete your request.

SubscriptionKey

A subscription key to generate the label catalog. Automation configuration consumes the Document API to generate the label catalog and needs a subscription key for authentication. You can get your Subscription Key from the Developer Portal.

Variables

Name-value pairs for your label variables. For each “name”, you must provide a matching “value”. You send all name-value pairs to your label to use with variables defined with the same “name”. Value mapping takes place automatically based on matching names.

Report

Multiple items providing name-value pairs for the variables used in the Report object in the label template. Each “item” is used as a new row in the Report object. This is an optional field.

Feedback messages

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.

  • Successful execution. If there are no data processing errors, business systems receive JSON or XML-formatted messages. Your response structure depends on on the API method you execute.

  • Erroneous execution. If there are processing errors like “label not found”, “printer not available”, or “wrong data for label objects”, your NiceLabel Automation trigger raises an error and sends back details in the trigger response.

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.

NAME

DESCRIPTION

PrinterName

Windows printer driver name visible to NiceLabel Automation. Windows users can change this name.

DriverName

Windows printer model name (defined by printer driver). Windows users cannot change this name.

Variable Structures

Each variable on your label contains Variable elements.

For more information, read our user guide:

NAME

DESCRIPTION

Name

Variable name.

Description

Variable description.

DefaultValue

Default value defined for your variable during label design.

Format

Acceptable types of variable content (characters).

IsPrompted

Shows if the variable is prompted at print time.

PromptText

Text that prompts your users for value input.

CurrentValue

Actual value used for printing.

IncrementType

Shows if the variable is defined as a counter. If identified as a counter, IncrementType shows the counter type.

IncrementStep

Counter step information. Your counter value increases/decreases by this value on your next label.

IncrementCount

Counter value increment/decrement information. Counters usually change values for each label, but you can choose custom increments.

Length

Maximum number of stored characters in the variable.

IsPickListEnabled

Shows if your users select variable values from a pick list.

PickListValues

Actual (selectable) pick list values.

LabelCatalog Structures

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

  • The Automation configuration for NiceLabel 10 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 Automation configuration for NiceLabel 2019 uses a CLI (command-line interface) helper application, which is limited in its functionality.

Note

You can change the returned label catalog structure to fit your requirements. Just edit the trigger that generates the label catalog in the provided Automation configuration.

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

NAME

DESCRIPTION

Id

Internal id of the label templates as generated in the Document Management system.

ItemPath

The full path and filename to the label template.

Created

Creation timestamp.

Modified

Modification timestamp.

ModifiedBy

Id of the user that modified the label template last.

VersionNumber

The version of the most recent label template.

WorkflowName

The name of a workflow defined for the folder in which the label template is saved.

WorkflowStepName

The name of the workflow step that the label template occupies.

The structure that NiceLabel 2019 configuration provides is the following:

NAME

DESCRIPTION

Name

Label name, including path from Document Storage root folder. Server names and port numbers are not included; NiceLabel Automation knows DMS locations.

Width

Label width in 1/1000 millimeters.

Height

Label height in 1/1000 millimeters.

PrinterName

The printer your label is designed for.

Note

You can specify different printers for printing. NiceLabel Automation adapts label templates for your new printer types.

Description

Label description you can configure.

Revisions

Comma-delimited list of revisions accessible to NiceLabel Automation.

Note

Role-Based Access Control (RBAC) determines label visibility. When you run NiceLabel Automation as an Operator (best practice), you can only access approved label revisions.