Generate Articles from BizTalk

^{New 7.12}

Nodinite writes Articles that describe your BizTalk integrations, from facts in the BizTalk management database. No AI is involved: the same BizTalk configuration always gives the same text. You start it from the Generate from BizTalk wizard, where you can generate C4 Diagrams, Articles, or both in one run, or straight from an End Point, Integration, or System in the Repository.

• Sections Nodinite writes are replaced on every run. Sections you write yourself are never touched.
• A re-run that finds no BizTalk change writes nothing at all.
• Articles describe the design, never the runtime state. Every port, location, and orchestration is included whether it is started, stopped, enabled, or disabled, and its state is not written. Stopping a port for maintenance never changes an Article. Live state belongs to Monitoring, which the Articles link to.

Understanding BizTalk Article Generation

The wizard reads one BizTalk group through its BizTalk Log Agent (teal), and the run (blue) writes the four kinds of generated documents (green). The actions on an End Point, Integration, or System page (purple) write one document without the wizard; see Start from a Repository Page. Building Blocks are included in Integration Articles, which appear on the Integrations list, in Monitor Views, and on C4 diagram nodes (orange); see Where Generated Articles Appear.

The Kinds of Generated Documents

Each kind uses its own shipped Document Profile; see BizTalk Document Profiles and Section Keys.

Words the Wizard Uses

Generated Articles vs Hand-Written Articles

You can't create a generated Article by hand.

What You Need Before Starting

• You are a member of the built-in Administrator Role, and the installation has a Mapify product key (see Manage License). The same requirement applies to every way of starting or refreshing a generation.
• A BizTalk Log Agent configured against the BizTalk management database. Each run uses exactly one Log Agent, which means one BizTalk group.
• Optional: a BizTalk Monitoring Agent 7.10.x or later, for orchestration designs.
• Optional: Add Monitoring on the Options step, to link Articles to Monitoring Resources.

Start the Wizard

Open the Generate from BizTalk wizard from any of these places:

The steps are Environment › Options › Application › Articles › Grounding › Diagrams › Confirm. Application and Diagrams are skipped when Generate C4 diagrams is off; Articles is skipped when Generate Articles is off. The diagram steps are described in Generate C4 Diagram Sets from BizTalk Applications; this page covers what is new for Articles.

To document one port, one integration, or one application, you don't need the wizard: start from its End Point, Integration, or System instead; see Start from a Repository Page.

Step-by-Step: Generate Articles

Step 1: Turn On Articles in the Options Step

1. Tick Generate Articles (deterministic documentation). It is off by default.
2. Keep Generate C4 diagrams ticked to also generate diagrams, or clear it for an Articles-only run. At least one must be on; otherwise the wizard says Choose at least one: C4 diagrams, Articles, or both.
3. Decide on the existing options. They control which Binding choices are available on the Articles step:
   • Generate Nodinite Repository Artifacts: needed to link Articles to Integrations, Services, Message Types, and Systems.
   • Add Monitoring: needed to link Articles to Monitoring Resources.
   • Generate Snapshot Provenance custom metadata: writes BizTalk provenance as Custom Metadata.

The Options step. The help text under Generate Articles repeats the key promise: no AI, facts from the BizTalk management database, your own sections never overwritten, and nothing written when nothing changed.

Step 2: Choose Applications for the Diagrams

The Application step drives the diagrams only. It never limits which routes you can put in an Article, because a route often crosses applications: a hub receive port in one application and its subscriber in another.

Step 3: Define the Articles

The Articles step holds everything about the documents, from top to bottom. It has two parts: the Articles to write (Integration Articles and Other Articles), then the options for how they are written (profiles, binding, tags, and advanced settings). The suggested values are a starting point: accept or change them.

The top of the Articles step with the built-in help open, the run size, and one accepted suggestion marked updates existing. The default pattern finds 3 of 5 routes and suggests one Article.

