Keeping Generated Articles Up to Date
New 7.12
BizTalk changes; your documentation should follow. Re-run Generate Articles from BizTalk, or refresh single documents, and Nodinite replaces only the generated sections whose facts changed. Your own text is never touched, and a run that finds no BizTalk change writes nothing at all.
Understanding What a Run Changes
or the options change?"} Q -->|"No"| None["fa:fa-circle-check Nothing written
no revision, no change date,
no audit line"] Q -->|"Yes"| Rev["fa:fa-clock-rotate-left One revision saved
reason Generator run"] Rev --> Gen["fa:fa-lock Changed generated
sections replaced"] Gen --> Keep["fa:fa-pen Your sections, title, slug,
profile, tags, manual links kept"] style Run fill:#2678BD style None fill:#93d16d style Rev fill:#E47528 style Gen fill:#3F827B style Keep fill:#93d16d
A run (blue) compares the facts first. With no change, nothing is written (green). Otherwise it saves one revision (orange), replaces only the changed generated sections (teal), and keeps everything that is yours (green).
When a section changes, the Article's Updated date in the reader moves to that time, matching the section's updated time, and Documentation Health no longer reports the Article as stale. A run that changes nothing leaves the date alone. All these times are shown in your local time.
What a Run Replaces, and What It Never Touches
| On a run | |
|---|---|
| Generated sections whose content changed | Replaced, after one revision with the reason Generator run |
| Generated sections whose content did not change | ✅ Kept |
| Your sections (Description, Notes, and every other section you write) | ✅ Never touched |
| The document's title (a rename is kept), its slug, and its Document Profile | ✅ Never touched |
| Tags you added or removed | ✅ Never touched; tags are only ever added, never removed |
| Links you made by hand | ✅ Never touched |
| Links the generator made | Kept in line with BizTalk |
Because the revision is saved before the change, the History panel and Compare Articles show exactly what a run changed; see Revision History.
Special Cases
- Nothing changed in BizTalk: the document is not touched at all: no revision, no change date, no audit line. This also holds for shared Building Blocks.
- Different options: a re-run with other options, such as a different Orchestration design, updates the document even when BizTalk didn't change, because it now describes a different selection of facts.
- A generated section edited outside the editor (through the API or the database): the next run overwrites it and reports it. Until then, Documentation Health lists it as a drifted generated section.
- A generated document you deleted: a later run never recreates it and reports it as deleted by a user. Restore it, or permanently delete it, to let the generator write it again.
Warning
Generated documents are keyed on the Log Agent Value Id of their BizTalk Log Agent. Changing it makes the next run create a second set of documents. The Log Agent page warns before you save and names how many diagrams, Articles, and Building Blocks are keyed on the current value.
Three Ways to Refresh Existing Documents
| Action | Where | What it does |
|---|---|---|
| Refresh from BizTalk | The reader of any generated document, and an Integration documented by an Integration Article | Regenerates this document's generated sections from its own stored selection and options. It never adds or removes links or tags. |
| Edit selection... | The reader of an Integration Article, and a row's Action menu on the Articles list; on an Integration it is called Edit BizTalk routes | Opens the route picker on the Article's stored routes. Change the routes, and optionally the Integration Key pattern; the Article is then regenerated. The title stays, so the document keeps its identity. |
| Regenerate from BizTalk (n) | With Selected on the Articles, Snippets, and Integrations lists | Refreshes many generated documents at once, grouped per Log Agent, after you confirm. A result dialog groups them: regenerated, with the sections that changed or the reason they were retired; Warnings, with the reason; and Unchanged. See Bulk Actions. |
- Refreshing an Integration Article or Entry Point Article also refreshes the Building Blocks it includes.
- These actions are not in the editor: a refresh reloads the document and would drop unsaved edits.
- They need the same access as the wizard: the built-in Administrator Role and a Mapify product key.
- The page is locked while the document regenerates.
- To start from an End Point, Integration, or System instead, see Document from the Repository.
The reader of a generated Integration Article. Refresh from BizTalk works on any generated document; Edit selection... only on Integration Articles.
Tick the generated documents to refresh, then choose Regenerate from BizTalk (n).
Confirm to start the refresh.
The result of With Selected › Regenerate from BizTalk: each document is listed with its outcome, and each warning with its reason.
Integrations That Disappear from BizTalk
When none of an Integration Article's routes exists in BizTalk any more, the Article is not deleted:
- Its summary gets the banner No longer present in BizTalk since
. - It is tagged
BizTalk: Retired. - It is frozen: later runs don't change it.
- Documentation Health lists it.
Your text survives. Delete the Article yourself when it is no longer needed. A single route that disappears is listed under Findings as removed from BizTalk; it is never dropped silently.
A retired Integration Article keeps your sections and says since when its routes are gone.
Remove Generated Documents
Nothing is ever removed automatically. Generated documents are deleted, restored, and permanently deleted like any other, one by one or with With Selected on the Articles and Snippets lists (see Bulk Actions).
To remove everything one run produced:
- Filter the list on Generation run (or Generated by). See Where Generated Articles Appear.
- Select the documents, and choose With Selected › Permanently Delete. You don't have to delete them first; to keep a way back, choose Delete instead and permanently delete later.
- A Building Block that a live Article still includes can't be permanently deleted.
- Shipped documents can't be deleted at all.