Official translation unavailable. Translate this page with Google:

Product level info

Requires NiceLabel Cloud subscription.

To learn more about triggers in general, see section Understanding Triggers.

Read more about NiceLabel Label Cloud here.

Cloud trigger allows you to integrate your NiceLabel Cloud or on-premise Control Center with existing business systems that run in private clouds or in dedicated data centers. If an existing business system (e.g., SAP S/4HANA or Oracle NetSuite) produces an output, a cloud-hosted API enables you to send HTTP requests to the cloud trigger.

The cloud trigger allows you to locally print labels whose content originates from the cloud information systems. Because the cloud trigger that runs on the local Automation server uses standard methods for accessing the cloud-based services, you can deploy local printing in a secure and time efficient way.

The cloud trigger enables a secure and transparent way to integrate your local label printing using applications that communicate over the open Internet.

Compared to the HTTP server trigger, the cloud trigger does not require you to open any inbound ports on your firewall. The cloud trigger uses a dedicated NiceLabel API that runs in the cloud. This is why the trigger only requires open outbound port 443, or ports 9350-9354. In most cases, these ports are already open.

When deploying the cloud trigger, you have two options:

Both options are equal in terms of offered functionalities. Chose your preferred option based on your available infrastructure.

Deploying Cloud Trigger with NiceLabel Cloud

Deployment Stages for NiceLabel Cloud

To enable local label printing using the cloud trigger deployed in NiceLabel Cloud, you must establish cooperation between users with three roles: a user that configures the cloud trigger on the local Automation server (developer), a user that sets up the cloud trigger in NiceLabel Cloud, and a user that makes the subscription on the Developer Portal.

UUID-4a7834ab-e9e3-d7ac-d0fd-c550f1520e0e.png
  1. The developer configures and deploys the cloud trigger configuration on the local Automation server using Automation Builder and Automation Manager.

    Note

    NiceLabel Automation must be signed in to the NiceLabel Cloud.

  2. The NiceLabel Cloud administrator gives the external integrator access to the cloud trigger in Control Center. When done, the NiceLabel Cloud administrator sends the external integrator the corresponding integrator key.

  3. The external integrator joins the Developer Portal to bring the customer's business system and the NiceLabel Cloud together.

    Note

    The Developer Portal hosts the dedicated API called Cloud Trigger. This API serves as an interconnection point between the events that take place in the customer's business system, and the Automation configuration that runs locally.

    Note

    The word "external" means that this user's role is to make the subscription on the Developer Portal. The created subscription authenticates the integrator. External integrators are not necessarily outside collaborators. They can be in-house integrators who belong to the company's own development team.

    The external integrator performs the following actions on the Developer Portal:

    1. Signing in to the Developer Portal. Before the first sign-in, the integrator must also finish the sign up procedure.

    2. Creating a subscription for the Cloud Trigger API.

    3. Connecting the subscription with the integrator key. This is how the subscription gains access to the customer's cloud triggers.

      For details, see section Setting up the NiceLabel Cloud API on the Developer Portal for details.

Configuring cloud trigger in Automation Builder

