Web Service Trigger

Cloud_Business.png

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

Web Service trigger event occurs if a monitored socket (IP address and port number) receives data. The data must follow SOAP notation – it encodes XML data into an HTTP message. The Web Service interface is described with WSDL document. Such document is available with each defined Web Service trigger.

Web Service trigger provides feedback about print job status, but you have to enable the synchronous processing mode. For more information, see section Print Job Status Feedback.

Typically, programmers use Web Service to integrate label printing into their own applications. An existing business system executes a transaction, which sends the data to Loftware Automation server using a specific socket. The sent data is formatted as a SOAP message. The data can be provided in CSV, XML and other structured formats, or it can be provided using one of the legacy formats. In both cases, Loftware Automation reads the data, parses values using filters and prints them on labels. For more information on how to parse and extract data, see section Understanding Filters.

General

This section allows you to configure general file trigger settings.

  • Name: Specifies the unique name of the trigger. The names helps you distinguish between different triggers when you configure them in Automation Builder, and later when you run them in Automation Manager.

  • Description: Allows you to describe the role of this trigger. Help the users with a short explanation about what the trigger does.

Communication

[Note] Note

This trigger supports Internet Protocol version 6 (IPv6).

This section allows you to configure mandatory port number and optional feedback settings.

  • Port: Specifies number of the port that accepts incoming data. 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] Note

    If your server has multi-homing enabled (multiple IP addresses on one or more network cards), Loftware Automation responds on the defined port on all IP addresses.

  • Secure connection (HTTPS): Enables secure transport layer for your HTTP message and prevents eavesdropping. For more information on how to set up a secure conection, see section Using Secure Transport Layer (HTTPS).

  • Maximum number of concurrent calls: Specifies the maximum number of accepted connections. That many concurrent clients can send data to the trigger simultaneously.

  • Response data: Defines the custom response that can be used with ExecuteTriggerWithResponse and ExecuteTriggerAndSetVariablesWithResponse methods. The response data contains the content as provided in the text area. You can combine fixed values, variable values and special characters. To insert (or create) variables and special characters, click the arrow button to the right of the text area. The response can contain binary data, such as image of label preview and print file (*.PRN).

Status Feedback

By design, Web Service trigger provides feedback about the status of the created print job. The trigger accepts the provided data and uses it to execute the defined actions. You can supervise the execution of actions – the trigger reports success status for every event that happens during execution. To enable status reporting during the printing process, activate Synchronous Print Mode.

Web Service trigger exposes the following methods (functions):

  • ExecuteTrigger: This method accepts data into processing and provides optional status feedback. One of the input parameters enables or disables feedback. If you enable status reporting, feedback contains error ID and detailed description of the error. If error ID equals 0, this makes no issue while creating the print file. If error ID is greater than 0, some error occurred during the print process. Web Service response in this method is not configurable – the response always contains error ID and error description.

  • ExecuteTriggerWithResponse: This method accepts data into processing and provides custom status feedback. Web Service response is configurable. You can respond using any type of data organized in any available structure. You can use binary data in the response.

  • ExecuteTriggerAndSetVariables: Similar to the above described ExecuteTrigger, this web service exposes an additional inbound parameter that accepts the formatted list of name-value pairs. The trigger automatically parses the list, extracts values and stores values in variables of the same name, so you don't have to create any data-extraction filter yourself.

  • ExecuteTriggerAndSetVariablesWithResponse: Similar to the ExecuteTriggerWithResponse above, this web service exposes an additional inbound parameter that accepts the formatted list of name-value pairs. The trigger automatically parses the list, extracts values and stores the values in variables of the same name, so you don't have to create any data-extraction filter by yourself.

For more information about the structure of messages that you can send using one of the above listed methods, see section WSDL below.

WSDL

Web Service Description Language (WSDL) specifies style of SOAP messages. It can either be Remote Procedure Call (RPC) style or Document style. Choose the style that your data providing application supports.

WSDL document defines input and output parameters of the Web Service.

After you define the Web Service trigger on port 12345, deploy it in Automation Manager and start it. WSDL becomes available at:

http://localhost:12345

WSDL exposes several methods that all provide data into the trigger. Choose the most appropriate method for what you are trying to achieve.

  • Methods that have WithResponse in their names allow you to send customized responses, such as custom error messages, label previews, PDF files, print files (*.PRN), and similar. Methods without WithResponse in their name also provide feedback, but you cannot customize the response. The feedback contains default error messages.

  • Methods that have SetVariables in their names allow you to provide a list of variables in two predefined formats. Automation automatically extracts values and maps them to the appropriate variables. This saves you time because you don't have to set up any filter to do the extraction and mapping. For the methods without SetVariables in their names, you have to define the filter by yourself.

Web Service interface defines the following methods:

Method ExecuteTrigger

Main part of the definition is:

