Creating/Editing an EDI Implementation Guideline
- What is an EDI implementation Guideline?
- The Standard Exchange Format
- Editing SEF Files
- Editing SEF Files with the SEF Manager
- Changing a Data Segment in the Transaction Set
- Changing a Data Element
- Changing a Code Set of an Element in the Transaction Set
- Changing a Code Set in the Elements Directory
- Inserting a Data Segment into a Transaction Set
- Changing a Syntax Rule
- Adding a new Data Segment
- Adding a new Data Element
- Creating another Instance of a Data Segment
- Creating another Instance of a Loop (Group)
- Editing the Message Version
- Deploying the Implementation Guideline
Before companies can exchange EDI files among themselves, a set of rules defining their EDI files and how they should be processed have to be established and documented. This document is known as the implementation guideline (or companion guide). Some examples of rules in an implementation guideline document can include: the requirement of a data segment whether it be optional or mandatory; or the validity of a value in a data element; or the number of times a loop or group of segments can be used. The implementation guideline is the single most important document for a user creating a mapping of the corresponding EDI file to/from an existing system. If an implementation guideline document is well written, it would be the only document needed for creating an EDI processing solution.
An implementation guideline document can come in many forms. It can be a printed hard-copy document, or in digital file formats such as pdf, rtf or doc files. But, the preferred and most useful implementation guideline format is the Standard Exchange Format (or SEF) file. SEF files are text files that have a standard format of presenting the implementation guideline, which makes it possible to programmatically parse and obtain information from the file, and therefore is machine-readable. Below is an example of a SEF file in its raw format.
Because a SEF file is machine-readable, the file can be loaded into a translator application and have its information programmatically obtained. The information can then be presented onto screen in a user-friendly format for a user to view the implementation guideline, or can be used to parse, construct or validate a corresponding EDI file automatically in an application. Having the implementation guideline in a format that can be immediately used by both the user and EDI application is the major advantage SEF files have over all other file formats. With SEF files, the step of having to convert the information a user has read from an implementation guideline, to a format that an application program can use, is eliminated. Thus saving time as well as avoiding possible errors during conversion.
The advantage of EDI (Electronic Data Interchange) files over all other data formats such as XML or delimited files is that, in EDI, all the implementation guideline for each type and version of documents have already been established. In X12, the document standards are called transaction sets, while in UN/EDIFACT they're simply called messages. Additionally, all the implementation guidelines for these transaction sets or messages are available in SEF. Therefore, one does not have to create an implementation guideline from 'scratch', but can create one from an existing SEF file. So to create an implementation guideline, one only needs to obtain the appropriate SEF file, and then edit it.
- SEF files can be obtained from our eShop
For example, to create an implementation guideline for an 810 version 4010 EDI file, it would just be a matter of obtaining an 810 4010 SEF file, and then editing it to include your own (or trading partner's) requirements. SEF files are text files, and can be modified by using any text editor. But a better method of editing a SEF file with less chance of corrupting the file is by using our SEF Manager.
- The SEF Manager Utility is packaged with Framework EDI. Click here to download the trial version.
If one can understand the basic structure of an EDI file, then one can easily comprehend the format of SEF, since SEF files are basically templates or schemas of EDI files. An EDI file consists of a message, which is made up of data segments, which are in turn made up of data elements. So if one were to open a SEF file, one would see it divided into sections. Below are descriptions of some of them:
- .SET or Transaction Set - This section contains the template of an EDI message. It contains all the data segments and elements allowed, and their requirement if they are mandatory or optional in an EDI file. It also contains the number of times a segment or a group of segments can be used.
- .SEGS or Data Segment Directory - This section lists all data segments used in the transaction set, as well as displays the data elements that constitute each of the data segments. Editing a data segment in this section will affect all of the same data segment in the transaction set (.SETS).
- .COMS or Composite Element Directory - This section lists all composite elements used in the transaction set, as well as displays the sub data elements that constitute each of the composite elements. Editing a composite element in this section will affect all of the same composite element in the transaction set.
- .ELMS or Data Element Directory - This section lists all data elements used in the transaction set. It describes the structure of the data elements by listing each of their data type, and minimum and maximum length of their values. Editing a data element in this section may affect the composite element and data segment directories and transaction set section.
- .CODES or Code Directory - This section lists all data elements that have codes in them being used in the transaction set. Editing the codes of the data elements in this section will affect all code sets of the same data element in the transaction set.
- .TEXT or Message Text Information - This sections contains notes made in the transaction set.
Creating an EDI Implementation Guideline quickly and accurately
The SEF Manager allows a user to view and edit a SEF file in a more user-friendly way. In edit mode, the SEF Manager lays out the structure of the implementation guideline in a hierarchical tree format so that one can easily identify each unit of the structure (such as segments and elements) and see the relationships between them. Below is an example of how a SEF file is viewed with the SEF Manager in edit mode.
By default, the SEF Manager expands the Transaction Set Directory (.SETS) node when a SEF file is loaded. If the Transaction Set Directory is collapsed, the other sections (.SEGS, .COMS etc.) mentioned above can be seen in the same root level. The nodes in the hierarchical tree represent units of directories, loops, segments, elements etc. in a SEF file. Nodes can be expanded to drill-down to other nodes, or collapsed by double-clicking on them. To edit a node, simply right-click on it, and then select an action from the pop-up menu.
To edit the properties of a data segment in a transaction set section, simply right-click on the data segment node in the transaction set tree, then select "Change Segment Reference" from the pop-up menu. Then on the dialog box, edit the fields you want to change.
- Position - This is a a numerical id of the data segment.
- Seq - This is the numerical order of the data segment.
- Description - This is a text description of the data segment.
- Requirement - This field contains the standard requirement setting of the data segment. If a segment requirement needs to be changed, it is recommended that it should be changed from the User Requirement field.
- Maximum Usage - This field holds the number of times this specific segment can be used.
- User Requirement - This field contains the user setting requirement for the data segment. The User Requirement setting overrides the standard Requirement setting.
To edit a data element of a segment, simply right click on the data element node, then select "Change Element" from the pop-up menu, and then edit the fields on the dialog box.
- Description - This is a text description of the data element
- Requirement - This is the standard requirement setting of the data element
- Minimum Length - This is number of characters the data element can least contain.
- Maximum Length - This is the number of characters the data element can have at most.
- User Requirement - This is the user requirement setting of the data element. The User Requirement setting overrides the standard Requirement setting.
If a data element in a transaction set is to have a different set of codes than the code set in the directory, you can edit the data element code set in the transaction set by first expanding the node of the data element to expose the Code node.
Then simply right-click on the node and select an action from the pop-up menu to either add or remove codes. (Note that the data element must already have a code set in the element directory before you can add codes to the same data element in the transaction set.) When code values are added into code sets of data elements in a transaction set, they are grouped into partitions, which in most cases (and by default) would have only one. Having more than one partition would mean that all combination of code values concatenated between partitions are valid values for that particular data element.
A code set can be created in the Data Elements Directory (.ELM) section by right-clicking on the data element, then selecting the "Add Code" from the pop-up menu.
Only once a data element has a code set in the Data Elements Directory (.ELMS) , will it become possible to edit the code set for the same data element in the transaction set (.SETS) section.
Before a new data segment can be inserted into a transaction set, the data segment must already exist and be defined in the Data Segment Directory (.SEGS section). (To add a new data segment into the Data Segment Directory, please read the topic "Adding a New Data Segment".) To insert a data segment, simply right-click on the segment node where you want the segment inserted, and then select either "Insert Segment Reference (Before)" or "Insert Segment Reference (After)" from the pop-up menu.
The requirement of a data element can sometimes be conditional to the state of another data elements of the segment. For example, in data segment ACT, the data element 6 is required if element 5 is present. This conditions are represented as a syntax rule in the SEF file, which can be edited by finding and expanding the data segment in the Data Segment Directory, and then right-clicking on the Syntax Rule.
A new data segment can be added into the Data Segment Directory (.SEGS section) by right-clicking on the directory node, and then selecting "Add Data Segment" from the pop-up menu. You can then edit the fields on the dialog box similar to the one below to add a segment ID, description, data elements and composite elements.
Note that the data elements and composite elements (that will constitute the data segment) must already exist and be defined in their directories (.ELMS and .COMS) before they can become available in the selection for inclusion.
A new data element can be added by right clicking on its directory node, and then selecting "Add Data Element" from the pop-up menu. You can edit the following element properties on the dialog box.
Element ID - Enter the data element ID comprising of numerical characters.
Description - Enter the description for the data element.
Data Type - Select the element data type. Below is how Framework EDI translates the following data type:Minimum Length - The minimum number of characters the data element can contain
- AN - alphanumeric string value containing at least one non-space character. Leading spaces are valid characters, but trailing spaces will get truncated.
- DT - Date value consisting of numbers in either format YYMMDD or CCYYMMDD.
- ID - Identifier value. Valid values must be listed in the .CODES section of the SEF file.
- N0...N9 - Numeric value with no decimal point, but the decimal point is implied at the position count (taking the number after the letter "N" as the count number) from the right of the value . e.g. 123 of data type N2 should be translated as 1.23
- R - Real numeric value, which can consist of a decimal point.
- TM - Time value consisting of numbers in the format HHMMSS.
Maximum Length - The maximum number of characters the data element can contain
In cases when you want to be more specific with the conventions for each instance of a repeating data segment (e.g. repeating a DTP segment so that one instance holds an Order Date, while the other holds an Initial Treatment Date), you would first have to create a duplicate of the data segment by right-clicking on the data segment, and then selecting "Duplicate Segment Reference" from the pop-up menu.
(Please note that duplicating a data segment is not the same as inserting a new data segment with a similar Segment ID name because inserting a segment would create a different Segment Position number for the new data segment.) Once the data segment is duplicated, you can then edit the data elements of each data segment and adding to them their own different conventions. You must make sure that the data element qualifier for each instance of the data segment has a different value so as to differentiate the data segment instances. In our above example, the qualifier for the DTP segment is in Element ID 374 (or DTP01), which in one of the instances has the value "938" or the Order Date; and in the other instance has the value "454" or the Initial Treatment Date.
An extra recommended step for Framework EDI users is to include triggers into the SEF file so that they do not have to be included into your program source code. A data segment trigger is a line declaration to the Framework EDI component commanding if its specified segment is encountered in an EDI file, then the convention the trigger is referring to must be used to parse that specific segment in the EDI file. The trigger syntax is not part of the open standard, but is proprietary to EDIdEv, so the trigger commands have to be included in the .PRIVATE EDIdEv section of the SEF file. The syntax for a segment trigger is:
TriggerID - A unique identifier for the segment trigger line. Must start with the letters "SEGMENT"
TranSetID - The transaction set (or message) identifier of the data segment.
Area - The area or table number in the transaction set of the data segment.
LoopSect - The loop section of the data segment.
SegID - The data segment identifier
ElemPos - The data element position number of the segment qualifier.
SubElemPos - If the ElemPos was a composite element, then this is the position number for the sub element of the segment qualifier.
ElemValue - The value of the segment qualifier that will trigger to its reference. This value must be unique from the other qualifiers of the other data segment instances.
RelPos - Relative position of the instance of the data segment from its other instances.
LooPID - The loop id of the data segment. (This is optional.)
For example, the data segment triggers for the DTP segment instances (illustrated above) are:
Similarly, the conventions for each instance of a repeating loop can be specified by doing the similar steps as described above for the data segments. To create another instance of a loop, you would first have to duplicate it by right-clicking on the loop and then selecting "Duplicate Loop" from the pop-up menu. Once the loop is duplicated, you can then edit the conventions for each loop. Each loop instance must have a unique entity identifier so that the loops can be differentiated. Normally, an entity identifier is contained in a data element of the first data segment in the loop. In our illustration below, two instances of the HL loop are displayed. The first loop instance has a Loop ID 2000A with HL03 as the data element that contains the entity identifier "20" or "Information Source"; while the second loop instance has a Loop ID 2000B with an entity identifier "22" or "Subscriber".
The syntax for the loop trigger is
TriggerID - A unique identifier for the loop trigger line. Must start with the letters "LOOP"
TranSetID - The transaction set (or message) identifier of the data segment.
Area - The area or table number in the transaction set of the data segment.
LoopSect - The loop section.
ElemPos - The position number of the entity identifier data element.
SubElemPos - If the ElemPos is a composite element, then this is the position number of the entity identifier sub element.
ElemValue - The value of the entity identifier data element that will trigger to its reference. This value must be unique from the other loop instances' entity identifier.
LooPID - The loop id of the loop instance.
For example, the loop triggers for the above illustrated HL loops are:
Some industries or companies create a message version code (industry code or association assigned code) in their implementation guideline so as to differentiate it from the standard published version or from other implementation guideline of the same group version. For example, EDI X12 files that follow the VICS industry standard would have the "VICS" industry code after the group version in the GS08 data element e.g. 004010VICS. In the HIPAA industry, EDI files for the Professional Health Care Claim would have the "X098" code after the group version in the GS08 data element e.g. 004010X098. While in EDIFACT, the association assigned code can be found in UNH0205 data element e.g. EAN008. To edit the message version of the SEF file with the SEF Manager so that the message version will correspond accurately with the associated EDI file, simply expand the "Information (.INI) node, then right click on the "Functional Group Version" node, then select "Change Information", and then edit the code in the Industry Code field.
Another advantage with the SEF file is its small size. A typical SEF size is less than 300KB, which makes it easily portable. It can easily be sent by email, ftp, disk or downloaded from a company website. Although, quite unreadable in its raw format, a SEF file can be viewed clearly with a SEF Reader.
Above is an example of a SEF file viewed with our SEF Reader.
For more about SEF files, click here.
- For editing Semantic References with the SEF Manager, please visit http://www.edidev.net/edidev-ca/help/Utilities/SefManager/SemanticReference/SemanticReference_Topic.htm
Editing a SEF file for a more accurate EDI validation