To convert an EDI document to a business object, the EDI data handler loops through the attributes of the top-level business object definition. It obtains the name of the business object to create, then processes the attributes recursively, in the order in which attributes appear in the top-level business object and its children, assigning element values from the EDI document to the business object.
The EDI data handler processes an EDI document into a business object as follows:
To initialize itself to convert an EDI document to a business object, the EDI data handler takes the following steps:
Each of these steps is described in more detail in the subsections that follow.
The EDI data handler must be able to mark a particular position within the EDI document and then subsequently return to that position. Because the EDI document is passed to the EDI data handler as a Reader object, this Reader object must be able to support the mark() operation.
As its first initialization step, therefore, the EDI data handler checks that the Reader object that it receives supports the mark() operation. If not, the data handler logs an error and generates an exception. It is recommended that all serialized data be passed into the EDI data handler in a StringReader object.
To convert an EDI document to a business object, the EDI data handler must correctly read separators in the EDI document. The data handler parses the document to obtain these separators. Because the first three characters of the EDI document are known, the data handler parses these characters first. It reads the first three characters to determine if they represent:
The UNA service string advice contains the document separators to use.
The data handler must parse the document to obtain the document separators and other positional information.
The UNA service string advice is the optional first element in
EDI documents that follow the EDIFACT standard. This service string
consists of six alphanumeric characters in the following order:
Component separator |
Element separator |
Decimal mark |
Release character |
Repeat separator (syntax version 4 only) |
Segment separator |
If the first 3 characters of the EDI document are "UNA", the data handler uses the values that the UNA service string specifies to interpret the EDI document. These separator values take precedence over any other separator settings in the EDI document, including any in the UNA or UNB positional-information attributes of the child meta-object.
If the first 3 characters of the EDI document are not "UNA", the data handler assumes that they represent the name of the initial segment. The data handler assumes that the initial segments are part of the header and have names that are exactly three characters in length. If no UNA service string advice exists, the data handler must obtain document separators from the EDI document itself. The data handler continues parsing the EDI document, performing the following tasks:
If the data handler is unable to determine the element separator, it uses the value of the SEPARATOR_ELEMENT attribute from the child meta-object. The delivered value for SEPARATOR_ELEMENT is an asterisk (*). If, for any reason, the data handler is unable to obtain the element separator from the child meta-object, it uses its hard-coded default of a plus sign (+).
Positional information includes the separators ( segment, composite, and repeat separators), transaction ID, and DUNS number. The data handler can usually determine this positional information by scanning the EDI document.
To help the data handler locate the positional information within the EDI document, the child meta-object associated with the EDI data handler (MO_DataHandler_DefaultEDIConfig by default) contains an attribute that holds this positional information. The name of this positional-information attribute corresponds to the name of the first element in the EDI document, as follows:
The positional-information attribute specifies the information with the
series of tags that Table 43 shows.
Table 43. EDI document information in the positional-information attribute
EDI document information | Attribute tag | Description | Required? |
---|---|---|---|
Segment separator | length | Specifies the length of the first segment (in number of characters), including the segment name but excluding the segment separator. | Yes |
Segment count | seg_count | Specifies the relative position of the field that contains the number of segments written to the EDI document (during business-object-to-EDI conversion). For information about the use of this tag, see Converting business objects to EDI documents. | Yes |
Composite separator | cs | Provides the relative position of the composite separator. | No |
Repeat separator | rs | Provides the relative position of the repeat separator. | No |
Transaction identifier | tid | Provides the relative position of the transaction ID. | Yes |
DUNS number | duns | Provides the relative position of the DUNS number. | Yes |
Version/release number | version | Provides the relative position of the functional group/message version number. | No |
As Table 43 indicates, the positional-information attribute must provide
values for the seg_count, length, tid, and
duns tags and optionally the version tag.
Specifying values for the cs and rs tags is not
required. However, if either of these tags are omitted and the data
handler parses EDI documents that contain composites, the data handler uses
the precedence shown in Table 44 to obtain a value.
Table 44. Default values for composite and repeat separators
The cs, rs, tid, and duns tags use the following format to indicate relative position within an EDI document:
tagname=seg_name+elem_pos+compos_pos
where:
The seg_count tag uses the following format to indicate its relative position within an EDI document:
seg_count=seg_name+elem_pos
where seg_name and elem_pos are as described above; that is, the seg_count specification never includes a compos_pos value.
Figure 29 lists a sample EDI document that uses the X.12 standard. To improve readability of this EDI document, the example inserts newline characters at the end of each segment.
Figure 29. Sample EDI document in X.12 standard
ISA*00*0000000000*02*XXXX*cw*ldtp3*cw*ld*970106*1525*U*00200*0000000100*0*P*< GS*AA*ldtp3*ld*20010424*1525*142*X*004010 ST*846*001420001 SE*2*001420001 GE*1*142 IEA*1*0000000100
To obtain the positional information from an EDI document that follows the X.12 standard, the EDI data handler takes the following steps:
For the sample EDI document in Figure 29, the child meta-object needs to contain an ISA attribute (because the name of the first segment is ISA).
In the current example, the ISA attribute contains the following positional information:
length=77;tid=ST+1;duns=ISA+6;seg_count=SE+1
or (If version is included in the dbfile.txt) then
length=77;tid=ST+1;version=GS+8;duns=ISA+6;seg_count=SE+1
The Figure 29 document follows the X.12 standard. This example does not include any composites. Therefore, its ISA attribute (in 2) does not include the composite (cs) or repeat (rs) separators. This attribute does include the tid tag, which specifies that the transaction ID occurs as the first element in the segment named ST; therefore, the transaction ID for the Figure 29 document is 846.
In Figure 29 the version is the 8th element of the GS segment: 004010.
In 2, the duns tag specifies that the DUNS number occurs as the sixth element in the segment named ISA; therefore, the DUNS number for the Figure 29 document is ldtp3.
To obtain the positional information from an EDI document that follows the EDIFACT standard, the data handler takes the same steps as described for parsing an EDI document that follows the X.12 standard. The only major differences are:
The following line is a fragment of an EDI document that follows the EDIFACT standard:
Figure 30. Sample EDI document fragment with composite separator
ST*st_child_value_1*,*st_grand_child_val_11,st_grand_child_val_12^ st_grand_child_val_13,st_grand_child_val_14*st_child_value_4* st_grand_child_val_21,st_grand_child_val_22
If its first segment was named "UNB", then the child meta-object contains a UNB attribute that includes the following cs tag:
cs=ST+2;
This cs tag specifies that the composite separator occurs as the second element in the segment named ST; therefore, the data handler interprets the comma (,) as the composite separator. Suppose that the EDI document in which this fragment occurs did not specify a repeat separator; it uses the default value of the caret (^). Therefore, the UNB attribute in the child meta-object that this document uses does not need to contain an rs tag to specify the repeat separator. With no rs tag, the data handler assumes that the repeat separator has its default value. When the data handler encounters a caret (^), it interprets this character as the repeat separator.
To define a non-default repeat separator, the EDI document must include the non-default character in a field (usually in the header) and the positional-information attribute in the associated child meta-object must include the rs tag to indicate the location of this field.
A data handler can receive serialized data in one of two ways:
If the data handler does not receive a business object, the data handler must determine the type of the business object to create. The data handler calls the name handler, which takes the following steps:
If the lookup of the business object name fails, the data handler logs an error and generates an exception. If the lookup is successful, the data handler creates a business object of the specified type to contain the data.
Once the EDI separators have been determined and the top-level business object has been created, the data handler takes the following steps to populate it with the serialized data:
Once the data handler has populated all attributes of the top-level business object, it can perform an optional check to ensure that all the EDI data has been parsed.
The structure of the business objects that hold EDI is determined by the EDI document specification. (For information on how to create this business object structure, see Creating business object definitions for EDI documents.) The EDI data handler uses the cardinality of the attribute to determine this attribute represents the current EDI part of the EDI document. Based on this cardinality, the data handler takes the following actions:
Table 45. Application-specific information and the associated EDI business objects
Application-specific information | Child business object |
---|---|
type=header | Header business object |
name=segment name | Segment business object |
name=name of first segment in loop;type=loop | Segment-loop business object |
type=trailer | Trailer business object |
The EDI data handler parses information in the EDI document based on the
separators it has identified in the initialization phase. These
separators determine each of the different pieces of data, which the data
handler then matches to the appropriate attribute. Table 46 shows the parsing tasks that the data handler takes for the
different EDI business objects.
Table 46. Parsing tasks for EDI business objects
Application-specific information | Parsing task |
---|---|
type=header, type=trailer | The data handler finds the position in the business object that corresponds to the next segment that appears in the document, and parses that segment to populate the child business object. |
name=segment_name (no type tag) | The data handler assumes that the business object represents a segment and parses the current segment to populate the business object. |
type=loop | The name of the first segment contained in the loop should be specified in the application-specific information. The data handler parses the EDI document for these loop segments and adds the data to the business object. |