by Sandro Pereira | Nov 12, 2019 | BizTalk Community Blogs via Syndication
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 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:
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>
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
The post BizTalk Documenter Tool: How to customize the cover page appeared first on SANDRO PEREIRA BIZTALK BLOG.
by Sandro Pereira | Nov 8, 2019 | BizTalk Community Blogs via Syndication
Without a doubt, 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. I do miss this kind of tool for Azure Integration projects.
However,
each time I install this tool I always got the exact same problem:
Unable to locate the help compiler executable
which I know well, and I know why since it was very well explained by Mitch Vanhelden in this blog post.
So, why this blog post?
Well, for two main reasons:
- I’m
always searching to find the link to the component I need to install;
- Basically,
this is just an easy personal reminder;
- And
second and most important, the link to the resource that Mitch point is
obsolete and not working anymore;
Cause
Has Mitch explained in his blog post, the
reason for this is quite clear, the application can’t locate the help compiler
executable, either because:
- it
isn’t installed à most common situation
- or
it is also possible if you’re working on a 64-bit machine.
Solution
Make sure you have installed the HTML Help
Workshop compiler because this is the most common cause for this issue and if
not:
- First, download and install this compiler that can be found here: HTML Help Workshop and Documentation;
- And then install it, by executing the htmlhelp.exe file
- On the HTML Help Workshop 1.3 screen, click Yes
- On
the HTML Help Workshop 1.3 Setup screen, click Yes
- Specify
the installation directory and then click OK
- And
finally, when the installation finish, click OK
After these steps, you should be able to
generate the BizTalk Server documentation form the tool. Otherwise, make sure
that the path to this help compiler is configured correctly in BizTalk
Documenter by:
- Access
to the installation path of BizTalk Documenter
- By
default: C:Program Files (x86)Microsoft ServicesBizTalk Documenter
- Open
Microsoft.Services.Tools.BiztalkDocumenter.exe.config file and validate
and, if necessary, change the path for the HelpCompilerLocation key
that needs to contain the correct path to the HTML Help Workshop compiler
component.
The post BizTalk Documenter: Unable to locate the help compiler executable while trying to generate the documentation appeared first on SANDRO PEREIRA BIZTALK BLOG.
by Uma R | Mar 8, 2017 | BizTalk Community Blogs via Syndication
Document management and versioning is a regular and a necessary activity in any organization. We do face some challenges in our organization too. We searched the best option to overcome those. Finally, we found a solution via SharePoint versioning.
What is Versioning?
You can find a clear idea about versioning by seeing the picture below. Versioning describes the management of changes in your document. You can track your document changes in each version and can reuse whenever you want. You can maintain major versions (V1.0, V2.0) alone or if you need your draft copies, you can maintain them in minor versions too (V1.1. V1.2, V1.3 and V2.1, V2.2, V2.3).
Why we use Versioning
- Versioning, combined with other settings, like checkout and check-in, which gives you a lot of control over your document
- Versioning is automated. You don’t need to give version numbers for your updated files at each time when you check-in. It starts from 0.1 for Minor version and 1.0 for Major version. Versioning provides a user-friendly infrastructure for finding out who made what changes and when
- You can set your maximum major and minor versions limit values for avoiding large storage of files
How to use Versioning in SharePoint
You can enable versioning through either of the following two ways:
- Through Settings page
- Through Library Settings
Both ways are described below.
Through Settings Page
- Go to settings which is located in the top right corner -> Click Site settings from the drop-down
- Click Site libraries and lists -> Click Customize “Documents” -> Click Versioning settings.
Through Library settings:
- Select the file or folder -> Files or library items will be displayed in top menu.
- As you click Library, a drop down window is displayed -> Click Library settings -> Click versioning settings link
You can reach the Versioning Settings page. Here you can set your limitations. Let’s see the items briefly here:
- Content approval
If you enable this item, your file can be viewed only when your approver approves. Won’t We don’t use this option in our organization, as we see more time consuming and dependent on approver for any other team member to access the file.
- Document Version history
- No versioning – Disable the version control
- Create major versions – Only Major versions can be created and there are no draft items maintained here
- Create Major and minor versions – We are using this feature for finding the status of the document. If the document lies in Brainstorming or Review and is still being updated, we place it under minor versions.
Once finalized the document comes under Publish as a major version.
- You can set your maximum count value to maintain major and minor versions
- Draft item security
- You can set who can be able to view your changes of document after check in.
- Requires checkout
- You can set whether the checkout is needed or not every time you open the document
Scenario for versioning
The notable point in versioning is, it does not support in folder level. Only Documents can be maintained using version settings. Try out the following steps to perform versioning.
- When versioning enabled in site settings, the existing files were in Major version. When we want to update the same file or edit, Click Checkout option by clicking … -> Advanced -> check out
You can find a downward pointing arrow mark in green color that indicates check out is done. We can see who has checked out the document by doing mouse hover on that arrow mark. You can use the document for your changes now.
- After you are done with the changes, you have to check in the document by clicking the Check in button. In case you do not want to save the changes, you can use the option to Discard check out which will revert the document to the last checked in version
- When you click the Check in option, SharePoint asks the user to select the type of version based on your document which keeps as a draft item or published version.
You can see your items by clicking Version history option. All minor and major version items are listed. As mentioned before, Major versions items are maintained as whole numbers (1.0, 2.0) and minor version are maintained as decimal numbers starting from the last whole numbers (0.1, 0.2). User will not be able to change the versioning numbers.
We followed this versioning in our organization with both major and minor version concepts. The document is maintained as minor version for requirement analysis, brainstorming section and review stages until requirements freeze. Before the feature is considered for development, user will publish as a major version so that everyone can use it.
- Versioning also allows us to restore a document to earlier versions when required.
Conclusion
We started using Versioning in our organization to maintain same document base for feature development and any updates. All change requests, enhancements are captured in the same document by modifying it and saving it as different versions.
Though there are many document versioning systems, SharePoint in Office 365 is very easy to setup and use.
The post Enabling Versioning in Office365 SharePoint appeared first on BizTalk360.
by Dan Toomey | Aug 15, 2016 | BizTalk Community Blogs via Syndication
One of the many challenges with an integration project is typically the mapping of messages from one API to another. The difficulty most often lies not with the technical implementation (although some former projects mapping SAP iDocs to EDI X12 are still giving me nightmares), but rather with forming the specification of the mapping itself, including understanding the semantical meaning behind each element. This is difficult because it requires expert knowledge of both the source and target system, as well as an analysts who can correct “draw the connecting line” between the two. The correct end result is only achieved through significant collaboration amongst the relevant parties.
The BizTalk Mapper goes a long way to facilitating this task with it’s graphical mapping interface. Aside from providing the developer a means of rapidly implementing a transformation, it also servers as a visual representation of the mapping that can be understood by a business analyst (if not too complex):
(image courtesy of MSDN)
There are two problems with this approach, however:
- It requires BizTalk Server, which is not only expensive, but also may be overkill for a solution that can easily be implemented in WCF, REST, or another platform;
- The mapping must be implemented by a developer before it can be shown to analysts and business users for discussion and validation. This usually entails a number of iterative cycles until the mapping is correct.
Enter api-map.com – a new free online tool created by my colleague Joseph Cooney specifically to address these particular challenges. api-map provides a medium to formulate, display and share mapping documentation which can eventually be handed over to a developer for implementation on any chosen platform.
As a first step, the tool allows you to upload schemas (either JSON or XML) with the ability to display, edit and annotate them:
These schemas can then be used to define mappings, even providing automatic hints along the way using very clever heuristics. You can specify direct mappings or indicate that a transformation is required – including a description of the necessary condition and/or logic that defines the transformation. You can also map multiple source elements to a single target, and specify constant values to be assigned where appropriate.
Once this is completed, you can then display the mapping in a clear visual diagram that is easily understood by any analyst. Even better, you can combine multiple diagrams into one composite “end-to-end” view – providing a traceability which you cannot achieve within BizTalk maps. This is incredibly useful in the situation where canonical business schemas are employed within an ESB (a common scenario for most of my projects). And by selecting any element involved in a mapping, you get an independent end-to-end view of all elements involved in a mapping:
Finally, when everything has been sorted, you can export the mapping to a handy Excel spreadsheet, serving as documentation within a source repository for developers to work from:
A few other nifty features include the ability to tag items to make them searchable, join teams in order to share project artefacts, and an option to attach images of a user interface to clarify the association of an element with a system control.
Watch Joseph’s video to see a live demonstration of the tool. Still in beta, Joseph is continually adding new features, but already I believe this will be a handy utility on many of my upcoming projects!
