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:

Click Configure > LAYOUTS > Advanced Text.
Click Create Advanced Text Layout.
On the Create Layout screen, select the Layout Builder option in the Select Layout UI Type field.
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 two ways:
  - Import Definition file
  - Enter the Fields Sequentially
  Using Import Definition File
  1. Select Import Definition File.
  2. In the Identifier Field, select either First Field or Define Field.
    - If you select First Field, the first field of the record is considered as the record identifier.
    - If you select Define Field, you can specify a field that you want to use as the record identifier.
  3. Select the type of file in the Definition File field.
    The available options are Data and JSON.
  4. Browse and upload the data file in Upload Data File field.
  5. Select the project in the Project field.
  6. Click Continue.
  Using Entering the Fields Sequentially
  1. Select Enter the Fields Sequentially as a definition mode.
  2. In the Identifier Field, select either First Field or Define Field.
    - If you select First Field, the first field of the record is considered as the record identifier.
    - If you select Define Field, you can specify a field that you want to use as the record identifier.
  3. Select the project in the Project field
  4. Click Continue.
On the Record Definition screen, enter the following details.
1. In the Record Identifier Field, enter the field that you want to specify as the record identifier.
  
  This field is available only when you select Define Field option on the previous screen.
2. In the Record Identifier Value field. enter a value for the Record Identifier Field. You can also use a regular expression in this field.
3. Consider the two points below to complete the steps that follow.
  - If you are using a definition file to define the layout, the fields' names in the table under Record Definition section will be pre-populated and can be updated. Skip step d if you do not want to update the fields' names.
  - If you are using Enter the Fields Sequentially option, you need to manually enter the fields' names in the Field Name under Record Definition section.
4. In the Field Name, enter/update the name of a field. 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.
5. 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.
6. Enter a particular pattern that you want to skip in the Skip Pattern textbox. You can also use regular expression in this textbox.
7. Enter the minimum and maximum size of the field in the Min Size and Max Size textboxes respectively.
  
  The Min Size and Max Size fields in the Advanced Text Layout have predefined/default values of the character count. You can change these default values based on your requirement.
8. 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.
9. 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.
10. Click Save.
Click Definition on the top-right of the screen to open Definition panel.
On the Definition panel, select the type of layout in the Reference Layout Type field that you want to take as a reference.
Select the layout which you want to use as a reference layout in the Reference Layout field.
Select the Project in the Project field.
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 in the 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 checkbox 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.
14. Select Ignore Empty Records to ignore a record that does not hold any value in any of its fields, including the record identifier.

Defining a New Record

Once the required properties are defined, you can define a New Record.

In the File View area, select the row that you want to use for defining the new record.
Right-click and select New Record.
Follow the steps from 5(a) through 5(j) in the section, Steps to create Advanced Text Layout.
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.

Defining the Control Total

Once the required properties are defined, you can 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:

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.
Right-click and select Control Total option.
Follow the steps from 5(a) through 5(j) in the section, Steps to create Advanced Text Layout.
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.
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.
You can view the records and control total Data in Records Hierarchy panel.
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.
You can test the layout by clicking Test Layout button from the toolbar. Click here to get more details.
Click Save Layout button in the toolbar to save the advanced text layout.

You may be interested in...

What's new

Best practices

Training guides

Frequently asked questions

Adeptia Connect APIs

Adeptia security report