Documenting BizTalk Environment and BizTalk Solution
When it comes to documentation with BizTalk it can be challenging task. What do and what do I not document and how do I document it. In my view there are three types of documentation when it comes to BizTalk in my opinion. That is:
- BizTalk Environment (Design) document
- Functional Design of BizTalk Solution
- Technical (Design) of BizTalk Solution
BizTalk Environment (design) documentation you can described the different BizTalk environment Development, UAT and Production. In this type of document you can roughly describe the following:
- Purpose;
- Design Decisions regarding environments;
- Considerations/Issues;
- Landscape (how does it fit with in IT-Landscape in Enterprise);
- MS BizTalk and SQL Server editions;
- SQL Server configuration (sizing disk, clustering e.a.);
- ICT Policy (Back up, Anti-virus, Patching, e.a.) applied in Enterprise;
- Operating Systems;
- Security Settings;
- Backup and Restore (procedures e.a.);
- BizTalk Group Configuration (clustering, availability e.a.);
- Host configuration;
To add you in documenting the environment or take into consideration (i.e. reference material) is MSDN Microsoft BizTalk Server 2010 Operations Guide.
Functional Design you describe how solution will work, which service it will call, what type of message’s it excepts, processes and sends. You can use notation symbols found in EAI Patterns site and create a functional model for your BizTalk solution (see example below).
You can also use UML like state diagram to depict process that is implemented in BizTalk solution (see picture below).
![clip_image002[6]](https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjX1_I8pLomoSPMKY-5koskwLrFqzJsyR380pjaHxsuSEAKViKbSxH0vwTeNrfR9ZaxRSYmwNtHfmQhV6SR9F3yHk0DeZSP5RMe8N7ClMTRX2JKbMvO_3W7N8n-NL-Mruxjd0Hh/s1600-h/clip_image002%25255B6%25255D%25255B4%25255D.jpg "clip_image002[6]")
Besides diagrams, you will also document specifications for messages (data types, restrictions, e.a.), security settings, protocols, message patterns, and so on.
Finally Technical (design) documentation of BizTalk solution and its configuration is fairly simple as you use BizTalk documenter for it. This is tool found on codeplex that can automatically generate a document (compiled chm, and even HTML for 2010 version).You can start documenter and following screen will be shown.
Click Next, Select if you want to completely document entire configuration of specific BizTalk application.
Click Next, you can select (this is new with BizTalk 2010 documenter) SSO configuration e.a.
Click Next, choose output options.
Finally you can click Generate Documentation and documentation will generated for you in desired format.
As you can see working with documenter is pretty straight forward and type of documentation can be realized with minimal effort. You can keep this documentation easy up to date when changes are made to BizTalk solution. Versioning your solution and its documentation is very important here! Documentation of BizTalk environment will take more effort and will be done in MS Word with perhaps drawings from Visio (there are BizTalk stencils, see post by Sandro). Functional documentation regarding your BizTalk solution will also require some effort, but vital before implementing your solution. Usually MS Word and Visio are used here as well.
Comments are welcome as I am interested in your view on documenting BizTalk.
Cheers!
Comments
Have you thought about how you design and document a new BizTalk Application?
You might want to look at BPMN. I have been using Visio 2010 Premium to design, model, and document all my BizTalk Applications.
Many of my clients have standardized on it.
Great details on what to document for BizTalk.
I would like to suggest, that you organize the same content within already acknowledged document formats. Im thinking of 4+1 or later adaptations:
http://en.wikipedia.org/wiki/4%2B1_Architectural_View_Model
The level of detail depends on the project, the viewpoints are the absolute minimum, which can be extended endlessly to fit the project stakeholdes (Users to Operations)
I have seen BPMN, but not applied for BizTalk Solution Design. I agree it can be an useful notation for BizTalk still not many clients in the Netherlands use it for BizTalk. I have seen it being used for SOA.
Different viewpoints of BizTalk environment is an absolute must and using 4+1 model is something I definetly will look into as I have not viewed at BizTalk and solutions that way.
I find that too often you change the flow of work so I tend NOT to document the functional part using illustrations. I use words instead.
An illustration is, however, VERY useful from a high level to show which servers are involved etc.
My basic principle is that you should NEVER document things which a developer has access to and does not benefit from documentations. As such I tend not to document orchestrations nor maps in any detail as these are accessable by the developer. A tool like BizTalk Documenter is (in my view) not very useful at all as it only collects information that is accessable by the developer.
A question put to you and anyone else that might be reading: Were (if done) do you document information about ports and port settings?
You can use the documenter to document ports and port settings. You need discipline and use versioning whenever a port and/or setting changes. If documenter is not fit for purpose either commercial or custom solution (using WMI for instance) will be required to do the job.
In my experience you never have the dicipline to update documentation. It will always be out of sync with the actual settings (yes I know you can incorperate that in the build).
I think a tool like documenter is good in cases were there is no documentation nor knowledge and you need to create some kind of overview.
Hi i think the BizTalk Documenter is perfect when you work the way we do, the developer make the code and we as an operation Team deploy the solution. We use the BizTalk Documenter to verify the code, how the developer have done in the code, to see if it is the optimal solution to run on the infrastructure. And often this is the only way for us to actually see the code.
healthcare, e commerce, programming, multi platform,inventory management, cloud-based solutions, it consulting, retail, manufacturing, CRM, technology means, digital supply chain management, Delivering high-quality service for your business applications,
Solutions for all Industries,
Getting your applications talking is the key to better business processes,
Rapid web services solutions for real business problems,
Web-based Corporate Document Management System,
Outsourcing Solution,
Financial and Operations Business Intelligence Solution,