This section describes how to configure the cloud trigger in Automation that runs on your local server.

  1. Open your Automation Builder. Make sure the Automation Builder is signed in to NiceLabel Cloud. Go to File > About > NiceLabel Cloud account to confirm that you are signed in.

  2. The Configuration Items tab opens. Click Cloud Trigger to create a new configuration for the cloud trigger.

  3. Set Name and Description to make your cloud trigger easy to find among other triggers.

  4. Set the trigger Communication settings:

    • Define the Unique identifier. After you deploy the trigger, this unique identifier is necessary for calling the trigger.

      If you are running the cloud trigger configuration on multiple computers, you must make sure each computer automatically uses its own unique identifier. To prevent unwanted duplications, insert internal variables as part of the Unique identifier. You can use two internal variables for this purpose:

      • ComputerName: The name of the computer on which the configuration is running.

      • SystemUserName: The Windows user name of the currently logged-in user.

      To insert internal variables to the Unique identifier, click Insert data source and select your internal variables.

      UUID-7905238a-2b2d-69c4-9856-247bdcb0320c.png
    • Wait for trigger execution to finish: The HTTP protocol requires a receiver (in this case NiceLabel Automation) to send a numeric response back to the sender indicating the status of the received message. By default, NiceLabel Automation responds with code 200. This indicates Automation successfully received the data, but gives no information about the success of trigger actions.

      This option specifies that a trigger doesn't send a response immediately after receiving the data, but waits until all actions execute. Then, it sends the response code indicating a successful action execution. With this option enabled, you can send back a custom response type and data (e.g., the response to a HTTP request is label preview in PDF format).

      With cloud trigger, the relevant built-in Automation standard HTTP response codes are:

      HTTP Response Code

      Description

      200

      All actions executed successfully.

      500

      There were errors during action execution.

      Note

      To send feedback to Automation about the print process, enable synchronous print mode. For more information, see section Synchronous Print Mode.

    • Response type: Specifies the type of your response message. Frequently used Internet media types (also known as MIME types, or Content-types) are predefined in the drop down box. If your media type is not available in the list, type it yourself. Automation sends the response data outbound as feedback, formatted in the defined media type. Variable enables variable media types. If enabled, select or create a variable that contains media type.

      Note

      If you don't specify the Content-Type, NiceLabel Automation uses application/octet-stream as a default.

    • Response data: Defines the content of your response message. Examples of what you can send back as an HTTP response are custom error messages, label previews, generated PDF files, print stream (spool) files, XML files with details from the print engine plus the label preview (encoded as a Base64 string).

      If your output consists of binary-only content (such as label preview or print stream), make sure you select a supported media type, e.g. image/jpeg or application/octet-stream.

    • Additional headers: Allow you to define custom MIME headers for the HTTP response message.

      Response header syntax and examples are available in the HTTP Request action section.

      Tip

      With Response data and Additional headers, you can use fixed content, mix of fixed and variable content, or variable content alone. To insert variable content, click the button with an arrow to the right of the data area and insert your variable from the list. You can also create a new variable that contains the data you want to use. For more information, see section Using Compound Values.

  5. Deploy and start the trigger in Automation Manager. The cloud trigger now monitors incoming requests.

Note

If your configuration requires increased availability and scalability, you can deploy multiple identical cloud triggers. To do this, install multiple instances of Automation, and deploy the cloud triggers on them. If the deployed cloud triggers share the same Unique identifier, the built-in load balancer in NiceLabel Cloud automatically distributes the traffic load among them.

Setting up Cloud Trigger Access for the External integrator

Note

