Register
Ask the Community

How to Interact With Anaplan Application Lifecycle Management (ALM) APIs?

What is covered in this article?

Anaplan’s Application Life Cycle Management (ALM) process flow and ALM APIs for automation of ALM processes.

What is NOT covered in this article?

This article does not present ALM best practices. It is focused on the usage of ALM APIs for the automation of ALM steps. For those who are new to Anaplan ALM, we highly recommend reviewing the following resources:

  1. What is Application Lifecycle Management (ALM)
  2. [Start Here] - ALM: The Basics

What pre-requisites do I need?

  • Knowledge of Anaplan model-building concepts.
  • Knowledge of Anaplan ALM concepts and best practices.
  • 熟悉REST API concepts & Postman (or a similar REST client).
  • Knowledge of Anaplan Authentication Services API.
  • Completion of Level 1 Model Buildingcourse.
  • Access to the completed Level 1 Model.
  • Workspace Administrator Access to Anaplan Models.

Introduction

Anaplan Application Life Cycle Management (ALM) APIs help orchestrate change deployments and automate ongoing maintenance of applications in Anaplan. This article introduces you to REST API endpoints that perform the following ALM tasks:

  • Create a revision tag
  • Change a model’s online status
  • Retrieve compatible source model revisions
  • Retrieve the latest revision
  • Create a model sync task
  • Retrieve model sync task info
  • Retrieve syn tasks for a model

In this article, we will use the model you have built as part of the Level 1 Model Building course to illustrate how to orchestrate and automate model deployment using ALM API.

Anaplan Setup

In this setup, you will set up Anaplan source & target models that will be used in deployments via API.

  • Make a copy of your and name itL1 Model Building Model Source.
  • UnderRevision Tagsin Model Settings, use “Create Model From Revision”to make a copy of theL1 Model Building Model Source.Name the new modelL1 Model Building Model Target.

annejulie_0-1635968254691.png

  • OpenL1 Model Building Model Sourceand update ---Geo Hierarchy--- to include the following Countries and Locations:
    • Chile (Santiago, Valparaiso)
    • Portugal (Lisbon)

annejulie_1-1635968254699.png

  • You will need following information to get started with ALM APIs.
    • Anaplan Workspace Id:__________________________________
    • L1 Model Building Model Source Id (source_model_id): _________________________
    • L1 Model Building Model Target Id (target_model_id): __________________________

Postman Setup

  • Create a collection namedALM API
  • Create an environment namedALM API
  • Create following environment variables in the environmentALM API

annejulie_2-1635968254708.png

ALM Process

We will use steps outlined in ALM process below to deploy changes made toL1 Model Building Model SourcetoL1 Model Building Model Target.

annejulie_3-1635968254715.png

Current ALM APIs support steps 0-5 & 7. Steps 3.1, 3.2, and 6 are performed manually using Anaplan UX. For this article, we will use Postman to make ALM requests.

Step 0: Create Revision

  • Use following ALM API endpoint to create a model revision.

Request Method

POST

Base URL

https://api.anaplan.com/2/0

Endpoint

/models/{source_model_id}/alm/revisions

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Content-Type: application/json

Body

