I have been working with BizTalk for a long time. Like many, I came from the world of “let’s jump in and get this thing done.” (aka Cowboy Coding or Get ‘er Dun!)
That has served me well and continues to do so. However, as I work on more large, enterprise-scale, cross-functional integration projects, the need for the D word increases – Documentation (developers shudder!).
I am not one for writing reams of documentation, as are most developers. I prefer to focus on diagrams, well-written code, and a brief configuration document (endpoints).
However, one document that has become a staple is an easy-to-read mapping document. I have gotten into the habit of creating an Excel spreadsheet for each of the major maps in an integration. I use it heavily during the tedious process of field-mapping discovery. I define the source and target schema, put the target schema into a spreadsheet, and then use it as a guide to define the field mappings with subject matter experts. If possible, I have a projector and sit with clients to complete the document with them. Screen-sharing with Lync or GoToMeeting works quite well also.
Sample mapping document (simplified for brevity, not a real-world example).
A few points on the document…
- Pseudo-code and pseudo-xpath expressions describe source field mappings and logic
- Dark blue signifies groups of records
- Light blue signifies a record element
- White rows are field elements or attributes
- Yellow highlights show things in need of follow up.
- Red highlights would show if something were a critical issue.
- The date on the left is the last time an issue was discussed.
- This sample shows an element-centric PO being mapped to an attribute-centric Invoice.
I have found these documents to be extremely valuable, especially when questions arise as to “what comes from where and why?” Rather than having to crack open the code, or ask a developer, business folks can reference these documents. On some occasions, I have been able to hand a document stubbed out with the “To” schema to a Business Analyst and have them make a first pass at the field mappings. Then we would review it and use it in the map development cycle.
Other random thoughts on mapping…
Having done this, and used this process for a long time, I have some tips and opinions.
- The document is complete, or near complete BEFORE developing the BizTalk map. If field-mapping discovery drags on, I will go ahead and map what is in the document up to now. This is when the dates in column A come in really handy.
- I never do mapping sessions with a client using the BizTalk mapper itself. I want to train the client to use these documents themselves. Otherwise they will always depend upon a developer to crack open BizTalk to answer questions about field mappings. I want to train them to answer their own questions using these documents.
- I have tried using the BizTalk Map Documenter, and I like the tool. However, it is a post-development tool. In very complex scenarios, up-front analysis has saved me a lot of time.
- Clients I have worked with love these documents, both because they have a stake in completing them, and they are a durable non-code artifact they can understand and refer to.