If you work in the map development field (as a developer or a business analyst), you know that a good bridge document (crosswalk, design, MRG and so on – document which describes how to translate source structure into target) is very important. There are several ways to create a bridge document and I use several rules to create a good one.
First of all, design document should be based on the target structure, not the source. I.e. if you need to describe SAP IDoc to EDIFACT translation, you should start with the EDIFACT structure, not the IDoc.
VBELN -> BGM-02
BGM-02 <- DELVRY03/IDOC/E1EDL20/VBELN
Next, your bridge should contain the following information about elements, records and groups/loops:
- Entity’s name. PID-05 is not as clear as “Product/Item Description”
- Elements: data type, data length, format
- Records and groups/loops: Repeatable/Non-repeatable
- Records and groups/loops: Relation to the parent entity (if exists)
Then, the mapping rules of course. There are two main type of the mapping rules – hardcoded values and values which come from the source data.
Hardcoded values are self-explaining. However, you should try to avoid rules like “Hardcode ‘BM'” – it’s really not clear why a map developer should hardcode ‘BM’, especially if she/he doesn’t know the format well. A better way is to give more details: “Hardcode ‘BM’ (BM = Bill of Lading)”
Values from the source data
I prefer to use the full path to avoid possible misunderstanding (some business analysts don’t know that there might be the REF segments at the different levels in X12 for example) – i.e. DELVRY03/IDOC/E1EDL20/VBELN or ST/LIN/REF/REF-02 instead of E1EDL20/VBELN or REF/REF-02. Also, I found it useful to use XPath-style paths like:
ST/LIN/REF[REF-01 = ‘BM’]/REF-02
If there are more complex condition, you should describe them in the “Comments” column.
If there are some conversion rules, for example Unit -> C62, I use a comment ” + Conversion:” and describe every conversion pair (and description of every value, see above).
Last, there should be “Comments” section for every structure entity.
Usually I use MS Excel for creating such bridges. There should be the main sheet + change log sheet. During the testing my maps I mark “implemented” rules with yellow background, “implemented and tested” with green and “questions/doubts” with pink.
In addition to the bridge I really like to have: input/output data examples and the original specifications for the output and input.