{

“name”: ””,

“description”: ””

}
  • First step in making ALM API request is to generate Anaplan authentication token using Anaplan Authentication REST API. Use authentication service API (https://auth.anaplan.com/token/authenticate) to generate a token using either Basic or CA Certificate. We will not go into details to authentication API in this article. Details on how to generate authentication token can be found at resources below.
  • Using Postman, we will make a request toCreate Revisionsendpoint using API information provided above. You will provide a request method (POST), URL, Headers, a body.

annejulie_4-1635968254717.png

annejulie_5-1635968254722.png

annejulie_6-1635968254728.png

  • Response fromCreate RevisionsAPI request should return a status of “201 Created” along with revision metadata in a JSON format..

annejulie_7-1635968254739.png

  • Open yourL1 Model Building Model Source.In the Source model, you should see a newly created revision tag titled “Updated Geo Hierarchy”.

annejulie_8-1635968254744.png

Step 1: Take Target Model Offline

Once a revision tag is created, we will change status ofL1 Model Building Model TargettoOffline.

Note, this step is optional. Oftentimes you will want to take the model offline to make sure changes synced correctly, but it is possible to leave model online and sync changes.

  • Use following ALM API endpoint to change model status tooffline.

Request Method

POST

Base URL

https://api.anaplan.com/2/0

Endpoint

/models/{target_model_id}/onlineStatus

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Content-Type: application/json

Body

{

“status”: “offline”

}

  • Using Postman, we will make aChange a model’s online statusrequest using API information provided above. You will provide a request method (POST), URL, Headers, a body.

annejulie_9-1635968254746.png

annejulie_10-1635968254751.png

annejulie_11-1635968254754.png

  • Response status should be 204: No Content

annejulie_12-1635968254757.png

  • RefreshL1 Model Building Model Target. It should update the status toOFFLINE.

annejulie_13-1635968254758.png

Step 2: Retrieve last revision from Target Model

Next step in ALM API process is to get the id for last revision in the Target Model. We will use an environment variable last_rev_target to store revision id for the last revision tag in the target model. Our API request in Postman will automatically parse the JSON response and update this variable.

  • Use following ALM API endpoint to get last revision from the target model.

Request Method

POSTGET

Base URL

https://api.anaplan.com/2/0

Endpoint

/models/{target_model_id}/alm/latestRevision

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Tests

pm.environment.set(“last_rev_target”, pm.response.json().revisions[0].id);

  • Using Postman, we will make a request to get last revision tag in the target model. You will provide a request method (POST), URL, Headers, a postman command to set environment variable.

annejulie_14-1635968254760.png

annejulie_15-1635968254764.png

annejulie_16-1635968254766.png

  • Response status should be 200 OK with a JSON containing metdata for the latest revision tag in the target model.

annejulie_17-1635968254775.png

  • Your environment variablelast_rev_targetshould also be updated with the id for the latest revision in the target model.

annejulie_18-1635968254782.png

Step 3: Retrieve syncable revision tag from the source model

Once we have the target revision, we will retrieve revision tag id for compatible revisions in the source model. Similar to last revision tag in target model, we will use an environment variable rev_tag_source to store revision id for the revision tag in the source model. Our API request in Postman will automatically parse the JSON response and update this variable.

  • Use following ALM API endpoint to get compatible revisions from the source model.

Request Method

POSTGET

Base URL

https://api.anaplan.com/2/0

Endpoint

/models/{target_model_id}/alm/SyncableRevisions?sourceModelId={source_model_id}

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Tests

pm.environment.set(“rev_tag_source”, pm.response.json().revisions[0].id);

  • Using Postman, we will make a request to get last revision tag in the target model. You will provide a request method (POST), URL, Headers, a postman command to set environment variable.

annejulie_19-1635968254784.png

annejulie_20-1635968254791.png

annejulie_21-1635968254796.png

  • Response status should be 200 OK with a JSON containing metadata for the compatible revision tag in the source model.

annejulie_22-1635968254815.png

  • Your environment variablerev_tag_sourceshould also be updated with the id for the compatible revision in the source model.

annejulie_23-1635968254832.png

Step 3.1: Generate Comparison Report Task

Retrieving the sync comparison report (which shows changes to be affected in the production model) is a three step process. We create a comparison report task, then get the details of the task to grab the URL where we can then download the comparison file.

Request Method

POST

Base URL

https://api.anaplan.com/2/0

Endpoint

/ / {target_model_id} / alm / comparisonReportTask模型s

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Content-Type: application/json

Body

{

“sourceRevisionId”:”rev_tag_source”,

“sourceModelId”: “”,

“targetRevisionId”: “last_rev_target”

}

Tests

pm.environment.set(“comparison_task”, pm.response.json().task.taskId);

Step 3.2: Retrieve Comparison Report Task Results URL

Request Method

GET

Base URL

https://api.anaplan.com/2/0

Endpoint

/ / {target_model_id} / alm / comparisonReportTask模型s/{comparison_task}

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Content-Type: application/json

Body

Tests

pm.environment.set(“comparison_URL”, pm.response.json(). Task.result.reportFileUrl);

Step 3.3: Retrieve Comparison Report

Request Method

GET

Base URL

Just use full URL from prior step

Endpoint

{comparison_URL}

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Body

Tests

annejulie_24-1635968254844.png

Step 4: Create/Run Sync Task

Once we have identified compatible revisions in the source model and the latest revision in the target model, we are ready to execute a sync between the two models propagating changes from source model to the target model.

  • Use following ALM API endpoint to execute a sync between the source and target model.

Request Method

POST

Base URL

https://api.anaplan.com/2/0

Endpoint

/models/{target_model_id}/alm/syncTasks

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Content-Type: application/json

Body

{

“sourceRevisionId”:”rev_tag_source”,

“sourceModelId”: “”,

“targetRevisionId”: “last_rev_target”

}

Tests

pm.environment.set(“rev_tag_source”, pm.response.json().revisions[0].id);
  • Using Postman, we will execute a sync task from source to target model. You will provide a request method (POST), URL, Headers, body, a postman command to set environment variable. Instead of hard coding values for model id and revision tag ids, we will leverage environment variables in this request.

annejulie_25-1635968254846.png

annejulie_26-1635968254851.png

annejulie_27-1635968254856.png

annejulie_28-1635968254859.png

  • Response status should be 201 Created with a JSON containing sync task id and status. In the next step, we will use sync task id to review details of sync task execution.

annejulie_29-1635968254872.png

  • Environment variablesync_task_idshould be populated with the taskId from JSON response.

annejulie_30-1635968254881.png

Step 5: Get Sync Task Info

Using taskId from Sync task execution, we can obtain status of sync task. Using following API information to check sync status.

Request Method

GET

Base URL

https://api.anaplan.com/2/0

Endpoint

/models/{target_model_id}/alm/syncTasks/{sync_task_id}

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

annejulie_31-1635968254883.png

annejulie_32-1635968254886.png

annejulie_33-1635968254895.png

Step 6: Check for changes in the target model

Once sync is completed, you should new see two new countries (Chile, Portugal) and three locations (Santiago, Valparaiso, and Lisbon) in Geo Hierarchy of the target model,L1 Model Building Model Target.

annejulie_34-1635968254898.png

Step 7: Take Target Model Online

Once the source to target model sync is complete, we are ready to bring the target model back online usingChange a model’s online statusAPI.

  • Use following ALM API endpoint to change model status tooffline.

Request Method

POST

Base URL

https://api.anaplan.com/2/0

Endpoint

/models/{target_model_id}/onlineStatus

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Content-Type: application/json

Body

{

“status”: “online”

}

  • Using Postman, we will make aChange a model’s online statusrequest using API information provided above. You will provide a request method (POST), URL, Headers, a body.

annejulie_35-1635968254900.png

annejulie_36-1635968254904.png

annejulie_37-1635968254907.png

  • Response status should be 204: No Content

annejulie_38-1635968254910.png

  • RefreshL1 Model Building Model Target. It should update the status toonline.

annejulie_39-1635968254911.png

Summary

In this article, we outlined and described steps in an ALM process that guide automation of dev to prod model deployment using ALM APIs. You have learned how to perform following granular tasks using API:

  • Change model status
  • Create a revision tag
  • Retrieve revision tag ids for source and target models
  • Performance revision comparison
  • Create and execute a sync task
  • Check sync task run status

You can, now, extend your experience with ALM APIs to other scripting languages such as python for end to end automation.

Got feedback on this content? Let us know in the comments below.

The content in this article has not been evaluated for all Anaplan implementations and may not be recommended for your specific situation.
Please consult your internal administrators prior to applying any of the ideas or steps in this article.
Comments
JaredDolich
‎11-03-202104:01 PM
‎11-03-202104:01 PM

Another great article@joeymorisette@christophe_keom@pmarpakaand@annejulie

So needed.

annejulie
‎11-08-202101:44 PM
‎11-08-202101:44 PM

Glad you like it@JaredDolich!

Let us know ifwhen:winking_face:you are playing with the APIs and your experience with those, we are looking forward to hearing about your experience!

Version history
Last update:
‎11-03-202103:02 PM
Updated by:
Community BossCommunity Boss
About the Author
Contributors