The BizTalk Documenter has been available for many years on Codeplex for different BizTalk versions, starting with 2004 all the way to 2013 R2. The Documenter for 2004, 2006, 2006 R2 and 2009 can be found here. Some years later, a version for BizTalk 2010 was created. Last year, MBrimble and Dijkgraaf created a newer version which also supports BizTalk 2013 and 2013 R2. They did a great job; all improvements and fixes are listed here.
As in many things in life, there is always room for further improvement. While using the BizTalk 2013 Documenter, we realised that some changes could be done to better document BizTalk Solutions. I downloaded the source code and did some changes for my own, but then after sharing with the team what I had done, they invited me to collaborate in the project. I created the BizTalk 2013 Documenter 5.1.7.1 for BizTalk 2013 with some fixes and improvements.
I will share here not only the changes that I did, but some tips that I consider can help you to better document your BizTalk solutions. If you would like to implement them, please make sure you have got the latest version of the Documenter.
1. Leverage the BizTalk Documenter
The first and obvious tip is to leverage the BizTalk Documenter. This tool allows you to create a CHM file describing your BizTalk environment and BizTalk Solutions. The first main section of the generated documentation contains your BizTalk Applications, listing all their artefacts and providing a navigable and very graphical documentation of all artefacts. The second main section describes the platform settings like hosts and adapters. The third main section documents BRE policies and vocabularies. You can expect an output similar to the one shown below.
2. Use embedded documentation as much as possible
The practice of embedding documentation can be applied to your BizTalk Solutions. Using the BizTalk artefact’s description field within the Admin Console allows you to describe the purpose and function of each artefact and keep this always visible for administrators and developers. If you use the BizTalk Deployment Framework you can easily replicate your artefact’s description on all you environments by exporting applications’ bindings.
In our projects, we wanted to fully use embedded documentation for the BizTalk Solutions, but the previous Documenter has some minor bugs and Receive Ports, Schemas and Pipelines did not include the description field as part of the generated documentation. I’ve fixed them by updating some “.xslt” files and a class of the BizTalkOM library; and now the output includes description for all different artefacts.
3. Include your ESB Itineraries as part of your documentation
The BizTalk ESB Toolkit provides a lot of functionality which allows and simplifies the implementation of an Enterprise Service Bus; and ESB Itineraries are usually a key component of these solutions. That said, when they are part of a solution, itineraries should be within the documentation to fully understand the solution as a whole.
However, itineraries are not documented in the BizTalk Documenter out-of-the-box. One way to do it is to create a web page which briefly describes the itinerary and attach it to the documentation. There is a simple and easy way to do it. The first step is to create a Word document, including a picture of the itinerary designer, a description of its purpose and functionality, and the configuration of the resolvers. Then, after creating this document, save it as a Single File Web Page “.mht”.
I’ve introduced a change to the BizTalk Documenter to accept not only “.htm” and “.html” files as additional resources, but “.mht” files also. The big advantage of this is that documentation which includes images can be created on Word, saved as a “.mht” file and easily added to the BizTalk documentation.
Once created the documentation for each itinerary, they should be saved in a subfolder which can be called “Itineraries“. I suggest this folder name to have a clear structure in the generated documentation, but it can be set according the specific needs. This folder should be under a “Resources” folder which will be selected during the creation of the documentation.
The last step is to be executed when generating the documentation. Under the “Output Options” page, in the “Advanced Documentation Options” section, the Resources folder which contains the Itineraries folder should be selected.
Doing so, the generated documentation should have the “Itineraries” branch under “Additional Notes“, and under this, the list of itineraries. This way, these important components of your BizTalk solutions are now part of your documentation.
4. Document your Maps
We have incorporated the functionality of another Codeplex project, the BizTalk Map Documenter, as part of the BizTalk Documenter. If you want to include documentation of your maps in more detail, the BizTalk mapper “.btm” source files must be available, and the following steps must be executed when generating the BizTalk documentation.
First, copy the BizTalk mapper files of the BizTalk Applications that are to be documented into a folder named “BtmSourceFiles“. Then, rename the maps so that they have the full name as they appear in the BizTalk Admin Console, but here including the “.btm” extension. And finally copy the “BtmSourceFiles” folder under your Resources Folder to be selected in the Documenter Output Options. The “BtmSourceFiles” name of the folder and the full name of the maps are required for the Documenter to be able to document in detail the maps.
In the following screenshots it can be seen the detailed BizTalk map documentation which you can expect. It shows direct links between source and target nodes, functoids, and constant values utilised in the map.
5. Enrich your documentation with other relevant information
In the tip #3, I mentioned how you can include your itineraries as part of your documentation. In addition to that, you can enrich your documentation with any Word or Excel document saved as “.mht” file or any other html file which is relevant to your solution. As an example, you could include the SettingsFileGenerator file of the BizTalk Deployment Framework. You just need to open it on Excel and save it as “.mht” file. This file must be saved in the corresponding folder under your Resources folder selected when you create the BizTalk Documentation. This way, your settings for Deployment can be included in your documentation.
6. Document only artefacts relevant to your solution
Previous versions of the BizTalk Documenter allowed you to select those BizTalk applications to be included in the documentation. However, the Platform Settings and Business Rule Engine sections of the generated documentation always included all hosts, adapters, policies and vocabularies. In some projects, we had the need of documenting only those hosts, adapters, and BRE artefacts relevant to the solutions in scope. To satisfy this need, I added the “Additional Filters” page on the Documenter. On this page, you can filter hosts, adapters and BRE artefacts. Filters are applied using a “StartWith” function, which means that all artefacts starting with the filter will be included. Multiple filters can be defined using a “|” (pipe) delimiter. The following screenshots show the configuration and the output of this new functionality.
7. Put a nice cover to your documentation
The icing on the cake of a good documentation would be to put a nice cover which is aligned to your needs. To do this, you need to add a custom “titlePage.htm” file on the root of your Resources folder selected in the Output Options tabs. If you are using your own custom images, you need to add them to the same root folder.
The default cover page and a customised one can be seen in the following two images.
The option of customising the cover page has been available since past versions of the Documenter, but in order to get the template of it, the source code has to be downloaded. In this link you can see and download the html template only which you can customise according to your needs.
Note that the template makes use of a stylesheet and images which are part of the documenter. You can use yours by adding them in the same Resources root folder. You can freely customise this html according to your preferences and needs. Make sure you name your “.htm” file as “titlePage.htm“.
I hope you find these tips useful and the BizTalk Documenter can help you to provide a comprehensive and quality documentation to your implemented BizTalk solutions. Please feel free to suggest to the team your ideas or improvements for the BizTalk Documenter on the Codeplex page.
Reblogged this on BizTalk musings and commented:
Paco has added some new functionality to BizTalk Documenter and has written the following blog with how to use it to get the maximum benefits out of it.
On the ‘Select Documentation Type’ screen, I selected ‘Specific BizTalk Application’ and got the following exception:
“Could not load file or assembly ‘Microsoft.Biztalk.Interop.SSOClient, Version=7.0.2300.0 …’ or one of its dependencies.”
Similarly, when I selected ‘List Orchestrations’ on the Orchestration Info page, I got the same error.
I am running BizTalk Server 2013 R2 on Windows Server 2012. I installed the BizTalk Server 2013 R2 Fix for SSO Configuration Application MMC Snap-In (SSOMMCSnapIn.dll) by Sandro Pereira, overlapping the existing file at ‘C:\Program Files (x86)\Microsoft Services\SSO Application Configuration\’ folder.
Hi Hector,
This version of the BizTalk Documenter has been compiled with BizTalk 2013 binaries. However you can do a binding redirect on your own environment.
On your BizTalk app.config you need to add the following configuration element. You just need to make sure the assembly newVersion matches yours
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1" appliesTo="v4.0.30319">
<dependentAssembly>
<assemblyIdentity name="Microsoft.BizTalk.Interop.SSOClient" publicKeyToken="31bf3856ad364e35" culture="neutral" />
<bindingRedirect oldVersion="7.0.2300.0" newVersion="9.0.1000.0"/>
</dependentAssembly>
</assemblyBinding>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1" appliesTo="v4.0.30319">
<dependentAssembly>
<assemblyIdentity name="Microsoft.EnterpriseSingleSignOn.Interop" publicKeyToken="31bf3856ad364e35" culture="neutral" />
<bindingRedirect oldVersion="7.0.2300.0" newVersion="9.0.1000.0"/>
</dependentAssembly>
</assemblyBinding>
</runtime>
More info about binding redirect here:
https://msdn.microsoft.com/en-us/library/7wd6ex19(v=vs.110).aspx
HTH
Paco, thanks for the prompt reply. Believer it or not, I’ve been busy doing other things till now, and just now got back to this task. Can you clarify something, though, please . . . You said, “On your BizTalk app.config …” Did you mean the BizTalk app.config or the BizTalk Documenter app.config? Isn’t it BizTalk Documenter that’s trying to access BizTalk’s SSO?
You are right, I meant the Documenter config 🙂 Let me know how it goes…
Paco, your solution worked like a champ. Yes, i did change Documenter’s .config file, not BizTalk’s.
Great! Thanks sharing it! Happy coding and documenting 😉
So I made the same change to the config, it was looking for 9.0.100.0, so I changed it to point to 9.0.1865.0, but now it errors:
System.IO.FileNotFoundException: Could not load file or assembly ‘Microsoft.BizTalk.Interop.SSOClient, Version=9.0.1865.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35’ or one of its dependencies. The system cannot find the file specified.
File name: ‘Microsoft.BizTalk.Interop.SSOClient, Version=9.0.1865.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35’ —> System.IO.FileNotFoundException: Could not load file or assembly ‘Microsoft.BizTalk.Interop.SSOClient, Version=9.0.1000.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35’ or one of its dependencies. The system cannot find the file specified.
File name: ‘Microsoft.BizTalk.Interop.SSOClient, Version=9.0.1000.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35’
Here’s what I changed in the config
Thanks,
TRH, Were you able to fix this issue? You need to make sure that the binding redirection is according to the versions installed on your environment.
yes those file are the the resources\btmsourcefiles. I included the map .btm and .cs files and left the extensions on there. Does it need any of the schema files with it?
Like I said it copied the files into the ~working directory, but then it didn’t do anything with them. Wondering if it doesn’t like the filenames with . in them?
Yes, I had to just the versions number correct. Thanks!
For the map documenting, I copied the .btm files. Gave them the complete name, like IT1.EDI.Order.Map850To850EDI.btm.
And then ran it, it completes, but the map is empty. I added the schema files and the .cs files to the folder and it still doesn’t work. Any other tips on the map file? I see they are getting copied into the ~working folder – but then the map in the .chm is empty?
Thanks!
Hi TRH,
Did you create the “BtmSourceFiles” subfolder as mentioned above? Both, the subfolder and the map source files to be included there are required for the map documentation feature.
yes those file are the the resources\btmsourcefiles. I included the map .btm and .cs files and left the extensions on there. Does it need any of the schema files with it?
Like I said it copied the files into the ~working directory, but then it didn’t do anything with them. Wondering if it doesn’t like the filenames with . in them?
At the top of the map is says:
From Schema(s): Unable to determine source schema(s). Update stylesheet to correct this issue.
To Schema:
But is says that on other maps that aren’t included in the btmsourcefiles – I only copied over for some of the maps, not all of them.
I haven’t seen this behaviour before. This seems to be related to the stylesheet used to read the source schemas, which is part of the BizTalk Map Documenter, (https://biztalkmapdoc.codeplex.com/) which we just embedded in the BizTalk Documenter (https://biztalk2013documenter.codeplex.com/), but it’s a different tool.
I would suggest:
* Add ONLY the “btm” files in the corresponding folder. The file name has to be exactly as it appears in the BizTalk Admin console with the “.btm” extension. Remove any other files in the folder.
* If you have more than one map, then try one first, and see if it produces the output. Probably there is one which might be causing the issue?
If this does not fixes the issue, then I would suggest you to raise it in this link: https://biztalk2013documenter.codeplex.com/workitem/list/basic and give more details, if possible attach your btm file, and source and target schemas so it could be troubleshot.
Please bear in mind that this is an open source project and some people work in their free time to provide these tools to the community, so it might take some time to get a solution or an answer. Ideally, you might want to get the source code and debug it yourself and help the team to keep improving it 🙂
Cheers,
Reblogged this on Sprouting Bits.
Hello, Does the change to include “mht” files applies to BizTalk Server 2013 R2 version of Documenter? I tried to add “mht” file, nothing happened. Tried with “htm”, document was compiled in output but as you mentioned images were not added.
where is the documenter’s app config? what iis the location?
i got the below error
Could not load file or assembly ‘Microsoft.Biztalk.Interop.SSOClient, Version=7.0.2300.0 …’ or one of its dependencies.”