Understanding Filters

Loftware Automation uses filters to define structure of the data received by triggers. Each time a trigger receives data, one or many filters parse the received data. This process extracts relevant values for your configuration. Each filter includes rules to identify fields within received data.

	Note
	As a result, the filter provides a list of fields and their values (`name:value` pairs).

Filter Types

For more information, see sections Structured Text Filter, Unstructured Data Filter, XML filter, and JSON Filter.

Data Structure

Filter complexity depends on the data structure. Files with structured data, such as CSV or XML files, make data extraction easy. In this case, field names are already defined by the data. Extraction of name:value pairs is quick. In case of data without a clear structure, it takes more time to define the extraction rules. You might come across such data when exporting documents and reports from legacy systems, intercepted communication between devices, and captured print streams.

The filter defines a list of fields that are extracted from the incoming data once you run the filter.

Loftware Automation supports various types of input data that can all be parsed by one of the supported filter types. Make sure you select the correct filter to match the type of incoming data. For example, you would use Structured Text filter for incoming CSV data, JSON filter for incoming JSON data, and XML filter for incoming XML data. For any unstructured data, you would use Unstructured Data filter. For more information, see section Understanding Data Structures.

Extracting Data

Filter is a set of rules and doesn't do any extraction by itself. To run the filter, run the Use Data Filter action. This action executes filter rules against the data and extracts the values.

Each trigger type can execute as many Use Data Filter actions as necessary. If you receive compound input data that cannot be parsed by a single filer alone, define multiple filters and execute their rules using a sequence of Use Data Filter actions. Finally, use the extracted values from all actions on the same label.

Mapping Fields to Variables

To use the extracted values, you have to store them in variables. The Use Data Filter action does both – extracts values and saves them in variables. To configure this process, map each variable with the respective field. The value of the field is then saved in the mapped variable.

	Tip
	It's a good practice to define fields and variables with matching names. In this case, the auto-mapping feature links variables to the fields of the same names, eliminating the need for manual mapping.

Auto-mapping is available for all supported filter types. With auto-mapping enabled, the Use Data Filter action extracts values and automatically maps them to the variables with the same names as field names. For more information, see the section Enabling Dynamic Structure for Structured Text filter, Defining Assignment Area for Unstructured Data filter, and Defining Assignment Area for XML or JSON filters.

Running Actions with Extracted Data

Usually, you want to run actions using the extracted data, such as Open Label, Print Label, or some of the outbound connectivity actions. It is critically important that you nest your actions under the Use Data Filter action. This ensures that the nested actions are run for each data extraction.

Example 1. Example

If you have a CSV file with 5 lines, the nested actions also run for 5 times; once for each data extraction. If the actions are not nested, they only execute once and only contain data from the last data extraction. As for the example above, the 5th CSV line would be printed leaving out the first four lines unprinted. If you use Sub Areas, make sure you nest your action under the correct placeholder.

Configuring Structured Text Filter

Structured Text Filter

To learn more about filters in general, see section Understanding Filters.

Use this filter whenever you receive a structured text file. These are the text files in which the fields are identified by one of the following methods:

Fields are delimited by a character: Usual delimiter characters are comma or semicolon. CSV (comma separated values) is a typical example of a delimited file.
Fields contain fixed number of characters: In other words, fields are defined by fixed-width columns.

For examples of structured text data, see section Text Database.

Defining Structure

To define the structure of a text file, you have the following options:

Importing structure using the Text File Wizard: In this case, click the Import Data Structure button in the ribbon and follow the on-screen instructions. After you finish the wizard, the type of text database and all fields are defined. If the first line of data contains field names, the Wizard can import them. This is the recommended method, if the trigger always receives data whose structure does not change.
Manually defining the fields: In this case, you have to manually define the type of data (delimited fields or fixed-width fields) and then define the field names. For more information, see section Defining Fields.
Dynamically read the fields: In this case, the trigger might receive data that is structured in a different way. An example for this are new field names – dynamic structure eliminates the need to update the filter for each structural change. Support for dynamic structure automatically reads all data fields, no matter if new fields exist or if some of the old fields are missing. It maps them automatically with the variables using the same names. For more information, see section Enabling Dynamic Structure.

Data Preview section simplifies the configuration. In the preview pane, the result of a defined filter rule highlights the area along with every configuration change. Data Preview enables you to check what data is extracted with each rule.

Defining Fields

For structured text files, the definition of fields is very straightforward. There are two options:

Delimiter defines the fields: In this case, you have a delimiting character, such as comma or semicolon separating the fields. You just have to define the field names in the same order as they appear in the data received by a trigger.
Fixed-width fields: In this case, define the field names in the same order as they appear in the data received by a trigger, and define the number of characters the field would occupy. That many characters are going to be read from the data for this field.

Data Preview

This section provides preview of the field definition. If the defined item is selected, the preview highlights its placement in the preview data.

Preview file name: Specifies the file that contains sample data that is going to be parsed by the filter. The preview file is copied from filter definition. If you change the preview file name, the new file name is saved.
Open: Selects another file upon which you want to execute the filter rules.
Refresh: Re-runs the filter rules upon the contents of the preview file name. Automation updates the Data Preview section with the result.

Formatting Options

This section defines string manipulation functions that apply on the selected variables or fields. You can select one or several functions. These functions are applied in the same order as selected in the user interface – from top to bottom.

Delete spaces at the beginning: Deletes all space characters (decimal ASCII code 32) from the beginning of a string.
Delete spaces at the end: Deletes all space characters (decimal ASCII value 32) from the end of a string.
Delete opening and closing character: Deletes the first occurrence of the selected opening, and closing characters that are found in a string.

