Archi Confluence Upload Scripts

Started by yveszoundi, December 03, 2021, 09:02:30 AM

Previous topic - Next topic

yveszoundi

I'm finalizing Archi scripts for Confluence publishing, via REST API integration: I originally had a working but less flexible version.
  • A "convenient" dialog helps you store Confluence settings (URL, API token, etc.)
  • After defining a publishing pipeline, you can update one or multiple pages on Confluence from Archi

Confluence Settings screenshot
settings_screenshot.png

Confluence Pipeline screenshot
pipeline_screenshot.png

yveszoundi

Additional notes on top of the TLDR version.

Concepts

An archi-Confluence page is modeled as a Group element on a Sketch diagram:
  • An archi-Confluence page contains either nested sections (Groups) or references to diagrams (Canvas, Sketch or default Archimate diagrams).
  • Within an archi-Confluence page, the flow between sections is specified using connections. All page contents but the last element, must point once to something (either a section or diagram reference).
 
An archi-Confluence pipeline on a Sketch diagram contains one or multiple archi-Confluence pages:
  • If you don't select anything on a sketch diagrams, all the archi-Confluence pages will be published.
  • Alternatively, you can select specific archi-Confluence pages to publish.

The name of archi-Confluence page is used as Confluence page title (retrieve existing page information by title and Confluence space: page id, page version, etc.).

Confluence integration

Diagram documentation and images are published through the Confluence REST API.
  • You, create a Confluence API token and keep it in your password manager.
  • You, configure Confluence publishing settings in Archi: A utility script provides a dialog that helps persisting Confluence parameters in the Archi workbench preferences. This includes the Confluence username, API token, default space key, base URL.
  • The script, retrieves Confluence page information, based on the page title: Page titles are unique in Confluence within a given space (space key).
  • The script, renders any documentation associated to a view or 'section' using markdown (view/section documentation is parsed as Markdown and converted to HTML)
  • The script, exports any referenced view/diagram image as PNG binary data
  • The script, publishes text and image contents to Confluence pages accordingly to the desired sections/sub-sections.

Design decisions

It is more flexible to use Sketch diagrams than Canvas or regular Archimate views.
  • You can connect directly 'view references' to each other without additional nesting.
  • There's no need to think too much about the allowed structure: there are only groups, view references and connections (minimal validation in place).

yveszoundi

I had a bit of time today to fix some of the typos in the code and test it.
I'm reasonably "satisfied" so far and things seem to be working as expected: I replaced my old Confluence workflows today with the newer scripts.

To aggregate content from an other thread, there are similar efforts from @Xavier Mayeur