HTTP Server Trigger

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

HTTP server trigger fires if data is received on the monitored socket (IP address and port number).

Contrary to TCP/IP trigger, the received data is not a raw data stream, but includes standard HTTP header. Third party applications must use POST or GET request methods. They must provide data in message body or in query string. You can use both Internet media types in the message body – MIME Type, or Content-Type. NiceLabel Automation receives the message and extracts relevant data from the message content using a filter.

Typical use: Existing business system executes a transaction which sends data to NiceLabel Automation server formatted as HTTP POST message to a specific socket. The sent data might be structured in CSV, XML and other formats, or it can be structured using a proprietary legacy format. Either way, NiceLabel Automation reads the data, parses values using filters and prints the extracted data on labels. For more information on how to parse and extract data, see section Understanding Filters.

Providing data

Provide the HTTP trigger data using any of the following methods. You can also combine the methods if needed, and use both in the same HTTP request.

Data in the query string

Query string is a part of the uniform resource locator (URL) that contains data to be passed to the HTTP trigger.

Example of a typical URL that contains query string:

http://server/path/?query_string

Question mark is used as a separator and is not part of the query string.

Query string is usually composed of a series of name:value pairs. Within each pair, field name and value are separated by equals sign (=). Series of pairs are separated by ampersand (&). A typical query string provide values for fields (variables) in the following format:

field1=value1&field2=value2&field3=value3

HTTP trigger offers built-in support for extracting values from all fields, and for storing them in variables that carry the same name. As a result, you don't have to define any filters to extract values from the query string.

You don't have to define variables inside a trigger to populate them with values from the query string. NiceLabel Automation extracts all variables in the query string and sends their values to the currently active label. If variables of the same name exist in the label, Automation populates them with values. If the variables do not exist in the label, Automation ignores their values without reporting any errors.
If an action requires variable values, define matching variables in the trigger. To get and store all values from the query string, create matching variables using the same names as fields in the query string. For the example above, define trigger variables with names field1, field2 and field3.

You would usually use GET HTTP request method to provide the query string.

Data in body of HTTP request

Use POST request method to provide message in the body of an HTTP request.

You are free to send any type of data or use any data structure that you want in the body. You only need to ensure that you can handle the data using NiceLabel Automation filters. The content can be formatted as XML, CSV, or plain text. Sent content can even be binary data (Base64-encoded). Bare in mind that you have to parse the data with filters.

If you can affect the structure of the incoming message, use standardized structures, such as XML or CSV to simplify the filter configuration.

Use POST HTTP request method to provide the data in message body.

Communication

Note

This trigger supports Internet Protocol version 6 (IPv6).

This section allows you to configure the mandatory port number and optional feedback options. You can use standard HTTP Response Codes to indicate a successfully executed action. For more advanced purposes, you can also send the custom content back to the data-providing application. Such content may be a simple feedback string, or binary data, such as label preview or print stream.

Typical URL to connect to an HTTP trigger is as follows:

http://server:port/path/?query_string

Server: This is the FQDN or IP address of the machine where NiceLabel Automation is installed.
Port: Number of the port on which incoming data is received. Use a port number that is not in use by any other application. If the selected port is in use, you won't be able to start the trigger in Automation Manager. For more information about security concerns, see section Securing Access to your Triggers.

Note

If multi-homing is enabled on your server (multiple IP addresses on one or more network cards), NiceLabel Automation responds on the defined port on all IP addresses.
Path: Specifies optional path in the URL. This functionality enables NiceLabel Automation to expose multiple HTTP triggers on the same port. The client uses the triggers through a single port in a REST like syntax causing different triggers to be fired by different URLs. If you are not sure what to use, leave the default path (\).
Secure connection (HTTPS): Enables secure transport layer for your HTTP messages and prevents eavesdropping. For more information on how to set it up, see section Using Secure Transport Layer (HTTPS).
Query string: Specifies name-value pairs in the URL. This an optional parameter. The data is usually provided in the body of the HTTP request.

Wait for trigger execution to finish: 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 that 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 are executed. After that, 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).

The available built-in HTTP response codes are:

HTTP Response Code	Description
200	All actions executed successfully.
401	Unauthorized, wrong user name and password were specified.
500	There were errors during action execution.

Note

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

Maximum number of concurrent requests: Specifies the maximum number of concurrent inbound connections. That many concurrent clients can send data to the trigger simultaneously. This number also depends on the hardware performance of your server.

Learn more about Parallel Processing.
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, enter it by yourself. Automation sends the response data outbound as feedback, formatted in the defined media type. Variable enables variable media type. 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 the default one.
Response data: Defines content of the response message. Examples of what you can send back as an HTTP response are custom error messages, label preview, generated PDF files, print stream (spool) file, XML file with details from the print engine plus the label preview (encoded as Base64 string). The possibilities are countless.

If your output will consist of binary-only content (such as label preview or print stream), make sure you select a proper 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 example 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 arrow to the right of data area and insert variable from the list (or create a new one) that contains the data you want to use. For more information, see section Using Compound Values.

Authentication

None: No authentication method is in use.
User: Specifies that incoming messages include user name and password. When in use, the trigger only accepts HTTP messages with matching credentials. For more information about security concerns, see section Securing Access to your Triggers.
Application Group (defined in NiceLabel Control Center): As in case with User authentication type, this option also specifies that the incoming messages include user name and password. When in use, the trigger only accepts HTTP messages with adequate credentials for NiceLabel Control Center users who belong to a specific application group.
- Group: Multiple application groups can be defined on the NiceLabel Control Center. To select which group should be allowed to access the HTTP Server Trigger, use the Group drop-down list. The selected group and its users must be set as active when the trigger is running.
  
  Note
  
  Group with a specified name must exist on NiceLabel Control Center when the trigger is running. While working on the configuration in Automation Builder, you can use any group name. Make sure you eventually define a final name on NiceLabel Control Center and match it in the configuration before deploying it.
  
  Tip
  
  The users authenticate themselves using their credentials as defined in NiceLabel Control Center , Users tab. Refer to NiceLabel Control Center User Guide for details on user management (section Users and Groups).

Other

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