Example 2. Example

If you use "{" for the opening character and "}" for the closing character, the input string {{selection}} converts to {selection}.

Search and replace: Executes standard search and replace function upon the provided values for find what and replace with. You can also use regular expressions.

	Note
	There are several implementations of the regular expressions in use. uses the .NET Framework syntax for the regular expressions. For more information, see the Knowledge Base article.

Replace non printable characters with spaces: Replaces all control characters in the string with space character (decimal ASCII code 32). The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Delete non printable characters: Deletes all control characters in the string. The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Decode special characters: Special characters (or control codes) are characters that are not available on the keyboard, such as Carriage Return or Line Feed. uses a notation to encode such characters in human-readable form, such as <CR> for Carriage Return and <LF> for Line Feed. For more information, see section Entering Special Characters (Control Codes).

This option converts special characters from syntax into actual binary characters.

Example 3. Example

When you receive the data sequence "<CR><LF>", uses it as a as plain string of 8 characters. Enable this option to interpret and use the received data as two binary characters CR (Carriage Return - ASCII code 13) and LF (Line Feed - ASCII code 10).
Search and delete everything before: Finds the provided string and deletes all characters from the beginning of the data until the string. The found string itself can also be deleted.
Search and delete everything after: Finds the provided string and deletes all characters from the string until the end of the data. The found string itself can also be deleted.
Change case: Changes all characters in your strings to uppercase or lowercase.

Enabling Dynamic Structure

Structured Text filter has the ability to automatically identify fields and their values within the received data. This eliminates the need for manual variable-to-field mapping.

Dynamic structure functionality is helpful if the trigger receives data with changing structure. In such cases, main data structure remains unchanged (e.g., fields are delimited by a comma), or retains the same structure, but the order and/or the number of fields changes. There might be new fields, or some of the old fields could no longer be available. Because of enabled Dynamic structure, filter automatically identifies structure of the received file. At the same time, filter reads field names and values (name:value pairs) from the data. This eliminates the need for manual mapping of fields to variables.

Use Data Filter action does not offer any mapping possibilities, because it performs the mapping dynamically. You don't even have to define label variables in the trigger configuration. The action assigns field values to the label variables of the same name without requiring the variables to be imported from the label. However, this rule applies to the Print Label action alone. If you want to use the field values in any other action, you have to define variables in the trigger, while still keeping the automatic variable-to-field mapping.

	Note
	There is no error if the field available in the input data doesn't have a matching label variable. Loftware Automation silently ignores the missing variables.

Configuring the dynamic structure

To configure the dynamic structure, enable the Dynamic structure option in Structured Text filter properties.

The first line of data must contain field names.
The line that you select for Start import at line must be the line with the field names (usually the first line in data).
Data structure must be delimited.
You can format the data, if necessary.

Formatting Options

Delete spaces at the beginning: Deletes all space characters (decimal ASCII code 32) from the beginning of a string.
Delete spaces at the end: Deletes all space characters (decimal ASCII value 32) from the end of a string.
Delete opening and closing character: Deletes the first occurrence of the selected opening, and closing characters that are found in a string.

Example 4. Example

If you use "{" for the opening character and "}" for the closing character, the input string {{selection}} converts to {selection}.

Search and replace: Executes standard search and replace function upon the provided values for find what and replace with. You can also use regular expressions.

	Note
	There are several implementations of the regular expressions in use. uses the .NET Framework syntax for the regular expressions. For more information, see the Knowledge Base article.

Replace non printable characters with spaces: Replaces all control characters in the string with space character (decimal ASCII code 32). The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Delete non printable characters: Deletes all control characters in the string. The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Decode special characters: Special characters (or control codes) are characters that are not available on the keyboard, such as Carriage Return or Line Feed. uses a notation to encode such characters in human-readable form, such as <CR> for Carriage Return and <LF> for Line Feed. For more information, see section Entering Special Characters (Control Codes).

This option converts special characters from syntax into actual binary characters.

Example 5. Example

When you receive the data sequence "<CR><LF>", uses it as a as plain string of 8 characters. Enable this option to interpret and use the received data as two binary characters CR (Carriage Return - ASCII code 13) and LF (Line Feed - ASCII code 10).
Search and delete everything before: Finds the provided string and deletes all characters from the beginning of the data until the string. The found string itself can also be deleted.
Search and delete everything after: Finds the provided string and deletes all characters from the string until the end of the data. The found string itself can also be deleted.
Change case: Changes all characters in your strings to uppercase or lowercase.

Configuring Unstructured Data Filter

Unstructured Data Filter

To learn more about filters in general, see section Understanding Filters.

Use this filter whenever a trigger receives non-structured data, such as documents and reports exported from legacy system, intercepted communication between devices, and captured print stream. The filter allows you to extract individual fields, fields in repeatable sub areas, and even name-value pairs.

For examples of the structured text data, see sections Legacy Data, Compound CSV and Binary Files.

Defining Structure

The items you can use to configure the filter:

Field: Specifies the location of field data between field-start and field-end locations. There are various options to define the field location, from hard-coding the position to enabling relative placements. You must map the defined fields to respective variables in the Use Data Filter action. For more information, see section Defining Fields.
Sub area: Specifies the location of repeatable data. Each sub area defines at least one data block, which in turn contains data for labels. There can be sub areas defined within sub areas, which allows you to define complex structures. You can define fields within each data block. You must map the defined fields to respective variables in the action. For each sub area, Automation defines a new level of placeholder within the Use Data Filter action, so you can map variables to fields of that level. For more information, see section Defining Sub Areas.
Assignment area: Specifies the location of repeatable data containing the name-value pairs. Automation reads field names and their values simultaneously. Automation also automatically performs mapping to variables. Use this feature to accommodate filter to the changing input data, eliminating the maintenance time. You can define the assignment area at the root level of the document, or inside the sub area. For more information, see section Defining Assignment Areas.

