Creating an Advanced Text Layout using Layout Builder

You can use this layout service to define how to read data from and write data to an advance text file. An advance text file refers to a text file which can have multiple record formats and field separators.

By default, this feature remains disabled in the product. You need to enable this feature before you start working on this.  

Steps to create Advanced Text Layout:

1. Click Configure > LAYOUTS > Advanced Text.
2. Click Create Advanced Text Layout.
   
3. On the Create Layout screen, select the Layout Builder option from the drop-down list of Select Layout UI Type field.
   
   
   
   
4. Click Next. The Create New Advance Text screen is displayed in a new page.
   

   1. Type the name and description in the Provide Layout Name and Provide Layout Description text boxes.
      
      Name: Only alphanumeric and underscore are allowed and you must start the layout name with an alphabet or underscore.
      Description: Only alphanumeric and few special characters(_ - . : , @ $ ? \\ and space) are allowed and you must start the description with an Alphabet/Underscore/Number.
      
      

   2. Provide the record separator, for example, \n for newline or " " for space, in the Record Separator. The record separator is used to separate the records.

   3. Provide the field separator, for example, \t for Tab or " " for space, in the Field Separator. Field Separator is used to separate fields.
      

      • You can specify multiple record and field separators. You can also use regular expressions to specify field separators. For example, you can use "\s:" to specify space or colon ( : as a field separator.

      • You can not directly use special characters such as '', '', or '|' in your regular expression as field separators. To use them you need to put these characters within square brackets in the *Field Separator field. For example, [], [*] or [|].
      • However, if you use the same layout at the target end, in a target data file then the layout will print the field separator along with the square brackets. To avoid this, enter '+', '', or '|' in the *Target Field Separator field in Advanced Properties.
      • You can also use hex values in record and field separators. 
        
        • As field separator at target end, use 0x before the value. For example, for space as field separator use 0x20.
        • As field separator at source end, use as regular expression. For example, for space as field separate or use \x20 .
        • Record separator uses regular expression to support hex values at both source and target end. For example, for space as a record separator, use 0x20 .
      • You can also specify two hex values together in record and field separator. For example, for two spaces you need to use 0x200x20.
   4. Select the definition mode for the Advanced text layout. You can define the schema in the following three ways: 
      • Import Definition file
      • Enter the Fields Sequentially
      
      Using Import Definition File
      
      1. Select Import Definition File.
      2. Select the type of file from the Definition File drop down list box.
         The available options are Data and JSON.

      3. Browse and upload the data file in Upload Data File field.

      4. Select the project from the Project drop-down box.

      5. Click Continue.

      
      Using Entering the Fields Sequentially
      1. Select Enter the Fields Sequentially as a definition mode.
      2. Select the project from the Project drop-down box.

      3. Click Continue.

5. In Definition panel, select the type of layout from the drop-down list of Reference Layout Type field that you want to take as a reference.
6. Select the layout which you want to use as a reference layout from the drop-down list of Reference Layout field.
7. Select the Project from the drop-down list of Project. 
   
8. Expand Advanced Properties.
   1. Type the row start position in the Row Start Position textbox. Row Start Position specifies which row of the text file is counted as first row.
      
      For example, if you enter value as 5 in the Row Start Position, 5^th row of the text file is counted as the first row. If this layout is used at source end, the data from the 5^th row onward is taken for processing.
   2. In case, you want to skip certain bottom row from the text file then define the row count from Bottom Row Skip Count field.
   3. Define the Character-set encoding for your text layout from the drop-down list of Character Set Encoding field. The available options are UTF-8, UTF-16, and ISO-8859-1.
      
      In case, the data you are processing through Adeptia Connect contains characters that are a part of another character set encoding, for example, UTF-8, then you need to change the character set encoding.
   4. In the Target Field Separator field, enter the target field separator value. It helps to separate the data fields in a data record.
   5. Select Quotes Handling check box to enable quotes handling.

   6. When using Text schema at the target side, select the Enclose Target Field Values in Double Quotes check box to enclose the target field values in double quotes. For example, "John","Smith".

   7. Select Allow Less Fields check box to process the data in case the number of fields in the data file is less than the number of fields defined in the layout.
      

   8. Select Remove Last New Line Record Separator check box if you want to remove the new line record separator from the target file.

      • When the number of fields in the data file is less than the number of fields defined in the schema then schema will not process the data and give an error during execution.

      • When you select the Allow Less Field check box then layout generates an empty tag for fields that are not present in the data file.
      • This option is applicable only when you use the schema at the source end.

   9. Select the Ignore Header check box if you want the header line in the data file is to be ignored.

   10. Select the Look Ahead check box if the data file has new line or multiple new line to separate the fields. 

   11. Select the Singe Record Type check box if the data has one record type and record identifier is not fixed.

   12. In case the input data contains some characters that are invalid in XML then this may result in the aborted mapping. You can filter these invalid XML characters by selecting the Filter Invalid XML Characters check box.

   13. Select the Filter Record Identifier At Target check box if you want to skip the record identifier in the target file. 
9. Once the required properties are defined, you can define New Record and Control Total.
   

   Steps to define the New Record

   1. In the File View area, select the row which you want to use for defining the new record.
   2. Right-click and select New Record.
      
      
      
      
   3. On the Record Definition screen,
      
      
      
      
      1. Enter the record identifier in the Record Identifier field. You can use a regular expression in this textbox.
      2. You can edit the Field Name value. If reference layout is defined, click the field to get the suggestions based on the reference layout.

      3. In the Match Pattern textbox, enter the pattern against which you want to match the record.

         You can use regular expression in the Match Pattern textbox.
      4. Enter a particular pattern that you want to skip in the Skip Pattern textbox. You can also use regular expression in this textbox.
      5. Enter the minimum and maximum size of the field in the Min Size and Max Size textboxes respectively.

      6. Enter the position in the Position textbox.

         For adding more fields in the same record format, click the Add Row button. Click Delete Row button to delete the field.
      7. In the Validation Properties section, do the following:
         • In the minoccur field, enter the minimum number of occurrences of the current record that you want in the source file. The minimum allowable value is 1.
         • In the maxoccur field, enter the maximum number of occurrences of the current record that you want in the source file. The maximum allowable value is 2147483647.
         • Select the Required check box to indicate if you want the current record to be present in the source file.
      8. Click Save.

   4. You can see the created New Record in the Records Hierarchy panel. 

      Click  button to open record in the Data View tab. Also, click  button to know the details on the defined record.
      
      In the Data View area, under Record Definition, click button to edit the record. You can also delete the record by clicking button.
   Steps to define the Control Total
   Before defining the control total value, you must specify these values:

   • Define the Row Start Position in case you want to parse value in header. The value must be more than 0.

   • Define the Bottom Row Skip Count in case you want to parse value in footer. The value must be more than 0.

   Follow these steps to define the control total:

   1. In File View area, select the row (based on the defined Row Start Position or Bottom Row Skip Count) which you want to parse to the source side. 
   2. Right-click and select Control Total option.
      
      
      
      
   3. On Control Total Definition screen:
      
      
      
      
      1. Enter the record identifier in the Record Identifier field. You can use a regular expression in this field.
         

      2. You can edit the Field Name value. If reference layout is defined, click the field to get the suggestions based on the reference layout.

         You can use spaces and other special characters (~`! @ # $%^&*() {} [] | \\ : ; " ' - + =<> / ? . ,  ) in the field names. The special characters are rendered as underscores (__) if you use this layout in a Mapping.

      3. In the Match Pattern textbox, enter the pattern against which you want to match the record.

         You can use regular expression in the Match Pattern textbox.
      4. Enter a particular pattern that you want to skip in the Skip Pattern textbox. You can also use regular expression in this textbox.
      5. Enter the minimum and maximum size of the field in the Min Size and Max Size textboxes respectively.

      6. Enter the position in the Position textbox.

         For adding more fields in the same record format, click the Add Row button. Click Delete Row button to delete the field.
      7. In the Validation Properties section, do the following:
         • In the minoccur field, enter the minimum number of occurrences of the current record that you want in the source file. The minimum allowable value is 1.
         • In the maxoccur field, enter the maximum number of occurrences of the current record that you want in the source file. The maximum allowable value is 2147483647.
         • Select the Required check box to indicate if you want the current record to be present in the source file.
      8. Click Save.

   4. You can see the created Control Total in the Records Hierarchy panel. 

      Click  button to open record in the Data View tab. Also, click  button to know the details on the defined record.
      
      In the Data View area, under Record Definition, click button to edit the record. You can also delete the record by clicking button.

       

10. After defining records you need to define their hierarchy. 

    • You can define hierarchy by dragging and dropping records as desired in the Records Hierarchy panel.

    • Hierarchy of the control total record can not be changed.

11. You can view the records and control total Data in Records Hierarchy panel.

12. If you want to see the layout in XSD format, click XSD View  button from the toolbar. You can also download the XSD file by clicking Download XSD button. 

13. You can test the layout by clicking Test Layout  button from the toolbar. Click here to get more details.

14. Click Save Layout button in the toolbar to save the advanced text layout.