[en] Configuring XML filter

[en] XML Filter

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

[en] 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).

[en] While you can define the structure of the XML file by yourself, NiceLabel 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.

[en] For XML data examples, see section XML Data.

[en] Defining Structure

[en] To use the XML items, configure them as:

[en] 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.
- [en] 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.
[en] 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.
- [en] 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.
- [en] 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.

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

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

[en] Defining XML Fields

[en] 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.

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

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

[en] Formatting Options

[en] 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.

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

例 10. 示例

[en] If you use "{" for the opening character and "}" for the closing character, the input string {{selection}} converts to {selection}.
[en] 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.

注意

[en] 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.
[en] 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.
[en] 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.
[en] 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).

[en] This option converts special characters from syntax into actual binary characters.

例 11. 示例

[en] 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).
[en] 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.
[en] 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.
[en] Change case: Changes all characters in your strings to uppercase or lowercase.

[en] Data Preview

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

[en] 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.
[en] Open: Selects another file upon which you want to execute the filter rules.
[en] Refresh: Re-runs the filter rules upon the contents of the preview file name. Automation updates the Data Preview section with the result.

[en] Defining Repeatable Elements in XML Filter

[en] 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.

[en] Example

[en] 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>

警告

[en] 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>

[en] 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.

[en] There are four possible solutions:

[en] Avoid nested data blocks.

[en] 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>

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

[en] Defining XML Assignment Area

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

[en] 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.

[en] 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.

注意

[en] 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.

[en] Configuring XML Assignment Area

[en] 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.

[en] 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.
[en] Variable value: Specifies the item that contains field value. The name can be defined by the element name, selected attribute value, or element value.

警告

[en] 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.

[en] Formatting Options

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

例 12. 示例

[en] If you use "{" for the opening character and "}" for the closing character, the input string {{selection}} converts to {selection}.
[en] 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.

注意

[en] 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.
[en] 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.
[en] 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.
[en] 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).

[en] This option converts special characters from syntax into actual binary characters.

例 13. 示例

[en] 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).
[en] 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.
[en] 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.
[en] Change case: Changes all characters in your strings to uppercase or lowercase.

[en] Example

[en] 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>