Data Preview section simplifies the configuration. The result of a defined filter rule gets highlighted in the preview area along with every configuration change. You can observe which data items would be extracted with each rule.

The fields can be defined at the root level as document fields. The fields can be defined inside a data block. The name-value pairs can be defined inside assignment area.

General

This section defines general properties of the unstructured data filter.

Name: Specifies the filter name. Use a descriptive name that identifies the role of the filter in a configuration. You can change it anytime.
Description: Allows you to describe the purpose of this filter. You can use it to write a short explanation about what does the filter do.
Encoding: Specifies the encoding of the data this filter works with.
Ignore empty lines in data blocks: Specifies not to raise errors if the filter extracts empty field values from the data blocks.

Defining Fields

After you define a field, you have to define its name and rules for extracting field values from the data. When the filter executes, the extraction rules apply to the input data and assign result to the field.

Field Properties

Name: Specifies the unique name of the field.
Field has binary data: Specifies that the field contains binary data. Don't enable this option unless you really expect to receive binary data.

Field Start

Position in document: Hard-coded position in the data determines the start/end point. The coordinate origin is upper left corner. The character in the defined position is included in the extracted data.
End of document: The start/end point is at the end of the document. You can also define an offset from the end for a specified number of lines and/or characters.
Find string from start of document: Position of searched-for string defines the start/end point. After Automation finds the required string, the next character determines the start/end point. The searched-for string is not included in the extracted data. The default search is case sensitive.
- Start search from absolute position: You can fine-tune searching by changing the start position from data-start (position 1,1) to an offset. Use this feature to skip searching at the beginning of data.
- Occurrence: Specifies which occurrence of the search string should be matched. Use this option if you don't wait to set start/stop position after the first found string.
- Offset from string: Specifies the positive or negative offset after the searched-for string.
  
  Example 6. Example
  
  You would define the offset to include the searched-for string in the extracted data.

Field End

Position in document: Hard-coded position in the data determines the start/end point. The coordinate origin is upper left corner. The character in the defined position is included in the extracted data.
End of document: The start/end point is at the end of the document. You can also define an offset from the end for a specified number of lines and/or characters.
Find string from start of document: Position of searched-for string defines the start/end point. After Automation finds the required string, the next character determines the start/end point. The searched-for string is not included in the extracted data. The default search is case sensitive.
- Start search from absolute position: You can fine-tune searching by changing the start position from data-start (position 1,1) to an offset. Use this feature to skip searching at the beginning of data.
- Occurrence: Specifies which occurrence of the search string should be matched. Use this option if you don't wait to set start/stop position after the first found string.
- Offset from string: Specifies the positive or negative offset after the searched-for string.
  
  Example 7. Example
  
  You would define the offset to include the searched-for string in the extracted data.

Find string after field start: The start/stop end point is defined by the position of the searched-for-string as in the option Find string from start of document, but the search starts after the start position of the field/area, not at the beginning of the data.
Length: Specifies the length of the data in lines and/or characters. The specified number of lines and/or characters will be extracted from the start position.
End of the line: Sets the configuration to extract the data from the start position until the end of the same line. You can define a negative offset from the end of the line.

Formatting Options

Delete spaces at the beginning: Deletes all space characters (decimal ASCII code 32) from the beginning of a string.
Delete spaces at the end: Deletes all space characters (decimal ASCII value 32) from the end of a string.
Delete opening and closing character: Deletes the first occurrence of the selected opening, and closing characters that are found in a string.

Example 8. Example

If you use "{" for the opening character and "}" for the closing character, the input string {{selection}} converts to {selection}.

Search and replace: Executes standard search and replace function upon the provided values for find what and replace with. You can also use regular expressions.

	Note
	There are several implementations of the regular expressions in use. uses the .NET Framework syntax for the regular expressions. For more information, see the Knowledge Base article.

Replace non printable characters with spaces: Replaces all control characters in the string with space character (decimal ASCII code 32). The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Delete non printable characters: Deletes all control characters in the string. The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Decode special characters: Special characters (or control codes) are characters that are not available on the keyboard, such as Carriage Return or Line Feed. uses a notation to encode such characters in human-readable form, such as <CR> for Carriage Return and <LF> for Line Feed. For more information, see section Entering Special Characters (Control Codes).

This option converts special characters from syntax into actual binary characters.

Example 9. Example

When you receive the data sequence "<CR><LF>", uses it as a as plain string of 8 characters. Enable this option to interpret and use the received data as two binary characters CR (Carriage Return - ASCII code 13) and LF (Line Feed - ASCII code 10).
Search and delete everything before: Finds the provided string and deletes all characters from the beginning of the data until the string. The found string itself can also be deleted.
Search and delete everything after: Finds the provided string and deletes all characters from the string until the end of the data. The found string itself can also be deleted.
Change case: Changes all characters in your strings to uppercase or lowercase.

Defining Sub Areas

Sub area is a section of data that includes several blocks of data identified by the same extraction rule. Each data block provides data for a single label.

All data blocks must be identified by the same configuration rule. Each data block can contain another sub area. You can define an unlimited number of nested sub areas within parent sub areas.

If the filter contains definition of a sub area, the Use Data Filter action displays sub areas with nested placeholders. All actions nested below such placeholder execute only for data blocks at this level. You can print different labels with data from different sub areas.

Configuring Sub Area

