The BizTalk Documenter has been available for many years and different BizTalk versions, starting with 2004 to the latest one: BizTalk Server 2016. And once again, without a doubt for me, BizTalk Documenter is my favorite documentation tool, and I do think that if each product had a tool like for the generation of technical documentation, it would be simpler to do, as the existing documentation significantly improved.
However, the default cover page is quite simple and looks old fashion:
CHM files are the HTML Help 1.0 specification which is quite pretty old. Basically, It is a complete HTML-based Help system that uses a Help Viewer that internally uses Internet Explorer to render the HTML Help content that was introduced somewhere in 1997 when Internet Explorer 4 was also introduced.
Nevertheless, CHM continues to be a popular help format because it is very easy to produce content for it, using plain HTML, which is quite interactive, and because it works with many Windows application platforms out of the box.
And I normally like to personalize my documentation according to the client like:
- Using the Logotype and there name on the cover;
- Using their color pattern;
- Sometimes using some cover picture;
So, the question here is: Can we customize the cover page produced by BizTalk Documenter?
And the answer is obviously: yes, of course, you can.
And I have been doing that in my client for a long time, however, and this also serves me as a personal reminder, because each time I’m going to a new client I’m always:
- Forgetting how to do it;
- What kind of resources do I need to have? And what are there names? if they are mandatory;
- Taking a long time to format the HTML according to my requirements;
And don’t get me wrong there are several blog posts guiding you on how to do it. But most of them do not provide you the resources for you to download and:
- use
it as a template;
- Where you can easily modify the pictures, colors and so on;
- Or use it as an inspiration, tutorial or sample to your custom cover;
How to customize the BizTalk Documenter cover page
What is really necessary to transform your cover page from the default one presented in the picture above to something like this:
That contains:
- 1- Logotype of BizTalk Server version;
- 2-
Header title and subtitle;
- That can be your platform code name like “<client name> ESB”;
- 3- Logotype of the client organization;
- 4- Name of the documentation;
- 5- Other pictures like for example project logotype;
- 6- Disclaimer;
- 7- background color;
- 8- Copyright;
Or something like this with a background picture:
And in fact, this is a quite simple task. Fortunately for us, BizTalk Documenter allows us to specify a Resource Folder on the Output Options screen:
For the sake of simplicity, let’s call it Resources (but it can be other as you see in the picture Resource V1). In the root of this folder, you should:
- Add
a custom HTM page that you mandatory need to called it: titlePage.htm
- If you give it another name it will not work. The file will be ignored and the default cover will be generated;
- And you should, once again for the sake of simplicity, add all the necessary picture files on the folder or sub-folder;
This is the content/aspect of my titlePage.htm file for the first sample provide it here:
<HTML> <HEAD> <META http-equiv="Content-Type" content="text/html; charset=UTF-8"/> <TITLE>BizTalk Configuration</TITLE> <LINK href="CommenTReport.css" type="text/css" rel="stylesheet"/> </HEAD> <BODY style="background-color:#7FB4C4; PADDING-BOTTOM:20px; PADDING-LEFT:20px; PADDING-RIGHT:20px; PADDING-TOP:20px;"> <TABLE cellspacing="0" width="100%" height="100%"> <TR bgcolor="#0072C6"> <TD style="PADDING-BOTTOM:20px; PADDING-LEFT:20px; PADDING-RIGHT:20px; PADDING-TOP:20px;"> <IMG SRC="bts.png"/> </TD> <TD width="100%"> <p style="COLOR:#FFFFFF;TEXT-ALIGN:left;FONT-FAMILY:Calibri,Verdana, Arial, sans-serif;FONT-SIZE:40;"><b>BizTalk Server 2016</b><br>Solution Technical Documentation</p> </TD> <TD align="right" style="PADDING-BOTTOM:20px; PADDING-LEFT:20px; PADDING-RIGHT:20px; PADDING-TOP:20px;"> <IMG SRC="logotype.png"/> </TD> </TR> <TR> <TD colspan="3" height="150"> <BR/> <BR/> <BR/> </TD> </TR> <TR style="background-color: #0072C6;"> <TD colspan="2" style="PADDING-LEFT:20px; PADDING-RIGHT:20px;"> <BR/> <BR/> <BR/> <SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:18;FONT-WEIGHT:bold;PADDING-LEFT:5px;PADDING-RIGHT:5px;">Name: #APPLICATION#</SPAN> <BR/> <BR/> <SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:18;FONT-WEIGHT:bold;PADDING-LEFT:5px;PADDING-RIGHT:5px;">Installation Server: #SERVER#</SPAN> <BR/> <SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:18;FONT-WEIGHT:bold;PADDING-LEFT:5px;PADDING-RIGHT:5px;">Installation Database: #DATABASE#</SPAN> <BR/> <BR/> <BR/> <BR/> <SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:11;">All information in this document is confidential and for Sandro Pereira exclusive access. Access to this document by any other entity is not permitted without prior permission.</SPAN> <BR/> <SPAN style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:11;">Any entity with access to this document is bound by its confidentiality.</SPAN> <BR/> <BR/> <BR/> </TD> <TD style="PADDING-BOTTOM:20px; PADDING-LEFT:20px; PADDING-RIGHT:20px; PADDING-TOP:20px;"> <IMG SRC="documentation.png"/> </TD> </TR> <TR> <TD colspan="3" height="100%"> <BR/> <BR/> <BR/> </TD> </TR> <TR> <TD colspan="3" align="right"> <P style="COLOR:#FFFFFF;TEXT-ALIGN:right;FONT-FAMILY:Verdana, Arial, sans-serif;FONT-SIZE:10;">Generated on: #GENDATE#<BR/>Copyright © Sandro Pereira 2019</P> </TD> </TR> </TABLE> </BODY> </HTML>
Download
THIS RESOURCE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND.
You can download the BizTalk Documenter tool: Cover Customization Resources from GitHub here:
It is quite powerful tool but crashes on our side… I cannot select “Document entire configuration” but has to select a few in order for it to work. in worst case 2 applications / run….I have no idea what causes this…complex applications?