Transactional APIs - Part 2: Use Cases

• Introduction
• Following use cases will be presented in this section:
• How to retrieve id for a given dimension/list & list member from its name or code
• How to retrieve allocated & consumed space for a Workspace & Model
• Workspace Sizing Use case
• Model Memory Usage Use case
• How to retrieve permitted number of Items & Index Count for Numbered Lists
• Make updates to Model Calendar using transactional API
• Update Current Fiscal Year
• Update Current Period

This article follows our Part 1 - Transactional APIs, the basics; we are taking it up a notch and are going technical; we encourage you to be familiar with Transactional APIs when you go through this content.

For an overview of Anaplan APIs, go here.

Disclaimer:  Scripts provided with this article are for reference only. They are not production grade and are not supported by Anaplan. They are provided to illustrate examples of different integration use cases using Anaplan APIs.

Target Audience:  Integration Developers

Pre-requisites:

• Familiarity with following:

  • REST, Python scripting, Anaplan API, Anaplan Modeling concepts.
  • Anaplan authentication token is generated.
• Scripts provided were tested on Python v3.8.2

Introduction

In this section, we will address Transactional APIs that allow you to gather model metadata. We will present different use cases that will benefit from using Transactional APIs. Sample Python scripts will be used to illustrate power of transactional APIs in model maintenance & management.

Following use cases will be presented in this section:

1. How to retrieve id for a given dimension/list & list member from its name or code.
2. How to retrieve allocated & consumed space for a Workspace & Model.
3. How to retrieve permitted number of Items & Index count for numbered lists.

4. Make updates to Model Calendar using transactional API.

   • How to update Fiscal Year for a model.
   • How to set current period for a model.
   • Set a new version (EA)
   • Update switchover period (EA).

How to retrieve id for a given dimension/list & list member from its name or code

Transactional data API call enable users to work with model data (saved view) without using Actions. For example, using Transactional API, you are able to read data from a saved view. An API request to query a saved view with page selectors may look something like:

https://api.anaplan.com/2/0/models/{modelId}/views/{viewId}/data?pages={dimensionId:itemId}&format=v1

In order to make this API request, you will need to gather ids for the model, view, dimension, and item.  This means, you will likely need to make four different API calls to get a list of all dimensions, for examples, and parse through the JSON response to get the id you are interested in.  Imagine doing this for every time you need to build a query. Wouldn’t it be convenient to create a simple python script you can use that returns an id based on a name or a code? You will learn how this is done using transactional APIs.

Following API endpoint can be used to retrieve all the lists and their ids in a specified workspace and model:

https://api.anaplan.com/2/0/workspaces/{workspaceId}/models/{modelId}/lists

Headers:

• Authorization: AnaplanAuthToken {anaplan_auth_token}
• Accept: application/json

transGetListIdFromName.py

A sample python script (transGetListIdFromName.py) is provided with this article, that can help you retrieve a list Id from a list name. This script takes three arguments at the command line: workspaceId, modelId, and a list name. It returns list name associated with the list name.

python transGetListIdFromName.pay {workspaceId} {modelId} {List Name}

transLookupItemIdFromName.py

You can also look up item id from name or code. Python script transLookupItemIdFromName.py retrieves list item Id from a list member name. This script takes three arguments at the command line: workspaceId, modelId, & listId.  It returns list name associated with the list member name. List member name can be provided in the script for the variable item_name. ListId can be obtained using the script described above (transGetListIdFromName.py).

python transLookupItemIdFromName.py {workspaceId} {modelId} {listId}

transLookupItemIdFromCode.py

You can also look up item id from name or code. Python script transLookupItemIdFromName.py retrieves list item Id from a list member code. This script takes three arguments at the command line: workspaceId, modelId, & listId. It returns list name associated with the list member name. List member name can be provided in the script for the variable item_code. ListId can be obtained using the script described above (transGetListIdFromName.py).

python transLookupItemIdFromCode.py {workspaceId} {modelId} {listId}

Note: Anaplan authentication token is hard coded into these scripts.

Prior to executing the script, you will need to update the value for anaplan_token in the script. Ideally, you would want to create a separate function to generate the token and pass the value of the token to the API request dynamically. For illustration purposes, we will focus on transactional API functionality. Details on how to generate authentication token via APIs can be found in our CA Certs Best Practices article here.

How to retrieve allocated & consumed space for a Workspace & Model

Do you want to monitor your workspaces and models for their size and take appropriate action when they reach a certain threshold? Do you have a need to monitor index count for numbered list before it reaches a max of 1,000,000,000? Transactional metadata APIs is your answer.

Transactional metadata APIs provide insights into Workspace and Model information. This information can be used to populate a dashboard in Anaplan that monitors key metrics regarding Workspace/Model size, current index count for a numbered list, etc. This section presents instructions and sample script(s) to gather these insights that can be loaded into a model.

Let’s take a scenario where we would like to monitor following:

• Workspace Size
• Model Memory Usage
• Current Index Count for a list

Workspace Sizing Use case

Let’s say we want to report on a list of all workspaces within our default tenant. We would also like to report on allocated space and consumed space for each workspace in our tenant.

Transactional metadata API endpoint with parameter tenantDetails=true will return a list of all workspaces in a tenant. It also returns additional workspace metadata that includes workspaceId, name, sizeAllowance (bytes), and currentSize (bytes). API call would look something like:

Headers

       Authorization : AnaplanAuthToken {anaplan_auth_token}

transGetWorkspaceSizeInfo.py