The sub area is defined with similar rules as individual fields. Each sub area is defined by the following parameters.

Sub Area Name: Specifies the name of the sub area.
Data Blocks: Specifies how to identify data blocks within the sub area. Each sub area contains at least one data block. Each data block provides data for a single label.
- Each block contains fixed number of lines: Specifies that each data block in a sub area contains the provided fixed number of lines. Use this option if you know that each data block contains exactly the same number of lines.
- Blocks start with a string: Specifies that data blocks begin with the provided string. All content between the two provided strings belongs to a separate data block. The content between last string and the end of the data identifies the last data block.
- Blocks end with a string: Specifies that data blocks end with the provided string. All content between the two provided strings belongs to a separate data block. The content between the beginning of data and the first string identifies the first data block.
- Blocks are separated by a string: Specifies that data blocks are separated with the selected string of characters. All content between the two selected strings belongs to a separate data block.
Beginning of First Data Block: Specifies the starting position of the first data block. At the same time, it defines the starting position of the sub area. Usually, the starting position is also the beginning of the received data. The configuration parameters are the same as for defining fields. For more information, see section Defining Fields.
End of Last Data Block: Specifies the ending position of the last data block. At the same time, it defines the ending position of the sub area. Usually, ending position is at the end of the received data. The configuration parameters are the same as for defining fields. For more information, see section Defining Fields.

Configuring Fields Inside Sub Area

Fields inside the sub area are configured using the same parameters as fields defined at root level. For more information, see section Defining Fields.

	Note
	The field lines numbers refer to the position within data block, not position within the input data.

Data Preview

This section provides preview of the field definition. If the defined item is selected, the preview highlights its placement in the preview data.

Preview file name: Specifies the file that contains sample data that is going to be parsed by the filter. The preview file is copied from filter definition. If you change the preview file name, the new file name is saved.
Open: Selects another file upon which you want to execute the filter rules.
Refresh: Re-runs the filter rules upon the contents of the preview file name. Automation updates the Data Preview section with the result.

Defining Assignment Areas

Unstructured Data filter automatically identifies fields and their values in the received data. This makes manual variable to field mapping unnecessary.

	Note
	There is no error if the field available in the input data doesn't have a matching label variable. Loftware Automation silently ignores the missing variables.

Configuring Assignment Area

The assignment area is configured using the same procedure as sub area. For more information, see section Defining Sub Areas. The assignment area can be defined on the root data level, appearing just once. Or it can be configured inside a sub area, so it executes for each data block in the sub area.

Configuring Fields in Assignment Area

When you create an assignment area, the filter automatically defines two placeholders. These two placeholders define the name:value pair.

Variable name: Specifies the field whose content is taken as variable name (name component in a pair). Configure the field using the same procedure as for document fields. For more information, see section Defining Fields.
Variable value: Specifies the field whose contents is taken as variable value (value component in a pair). Configure the field using the same procedure as for document fields. For more information, see section Defining Fields.

Example

The area between ^XA and ^XZ is assignment area. Every line in assignment area provides a name:value pair. Name is defined as the value between 6th character in the line and equal character. Value is defined as the value between "equals" character and end of the line with negative offset of three characters.

^XA
^FD01DonationHR=G095605 3412625^FS
^FD02DonationBC=DG0956053412625^FS
^FD03HospitalNoHR=HN060241^FS
^FD04HospitalNoBC=060241^FS
^FD05Surname=Hawley^FS
^FD07Forename=Annie^FS
^FD09Product=Blood^FS
^FD10PatientBlGp=O Rh +ve^FS
^FD11DoB=27 June 1947^FS
^FD12DateReqd=25 Dec 2012^FS
^XZ

Configuring XML filter

XML Filter

To learn more about filters in general, see section Understanding Filters.

Use this filter whenever a trigger receives XML-encoded data. The filter allows you to extract individual fields, fields in repeatable sub areas, and even name-value pairs. XML structure defines elements and sub elements, attributes and their values, and textual values (element values).

While you can define the structure of the XML file by yourself, Loftware recommends you to import the structure from the existing sample XML file. Click Import Data Structure button on the ribbon. After you import the XML structure, the Data Preview section displays the XML contents. It also highlights the elements and attributes that you define as output fields.

For XML data examples, see section XML Data.

Defining Structure

To use the XML items, configure them as:

Variable value: Specifies that you want to use the selected item as a field and that you will map its value to respective variables in Use Data Filter action. For more information, see section Defining XML Fields.
- Optional element: Specifies that the element is not mandatory. This corresponds with XML schema (XSD file) attribute minOccurs=0. The variable mapped to such field will have an empty value if the element does not appear in the XML.
Data block: Specifies that the selected element occurs multiple times and provides data for a single label. Data block can be defined as repeatable area, assignment area, or both.
- Repeatable area: Specifies that you want to extract values from all repeatable data blocks, not just from the first one. You can define fields within each data block. Map the defined fields to respective variables in Use Data Filter action. For more information, see section Defining Repeatable Elements.
- Assignment area: Specifies that the data block contains name-value pairs. Field names and their values are read simultaneously. Mapping to variables is done automatically. Use this feature to accommodate the filter to changing input data, eliminating the maintenance time. For more information, see section Defining XML Assignment Area.

The Data Preview section simplifies the configuration. The result of a defined filter rule is highlighted in the preview area.

To change the previewed XML data, click Open and browse for a new sample XML file.

Defining XML Fields

If you define XML fields, you make values of selected items automatically available. Filter definition makes such fields available for mapping to variables in actions. This allows you to extract values of elements or attributes.

To define an item value as field, do the following:

