Governance : Release and Version Management

Governance :  Release and Version Management


This functionality is designed to be particularly useful for

  • managing process documentation in industries subject to regulatory compliance.
  • complex (multi-sandbox) Salesforce implementations
  • driving operational change in large complex organizations
  • any project where robust version management of process documentation is important

The Release and Version Management is designed to make it simple to publish and maintain the latest approved process content in a controlled way.

Taking diagrams through their publishing lifecycle

The Release and Version Management process can be viewed in the context of the 4 states that your diagram goes through.

You create and edit in Draft. When you mark it as ‘Ready to release’ it is view-only. It is assigned to a Release and then that Release is published. Elements then automatically archives secure view-only records of the previous version.

This cycle is useful for well managed projects and operations. Vital in a compliant organization.

The process

The Release and Version Management involves a series of steps with specific roles and outcomes. It is best described as a process… and this map is available with links to screenshots in “Example maps” Space.

The ‘happy path’ of getting from draft, to preparing and publishing a release, and then updating it is relatively simple. Fall off that happy path and Elements has been developed to pick you up and manage you back on track. Read the Deep-dive and the Q&A at the end of this article and you’ll understand how this works for you.

Too heavyweight for you? Apply ‘Versioning lite’ using the Free version of Elements.

Before we go further, if you have read this far and are thinking that ‘this is all a bit complex for what I need’, then it probably is. If you are using the Elements free version there is an approach using 3 Spaces and copying maps between them.  It may be manual, and requires some discipline, but it is free for ever.  It is explained in more detail in at the bottom of the DeepDive section.


Summary of how to review the detail of the Process

Click on ‘Spaces’ in the left panel in Elements. Select “Example Maps’ Space. Click on Maps. Select  “Methodology: Release-Version Mgmt Lifecycle”. Follow the process, click on the attachments and view the screenshots if you want to walk through this. If you need to understand this and can’t get it from the Process map above, contact us We’re here to help.

This is fundamentally about taking a Diagram from ‘Draft’ to ‘Ready for Release’ so that it can be ‘Published’. It’s then about ensuring that any existing published content it replaces is archived and available when people need it at the click of a button.

If you’re documenting processes for a systems implementation like Salesforce, then you can group process diagram changes into Releases that are aligned with your Salesforce upgrades.

Assigning Release Managers

You must have at least one Editor with Release Manager rights. A Space Admin allocate rights in the Users page in the Space Management app. Select your Space and click on your  Space name at the top of the main app.

When in the Space Management app, select Users from the left menu. Select the user and check the Release Manager in the right panel.  The user must be an Editor

In a complex or regulatory compliant organization, the Release Manager role is a significant responsibility and should be undertaken with care by someone who understands what they are doing and the implications. Having said that, Elements is automating what is normally a laborious, yet well established, manual process.

Releases apply to all published content across the Space

When you setup a new release, it is in the context of the Space. So I could create “Release 0.3 – Early summer release” – just to change one diagram in one map. When I publish the release with that one changed diagram, all published content across all the maps in the whole Space (changed or unchanged), is brought up to “Release 0.3 – Early summer release”.

Think of the Space as a book. It has many chapters, sections, hundreds of pages….. If I release a new edition of the book, it applies to the whole book, both changed and unchanged parts. I don’t ‘Release’ a new book with just 3 of the 500 pages changed with a version noted in a footnote on each of the 3 pages. I release a new edition of the whole book.

Each release you publish in Elements is like a new edition of a book. Except as it costs nothing to put the latest edition in everyone’s hands, I can create new editions as often as appropriate. I can change one page, and create a new edition. I don’t have to worry about communicating and sending out the new editions. Any changes are simply there when I open my book. I’m looking at the latest edition.

So carefully planned and co-ordinated? Elements will do that for you. Ad-hoc and fluid? The rules and workflows allows you to be pragmatic and fix things on the fly quickly and simply. Reality for most organizations requires both.

Creating a Release and choosing a name 

