biztalk documentation tool

How to use the BizTalk Documenter with BizTalk Server 2020

Published on : Mar 1, 2022

Category : BizTalk Server

Lex

Author

Documenting BizTalk Server solutions

For reasons like maintenance and knowledge transfer, it is a good practice to document the software solutions that you develop. This practice also applies to developing BizTalk Server solutions. However, if there is any task that’s considered boring and time-consuming, then it is writing documentation.

Luckily, with the BizTalk documenter, a lot of documentation of BizTalk Server solutions can be generated automatically! In this article, we will have a look at how to install and use the BizTalk Documenter.

What is the BizTalk Documenter

This nifty tool has been around since 2006 and can be found on GitHub. Currently the BizTalk Documenter is maintained by Mark Brimble. After installation, the BizTalk Documenter can be executed against a BizTalk Server environment. It can generate documentation about the deployed BizTalk solutions in that environment, any configured Parties, the created Hosts, and the available Adapters.

BizTalk Documenter

Supported BizTalk Server versions

Since the BizTalk Documenter already exists for such a long time, it supports many different BizTalk Server versions, being: 2006, 2006R2 2009, 2010, 2013, 2013R2, 2016, and 2020. Depending on the BizTalk Server version you are using, you need to download a different version of the tool. For this, see the below table.

BizTalk Server version

BizTalk Documenter version

2006 to 2010

3.6.1

2013

5.1.7.1

2013R2

5.2.0.1

2016 to 2020(*)

5.3.0

(*) Support for BizTalk Server 2020 is not mentioned in the GitHub website, but we have tried it ourselves, and it seems to work properly.

Visit to the BizTalk Documenter Download folder in GitHub to get the version(s) you need.

Output options

Before generating the documentation, you can configure if you want to generate the documentation in one of the following formats:

  • A Compiled Help file (.chm)
  • Word 2003 XML document

Note: In case you want to generate a Compiled Help file, you must have HTMLHelp installed. More about HTMLHelp follows later in this article.

Below, you find an example of a page in a compiled Help file. The page shows some information about all that can be generated. The right side of the page shows information about the artifacts that are associated to a Host.

biztalk documentation tool

Branding Compiled Help files

The Front page of a Compiled Help file looks very basic. It only contains a simple image, and some basic information. However, when you are a little bit creative, you can customize that Front page to something like the below.

Before:

biztalk server documentation

After:

biztalk server documentation

This clearly makes the documentation look much better! Sandro Pereira has written a good blog about this topic. You find the blog here.

Dependence of HTMLHelp

As mentioned earlier, in case you want to generate Compiled Help files, the BizTalk Documenter depends on HTMLHelp. So, before generating such a file, you need to install HTMLHelp. This tool could previously be downloaded from MSDN, but since that website has been shut down, you now need to rely on the WayBack Machine for a copy of HTMLHelp.

Installation of BizTalk Documenter and HTMLHelp

Let’s have a look at how both tools must be installed.

Installation of BizTalk Documenter

To install the BizTalk Documenter, you need to perform the following steps:

  1. Download the BizTalk Documenter from GitHub
    (In this case, we run Microsoft BizTalk Server 2020, so we downloaded v5.3.0)
  2. Installation of BizTalk Documenter
  3. Start the installation, by double-clicking the MSI
  4. In the Welcome screen, click Next
  5. In the Select Installation folder screen, leave the default, and click Next
  6. In the Confirm Installation screen, click Next
    (Now, the BizTalk Documenter becomes installed)
  7. In the Installation Complete screen, click Close

That’s it! The tool is installed and can by started from the Windows menu.

Installation of HTMLHelp

If you intend to generate Compiled Help files, you need to install HTMLHelp. Follow the below steps, to download and install HTMLHelp.

  1. Download HTMLHelp via the WayBack Machine
  2. biztalk documentation generator
  3. Start the installation, by double-clicking exe
  4. Accept the License Agreement, by clicking Yes
  5. Answer Yes on the question if you wish to install the HTML Help Workshop
  6. Click OK, to install in the default installation directory
    Now, the HTML Workshop tool becomes installed
  7. Click OK, in the HTML Help Workshop install complete dialog

Also, the HTML workshop tool is now installed.

How to use the BizTalk Documenter

Now, let’s have a look at how to use the BizTalk Documenter.

You can start the BizTalk documenter from the Windows menu. The initial screen of the tool looks like below.

Using BizTalk Documenter

The screen is divided in three different sections:

  1. BizTalk Group details – This section contains the details of the BizTalk Management server and database, and (if configured) the details of the Rules Engine.
  2. Advanced Documentation option – Provide ConfigFramework.exe output XML to generate a system configuration overview (did not get it to work with BizTalk 2016 and 2020)
  3. Configuration options – Here you find several buttons that enable you to configure what all you want to be documented, the output options, etc. From here, you can also generate the documentation, and exit the tool

BizTalk Documenter configuration options

From the above-mentioned sections, the section with the configuration options, clearly is the most interesting one. Let’s have a look at what is in store there.

Server options – This is the screen that currently is shown. As mentioned, it contains the details about the BizTalk management server and database, and (if configured) also about the Business Rules Engine. If you want the Rules Engine to be documented too, enable the corresponding checkbox. Under Advanced Documentation options, you can provide the location of an exported Configuration file. This export can be generated by means of the BizTalk Server Configuration wizard. I added such a file but could not spot any difference with documentation that was generated without that file. So maybe, this does not work.

Output options – Here, you can configure whether you want the documentation to be generated as a Compiled Help file (.chm), or a Word 2003 XML file. There are also options to set the Report title and the output folder. In case you want to customize the cover page of the report, you can select the folder with the required resources here.

Additional Filters – In this section, you can configure the filters for Hosts, Adapters, BRE policies, and BRE Vocabularies that you want to include in the report. Filters are applied with the StartsWith operator, and can be delimited with the pipeline (|) character

Select documentation Scope – Here, you can select if you want to document all the BizTalk applications, or only specific ones.

Select Assemblies and Orchestrations – In this screen, you can configure which Orchestrations and Assemblies you want to be configured.

Select SSO Configuration – This screen enables you to select the SSO applications for which you want documentation to be generated.

Further, there are the buttons for generating the documentation, and a Quit button, to exit the application.

Resources

Here you have a couple of resources that you might find useful:

Conclusion

In this article, we had a look at the BizTalk Documenter, how it should be installed, including the installation of HTMLHelp, and what kind of documentation can be generated. We hope this article has been of help to you.