Principles

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 makes it simple to publish and maintain the latest approved process content in a controlled way.

This is a long help article because managing a hierarchy of process content (i.e. a map) is complex. However, Elements has made it simple with all the hard work happening behind the scenes. That way, more organizations can start to get control over their process documentation.

Taking diagrams through their publishing lifecycle

A process diagram can be be in one of these four states.

  1. You create and edit in Draft. 
  2. When you mark it as "Ready to release", it is locked in view-only. It is assigned to a Release.
  3. When the Release is published, that diagram is published. The previous published version is automatically archived as view-only.

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

The process

The Release and Version Management involves a series of steps with specific roles and outcomes. We have built a process map with links to screenshots to guide you . The map is called "Methodology: Release-Version Mgmt Lifecycle" and is available in the “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 think about this. 

Many organizations write this stuff down in ad-hoc office documents and then use Document Management Systems (DMS) like SharePoint or Documentum or file systems like Box to manage versions and govern content. All we are doing here is managing a Space like a DMS folder with roles, authorizations and different states for the documents that are in the folder. In the case of Elements, the folder is like a map and the documents and the different diagrams. Elements is doing all the hard work of maintaining the structure, the linkages, and the relationships - in a compliant, managed way.

If you are using the Elements Free version, just like using ad-hoc office documents, there is nothing wrong with having a disciplined manual approach to keeping on top of what names you have called the latest maps and diagrams, where the changes are, and who can see what. Just as with office documents, it's up to you to be disciplined and execute consistently. If you need to be compliant to a regulator, or to corporate policies in a larger company, that's where this managed governance in the Pro product comes in.

Detailed step by step: Managing through the lifecycle

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 allocates 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 set up 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 three of the 500 pages changed with a version noted in a footnote on each of the three 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 allow 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, is 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. However, 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 a map called “A”. However, the three different diagrams in the hierarchy are at different version numbers.  You can see the bottom right diagram has three versions - V1, V2, and 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 simply adds all unassigned ‘Ready for release’ diagrams to the next release and then publishes them.

A release manages 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.

Seeing previous versions of diagrams

The Right Panel on a diagram under the "VERSIONS" tab shows the available versions (as listed below). If a user does not see "VERSIONS" in the right panel, it would be because then are either in edit mode and have something on the Diagram selected, or the Space is not Pro, in which case they do not have access to the Release and Version management capability.

Other than navigating between versions and the draft, the only action driven from this panel is to make a draft diagram “Ready for release”. To do this, when you select a draft, a button will appear to the right of the line giving this option.

The diagram below shows the four states that a diagram exists in.

FAQ

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 simply adds 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.

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 I 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.

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

If an activity which has a drilldown 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 the system automatically, and it is created in a "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.

Did this answer your question?