Select the element or attribute in the structure list.
For Usage, select Variable value.
The item is displayed on the structure list with bold letters, indicating that it is in use.
The element or attribute name is used as output field name.
The Data Preview section highlights the value of the selected item.

Formatting Options

Delete spaces at the beginning: Deletes all space characters (decimal ASCII code 32) from the beginning of a string.
Delete spaces at the end: Deletes all space characters (decimal ASCII value 32) from the end of a string.
Delete opening and closing character: Deletes the first occurrence of the selected opening, and closing characters that are found in a string.

Example 10. Example

If you use "{" for the opening character and "}" for the closing character, the input string {{selection}} converts to {selection}.

Search and replace: Executes standard search and replace function upon the provided values for find what and replace with. You can also use regular expressions.

	Note
	There are several implementations of the regular expressions in use. uses the .NET Framework syntax for the regular expressions. For more information, see the Knowledge Base article.

Replace non printable characters with spaces: Replaces all control characters in the string with space character (decimal ASCII code 32). The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Delete non printable characters: Deletes all control characters in the string. The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Decode special characters: Special characters (or control codes) are characters that are not available on the keyboard, such as Carriage Return or Line Feed. uses a notation to encode such characters in human-readable form, such as <CR> for Carriage Return and <LF> for Line Feed. For more information, see section Entering Special Characters (Control Codes).

This option converts special characters from syntax into actual binary characters.

Example 11. Example

When you receive the data sequence "<CR><LF>", uses it as a as plain string of 8 characters. Enable this option to interpret and use the received data as two binary characters CR (Carriage Return - ASCII code 13) and LF (Line Feed - ASCII code 10).
Search and delete everything before: Finds the provided string and deletes all characters from the beginning of the data until the string. The found string itself can also be deleted.
Search and delete everything after: Finds the provided string and deletes all characters from the string until the end of the data. The found string itself can also be deleted.
Change case: Changes all characters in your strings to uppercase or lowercase.

Data Preview

This section provides preview of the field definition. If the defined item is selected, the preview highlights its placement in the preview data.

Preview file name: Specifies the file that contains sample data that is going to be parsed by the filter. The preview file is copied from filter definition. If you change the preview file name, the new file name is saved.
Open: Selects another file upon which you want to execute the filter rules.
Refresh: Re-runs the filter rules upon the contents of the preview file name. Automation updates the Data Preview section with the result.

Defining Repeatable Elements in XML Filter

If an XML element occurs in XML data for multiple times, it is a repeatable element. Usually, a repeatable element contains data for a single label. To indicate that you want to use data from all repeatable elements, and not just from the first one, define the element as a Data block and enable the Repeatable element option. If the filter contains definition of elements defined as data block / repeatable element, the Use Data Filter action displays repeatable elements with nested placeholders. All actions nested below such a placeholder execute only for data blocks at this level.

Example

The <item> element is defined as Data block and Repeatable element. This instructs the filter to extract all occurrences of the <item> element, not just the first one. In this case, the <item> should be defined as the sub-level in Use Data Filter action. You must nest the actions Open Label and Print Label under this sub-level placeholder, so they are going to be looped for as many times as there are occurrences of the <item> element. As shown in the example below, for three times.

<?xml ver sion="1.0" encoding="utf-8"?><asx:abap xmlns:asx="http://www.sap.com/abapxml" ver sion="1.0"> <asx:values>  <NICELABEL_JOB>   <T IMEST AMP>20130221100527.788134</T IMEST AMP>   <USER>PGRI</USER>   <IT _LABEL_DAT A>   <item>      <LBL_NAME>goods_r eceipt.nlbl</LBL_NAME>      <LBL_PRINT ER>Pr oduction01</LBL_PRINT ER>      <LBL_QUANT IT Y>1</LBL_QUANT IT Y>      <MAKT X>MASS ONE</MAKT X>      <MAT NR>28345</MAT NR>      <MEINS>KG</MEINS>      <WDAT U>19.01.2012</WDAT U>      <QUANT IT Y>1</QUANT IT Y>      <EXIDV>012345678901234560</EXIDV>   </item>   <item>      <LBL_NAME>goods_r eceipt.nlbl</LBL_NAME>      <LBL_PRINT ER>Pr oduction01</LBL_PRINT ER>      <LBL_QUANT IT Y>1</LBL_QUANT IT Y>      <MAKT X>MASS T WO</MAKT X>      <MAT NR>28346</MAT NR>      <MEINS>KG</MEINS>      <WDAT U>11.01.2011</WDAT U>      <QUANT IT Y>1</QUANT IT Y>      <EXIDV>012345678901234577</EXIDV>   </item>   <item>      <LBL_NAME>goods_r eceipt.nlbl</LBL_NAME>      <LBL_PRINT ER>Pr oduction01</LBL_PRINT ER>      <LBL_QUANT IT Y>1</LBL_QUANT IT Y>      <MAKT X>MASS T HREE</MAKT X>      <MAT NR>27844</MAT NR>      <MEINS>KG</MEINS>      <WDAT U>07.03.2009</WDAT U>      <QUANT IT Y>1</QUANT IT Y>      <EXIDV>012345678901234584</EXIDV>   </item>  </IT _LABEL_DAT A> </NICELABEL_JOB> </asx:values></asx:abap>

Warning

XML data filter with nested data block duplicates values from previous assignment area if a variable is defined in the first block but not in the second. For example, you print two labels. In the first assignment area, you defined a variable <manufacturer_serial>. In the second assignment area, this variable is not present.

