Deploying Cloud Trigger with Loftware Cloud

Deployment Stages for Loftware Cloud

To enable local label printing using the cloud trigger deployed in Loftware 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 Loftware Cloud, and a user that makes the subscription on the Developer Portal.

The developer configures and deploys the cloud trigger configuration on the local Automation server using Automation Builder and Automation Manager.

	Note
	LoftwareAutomation must be signed in to the Loftware Cloud.

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

The external integrator joins the Developer Portal to bring the customer's business system and the Loftware 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:

Signing in to the Developer Portal. Before the first sign-in, the integrator must also finish the sign up procedure.
Creating a subscription for the Cloud Trigger API.
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 Loftware 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.

Open your Automation Builder. Make sure the Automation Builder is signed in to Loftware Cloud. Go to File > About > Loftware Cloud account to confirm that you are signed in.
The Configuration Items tab opens. Click Cloud Trigger to create a new configuration for the cloud trigger.
Set Name and Description to make your cloud trigger easy to find among other triggers.

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.

Wait for trigger execution to finish: The HTTP protocol requires a receiver (in this case Loftware Automation) to send a numeric response back to the sender indicating the status of the received message. By default, Loftware 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, Loftware 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.

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.

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 Loftware 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.

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

                                https://<yourlabelcloudname>.onnicelabel.com/dashboard.

Go to Integrations > Cloud Integrations .
Click +Add. This opens the Add New Integrator Access page.
Type the Name of the integrator you are currently adding.
Copy the Key.
Click Save.

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

Link to the Loftware 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 subscriptions on the Developer Portal

After receiving the required information from the Loftware 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.

To set up your Developer Portal account and create subscriptions, follow the steps in Cloud Integrations.

Calling your cloud trigger (Loftware 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.

Open the Development Portal, open the Products tab, and click Label Cloud.
Select Cloud Trigger API v1.

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.

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.
Click Send.
- Response status is 200 OK.

Quick Check if your Cloud trigger works

Once you have set up your Loftware 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.

Open Automation Builder and create a new configuration. Make sure your Automation Manager is connected to the Loftware Cloud.
Add a new Cloud trigger.
Define Name and Description, and set the Unique identifier. Let's use the TestCloudTrigger Unique identifier in this case.
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.
Deploy the configuration.
Open your developer portal and go to your Cloud Trigger API v1 page.
Click Try it.

Paste TestCloudTrigger to the triggerID field. Click Send.

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