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