<wsdl:message name="WebSrviTrg_ExecuteTrigger_InputMessage">    <wsdl:part name="text" type="xsd:string"/>    <wsdl:part name="wait" type="xsd:boolean"/></wsdl:message><wsdl:message name="WebSrviTrg_ExecuteTrigger_OutputMessage"
    <wsdl:part name="ExecuteTriggerResult" type="xsd:int"/
    <wsdl:part name="errorText" type="xsd:string"/></wsdl:message>

The definition includes two input variables (you provide their values):

  • text: Filter in configuration parses this input string. Usually, the input string is structured as CSV or XML file which makes it easy to parse. You can also use any other textual file format.

  • wait: This is a Boolean field that specifies two things:

    • If you wish to wait for the print job status response or not.

    • If the Web Service should provide feedback or not.

    In case of True, use 1. In case of False, use 0. Depending on the selected method type, there is either a predefined response, or you can send a customized response.

These are the optional output variables (you receive their values, if you request them by setting wait to 1):

  • ExecuteTriggerResult: The integer response contains value 0 in case of reported data processing error(s). It contains an integer greater than 0 if there are errors. The application executing the Web Service call to Loftware Automation can use the response as error indicator.

  • errorText: This string value contains print job status response if an error occurs during trigger processing.

    [Note] Note

    If there is an error during trigger processing, this element is included in the XML response message and its value contains the error description. However, if there is no error, this element is not included in the XML response.

Method ExecuteTriggerWithResponse

You would use this method if a trigger send a custom response after it completes the execution.

Some examples of what you can send back as custom response: custom error messages, label preview, generated PDF files, print stream file (spool file), XML file with details from the print engine plus the label preview (encoded as Base64 string), the possibilities are endless.

Main part of the definition is:

<wsdl:message name="WebSrviTrg_ExecuteTriggerWithResponse_InputMessage">    <wsdl:part name="text" type="xsd:string"/>    <wsdl:part name="wait" type="xsd:boolean"/></wsdl:message><wsdl:message name="WebSrviTrg_ExecuteTriggerWithResponse_OutputMessage">    <wsdl:part name="ExecuteTriggerWithResponseResult" type="xsd:int"/>    <wsdl:part name="responseData" type="xsd:base64Binary"/>    <wsdl:part name="errorText" type="xsd:string"/></wsdl:message>

In the example above, there are two input variables (you provide their values):

  • text: Filter in configuration parses this input string. Usually, the input string is structured as CSV or XML file which makes it easy to parse. You can also use any other textual file format.

  • wait: This is a Boolean field that specifies two things:

    • If you wish to wait for the print job status response or not.

    • If the Web Service should provide feedback or not.

    In case of True, use 1. In case of False, use 0. Depending on the selected method type, there is either a predefined response, or you can send a customized response.

Furthermore, the following optional output variables are included in the example above.

[Note] Note

You receive values of optional output variables if you request them by setting the wait field value to 1.

  • ExecuteTriggerWithResponseResult: Integer response contains value 0 if there are no issues during data processing. The response contains an integer greater than 0, if there are errors. The application that executes the Web Service call to Loftware Automation can use this response as error indicator.

  • responseData: Custom response that you can define in the Web Service trigger configuration. The response is base64-encoded data.

  • errorText: If an error raises during trigger processing, this string contains the print job status response value.

    [Note] Note

    If there is an error reported during trigger processing, the XML response message includes the errorText element. Value of this element contains error description. However, if there is no error, this element is not included in the XML response.

Method ExecuteTriggerAndSetVariables

Main part of the definition is:

<wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariables_InputMessage">    <wsdl:part name="text" type="xsd:string"/>    <wsdl:part name="variableData" type="xsd:string"/>    <wsdl:part name="wait" type="xsd:boolean"/></wsdl:message>    <wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariables_OutputMessage">    <wsdl:part name="ExecuteTriggerAndSetVariablesResult" type="xsd:int"/>    <wsdl:part name="errorText" type="xsd:string"/></wsdl:message>

In the example above, there are three input variables (you provide their values):

  • text: Filter in configuration parses this input string. Usually, the input string is structured as CSV or XML file which makes it easy to parse. You can also use any other textual file format.

  • wait: This is a Boolean field that specifies two things:

    • If you wish to wait for the print job status response or not.

    • If the Web Service should provide feedback or not.

    In case of True, use 1. In case of False, use 0. Depending on the selected method type, there is either a predefined response, or you can send a customized response.

  • variableData: This is the string that contains name:value pairs. The trigger reads all pairs and assigns provided values to the trigger variables of the same name. If the variable doesn't exist in the trigger, the trigger discards that name:value pair. If you provide the list of variables and their values using this method, you don't have to define any data extraction with filters. The trigger does all the parsing for you.

    There are two available structures for the variableData content.

    XML structure

    The trigger provides variables within the <Variables /> root element of the XML file. Variable name includes attribute name, while the variable value includes element value.

    <?xml version="1.0" encoding="utf-8"?><Variables>    <variable name="Variable1">Value 1</variable>    <variable name="Variable2">Value 2</variable>    <variable name="Variable3">Value 3</variable></Variables>
    [Note] Note

    Embed your XML data inside the CDATA section. CDATA, meaning character data, is a section of element content that is marked for the parser to help it interpret the XML data as character-only data, and not as markup. As a result, the trigger handles the entire content as character data. For example, <element>ABC</element> gets interpreted as &lt;element&gt;ABC&lt;/element&gt;. Each CDATA section starts with <![CDATA[ sequence and ends with the ]]> sequence. To sum up, simply insert your XML data inside these two sequences.

    Name-value pairs

    Trigger provides variables using a text stream. Every name:value pair comes in its own line. Variable name is to the left of the equals character (=), variable value is to the right.

    Variable1="Value 1"