A sample python script, transGetWorkspaceSizeInfo.py, provided with this article returns a list of Workspaces in your default tenant with Allocated Size and Current Size for each workspace. To use this script, you will need to update the script with Anaplan authentication token.

Model Memory Usage Use case

Let’s say we would like to understand how much memory is being used by a model in a given workspace.  Using transactional API, you can retrieve a list of all models and each model’s memory usage with in a given workspace in your default tenant. 

Transactional metadata API endpoint https://api.anaplan.com/2/0/workspaces/{workspaceId}/models with parameter modelDetails=true will return a list of unarchived (“UNLOCKED”) models in a given workspace and available model usage in bytes.  If modelDetails is set to false or not defined, API call will not return the model memory usage information.  API call would look something like:

https://api.anaplan.com/2/0/workspaces/{workspaceId}/models?modelDetails=True

Headers

       Authorization : AnaplanAuthToken {anaplan_auth_token}

transGetModelSizeInfo.py

A sample python script, transGetModelSizeInfo.py, provided with this article returns a list of models in a selected workspace in your default tenant along with available memory usage information in bytes & MB for each model. It will also return number of models in selected workspace. To use this script, you will need to update the script with Anaplan authentication token.

How to retrieve permitted number of Items & Index Count for Numbered Lists

Each list item has an index. The maximum value for a list item index is 999,999,999. The next item index represents the index of the next new item. Subsequent imports can fail if your organization works with large amounts of data and the maximum value is reached. You can reset the Next item index if:

• You’re a workspace administrator
• The list item index of the selected list is between 899,999,999 and 999,999,999
• The select list does not contain any items. (source: Anapedia).

Using transactional API, Retrieve list metadata, you can setup automated monitoring of list item index value. You can, optionally, setup notification alerts when the index value reaches a certain threshold so you can take appropriate action such as resetting the index. There is an API endpoint available to reset the index. Endpoint to retrieve list metadata is as follows:

https://api.anaplan.com/2/0/workspaces/{workspaceId}/models/{modelId}/lists/{listId}

Headers:

• Authorization : AnaplanAuthToken {anaplan_auth_token}
• Accept : application/json
• Content-Type : application/json

Among other information, this API endpoint will return two pieces of information regarding index count: 

• permittedItems:  Indicates how many more items you can add to the existing list.  This value changes when the number of items in the list change.
• nextitemIndex:  This applies to only numbered list.  It returns the index of the next new item in the numbered list.

Two sample python scripts, transGetItemIndexCountInfo.py & transGetItemIndexCountInfoNList.py are provided with this article to illustrate how this endpoint can be used to monitor available number of list members and next item index value.

transGetItemIndexCountInfo.py returns number of permitted items in a standard list. It requires three input arguments: workspaceId, modelId, and listId.

python transGetItemIndexCountInfo.py {workspaceId} {modelId} {listId}

transGetItemIndexCountInfoNL.py returns two pieces of information: number of permitted items and next item index in a numbered list.  It requires three input arguments: workspaceId, modelId, and listId (numbered list).

Make updates to Model Calendar using transactional API

Updating time dimension for all the models in a workspace, each planning cycle, can be a daunting task.  Thanks to transactional APIs, you are now able to automate updating of Current Fiscal Year and Current Period via a script (ex: python).

In this section, we will present API endpoints (with sample Python scripts) that will facilitate updates to Current Fiscal Year & Current Period in Time settings of a model.

Update Current Fiscal Year

There are two API endpoints allow you to work with Current Fiscal Year in a model:

• Retrieve Current Fiscal Year using GET method
• Set Current Fiscal Year using PUT method

Let’s examine API details to set current fiscal year in a model.

URL:

https://api.anaplan.com/2/0/workspaces/{workspaceId}/models/{modelId}/modelCalendar/fiscalYear

Headers:

• Authorization : AnaplanAuthToken {anaplan_auth_token}
• Accept : application/json
• Content-Type : application/json

Body

            {“year”:“{fiscal year}”}

transSetCurrentFiscalYear.py script can be used to, programmatically, set Current Fiscal Year in a model.  This script has three input arguments:  workspaceId, modelId, & newFiscalYear (ex: FY23).

Example: 

Python transSetCurrentFiscalYear.py 8a81b09d5e8c6f27015ece3402487d33 35A6EF893D7F47EEA5A554D5CC7DC330 FY23

Update Current Period

There are two API endpoints allow you to work with Current Period in a model:

• Retrieve Current Period using GET method
• Set Current Period using PUT method

Let’s examine API details to set current period in a model.

URL: 

https://api.anaplan.com/2/0/workspaces/{workspaceId}/models/{modelId}/modelCalendar/currentPeriod?date={new_curr_period}

Headers:

• Authorization : AnaplanAuthToken {anaplan_auth_token}
• Accept : application/json
• Content-Type : application/json

transSetCurrentPeriod.py script can be used to, programmatically, set Current Period in a model. This script has three input arguments:  workspaceId, modelId, & newCurrentPeriod (ex: 2023-07-21).

Example: 

Python transSetCurrentPeriod.py 8a81b09d5e8c6f27015ece3402487d33 35A6EF893D7F47EEA5A554D5CC7DC330 2023-07-21

Now, let's move on to Part 3 and Data Virtualization.

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

Contributing authors: Joey Morisette, Christophe Keomanivong, and Pavan Marpaka.https://api.anaplan.com/2/0/workspaceshttps://api.anaplan.com/2/0/workspaces?tenantDetails=true