There are no rules. But be aware that the Release name will apply to all content in the Space. So it depends on the scope of what content you have published and are working with across the Space.

For example, if you have process diagrams for a Salesforce project  you may choose to match the Release naming to that project. e.g. your Salesforce project is “Mid-June’17 Service Cloud Lightning Upgrade”, so you match that for one of your planned releases.

The only issue with this is that all the work you have published around SalesCloud, your Salesforce CPQ project, your Salesforce integration with SAP finance processes, the maps the Lean Operations team are using are all tagged with “Mid-June’17 Service Cloud Lightning Upgrade”.

So think about the scope of your work. If you are only using this for the Service Cloud upgrade – then fine. But if your usage is broader and expanding, as is common, then simple date/month based naming works best.

Releases have names and versions. Diagrams have separate version numbers.

A release may relate to any number of changing diagrams. So it’s important that we track not just the versions of releases that have been published, but also the version of each individual diagram in a release, and the versions of each diagram

In the image below, all the published ‘Current’ diagrams are part of ‘Release 0.3″ called “Early summer release” for Map called “A”. But the 3 different diagrams in the hierarchy are at different version numbers.  You can see the bottom right diagram has 3 versions V1, V2, V3 and in the right panel for that diagram you can see the different version and the Releases they were tied to.


Allocating diagrams to releases

A Release Manager can create any number of future releases. An Editor can allocate diagrams to a Release.  Equally if you don’t know what release to assign your Draft to, select ‘None’ and it can be allocated to it manually, later. If you do select ‘None’ it is important to make sure that your Release Manager does simply add all unassigned ‘Ready for release’ diagrams to the next Release and then publishes them.

Releases manage your entire map (a hierarchy of diagrams)

What makes Elements unique, is the logic and business rules under the hood that allow you to have securely managed maps containing hierarchies of diagram information, all changing with different rhythms. Elements understands how to deal with the diagram parent-child relationships through the lifecycle – and all the permutations. It works no matter how big your map gets.  Usually dozens, frequently hundreds, sometimes thousands of interrelated diagrams in a map require version management in a release. That’s what this capability is designed for.

Keep developing your draft as soon as you have made a “Ready for release” copy

You can continue working on the Draft copy as soon as you have created your ‘Ready for release’ version of the diagram.  You may want to work on changes for future release. Apart from the draft, all versions of the diagram are view only.

Your end users always see the current published diagrams

By default, all users see the ‘Current’ published diagrams as they navigate around maps. If there is not yet a ‘Current’ published version of the diagram they are trying to navigate to, Elements will give them the option of opening the Draft. If they move into a Draft of a diagram, and then navigate around the map, Elements will keep them in the draft context. See FAQ below for more scenarios.

Versioning-lite using the free version of Elements

If you are using the Elements free version, and simply want to understand how to keep on top of showing people ‘a snapshot version of our Process documentation’ while you work on developing the next iteration of your diagrams, you can do that for free using 3 Spaces and copying maps between them.  This is explained in more detail in the DeepDive:

  • Create your process maps, with as many editors as you want, for free, in a space called “Draft”
  • When you are ready to ‘publish’ your map, copy it into a different space, called “Current – Published Maps”. Add  ” – v1.0″ to the Map name to bring in the versioning.
  • Invite the project or operational audience to this space and make it their default space
  • You only need one or two editors on the space to administer it. Keep disciplined about not changing anything in the ‘Published Maps’ space
  • If you want to change a Diagram, change the appropriate diagram in the ‘Draft space’.
  • When you want to publish the update, copy the current map from the ‘Published Maps’ space into the 3rd space, “Archived Maps”. On copying, change the name to [map name vn.0 – archived]
  • Copy the new version from the Draft space into the Current Published maps space, and modify the version number int the map name accordingly.

It may be manual, but use discipline and it works well enough for most companies outside of those subject to regulatory compliance. You want to get really involved and just update certain diagrams in the ‘Published space’, but still archive a version of the map? You still can, just a bit more involved and manual. But it works. And it stays free for all users. Forever.