<?xml ver sion="1.0" encoding="utf-8"?><asx:abap xmlns:asx="http://www.sap.com/abapxml" ver sion="1.0">    <jobs>      <element>         <data>            <item>               <manufacturer_serial>706583012001</manufacturer_serial>               <package_code>AA792CY</package_code>            </item>         </data>         <label_filename>serial_number_label.nlbl</label_filename>         <print_quantity>1</print_quantity>         <printer_name>Warehouse_printer_09</printer_name>      </element>      <element>         <data>            <item>               <package_code>BE273XS</package_code>            </item>         </data>         <label_filename>serial_number_label.nlbl</label_filename>         <print_quantity>1</print_quantity>         <printer_name>Warehouse_09</printer_name>      </element>   </jobs></asx:abap>

The expected result would be the second label without <manufacturer_serial> data. But in the actual print, the second label would contain <manufacturer_serial> value from the first label, which is 706583012001.

There are four possible solutions:

Avoid nested data blocks.

Define variable values as empty values if variables are not used in nested data blocks.

            <item>               <manufacturer_serial></manufacturer_serial>               <package_code>AA792CY</package_code>            </item>

Use conditions on actions to set variables.
Use string manipulations when detected missing variables.

Defining XML Assignment Area

XML filter automatically identifies fields and their values in the received data. This eliminates the need for manual variable-to-field mapping.

	Note
	There is no error if the field available in the input data doesn't have a matching label variable. Loftware Automation silently ignores the missing variables.

Configuring XML Assignment Area

When you configure the Data Block as assignment area, two placeholders appear under this element's definition. You have to define how the field name and value are defined, so the filter can extract the name-value pair.

Variable name: Specifies the item that contains field name. The name can be defined by element name, selected attribute value, or element value. To enable automatic mapping, label variable must have the same name.
Variable value: Specifies the item that contains field value. The name can be defined by the element name, selected attribute value, or element value.

	Warning
	The XML element containing `name:value` pairs cannot be set as a root element – this element must be set as at least a second level element. As shown in the XML example below, the element `<label>` is the second level element and can contain the `name:value` pairs.

Formatting Options

Delete spaces at the beginning: Deletes all space characters (decimal ASCII code 32) from the beginning of a string.
Delete spaces at the end: Deletes all space characters (decimal ASCII value 32) from the end of a string.
Delete opening and closing character: Deletes the first occurrence of the selected opening, and closing characters that are found in a string.

Example 12. Example

If you use "{" for the opening character and "}" for the closing character, the input string {{selection}} converts to {selection}.

Search and replace: Executes standard search and replace function upon the provided values for find what and replace with. You can also use regular expressions.

	Note
	There are several implementations of the regular expressions in use. uses the .NET Framework syntax for the regular expressions. For more information, see the Knowledge Base article.

Replace non printable characters with spaces: Replaces all control characters in the string with space character (decimal ASCII code 32). The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Delete non printable characters: Deletes all control characters in the string. The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Decode special characters: Special characters (or control codes) are characters that are not available on the keyboard, such as Carriage Return or Line Feed. uses a notation to encode such characters in human-readable form, such as <CR> for Carriage Return and <LF> for Line Feed. For more information, see section Entering Special Characters (Control Codes).

This option converts special characters from syntax into actual binary characters.

Example 13. Example

When you receive the data sequence "<CR><LF>", uses it as a as plain string of 8 characters. Enable this option to interpret and use the received data as two binary characters CR (Carriage Return - ASCII code 13) and LF (Line Feed - ASCII code 10).
Search and delete everything before: Finds the provided string and deletes all characters from the beginning of the data until the string. The found string itself can also be deleted.
Search and delete everything after: Finds the provided string and deletes all characters from the string until the end of the data. The found string itself can also be deleted.
Change case: Changes all characters in your strings to uppercase or lowercase.

Example

The <label> element is defined as data block and assignment area. The variable name is defined by value of the attribute name, the variable value is defined by element text.

<?xml version="1.0" standalone="no"?><labels _FORMAT="case.nlbl" _PRINTERNAME="Production01" _QUANTITY="1">    <label>        <variable name="CASEID">0000000123</variable>        <variable name="CARTONTYPE"/>        <variable name="ORDERKEY">0000000534</variable>        <variable name="BUYERPO"/>        <variable name="ROUTE"> </variable>        <variable name="CONTAINERDETAILID">0000004212</variable>        <variable name="SERIALREFERENCE">0</variable>        <variable name="FILTERVALUE">0</variable>        <variable name="INDICATORDIGIT">0</variable>        <variable name="DATE">11/19/2012 10:59:03</variable>    </label></labels>

Configuring JSON filter

JSON Filter

To learn more about filters in general, see section Understanding Filters.

Use the JSON filter if your trigger receives JSON-encoded data. JSON filter allows you to use variables and values from your JSON file. The filter supports data extraction from JSON arrays.

	Note
	Automation allows you to use all JSON data types. Read more about the available JSON data types here.

While you can define the JSON file structure manually, Loftware recommends you to import the structure from the received JSON files.

To import the JSON file structure:

Go to Data Filters and Edit your JSON filter.
Click Structure > Import Data Structure. Navigate to your JSON file and click Open.

After you import JSON files, the Data Preview section displays the JSON contents. The Data Preview also highlights the elements that you define as output fields.

For JSON data examples, see section JSON Data.

Defining Structure

To use the JSON items, configure them as:

