Software AG Products 10.7 | Integrating On-Premises and Cloud Applications | Integration Cloud | Applications | Flat File Applications | Creating a flat file Application manually
 
Creating a flat file Application manually
Integration Cloud can process flat files in which:
*The records in the flat file are defined using one of the following methods:
Property
Description
Delimiter
Each record in the flat file is separated by a delimiter.
Fixed length
Each record is a fixed number of bytes (for example, mainframe punch or print records).
Variable length
Each record is preceded by two bytes that indicate the length of the record. Records in the flat file can have different lengths.
*If the flat file contains record identifiers, the record identifiers must be located in the same location in all records in the file.
Integration Cloud can then identify fields in these records based on:
*Fixed position - Each field is defined by 1) the number of bytes from the beginning of the record and 2) the field length. This can be used regardless of whether a field delimiter has been specified.
*Delimiters - Each field is separated by a delimiter, and you can specify the Nth delimited field in a record to represent the record identifier. This can be used only when a field delimiter (and, if necessary, subfield delimiter) has been specified.
To create a flat file Application manually
1. From the Integration Cloud navigation bar, click Projects > <Select a Project> > Flat File Applications > Add New Application.
2. Type a name and description of the flat file Application and select the creation mode as Create manually.
3. Click Next and in the Flat File Definition page, configure the Record parser and the Record identifier.
4. In the Record parser section, to configure a delimited record parser, select Delimiter in the Record parser area and specify the following fields.
For a record delimiter, you can specify a character (for example, !) or character representation (for example, \r\n for carriage return).
Use the Delimiter record parser for the Flat File Application when each record is separated by a delimiter.
Delimiter
Record type
Description
Record
Character
Character that separates records in a flat file document.
--OR--
Character Position
Starting from the beginning of the document and counting from zero (0), the character position at which the record delimiter for this document is located.
Note:
For example, if you specify 3 as the character position, you have indicated that the record delimiter appears in the fourth character position from the beginning of the document.
Delimiter
Field or composite type
Description
Field or composite
Character
Character that separates fields in a flat file document.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the field delimiter for this document is located.
Note:
For example, if you specify 4 as the character position, you have indicated that the field delimiter appears in the fifth character position from the beginning of the document.
Delimiter
Subfield type
Description
Subfield
Character
Character that separates subfields in a flat file document. The default is a period “.”.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the subfield delimiter for this document is located.
Note:
For example, if you specify 5 as the character position, you have indicated that the subfield delimiter appears in the sixth character position from the beginning of the document.
Delimiter
Quoted release character type
Description
Quoted release character
Character
Character used to enable a section of text within a field to be represented as its literal value. Any delimiter characters that appear within this section will not be treated as delimiters.
Note:
For example, your field delimiter is (,) and your release character is “. When you want to use (,) within a field as text, you must prefix it with your quoted release character. When using the convertFlatFileToDocument operation to create the strings Doe, John and Doe, Jane, the record would appear as “Doe, John”,“Doe, Jane”. When using the convertDocumentToFlatFile operation to create “Doe, John”,“Doe, Jane”, the value of the record would be Doe, John and Doe, Jane. When using the convertDocumentToFlatFile operation, if you have specified both the Release Character and the Quoted Release Character, the Quoted Release Character will be used.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the quoted release character for this document is located.
Note:
For example, if you specify 5 as the character position, you have indicated that the quoted release character appears in the sixth character position from the beginning of the document.
Delimiter
Release character type
Description
Release character
Character
Character used to enable a delimiter to be used for its intended, original meaning. The character following the release character will not be treated as a delimiter.
Note:
For example, your field delimiter is + and your release character is \. When using + within a field as text, you must prefix it with your release character. When using the convertFlatFileToDocument operation to create the strings a+b+c and d+e+f, the record would appear as a\+b\+c+d\+e\+f. When using the convertDocumentToFlatFile operation to create a\+b\+c+d\+e\+f, the value of the record would be a+b+c and d+e+f.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the field delimiter for this document is located.
Note:
For example, if you specify 5 as the character position, you have indicated that the field delimiter appears in the sixth character position from the beginning of the document.
Next, set the record identifier.
5. Use a Fixed Length record parser type when each record is of a fixed length (for example, mainframe punch or print records). This parser splits a file into records of the same pre-specified length. To configure a fixed length record parser, in the Record Parser Type area, select Fixed Length.
Specify the following fields:
Fixed Length
Field or composite type
Description
Field or composite
Character
Character that separates fields or composites in a flat file document.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the field delimiter for this document is located.
Note:
For example, if you specify 4 as the character position, you have indicated that the field delimiter appears in the fifth character position from the beginning of the document.
Fixed Length
Subfield type
Description
Subfield
Character
Character that separates subfields in a flat file document.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the subfield delimiter for this document is located.
Note:
For example, if you specify 5 as the character position, you have indicated that the subfield delimiter appears in the sixth character position from the beginning of the document.
Fixed length
Quoted release character type
Description
Quoted release character
Character
Character used to enable a section of text within a field to be represented as its literal value. Any delimiter characters that appear within this section will not be treated as delimiters.
Note:
For example, your field delimiter is (,) and your release character is “. When you want to use (,) within a field as text, you must prefix it with your quoted release character. When using the convertFlatFileToDocument operation to create the strings Doe, John and Doe, Jane, the record would appear as “Doe, John”,“Doe, Jane”. When using the convertDocumentToFlatFile operation to create “Doe, John”,“Doe, Jane”, the value of the record would be Doe, John and Doe, Jane.When using the convertDocumentToFlatFile operation, if you have specified both the Release Character and the and the Quoted Release Character, the Quoted Release Character will be used.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the quoted release character for this document is located.
Note:
For example, if you specify 5 as the character position, you have indicated that the quoted release character appears in the sixth character position from the beginning of the document.
Fixed length
Release character type
Description
Release character
Character
Character used to enable a delimiter to be used for its intended, original meaning. The character following the release character will not be treated as a delimiter.
Note:
For example, your field delimiter is + and your release character is \. When using + within a field as text, you must prefix it with your release character. When using the convertFlatFileToDocument operation to create the strings a+b+c and d+e+f, the record would appear as a\+b\+c+d\+e\+f. When using the convertDocumentToFlatFile operation to create a\+b\+c+d\+e\+f, the value of the record would be a+b+c and d+e+f.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the field delimiter for this document is located.
Note:
For example, if you specify 5 as the character position, you have indicated that the field delimiter appears in the sixth character position from the beginning of the document.
Fixed length
Description
Record length
In the Record Length field, enter the length, in characters, of each record in the flat file. Record length cannot be empty.
Next, set the record identifier.
6. The Variable Length record parser type expects each record to be preceded by two bytes that indicate the length of the record. Each record may be a different length.
To configure a variable length record parser, in the Record Parser area, select Variable length, and specify the following fields:
Variable Length
Field or composite type
Description
Field or composite
Character
Character that separates fields or composites in a flat file document.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the field delimiter for this document is located.
Note:
For example, if you specify 4 as the character position, you have indicated that the field delimiter appears in the fifth character position from the beginning of the document.
Variable length
Subfield type
Description
Subfield
Character
Character that separates subfields in a flat file document.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the subfield delimiter for this document is located.
Note:
For example, if you specify 5 as the character position, you have indicated that the subfield delimiter appears in the sixth character position from the beginning of the document.
Variable length
Quoted release character type
Description
Quoted release character
Character
Character used to enable a section of text within a field to be represented as its literal value. Any delimiter characters that appear within this section will not be treated as delimiters.
Note:
For example, your field delimiter is (,) and your release character is “. When you want to use (,) within a field as text, you must prefix it with your quoted release character. When using the convertFlatFileToDocument operation to create the strings Doe, John and Doe, Jane, the record would appear as “Doe, John”,“Doe, Jane”. When using the convertDocumentToFlatFile operation to create “Doe, John”,“Doe, Jane”, the value of the record would be Doe, John and Doe, Jane.When using the convertDocumentToFlatFile operation, if you have specified both the Release Character and the and the Quoted Release Character, the Quoted Release Character will be used.
--OR--
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the quoted release character for this document is located.
Note:
For example, if you specify 5 as the character position, you have indicated that the quoted release character appears in the sixth character position from the beginning of the document.
Variable length
Release character type
Description
Release character
Character
Character used to enable a delimiter to be used for its intended, original meaning. The character following the release character will not be treated as a delimiter.
Note:
For example, your field delimiter is + and your release character is \. When using + within a field as text, you must prefix it with your release character. When using the convertFlatFileToDocument operation to create the strings a+b+c and d+e+f, the record would appear as a\+b\+c+d\+e\+f. When using the convertDocumentToFlatFile operation to create a\+b\+c+d\+e\+f, the value of the record would be a+b+c and d+e+f.
Character position
Starting from the beginning of the document and counting from zero (0), the character position at which the field delimiter for this document is located.
Note:
For example, if you specify 5 as the character position, you have indicated that the field delimiter appears in the sixth character position from the beginning of the document.
Next, set the record identifier.
7. Specifying a Record Identifier
When parsing a file, Integration Cloud looks at a record and extracts an identifier out of the data and uses that identifier to connect the record definition with a particular record in the flat file. The name of the record definition must match the value obtained by the record identifier.
To set the record identifier for a definition, if the flat file contains a record identifier, select Yes in the Record identifier area, and set the record identifier to one of the following values.
Record identifier
Value
Description
Start at position
Identifies the character position in the record (counting from zero) where the record identifier is located. Start at position record identifiers compare the value that occurs in the record, at the specified offset, to all the record names defined in the flat file structure. Note that the Start at position identifier cannot distinguish between all types of record names.
Note:
For example, if you name records “Rec1” and “Rec,” some instances of “Rec1” may be identified as “Rec,” because “Rec1” begins with “Rec.”
Nth field
Identifies the field in the record (counting from zero) that contains the identifier. Nth field identifiers use the value of the specified field as the record identifier. These identifiers count from zero (0).
Note:
For example, if 2 is specified, the third field is used as the record identifier.
Select No if the flat file does not contain a record identifier.
8. Click Next to define the Flat File Structure. Use the Flat File Structure page to add records to the flat file structure and define the hierarchical relationships between them.
The application receiving the flat file uses the structure to read the flat file. This structural information identifies the parent-child relationships between different records in the flat file. By nesting record elements in the flat file structure (adding record elements to a record), you can represent the hierarchical structure of the data in the flat file.
To add the first record, click the Add new element icon and in the Element type field, select Record Definition. Specify a name for the record definition and click Finish.
9. To add a Composite Definition after you have added a record definition, specify the following:
Extractor type
Description
Nth field
Field number in the record that contains the composite you want to extract. This pulls the subfield data from the composite. If you leave this property empty, the composite will not be extracted.
To add a Field Definition after you have added a record definition, specify the following:
Extractor type
Description
Fixed Position
Counting from zero (0), indicates a fixed number of bytes to be extracted from a record.
Position
Type the first byte to extract from the record. Type the first byte that is not included in the extraction. If you enter a negative number (for example, –1), the extractor returns all bytes from the byte specified in Start to the last byte in the record or composite.
Nth field
Counting from zero (0), indicates the field that you want to extract from the record.
Extractor
Type a value to indicate the position of the field that you want to extract from the record. This value cannot be null and must be an integer greater than or equal to zero (0).
Note:
For example, if you type 1, the second field will be extracted.
This option is available only if you specified a field delimiter when configuring the definition and structure of the Flat File Application. This extractor returns the field as a key–value pair. The key is the name of the field. The value is the String value of the field.
10. Click Finish to create the flat file Application.
After creating the flat file Application, create an Orchestrated Integration, select the Flat File Application created, and invoke the following predefined operations:
* convertFlatFileToDocument - Converts the flat file to a document (inbound)
* convertDocumentToFlatFile - Converts a document to a flat file (outbound)