Click How Articles work at the top right for the built-in help, shown open above. It explains Integration Articles, routes, Building Blocks, and the Integration Key, and how to fill the step. Hide help closes it.

Run Size

The counter n of max N Articles shows how many Articles the run will write, broken down per kind, plus at least n Building Blocks. The limit counts every Article kind; Building Blocks are counted but not limited. Next is disabled while the counter is over the limit. An administrator can raise the limit with the BizTalkArticleGenerationMaxPerRun System Parameter.

Integration Articles

1. Check the Integration Key pattern: a regular expression that finds the integration number in port and orchestration names. Routes with the same number are suggested as one Article. The default, ^(?i)([a-z]{1,4}[-_ ]?\d{3,4}[a-z]?), finds 1–4 letters, an optional -, _, or space, and 3–4 digits at the start of a name: INT001, INT-042, i0042b, AZI0104. Change it to fit your naming. If the pattern doesn't compile, the wizard says so and keeps the previous value for suggestions.
2. Click Accept suggestions to create one Integration Article per Integration Key the pattern found, up to the remaining limit. When the limit stops the rest, the wizard says so. Suggestions are always taken from the first Integration Key, so running again takes the same ones. To document the rest, narrow the Integration Key pattern, add Articles with New Integration Article..., or ask an administrator to raise the limit. When a suggestion has the title of an existing Article, its row is marked updates existing: the routes that Article already documents stay, and the suggested routes are added. Accept suggestions never removes routes from an Article.
3. Or click New Integration Article... to pick the routes yourself in the route picker.
4. Review the list: Title, Integration Key, Routes, and Profile. Each row has three buttons:
   • previews that one Article exactly as the run would write it, without writing anything, and marks every row that has a problem (This Article has problems). The preview is per Article; there is no preview of the whole run.
   • changes the Article's title, routes, or profile.
   • removes the Article from this run. Remove all empties the list.

The Integration Articles list after Accept suggestions. The note above the list says the run limit stopped the remaining suggestions.

Other Articles

• Entry Point Articles (one per receive port) and Application Overview Articles (one per application): each has an application selection, prefilled from the Application step. Empty means the applications of this run. For Entry Point Articles, applications without receive ports are greyed out, and a warning lists them.
• Building Blocks for all artifacts in the run's applications: when off, Building Blocks are generated only for the artifacts some Article uses.

Profiles

Pick one Document Profile per kind. The shipped BizTalk profiles are preselected and marked Shipped. Only profiles that hold every section the generator writes are listed. To add your own sections, clone a BizTalk profile and pick the clone here. The Entry Point and Application Overview profiles are greyed out until their Article kind is ticked.

The options part of the Articles step: Building Blocks, profiles, Binding, On existing Articles, and Tags.

Binding

Binding decides where the generated Articles are linked, so readers reach them from the things they describe. A switch is unchecked and disabled while the option it needs is off:

On Existing Articles

• Update generated parts (default): a re-run refreshes the generated sections of Articles that already exist. When BizTalk has not changed, nothing is written.
• Create missing only: only Articles that don't exist yet are written. Existing ones keep their generated sections as they are, even when BizTalk changed.

Your own sections are never overwritten in either mode. See Keeping Generated Articles Up to Date.

Tags

The Tags you enter are added to every generated document. The default is Source: BizTalk. Integration Articles also get BizTalk: <Integration Key>, Entry Point Articles get BizTalk Entry Point, and Application Overviews get BizTalk Application.

Advanced

Articles document the design: every port, location, and orchestration is included whether it is started, stopped, enabled, or disabled, and its state is not written. Stopping a port never changes an Article; Monitor Views show the live state.

• Follow transport loopbacks (heuristic): a send port that writes to an address a receive location of this group reads (same folder or queue) is treated as one continuing route. Matching is by address, so it can guess wrong. Off by default.
• Pipeline stages and components: on by default.
• Per-instance pipeline configuration (redacted): on by default. Values that look like passwords, keys, or connection strings are masked; see Sensitive Data in Generated Articles for exactly which values are masked.

