Creating a flat file connector from a file

Learn how to create a flat file connector from a sample file.

1. Click Projects.
2. Select a project and then click Connectors > Flat File > Add Connector.

   The New Flat File Connector page appears.

3. Select Import from file, and then drag or click Browse Files to upload the sample file from your computer.
4. Click Next.
5. In the connector definition page, type a name and description of the flat file connector.
6. Drag or click Browse files and select a connector icon, if necessary.
   In the preview window, webMethods Integration updates the sample file contents based on your selections.

   Note: The Show Preview is collapsed by default on the Description page. Click to view the file content.
7. Click Next.
8. In the Flat File Definition page, configure the Parser and the Record Identifier. Select the values or provide the custom input for the Delimiter, Fixed Length & Variable Length parsers. When the custom input is not in the valid format, an error is seen.

   In the Parser panel, select one of the following to indicate how the data in the sample file is formatted:

   Record Parser	Description
   Delimiter	Use this parser when each record is separated by a delimiter.
   Fixed Length	Use a fixed-length record parser when each record is of a fixed length (For instance, mainframe punch or print records). This parser splits a file into records of the same pre-specified length.
   Variable Length	This parser expects each record to be preceded by two bytes that indicate the length of the record. Each record might be of a different length.

   Select Use first row as field labels to make the first row as header.

   Note: Use first row as field labels checkbox is disabled until record length is selected. This option is not available in manual flat file creation or editing an existing flat file.

   If you select Delimiter as the parser type, specify the parser properties in the record parser panel. webMethods Integration updates the Preview contents based on your selections. Use the table to specify the delimiters used in the sample file.

   Property	Description
   Record	Character that separates records in a flat file document. If a new line character (\n) exists at the end of each record and the Record delimiter is not ending with \n, then webMethods Integration cannot render the records properly under the preview window.
   Field or Composite	A character that separates fields in a flat file document.
   Subfield	Character that separates subfields in a flat file document.
   Quoted Release 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. For instance, your field delimiter is (,) and your quoted 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 is used.
   Release 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. For instance, 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.

   If you select Fixed Length as the parser type, specify the parser properties in the record parser panel. webMethods Integration updates the Preview contents based on your selections. Specify the position of each field in Field separators. The Field separators must be comma-separated integer values, For instance, 5, 10, 15. You can set a value for Record length to adjust the record so that it appears correctly under the Preview pane. Record length supports only positive integer values between one and the total number of characters in the file and cannot be empty.

   If you selected Variable Length as the parser type, specify the parser properties in the Record Parser panel. webMethods Integration updates the Preview contents based on your selections. Use the following table to specify the delimiters used in the sample file.

   Property	Description
   Field	A character that separates fields in a flat file document.
   Subfield	Character that separates subfields in a flat file document.
   Quoted release 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. For instance, your field delimiter is (,) and your quoted 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 convertToValues service to create the strings Doe, John, and Doe, Jane, the record would appear as “Doe, John”,“Doe, Jane”. When using the convertToString service to create “Doe, John”,“Doe, Jane”, the value of the record would be Doe, John and Doe, Jane. When using the convertToString service, if you have specified both the Release Character and the Quoted Release Character, the Quoted Release Character is used.
   Release 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. For instance, 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 convertToValues service 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 convertToString service to create a\+b\+c+d\+e\+f, the value of the record would be a+b+c and d+e+f.

9. Specify a Record Identifier.

   When parsing a file, webMethods Integration 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 that is 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 then set the record identifier to one of the following values.

   Note: The Record Identifier Position has a default value that is selected as Start at field position.

   Record Identifier	Value	Description
   	Start at field position	Identifies the field in the record (counting from zero) that contains the identifier. Start at field position identifiers use the value of the specified field as the record identifier. These identifiers count from zero (0). For instance, if 2 is specified, the third field is used as the record identifier.
   	Start at the character position	Identifies the character position in the record (counting from zero) where the record identifier is located. Start at character 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. The Start at character position identifier cannot distinguish between all types of record names. For instance, if you name records “Rec1” and “Rec,” some instances of “Rec1” might be identified as “Rec,” because “Rec1” begins with “Rec.”

   Select No if the flat file does not contain a record identifier.

10. Click Next to view the Flat File Structure.

    You can 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.

    Enable the Edit Mode and use the Data fields panel on the Structure page to:

    • add an element using the "+" icon and select Record Definition from the Element type field to specify a name for the record definition,
    • quickly browse within the schema using the right, left, up and down arrows,
    • perform edit actions For instance cut, copy, paste, and delete fields and
    • utilize keyboard shortcuts for modifying the flat file schema fields.

    You can also modify the fields of the element in the property panel within the file schema when Edit Mode is enabled.

    Usage notes: The "+" option within the Data Fields panel functions in two ways:

    • If the selected element is a Field, it adds a sibling Field element to the end of the list.
    • If the selected element is any parent Element, the + option adds a child element to that parent.
    • The right arrow functionality is applicable only when a parent element is present below the selected element.
    • For schema elements, only the add and paste options are enabled. The paste option adds the copied or cut element as a child element.

    Select the Show Data to preview the sample data if you have created the flat file using the import feature.

    The Show Data feature is available only while creating the flat file using the import file function initially and not when you create the flat file manually or edit an existing flat file.

    Use the Expand or Collapse All option to view the schema properties for the flat file.

11. To add a Composite Definition after you have added a record definition, click the Element Type field and select Composite Definition. Specify a name for the record definition and click Save.

    Extractor type	Description
    Nth Field-Extractor	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.

12. To add a Field Definition after you have added a record definition, click the "+" icon and select Field Definition in the Element type field.

    Extractor Type	Description
    Fixed Position	Counting from zero (0) indicates a fixed number of bytes to be extracted from a record.
    	Extractor
    	Position
    Nth Field	Counting from zero (0), indicates the field that you want to extract from the record.
    	Extractor

    This option is available if you specified a field delimiter when configuring the definition and structure of the flat file connector. 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.

13. Click Next, the Summary page appears where the Overview tab provides information such as the File name, Description, and Connector icon. Also, it shows File Type details, including Parser type and Parser fields values. The Structure tab on the same page shows both the file schema and sample data details for the output.
14. Click Save to create the flat file connector. You are redirected to the Flat File Connectors page.

    You are redirected to the Flat File Connectors page.