ALM explained—Part 1: compatibility

DavidSmith
edited September 2023 in Best Practices

Introduction

Application Lifecycle Management (ALM) has been available since late 2016, and it is used widely and successfully across the Anaplan-customer base. ALM is founded on certain fundamental rules and structures, which if followed, will ensure the integrity between development, test, and production models is maintained. 

This is the first of a three-part series which will explain in detail some of these fundamental rules, techniques to validate the changes prior to deploying to production, and finally, what to do if things go wrong.

This series does assume that you already are familiar with ALM and understand the basic concepts. If you are new to ALM, it is advised to review the various articles and training materials available on Community and Anapedia. Here is a good starting point.

Let’s start the series by looking at the fundamental concept of ALM: compatibility. We will look at what compatibility is and how it is set up, how to ensure models stay compatible, and what to do to avoid breaking compatibility.

What is compatibility?

Compatibility is the term used to describe whether two or more models can be used as part of the ALM synchronization process—the process in which structural changes are deployed from a development model to test and production models. Structural information consists of a model's configuration settings and lists (with the exception of production lists). Structural information can't be edited when a model is in deployed mode. Changes that affect a model’s structural information are known as structural changes.

Revision tags are key to compatibility. We are not going to discuss revision tags in detail here, but more information and best practices can be found here. There is also an on-demand course

The other two terms associated with compatibility are source and target models.

  • The source model will have a number of revision tags containing sets of structural changes. This model can also be referred to as the development model.
  • The target model contains the same revision tags from the source model (or a subset of them). It is usually the production model for end users, and its model mode should be deployed. The target model can also be a test model. Finally, it is possible to have multiple target models that are compatible with a single source.

For a source and target model to be compatible, the two models must have a common origin. That means they both originated from the same revision, such as when one model has been copied to produce two models. Also, only one of the two models can have structural changes after it was copied or synchronized.

Common origin

Let’s look at the first condition; common origin.

To initiate ALM, a model must be copied. It does not matter if you create a development model by copying a production model, or if you create a production model by copying a development model. It is the copying process that creates the common origin and creates the initially shared revision tag.

If this is the first time the models have been copied, then a revision tag called “Copy Model” will be created in the source and the target models.

The “Copy Model” revision tag will also be created if there are any structural changes outstanding, i.e. changes that have not yet been crystallized in a revision tag (you can tell if this is the case because the “Add Revision Tag” icon is bold).

Assuming the model is copied without adding a revision tag for those outstanding changes, you will see the Copy Model revision tag in the source model once it is copied.

Assuming the revision tag was added for the outstanding changes, you will see the named revision tag in the development model.

Note that in the development model, the “Add Revision Tag” icon is now greyed out; this signifies that all structural changes have been captured in the revision tag or no structural changes have been made since the revision tag was added.

In the production model, when synchronized, the same revision tag is shown.

It is also possible to use the “Create Model From Revision” option.

This will create a copy of the model structures but will not create entries for production lists members or associated data. This is especially useful when setting up ALM, as it adheres to ALM best practices of keeping the development model small; it will create a shell model of just structures, so the development model will be much smaller than the production model (assuming you have set production lists in the production model first).

It can also be used to create a production model from a revision tag that is not the latest one within the development model; e.g. if you have already started work on phase 2. Using either ‘Copy Model’ or ‘Create Model From Revision’ will create a compatible model within the same workspace. As per best practice, this model should then be imported to a separate workspace.

Note that importing models across workspaces maintains the compatibility; it is possible to synchronize models across workspaces.

Checking compatibility

We mentioned above that is it possible to have multiple target models form a single-source model, and when many copies are taken (including archived models), it can be rather confusing to know if a target model is compatible with a source. There is a simple statement that will help clarify this.

“The latest revision in target model must exist in the source model.”

In our example, we can see that ‘Revision 2.1’ is shown in both source and target models. It is possible to create revision tags with the same name in different models, so to double-check, click on the icon next to the revision tag; this will show the source of the revision tag.

Maintaining compatibility

For ALM integrity, models must remain compatible. If, when running the synchronization process, you see a message like the one below, it is most likely that the models are not compatible. 

There is one exception. The last part of the description above states “a more recent revision tag must exist in the source model”. If you have just run a synchronization or are in the process of making changes in development but not yet added a respective revision tag, both models are structurally compatible, but there are no changes to the process, so the message appears.

This diagram shows the different stages of a development model and the associated message (assuming the models were compatible in the first place).

To maintain compatibility, the one golden rule to remember is: “Never take a production model out of deployed mode.”

Deployed mode prevents structural changes being made (even by an administrator), so if the production model is always in deployed mode, it is not possible to break compatibility. However, we do have situations where the compatibility is broken. So, if deployed mode prevents compatibility being broken, how does this happen?

Remember at the outset, the second element of compatibility was that only one model can have structural changes. Models cannot be compatible if there are structural changes in both source and target models. To make structural changes in a target model, the model mode must be changed from deployed to standard.