To set up the integrator's access to the cloud trigger, you must have the Manage cloud integration privilege on the cloud Control Center. See the Control Center user guide for details about managing the user privileges.

  1. Go to your cloud Control Center. Open the web browser and type:

    https://<yourlabelcloudname>.onnicelabel.com/dashboard.
  2. Go to Integrations > Cloud Integrations .

  3. Click +Add. This opens the Add New Integrator Access page.

  4. Type the Name of the integrator you are currently adding.

    UUID-48984233-2f5c-3b15-04d2-a284439f7360.png
  5. Copy the Key.

  6. Click Save.

  7. Direct the external integrator to the Developer Portal. Send the external integrator the following information:

    • Link to the NiceLabel Cloud API: https://developerportal.onnicelabel.com/

    • The integrator key (see step 5).

    • The trigger unique identifier. You can find this Unique identifier in the cloud trigger Automation configuration settings (see step 4 in section Configuring cloud trigger in Automation Builder.

    Note

    External integrator needs the key to authenticate themselves for calling the customer's cloud trigger.

Note

For more details, read the Cloud Triggers section of your Control Center user guide.

Creating subscription on the Developer Portal

After receiving the required information from the NiceLabel Cloud administrator, the external integrator must first sign up to the Developer Portal, and create subscriptions (per each customer) for calling the triggers. These trigger calls originate from the customers' cloud-based information systems.

Note

If you do not see the Developer Portal email in your Inbox, check your junk folder.

Note

Customers are companies that run cloud trigger configurations that receive the data from external information systems.

Note

Each integrator may call multiple cloud triggers using a single subscription.

  1. Open your browser and go to https://developerportal.onnicelabel.com/

  2. To complete the sign up procedure, follow the on-screen instructions. After you click Sign up, you receive a confirmation email. Click the confirmation link to activate your Developer Portal account.

  3. Open the Products tab and click Label Cloud. The page that you land on contains your APIs and existing subscriptions.

  4. Click Add subscription. The Subscribe to product page opens.

    Note

    You can create multiple subscriptions. However, a single subscription can be used for a single customer. This is why NiceLabel recommends you to include the name of the customer to the Subscription name, such as Cloud Trigger Example Customer.

  5. Type the Subscription name.

  6. Click Confirm. The newly created subscription becomes available on Products > Label Cloud.

  7. When again on the Label Cloud page, click the Developer Sign Up API v1.

  8. Click Try it. The API page opens.

    UUID-233e0250-4199-27da-0968-e7275329f997.png
  9. Insert the Integrator Key from the customer's cloud Control Center.

  10. Click Send.

    • The response is: Subscription <your subscription key> successfully associated with integrator key <integrator key value>.

    Note

    You received the integrator key from the NiceLabel Cloud administrator. The key looks like this: 979d7be5df2b473193ac5519f94cd901

    Example 26. Example

    When passing the integration key as a query parameter, the URL looks like this: https://labelcloudapi.onnicelabel.com/SignUpApi/DeveloperSignup?integratorKey=979d7be5df2b473193ac5519f94cd901.


    Once you make this call using the URL as shown in the example, the DeveloperSignup operation matches the subscription with the assigned customer. This is how the integrator authenticates themselves when calling the cloud trigger that runs in the customer's Automation.

    The connected subscriptions are also visible in the cloud Control Center. Check if the external integrator has connected their subscription under Integrations > Cloud integrations. The cloud integration should have the status Developer [name, email address] subscribed.

Calling your cloud trigger (NiceLabel Cloud deployment)

This step makes sure that the outputs of the external business systems successfully execute cloud triggers that run locally. This is the purpose of the CloudTrigger operation. In the URL of the call, specify the trigger name you are calling.

To call a trigger with the unique identifier MyCloudTrigger, use this URL:

https://labelcloudapi.onnicelabel.com/TriggerApi/CloudTrigger/MyCloudTrigger

For each event (output) in the external business system, call the URL as shown in the example. Each call executes the cloud trigger that runs on the local Automation server.

All API calls must include these two headers:

  • Api-Version is the version of the API you are using. Currently, the only available API version is v1.

  • Ocp-Apim-Subscription-Key is the key that identifies your subscription.

Testing CloudTrigger calls

To become familiar with how the CloudTrigger calls work, the Developer Portal allows you to test such calls.

Before you can test this call, you must set up a running Automation configuration.

  1. Open the Development Portal, open the Products tab, and click Label Cloud.

  2. Select Cloud Trigger API v1.

  3. Create a sample for GET or PUT methods. Click the appropriate link.

    • After you make the method selection, click Try it. A new page opens. The triggerID is already added under the Query parameters.

    • In the Value field, copy and paste the triggerID that you receive from the developer of the Automation configuration. This is the trigger's Unique identifier. The Unique identifier is available inAutomation Builder> Trigger Settings > General.

      UUID-b2a4eb67-50bc-91d5-4b8c-709a50ee1587.png
  4. Under Authorization, select the subscription key. Because you already have at least one subscription defined, the drop-down list already contains the key for the defined subscription. Select this key – either primary or secondary.

  5. Click Send.

    • Response status is 200 OK.

Quick Check if your Cloud trigger works

Once you have set up your NiceLabel Cloud API on the Developer Portal, you can make a simple configuration in Automation Builder to check if the cloud trigger works. If the trigger works, you receive the "Trigger works ok." message on the Cloud Trigger API page after you click Try it.

  1. Open Automation Builder and create a new configuration. Make sure your Automation Manager is connected to the NiceLabel Cloud.

  2. Add a new Cloud trigger.

  3. Define Name and Description, and set the Unique identifier. Let's use the TestCloudTrigger Unique identifier in this case.

  4. Enable Wait for trigger execution to finish. This allows you to track trigger responses.

    • Select text/plain as Response type.

    • Define the Response data. This is what you receive if the trigger works. Let's use the following string: "Trigger works ok."

    • Define the Additional headers. Use the Heading:Value format.

  5. Deploy the configuration.

  6. Open your developer portal and go to your Cloud Trigger API v1 page.

  7. Click Try it.

  8. Paste TestCloudTrigger to the triggerID field. Click Send.

    • Response content includes the confirmation: "Trigger works ok."

      UUID-7a2db5bb-633b-5b19-e8f2-16e863b1d8b3.png

Deploying Cloud Trigger with your on-premise Control Center

Configuring cloud trigger in Automation Builder

This section describes how to configure the cloud trigger in Automation that runs on your local server.

Open your Automation Builder. Make sure the Automation Builder is paired with your Control Center. To check, go to File > Options >Control Centerand see if the URL address of your Control Center is there.

Note

"Paired" Automation Builder and Control Center also means that both applications use the same license key.

The Configuration Items tab opens. Click Cloud Trigger to create a new configuration for the cloud trigger.

General tab
  1. Set Name and Description to make your cloud trigger easy to find among other triggers.

  2. Set the trigger Communication settings:

    • Define the Unique identifier. After you deploy the trigger, this unique identifier registers the trigger on your Control Center. Use only alphanumeric characters. Special characters are not permitted.

      If you are running the cloud trigger configuration on multiple computers, you must make sure each computer automatically uses its own unique identifier. To prevent unwanted duplications, insert internal variables as part of the Unique identifier. You can use two internal variables for this purpose:

      • ComputerName: The name of the computer on which the configuration is running.

      • SystemUserName: The Windows user name of the currently logged-in user.

      To insert internal variables to the Unique identifier, click Insert data source and select your internal variables.

      UUID-7905238a-2b2d-69c4-9856-247bdcb0320c.png
    • Wait for trigger execution to finish: The HTTP protocol requires a receiver (in this case NiceLabel Automation) to send a numeric response back to the sender indicating the status of the received message. By default, NiceLabel Automation responds with code 200. This indicates Automation successfully received the data, but gives no information about the success of trigger actions.

      This option specifies that a trigger doesn't send a response immediately after receiving the data, but waits until all actions execute. Then, it sends the response code indicating a successful action execution. With this option enabled, you can send back a custom response type and data (e.g., the response to a HTTP request is label preview in PDF format).

      With cloud trigger, the relevant built-in Automation standard HTTP response codes are:

      HTTP Response Code

      Description

      200

      All actions executed successfully.

      400

      No configuration available.

      500

      There were errors during action execution.

      Note

      To send feedback to Automation about the print process, enable synchronous print mode. For more information, see section Synchronous Print Mode.

    • Response type: Specifies the type of your response message. Frequently used Internet media types (also known as MIME types, or Content-types) are predefined in the drop down box. If your media type is not available in the list, type it yourself. Automation sends the response data outbound as feedback, formatted in the defined media type. Variable enables variable media types. If enabled, select or create a variable that contains media type.

      Note

      If you don't specify the Content-Type, NiceLabel Automation uses application/octet-stream as a default.

    • Response data: Defines the content of your response message. Examples of what you can send back as an HTTP response are custom error messages, label previews, generated PDF files, print stream (spool) files, XML files with details from the print engine plus the label preview (encoded as a Base64 string).

      If your output consists of binary-only content (such as label preview or print stream), make sure you select a supported media type, e.g. image/jpeg or application/octet-stream.

    • Additional headers: Allow you to define custom MIME headers for the HTTP response message.

      Response header syntax and examples are available in the HTTP Request action section.

      Tip

      With Response data and Additional headers, you can use fixed content, mix of fixed and variable content, or variable content alone. To insert variable content, click the button with an arrow to the right of the data area and insert your variable from the list. You can also create a new variable that contains the data you want to use. For more information, see section Using Compound Values.

Other tab

Options in the Feedback from the Print Engine section specify communication parameters that allow you to receive print engine feedback.

  • Supervised printing: Activates synchronous printing mode. Use it whenever you want to send the print job status back to the third party application. For more information, see section Synchronous Print Mode.

Options in the Data Processing section specify if you want to trim the data so that it fits into a variable, or ignore the missing label variables. By default, reports errors and breaks the printing process if you try to save values that are too long in label variables, or try to set values for non-existing label variables.

  • Ignore excessive variable contents: truncates data values that exceed the length of the variable as defined in the label designer to make them fit. This option is in effect if you are setting variable values in filters, from command files, and when you are setting values of trigger variables to label variables of the same name.

    Example 27. Example

    Label variable accepts 5 characters at maximum. With this option enabled, any value longer than 5 characters is truncated to the first 5 characters. If the value is 1234567 ignores digits 6 and 7.


  • Ignore missing label variables: When printing with command files (such as JOB file), the printing process ignores all variables that are:

    • specified in the command file (using the SET command)

    • not defined on the label

    Similar happens if you define assignment area in a filter to extract all name-value pairs, but your label contains fewer variables.

    When setting values of non-existing label variables, reports an error. If this option is enabled, the printing continues.

Options in Scripting section specify scripting possibilities.

  • Scripting language: Selects scripting language for the trigger. All Execute script actions that you use within a single trigger use the selected scripting language.

Options in the Save Received Data section specify the available commands for data that the trigger receives.

  • Save data received by the trigger to file: Enable this option to save the data received by the trigger. The option Variable enables variable file name. Select a variable that contains path and file name.

  • On error save data received by the trigger to file: Enable this option to save the data into the trigger only if an error occurs during the action execution. You might want to enable this option to keep the data that caused the issue ready for troubleshooting.

    Note

    Make sure you enable the Supervised printing support. If not, cannot detect errors during the execution. For more information, see section Synchronous Print Mode.

    Note

    saves the received data into a temporary file. This temporary file is deleted right after the trigger execution completes. The internal variable DataFileName points to that file name. For more information, see Internal Variables.

Security tab
  • Lock and encrypt trigger: Enables trigger protection. If you enable it, the trigger becomes locked and you cannot edit it any longer. This encrypts the actions. Only users with password can unlock the trigger and modify it.

Starting trigger

Deploy and start the trigger in Automation Manager. The cloud trigger now monitors for the incoming requests.

Note

If your configuration requires increased availability and scalability, you can deploy multiple identical cloud triggers. To do this, install multiple instances of Automation, and deploy the cloud triggers on them. If the deployed cloud triggers share the same Unique identifier, the built-in load balancer in NiceLabel Cloud automatically distributes the traffic load among them.

Calling the cloud trigger (On-premise deployment)

This step makes sure that the outputs of the external business systems successfully execute cloud triggers that run locally. This is the purpose of the CloudTrigger operation. In the URL of the call, specify the trigger name you are calling.

To call the trigger with your unique identifier MyCloudTrigger, call this URL:

https://<YourServerName>/epm/api/trigger/<MyCloudTriggerID>

Note

The URL might start with "http" or "https" – depending on how you set up your Control Center during the installation. See the Control Center installation guide, sections Setting up website and storage for details.

For each event (output) in the external business system, call the URL as shown in the example. Each call executes the cloud trigger that runs on the local Automation server.

All calls must include the header named Integrator-Key.

Example 28. Example

Integrator-Key: 9d59d7d444da412b8acfb488a01bb632