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

AnaplanOEG
AnaplanOEG
edited December 2022 in Best Practices

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.
  • Familiarity with REST API concepts & Postman (or a similar REST client).
  • Knowledge of Anaplan Authentication Services API.
  • Completion of Level 1 Model Building course.
  • 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 <L1 Model Building model> and name it L1 Model Building Model Source.
  • Under Revision Tags in Model Settings, use “Create Model From Revision” to make a copy of the L1 Model Building Model Source. Name the new model L1 Model Building Model Target.

annejulie_0-1635968254691.png

  • Open L1 Model Building Model Source and 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 named ALM API
  • Create an environment named ALM API
  • Create following environment variables in the environment ALM API

annejulie_2-1635968254708.png

ALM Process

We will use steps outlined in ALM process below to deploy changes made to L1 Model Building Model Source to L1 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”: ”<new_revision_title>”,

   “description”: ”<new_revision_desc>”

} 
  • 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 to Create Revisions endpoint 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 from Create Revisions API request should return a status of “201 Created” along with revision metadata in a JSON format..

annejulie_7-1635968254739.png

  • Open your L1 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 of L1 Model Building Model Target to Offline.

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 to offline.

 

 

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 a Change a model’s online status request 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

  • Refresh L1 Model Building Model Target. It should update the status to OFFLINE.

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

POST GET

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 variable last_rev_target should 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 variable rev_tag_source should 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

/models/{target_model_id}/alm/comparisonReportTasks

Headers

Authorization: AnaplanAuthToken {anaplan_auth_token}

Content-Type: application/json

Body

{

   “sourceRevisionId”:”rev_tag_source”,

   “sourceModelId”: “<source_model_id>”,

   “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

/models/{target_model_id}/alm/comparisonReportTasks/{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”: “<source_model_id>”,

   “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 variable sync_task_id should 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 using Change a model’s online status API.

 

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

 

 

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 a Change a model’s online status request 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

  • Refresh L1 Model Building Model Target. It should update the status to online.

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.

Contributing authors: Christophe Keomanivong, Joey Morisette, and Pavan Marpaka.

Tagged:

Comments

Categories