Orchestration Design

Choose None, ODX to Mermaid (default), or ODX plus designer image. The shapes (receive, decide, loop, scope, send) come from the orchestration's designer model, which only the BizTalk Monitoring Agent can read from the deployed assembly. The option is disabled when the run has no BizTalk Monitoring Agent.

• Only a changed design is drawn again.
• Designer images are rendered on the BizTalk server and take time. They are fetched only for orchestrations whose design changed, and stored in the Image Library.
• When the agent can't provide a design, the section shows a notice and the run continues.

The bottom of the Articles step: Advanced and Orchestration design.

Step 4: Grounding, Diagrams, and Confirm

• Grounding lists one Nodinite System per BizTalk application: the applications picked for diagrams, plus every application the defined Articles' routes touch. It also binds external systems and, when the run generates diagrams, the run's Integration; see Step 5: Apply grounding.
• Confirm summarises the run. The Articles row shows the number of Articles per kind, the Building Blocks choice, the On existing Articles mode, the tags, and the applications touched. In an Articles-only run, the Diagram Set selector is hidden.
• Nothing is written until you click Generate.

Step 5: Read the Run Result

The result counts what the run did:

• Articles: created, updated, unchanged, and removed from BizTalk, always shown.
• Building Blocks: created, updated, and unchanged, always shown.
• left alone, deleted by a user, and failed (in red) appear only when they are above 0.

It also shows Masked values and the correlation id, with two links:

• Show the Articles of this run
• Show the Building Blocks of this run

Both open the list filtered on this Generation run. Below them, every generated document is listed as a link with its status, such as Created, Updated, or Unchanged; an updated document also names the sections that changed. When the run also generated diagrams, the result starts with the diagram count and a View Diagram Set link.

A run with diagrams and Articles. The zero outcomes are hidden; the updated Integration Article names its two changed sections.

Start from a Repository Page

To document one port, integration, or application, start from its End Point, Integration, or System page instead of the wizard: Document this port, Document the integration, Document these ports (n), Edit BizTalk routes, Refresh from BizTalk, and Document this application. See Document from the Repository.

The Route Picker

The route picker is where you choose the routes of an Integration Article: from New Integration Article... on the Articles step, Edit selection... on an Article, Edit BizTalk routes on an Integration, or Document the integration on an End Point. It searches the whole BizTalk group, marks routes that are already documented, suggests a title from the Integration Key, and edits the routes of an existing Article. See The Route Picker.

Frequently Asked Questions

Does the generation use AI?

No. Every sentence comes from facts in the BizTalk management database. The same BizTalk configuration always gives the same text.

Why does my Integration Article show a stopped port?

Articles describe the design, not the runtime state. Stopped and disabled artifacts are included, and their state is not written. Check the live state in Monitor Views.

Why does a Building Block have no header or footer?

A Building Block is a Snippet that Integration Articles include. Its profile holds only its facts, your notes, and the generation info; the including Article supplies the Standard Header and Standard Footer.

Can I write in a generated Article?

Yes, in your sections, such as Description, Source and Target Systems, and Support and Governance. The generated sections are locked. See BizTalk Document Profiles and Section Keys.

Next Steps

• BizTalk Document Profiles and Section Keys
• The Route Picker
• Document from the Repository
• Keeping Generated Articles Up to Date
• Where Generated Articles Appear
• Sensitive Data in Generated Articles

Related Topics

• Generate C4 Diagram Sets from BizTalk Applications
• Knowledge base Articles
• Document Profiles
• Snippets
• BizTalk Log Agent
• Add or manage Endpoint - Document this port and Document the integration on a BizTalk End Point
• BizTalkArticleGenerationMaxPerRun
• Mapify