Variable value: Specifies that you want to use the selected item as a field. When building the configuration, you manually map values with respective variables in the Use Data Filter action. For more information, see section Defining JSON Fields.
- Optional element: Specifies that the element is not mandatory. The variable mapped to such field will have an empty value if the element does not appear in the JSON file.
Data block: Specifies that the included sub-items occur multiple times and provide data for your labels. Data block can be defined as repeatable area, assignment area, or both. In terms of JSON, the Data block works as an array.
- Repeatable area: Specifies that you want to extract values from all repeatable data blocks, not just from the first one. You can define fields within each data block. Manually map the defined fields to the respective variables in the Use Data Filter action. For more information, see section Defining Repeatable Elements in JSON Filter.
- Assignment area: Automatically creates the variables and assigns them relevant values. Field names and their values are read simultaneously. Mapping to variables is done automatically. Use this feature to accommodate the filter to changing input data, eliminating the maintenance time. For more information, see section Defining JSON Assignment Area.

The Data Preview section simplifies the configuration. The result of a defined filter rule is highlighted in the preview area.

To change the previewed JSON data, click Open and browse for a new sample JSON file.

Defining JSON Fields

If you define JSON fields, you make values of the selected items automatically available. Your filter definition makes such fields available for mapping to variables in actions. This allows you to extract the element values.

To define JSON fields:

Select your element and set its Usage to Variable value.
The element is displayed on the structure list with bold letters, indicating that it is in use.
The element is used as output field name.

The Data Preview section highlights the values of the selected element.

Formatting Options

Delete spaces at the beginning: Deletes all space characters (decimal ASCII code 32) from the beginning of a string.
Delete spaces at the end: Deletes all space characters (decimal ASCII value 32) from the end of a string.
Delete opening and closing character: Deletes the first occurrence of the selected opening, and closing characters that are found in a string.

Example 14. Example

If you use "{" for the opening character and "}" for the closing character, the input string {{selection}} converts to {selection}.

Search and replace: Executes standard search and replace function upon the provided values for find what and replace with. You can also use regular expressions.

	Note
	There are several implementations of the regular expressions in use. uses the .NET Framework syntax for the regular expressions. For more information, see the Knowledge Base article.

Replace non printable characters with spaces: Replaces all control characters in the string with space character (decimal ASCII code 32). The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Delete non printable characters: Deletes all control characters in the string. The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Decode special characters: Special characters (or control codes) are characters that are not available on the keyboard, such as Carriage Return or Line Feed. uses a notation to encode such characters in human-readable form, such as <CR> for Carriage Return and <LF> for Line Feed. For more information, see section Entering Special Characters (Control Codes).

This option converts special characters from syntax into actual binary characters.

Example 15. Example

When you receive the data sequence "<CR><LF>", uses it as a as plain string of 8 characters. Enable this option to interpret and use the received data as two binary characters CR (Carriage Return - ASCII code 13) and LF (Line Feed - ASCII code 10).
Search and delete everything before: Finds the provided string and deletes all characters from the beginning of the data until the string. The found string itself can also be deleted.
Search and delete everything after: Finds the provided string and deletes all characters from the string until the end of the data. The found string itself can also be deleted.
Change case: Changes all characters in your strings to uppercase or lowercase.

Data Preview

This section provides preview of the field definition. If the defined item is selected, the preview highlights its placement in the preview data.

Preview file name: Specifies the file that contains sample data that is going to be parsed by the filter. The preview file is copied from filter definition. If you change the preview file name, the new file name is saved.
Open: Selects another file upon which you want to execute the filter rules.
Refresh: Re-runs the filter rules upon the contents of the preview file name. Automation updates the Data Preview section with the result.

Defining Repeatable Elements in JSON Filter

If a JSON element occurs in your JSON data multiple times, it is a repeatable element. Usually, a repeatable element contains data for a single label template. Repeatable items produce multiple labels populated with relevant data.

To indicate that you want to use data from all repeatable elements, and not just from the first one:

Select the element and define it as a Data block.
Enable the Repeatable element option.

If the filter contains definition of elements defined as data block / repeatable element, the Use Data Filter action displays repeatable elements with nested placeholders. All actions nested below such a placeholder execute only for data blocks at this level.

Example

The "item" element is defined as both – Data block and Repeatable element. This instructs the filter to extract all occurrences of the array, not just the first one. In this case, the "item" should be defined as the sub-level in Use Data Filter action. You must nest the actions Open Label and Print Label under this sub-level placeholder, so they are going to be looped for as many times as there are occurrences of the "item" element. As shown in the example below, for three times.

{
    "NICELABEL_JOB": {
        "TIMESTAMP": "20130221100527.788134",
        "USER": "PGRI",
        "IT_LABEL_DATA": {
            "item": [
                {
                    "LBL_NAME": "goods_receipt.nlbl",
                    "LBL_PRINTER": "Production01",
                    "LBL_QUANTITY": "1",
                    "MAKTX": "MASS ONE",
                    "MATNR": "28345",
                    "MEINS": "KG",
                    "WDATU": "19.01.2012",
                    "QUANTITY": "1",
                    "EXIDV": "012345678901234560"
                },
                {
                    "LBL_NAME": "goods_receipt.nlbl",
                    "LBL_PRINTER": "Production01",
                    "LBL_QUANTITY": "1",
                    "MAKTX": "MASS TWO",
                    "MATNR": "28346",
                    "MEINS": "KG",
                    "WDATU": "11.01.2011",
                    "QUANTITY": "1",
                    "EXIDV": "012345678901234577"
                },
                {
                    "LBL_NAME": "goods_receipt.nlbl",
                    "LBL_PRINTER": "Production01",
                    "LBL_QUANTITY": "1",
                    "MAKTX": "MASS THREE",
                    "MATNR": "27844",
                    "MEINS": "KG",
                    "WDATU": "07.03.2009",
                    "QUANTITY": "1",
                    "EXIDV": "012345678901234584"
                }
            ]
        }
    }
}

