Developing Ensemble Productions
Using the Complex Record Mapper
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

If the message format consists of multiple heterogeneous records, you can use the Complex Record Mapper and handle these complex records with built-in file or FTP services and operations. Typically, these complex records have a header record followed by a pattern of records and terminated by a trailer record. These records can either be fixed-fields records or delimited records and can be optional and repeat. Typically, the records have leading data that identifies the kind of record.

Overview
Complex record maps can describe structured records that can contain:
  1. An optional header record.
  2. Sequence of elements where each element can be a record defined by a RecordMap or a sequence. A sequence can contain a sequence of records and other sequences.
  3. An optional trailer record.
The records within a sequence can either be delimited records or fixed-width records. Although it is possible to mix delimited and fixed-width records within a complex record map, typically all of the records are delimited or all are fixed-width.
The following delimited sample data can be described by a complex record map. The data consists of a header identifying a semester in a college and information about students and classes that each student takes.
SEM|194;2012;Fall;20
STU|12345;Adams;John;Michael;2;john.michael.adams@example.com;617-999-9999
CLS|18.034;1;Differential Equations;4
CLS|21W.759;1;Writing Science Fiction;4
STU|12346;Adams;Jane;Michelle;3;jane.michelle.adams@example.com;
CLS|21L.285;1;Modern Fiction;3
CLS|7.03;1;Genetics;4
STU|12347;Jones;Robert;Alfred;1;bobby.jones@example.com;
CLS|18.02;1;Calculus;4
The complex record map that describes this data consists of:
  1. Header record identified by the leading data “SEM|”.
  2. A sequence of students, where each student consists of:
    1. Student record identified by the leading data “STU|”.
    2. A repeating class record identified by the leading data “CLS|”.
The sequence of students defines the repeating structure of the complex record but does not correspond to a record in the data.
A complex record map defines both a file structure and an object structure. The complex record map file service parses a file using the file structure defined by the complex record map and then stores the data in an object defined by the object structure. The complex record map file operation performs the reverse—it takes the data in the object and writes it out to a file using the file structure defined by the complex record map.
Creating and Editing a Complex Record Map
You can create a new complex record map or edit an existing one by using the Complex Record Mapper in the Management Portal or by importing an XML definition and editing one in Studio.
The complex map has a top-level sequence in which you can define the fields. If your complex record consists of a single sequence of records, where the sequence does not repeat, you can enter the record maps of the records directly in the complex record map. But, if the entire sequence can repeat between the header and trailer, then you should enter a repeating sequence record as the only element of the top-level sequence.
Getting Started
To access the Complex Record Mapper from the Ensemble Management Portal, click Ensemble, Build, and Complex Record Maps. From here, you have the following commands:
Important:
The Save operation only writes the current complex record map to disk. In contrast, the Generate operation generates the parser code and the persistent object structure for the underlying objects.
Editing the Complex Record Map Properties
Whether you are entering properties for a new complex record map, starting from the wizard-generated map, or editing an existing map, the process is the same. For the complex record itself, enter or update values in the following fields:
Complex RecordMap Name
Name of the complex record map. You should qualify the complex record map name with the package name. If you do not provide a package name and specify an unqualified complex record map name, the complex record map class is saved in the User package by default.
Target Classname
Name of the Ensemble class to represent the complex record. By default, the Complex Record Mapper sets the target class name to a qualified name equal to the complex record map name followed by “.Batch”, but you can change the target class name. You should qualify the target class name with the package name. If you do not provide a package name and specify an unqualified target class name, the target class is saved in the User package by default.
Character Encoding
Character encoding for imported data records. The specified for the complex record map should be the same as the encoding for all record maps included in the complex record map. If they are not the same, the character encoding for the complex record map overrides the character encoding for the record maps.
Annotation
Text that documents the purpose and use of the complex record map.
If you create a new complex record map, the Complex Record Mapper creates a definition that consists of the following elements.
Editing the Complex Record Map Records and Sequences
A complex record map consists of the following:
  1. An optional header record.
  2. Sequence of elements where each element can be:
  3. An optional trailer record.
Each record is defined by a record map. A sequence is defined in the complex record map definition. It describes the structure of the data in the message but does not itself correspond to any fields in the data.
The header and trailer records are each defined by a record map. Although it is optional to include a header or trailer record in the complex record map definition, if the definition contains a header record, then the data must contain a header record, and if the definition contains a trailer record, then the data must contain a trailer record. Header and trailer records cannot repeat.
Every sequence must contain at least one record or sequence.
When you are editing a record, you can click the Make Sequence button to replace the record with a sequence. When you are editing a sequence, you can click the Make Record button to replace the sequence with a record.
You can specify the following properties for a record:
You can specify the following properties for a sequence:
Complex Record Map Class Structure
There are two classes that describe a complex record map in a similar manner to the two classes that describe a record map. The two classes that describe a complex record map are:
A complex record map business service reads and parses the incoming data and creates a message, which is an instance of the generated record class. A business process can read, modify or generate an instance of the generated complex record class. Finally, a complex record map business operation uses the data in the instance to write the outgoing data using the complex record map as a formatting template. Both the complex record map class and the generated complex record class have hierarchical structures that describe the data. The complex record map class and the generated complex record class have parallel structures. This is different from the RecordMap class, where the generated record class can have a different hierarchal structure.
When you create a new complex record map and then save it in the Management Portal, this action defines a class for that extends the EnsLib.RecordMap.ComplexMap and Ens.Request classes. In order to define the generated record class, you must click Generate in the Management Portal, which calls the Generate() method in the EnsLib.ComplexGenerator class. If you are working in Ensemble Studio, compiling the ComplexMap class definition does not create the code for the generated record class. You must use the Management Portal or call the ComplexGenerator.Generate() method from the Ensemble Terminal or from code. The generated class extends the RecordMap.ComplexBatch and Ens.Request classes.
The ComplexMap class defines the complex record structure in an XData definition that defines the ComplexBatch with records specified by RecordReference elements and sequences defined by RecordSequence elements. If the RECORDMAPGENERATED parameter of the existing class is 0, then the target class is not modified by the complex record map framework — all changes are then the responsibility of the production developer.
The ComplexBatch class has properties that correspond to the following top-level elements in the complex map definitions:
A class is defined for each sequence. The sequence class extends the ComplexSequence and %XML.Adaptor classes. The sequence class is defined within the package and namespace defined for the ComplexBatch class. All sequence classes are defined in this level of the namespace even if they are contained within other sequences.
Each sequence has properties that correspond to the records and sequences that it contains.
Using a Complex Record Map in a Production
To create a production that uses complex records, you do the following:
  1. Create the individual record maps for each part of the complex record, including the header and trailer. See Using the Record Mapper for a description of how to create the individual record maps. Note that if you intend to use a sample file, you should create a sample file that contains only the part of the complex record that you are defining in the individual record map. The sample file should not contain a complete complex record.
  2. Use the Complex Record Mapper to define the structure of the complex record.
  3. Create a production and add one or more of the built-in complex record services and operations.
  4. If your production is simply passing a complex record from one application to another, you may be able to use a simple routing engine process. But, if your production is converting one complex record into a different complex record, you will create a Data Transformation in the routing engine. If both the input and output complex records have the same structure, you can create a simple data transformation that connects the source and target fields. For example, you could use a simple data transformation to convert a complex record containing delimited records to a complex record containing fixed column records. But if the input complex record does not have the same structure as the output complex record, you must add code either within the data transformation or in a Business Process Language (BPL) process.