BizTalk Documenter Tool: How to customize the cover page

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:

biztalk documenter 2016: default cover style

CHM files are the HTML Help 1.0 specification witch 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 produce by BizTalk Documenter?

And the answer is obviously: yes, of course, you can.

And I 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 king 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:

biztalk documenter 2016: custom cover style

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:

biztalk documenter 2016: custom cover style

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:

BizTalk Documenter 2016 output options: resource folder

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>

Resources

THIS IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND.

You can download BizTalk Documenter tool: Cover Customization Resources from:

BizTalk Documenter tool: Cover Customization Resources
Microsoft | TechNet Gallery

Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.

2 thoughts on “BizTalk Documenter Tool: How to customize the cover page”

  1. 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?

Leave a Reply

Your email address will not be published. Required fields are marked *

BizTalk360
BizTalk Server

Over 500+ customers across
30+ countries depend on BizTalk360

Learn More
Serverless360
Azure

Manage and monitor serverless
components effortlessly

Learn More
Atomicscope
Business Users

Monitor your Business Activity in iPaaS
or Hybrid integration solutions

Learn More

Back to Top