Warning

JSON data filter with nested data block duplicates values from previous assignment area if a variable is defined in the first block but not in the second. For example, you print two labels. In the first assignment area, you defined a variable "manufacturer_serial". In the second assignment area, this variable is not present.

{
  "jobs": [
    {
      "data": [
        {
          "manufacturer_serial": "706583012001",
          "package_code": "AA792CY"
        }
      ],
      "label_filename": "serial_number_label.nlbl",
      "print_quantity": 1,
      "printer_name": "Warehouse_printer_09"
    },
    {
      "data": [
        {
          "package_code": "BE273XS"
        }
      ],
      "label_filename": "serial_number_label.nlbl",
      "print_quantity": 1,
      "printer_name": "Warehouse_09"
    }
  ]
}

The expected result would be the second label without "manufacturer_serial" data. But in the actual print, the second label would contain "manufacturer_serial" value from the first label, which is 706583012001.

There are three possible solutions:

Avoid nested data blocks.

Define variable values as empty values ("") if variables are not used in nested data blocks.

      "data": [
        {
          "manufacturer_serial": "",
          "package_code": "AA792CY"
        }

Use conditions on actions to set variables.
Use string manipulations when detected missing variables.

Defining JSON Assignment Area

JSON filter automatically identifies fields and their values in the received data. This eliminates the need for manual variable-to-field mapping.

	Note
	There is no error if the field available in the input data doesn't have a matching label variable. Loftware Automation silently ignores the missing variables.

	Note
	Because there are no optional attributes in JSON, Automation defines Variable names and Variable values automatically.

Formatting Options

Delete spaces at the beginning: Deletes all space characters (decimal ASCII code 32) from the beginning of a string.
Delete spaces at the end: Deletes all space characters (decimal ASCII value 32) from the end of a string.
Delete opening and closing character: Deletes the first occurrence of the selected opening, and closing characters that are found in a string.

Example 16. Example

If you use "{" for the opening character and "}" for the closing character, the input string {{selection}} converts to {selection}.

Search and replace: Executes standard search and replace function upon the provided values for find what and replace with. You can also use regular expressions.

	Note
	There are several implementations of the regular expressions in use. uses the .NET Framework syntax for the regular expressions. For more information, see the Knowledge Base article.

Replace non printable characters with spaces: Replaces all control characters in the string with space character (decimal ASCII code 32). The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Delete non printable characters: Deletes all control characters in the string. The non printable characters are characters with decimal ASCII values between 0–31 and 127–159.
Decode special characters: Special characters (or control codes) are characters that are not available on the keyboard, such as Carriage Return or Line Feed. uses a notation to encode such characters in human-readable form, such as <CR> for Carriage Return and <LF> for Line Feed. For more information, see section Entering Special Characters (Control Codes).

This option converts special characters from syntax into actual binary characters.

Example 17. Example

When you receive the data sequence "<CR><LF>", uses it as a as plain string of 8 characters. Enable this option to interpret and use the received data as two binary characters CR (Carriage Return - ASCII code 13) and LF (Line Feed - ASCII code 10).
Search and delete everything before: Finds the provided string and deletes all characters from the beginning of the data until the string. The found string itself can also be deleted.
Search and delete everything after: Finds the provided string and deletes all characters from the string until the end of the data. The found string itself can also be deleted.
Change case: Changes all characters in your strings to uppercase or lowercase.

Example

The "LIST_ITEM" element is defined as data block and assignment area.

{
  "DELIVERYNOTE": {
    "LIST_CUSTOMER_INFO": {
      "CUSTOMER_INFO": {
        "CUSTOMER_NAME": "Customer A",
        "CUSTOMER_STREET_ADDRESS": "Test St",
        "CUSTOMER_POST_ADDRESS": "1234, Test City",
        "CUSTOMER_NUMBER": "1234",
        "CURRENCY": "EUR",
        "DELIVERY_METHOD": "Express delivery",
        "EDI_INFORMATION": "EDI",
        "ORDER_TYPE": "CSO",
        "ORDER_NUMBER": "123",
      }
    }
  }
}

Setting Label and Printer Names from Input Data

Typically, filters extract values from the received data and send them to label variables for printing. In such cases, label or printer names are hard-coded into the actions. For example, Open Label action hard-codes the label name, and Set Printer action hard-codes the printer name. However, the input data can also provide meta-data. These are the values used inside the Loftware Automation processing, but not printed on the label, such as label name, printer name, label quantity, etc.

To use the values of meta-data fields in the print process, do the following.

Filter reconfiguration: Define new fields for the input data to extract the meta-data fields as well.
Variable definition: Manually define the variables to store the meta-data since they don't exist on the label and cannot be imported. Use intuitive names, such as LabelName, PrinterName, and Quantity. You are free to use any variable name.
Mapping reconfiguration: Manually configure the Use Data Filter action to map meta-fields to new variables.
Action reconfiguration: Reconfigure Open Label action to open the label specified by variable LabelName, and Set Printer action to use the printer as specified by the PrinterName variable.

Example

The CSV file contains label data, but also provides meta-data, such as label name, printer name and quantity of labels. The Structured Text filter extracts all fields, sends label-related values to the label variables and uses meta-data to configure actions Open Label, Set Printer and Print Label.

                        
                            label_name
                        ;label_count;printer_name;art_code;art_name;ean13;weight
label1.nlbl;1;CAB A3 203DPI;00265012;SAC.PESTO 250G;383860026501;1,1 kg
label2.nlbl;1;Zebra R-402;00126502;TAGLIOLINI 250G;383860026002;3,0 kg