Variable2="Value 2"
Variable3="Value 3"

These are the optional output variables:

[Note] Note

You receive values for optional variables if you request them by setting wait to 1:

  • ExecuteTriggerAndSetVariablesResult: Integer response contains value 0 if there are no issues during data processing. It contains an integer greater than 0, if data processing reports error(s). The application that executes the Web Service call to Loftware Automation can use the response as error indicator.

  • errorText: This string value contains print job status response in case it reports a trigger processing error.

    [Note] Note

    In case of trigger processing error, this element is included in the XML response message. Its value contains error description. However, if there is no error, this element is not included in the XML response.

Method ExecuteTriggerAndSetVariablesWithResponse

You would use this method if the trigger should send a custom response after it completes the execution.

Some examples of what you can send back as custom response: custom error messages, label preview, generated PDF files, print stream file (spool file), XML file with details from the print engine plus the label preview (encoded as Base64 string), the possibilities are endless.

Main part of the definition is:

<wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariablesWithResponse_
InputMessage">    <wsdl:part name="text" type="xsd:string"/>    <wsdl:part name="variableData" type="xsd:string"/>    <wsdl:part name="wait" type="xsd:boolean"/></wsdl:message><wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariablesWithResponse_
OutputMessage">    <wsdl:part name="ExecuteTriggerAndSetVariablesWithResponseResult"
type="xsd:int"/>    <wsdl:part name="responseData" type="xsd:base64Binary"/>    <wsdl:part name="errorText" type="xsd:string"/></wsdl:message>

There are three input variables (you provide their values):

  • text: Filter in configuration parses this input string. Usually, the input string is structured as CSV or XML file which makes it easy to parse. You can also use any other textual file format.

  • wait: This is a Boolean field that specifies two things:

    • If you wish to wait for the print job status response or not.

    • If the Web Service should provide feedback or not.

    In case of True, use 1. In case of False, use 0. Depending on the selected method type, there is either a predefined response, or you can send a customized response.

  • variableData: This is the string that contains name:value pairs. The trigger reads all pairs and assigns provided values to the trigger variables of the same name. If the variable doesn't exist in the trigger, the trigger discards that name:value pair. If you provide the list of variables and their values using this method, you don't have to define any data extraction with filters. The trigger does all the parsing for you.

    There are two available structures for the variableData content.

    XML structure

    The trigger provides variables within the <Variables /> root element of the XML file. Variable name includes attribute name, while the variable value includes element value.

    <?xml version="1.0" encoding="utf-8"?><Variables>    <variable name="Variable1">Value 1</variable>    <variable name="Variable2">Value 2</variable>    <variable name="Variable3">Value 3</variable></Variables>
    [Note] Note

    Embed your XML data inside the CDATA section. CDATA, meaning character data, is a section of element content that is marked for the parser to help it interpret the XML data as character-only data, and not as markup. As a result, the trigger handles the entire content as character data. For example, <element>ABC</element> gets interpreted as &lt;element&gt;ABC&lt;/element&gt;. Each CDATA section starts with <![CDATA[ sequence and ends with the ]]> sequence. To sum up, simply insert your XML data inside these two sequences.

    Name-value pairs

    Trigger provides variables using a text stream. Every name:value pair comes in its own line. Variable name is to the left of the equals character (=), variable value is to the right.

    Variable1="Value 1"
Variable2="Value 2"
Variable3="Value 3"

These are the optional output variables:

[Note] Note

You receive their values, if you request them by setting wait to 1:

  • ExecuteTriggerAndSetVariablesWithResponseResult: Integer response contains value 0 if there are no problems during data processing. It contains an integer greater than 0 if the response reports error(s). The application executing the Web Service call to Loftware Automation can use the response as error indicator.

  • responseData: Custom response that you can define in the Web Service trigger configuration. The response is base64-encoded data.

  • errorText: This string value contains print job status response in case it reports a trigger processing error.

    [Note] Note

    In case of trigger processing error, this element is included in the XML response message. Its value contains error description. However, if there is no error, this element is not included in the XML response.

Other

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

Cloud_Business.png

  • 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 25. 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] Note

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

    Automation 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

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