Taking a model out of deployed mode is not something that happens by accident. There are a number of steps needed to take a production model out of deployed mode:

  • Navigate to Manage Models.
  • Click to change the model mode.
  • Change the mode to Standard.
  • Click “yes” at the warning message.

However, despite this warning, target models are taken out of deployed mode. The main reasons for this are:

  • Setting up or re-initializing ALM; this is the obvious exception to the rule.
  • A quick temporary fix (there is a documented best practice for this that does not need the model mode to be changed).
  • A developer who just wants to quickly test something.
  • A developer who isn’t following the ALM protocols and decided to develop functionality in the production model.

The latter two points are difficult to police, but depending on the circumstances, it might be possible to restore compatibility, if and only if, a revision tag has not been set in the target model. If that has happened, the rule “the latest revision in the target must exist in the source” will have been broken. Once a new revision tag is set in the target model, compatibility is lost forever.

The following shows the different circumstances of compatibility: 

It is possible to “flip” the modes from deployed to standard without breaking the compatibility, but why would you? Any structural changes made will break the compatibility, even if done by accident.

The second situation is the most common and we will cover how to recover from it shortly, but in this state, it is easy to “accidentally” set a revision tag. A common occurrence in the field is developers make changes to test or check something. They know about the compatibility issues and understand that they will have to set the target model back as it was, so to preserve their work for reference, they copy the model.

As mentioned above as part of the initialization process, copying a model creates a new revision tag, immediately breaking compatibility. So, unless you are starting/re-initiating ALM from scratch and you have taken your target model out of deployed mode, DO NOT COPY IT.

Compatibility

As outlined, taking a model out of deployed mode is risky and should be avoided, but let’s finish by outlining how to restore compatibility.

Let’s assume a target model has been taken out of deployed mode and structural changes have been made. (Note: no new revision tags have been set in the target model).

We now want to synchronize ‘Revision 3’ to our target model.

As we navigate through the process, it seems initially that the models are still compatible; after all, they do still share a common revision tag (‘Revision 2.1’). Only in the final step to confirm the synchronization does the problem become apparent.

As mentioned, it is possible to restore compatibility (if no new revision tags have been set).

Navigate to the Revision Tags tab, and if structural changes have been made, the “Revert to Last Revision” icon will be bold.

Click the icon. As the message says, this will revert all structural changes made since the last synchronization, so setting the target model structures back to those as at ‘Revision 2.1’.

Reverting will restore the compatibility allowing the target model to synchronize to ‘Revision 3’.

Once ALM is initiated, there is no real reason why compatibility should be broken or mode models should be changed. It is always possible to start the ALM process again which will re-initiate compatibility, but this will not restore compatibility between existing models; rather, it will set up compatibility for a new set of models:

  • As above, copy/create from revision/import the development model to create a new production model. This is only viable if you can re-populate the production model and not lose data. This is sometimes the only option if compatibility is broken because of changes made in the production model.
  • As above, copy/create from revision/import the existing production model to create a new development model. This is the best option if changes in the development model changes are to be disregarded, although the development model can always be reverted to a previous point in its history, which is often a better and safer option.

Conclusion

Compatibility is key to the Application Lifecycle Management process. There are defined rules and model modes designed to maintain this compatibility. Following these rules will allow ALM to be used effectively without issues.

Part two of the series will cover how to test changes to prevent issues post-synchronization.

Comments

  • Excellent Article @DavidSmith . This will definitely be a help for many model builders. 

    Recently i faced one challenge in Creating a production model from revision tag directly into different workspace. 

    I was not getting the option to Deploy directly in production workspace. 

    Hence, I had to create prod model in same workspace first and than import the model in production workspace.

  • @NakulAggarwal 

    Thanks

    Yes, in terms of the set up, think of "Create from Revision" as a copy model rather than an import

    So the steps are

    1. Create from Revision, this will create a copy in the same workspace
    2. Navigate to the target Production  or Test workspace and Import the model created in 1.
    3. Delete the copy created in 1.

    Compatibility works across workspaces

    David

  • I was asked today if archiving a model breaks ALM.

    The answer is no, changing the model mode doesn't change the compatibility, and that includes archiving a model.  However, be careful if you bring a production model back from Archive mode. Ensure that is it brought back into Deployed mode to ensure it is protected from unwarranted changes.

    David

  • Hi @rob_marshall, I found this post (https://community.anaplan.com/t5/Chapter-6/6-03-01-Don-t-take-the-model-out-of-deployed-mode/ta-p/81502), but wanted to double check since it was published in 2020 and hoping this is no longer the case.

     

    We copied a DEV model to make a PROD model, and put the PROD model into 'Deployed' mode. We want to update Users selective access via import of a CSV file and get an error message that we cannot import to a 'Deployed' model. What will happen if we change the model from 'Deployed' mode to 'Standard' mode so that we can perform the import? Will that break the existing ALM connection between the DEV and PROD models?

    Thank you,

  • @Joshua.Huilar 

     

    Correct, it is not considered best practice to take models out of Deployed Mode as this can still break ALM.  If you take the Prod model out of Deployed Mode, create an action to load users, run the action, and then put it back in Deployed mode, you will break the AL sync process.