Help us expand this FAQ section : Let us know if you have any other questions we are not answering here…



Diagrams – Draft, Making ready for Release, Navigation

When can I carry on changing my draft copy of a diagram?

As soon as you have made a draft diagram ‘Ready for release’, Elements makes a copy which is set to ‘Ready for release’. So you can continue changing the draft as soon as there is a ‘Ready for release’ version showing in the right panel on a diagram.

What happens if I make another draft 'Ready for release' before I have published the last one?

Elements sets the old ‘Ready for release’ diagram to “Never Published” and then sets the new draft iteration to “Ready to Release”. The old “Never Published” diagram is shown in the version history tab

Is there a limit to the number of planned releases I can line up and what if I'm not sure yet?

A Release Manager can create any number of future releases. An Editor can allocate diagrams to a Release.  Equally if you don’t know what release to assign your Draft to, select ‘None’ and it can be allocated to it manually, later. If you do select ‘None’ it is important to make sure that your Release Manager does simply add all unassigned ‘Ready for release’ diagrams to the next Release and then publishes them.

What happens if I link from outside Elements to a specific draft diagram, which is then published. Where does the link take me?

Any URL links to diagrams in Elements from outside (or from within other maps), will link to the ‘Current’ published diagram, even though the diagram that was there when the links were created have since been archived.  The URL for a diagram never changes.

Publishing Releases

How do I review what diagrams are related to the release I want to publish?

All ‘Ready to release’ diagrams are visible when you click ‘Releases’ on the left panel in the main app and select a release. All diagrams related to the release are automatically checked in the list. You can add other diagrams, (e.g. those not allocated to a release – or even override those allocated to a different release) by simply clicking on the checkbox and selecting them.

In a complex or compliant organization, the Release Manager role is a significant responsibility and should be undertaken with care by someone who understands what they are doing and that everything they check in this list is going to be updated immediately.

What if want to insert a quick release in between planned releases?

Let’s say you are currently on a published release of [name] v4.0 and you have a list of planned releases with [name] v4.1, [name] v4.2….etc

There’s some work going on with cosmetic (color, style) changes to some diagrams that you want to publish immediately, i.e. before the planned 4.1 release next week. You can simply add in another release and manually change the release version number. Elements will automatically increment the last (planned) release number. So in this case a number like [name] v4.01 would work fine. Allocate the changed diagrams. Publish the release and then next week go ahead with your planned release.

Resolving issues with partial publishing or restructuring from Current v Draft

Having published a map, what if I renumber an activity with a drill-down in the draft of one of the diagrams?

If an activity which has a drill-down is renumbered, the diagram is made “Ready for release” and is then republished as part of a new release. But the child is not republished and Elements in the background needs to resolve the level number of the current child diagram version.

Before the parent was republished with the new activity number, it had a level number based on the parent activity number.  After the parent has been updated it now has a different level number.

In order to resolve this Elements archives the current child diagram and creates a new version of the child diagram which is an absolute copy of the current published child diagram but which now has the correct level number based on the new parent activity number.  This is the one time that a new diagram version is created by system automatically and it is created in an Published state, based on another Published version.

From the user point of view this is transparent but a new version will appear in the version list and in the version history this version starts its life In the Current state having been created by the system.

What if I am publishing a diagram where there is no published parent diagram?

It is perfectly possible and reasonable to publish into a release a diagram where the parent (or any of the diagram in the hierarchy back to the level 1) of the diagram has not been published.

In this case no level number can be assigned to the diagram in the Current published state as it is not possible to connect it back to the level 1.  The level number of the diagram will be set as ‘pending’ since it will be resolved once the chain back to the level is established at some point when another release included diagrams that complete the path back to the level 1.

Whilst it is not possible to drill down to a pending diagram that does not have a published parent it is quite possible to to reach to this diagram version by either navigating from the draft or potentially by following a line connector from another diagram.

Help us expand these FAQs

Let us know if you have any other questions we are not answering here…

  • Was this article helpful ?