Use Data Locking APIs

You can use data locking APIs in analytic applications and optimized stories to check if a model is data-locking enabled and to set or get data locks, even if the table is not planning enabled.

You can use the following APIs for data locking:

  • Table.getPlanning().getDataLocking

  • Table.getPlanning().getDataLocking.getSate

  • Table.getPlanning().getDataLocking.setState

The following prerequisites must be met:

  • You have assigned an SAP Analytics Cloud planning model to the table.

  • You have a license that allows you to read the data locking state.

Note

  • Data locking and the data locking APIs are not supported for SAP BPC models.

  • If data locking is disabled for a model, all locks will be deleted. If it is turned on again later, all members are reset to the default lock state. The same happens if the default lock state or driving dimensions are changed.

Using the getDataLocking API

You can use the getDataLocking API to check if a planning model is enabled for data locking.

The check is necessary because an end user cannot perform certain operations on a table, like setState and getState, if the model is not data-locking enabled.

Example
Sample Code

var planning = Table_1.getPlanning();
 

//gets the DataLocking object of the table - if DataLocking is enabled on the model

console.log(planning.getDataLocking());

Using the getState API

You can maintain the locking state of a cell belonging to a driving dimension by using the Table.getPlanning().getDataLocking.getSate API. This API function only works for SAP Analytics Cloud planning models that are enabled for data locking.

Example
Please have a look at the example below for how to set the data lock state for a selected cell, instead of using the Manage Data Locksquick actions menu option of the table.
Sample Code

var selection = Table_1.getSelections()[0];
 

//get the state of the selection
var selectionLockState =  Table_1.getPlanning().getDataLocking().getState(selection);

To make this example work, you have to select a cell on the table for which you want to retrieve the lock state. Alternatively, you can define the selection yourself in the script editor.

The API returns the state of the selection, which can be OPEN, RESTRICTED, LOCKED, or MIXED. If the state of the selection can't be determined, the API returns undefined. This can happen under following conditions:

  • Your selection is invalid.

  • The cell that belongs to the selection is not found.

  • The cell has an unknown state.

  • The cell has been created by the quick action menu "Add Calculation" at runtime.

  • You don't have a license that allows you to maintain the data locking state.

If you have activated the option to show data locks for the table (select Start of the navigation pathShow/Hide Next navigation step Data LocksEnd of the navigation path in the table's quick action menu), the lock icons will be updated after the API has been run.

Using the setState API

You can lock a cell belonging to a driving dimension by using the Table.getPlanning().getDataLocking.setSate API. This API function only works for SAP Analytics Cloud planning models that are enabled for data locking.

The API returns true if the setting of the lock was successful, and false for the following cases:

  • You can't set the data lock state on a private version. In this case, the error message You can only set data locks on public versions. Please use a public version and try again. is displayed.

  • If you try to set the state with the value Mixed, you will be notified in the script editor with the error message You can't set the state with the value 'mixed'. Please specify either 'open', 'restricted' or 'locked' as value.. The same error message is shown at runtime, if you attempt to execute the script, and the script fails.

  • If you select multiple cells and attempt to set the state, only the selection of the first cell will be considered when setting the state.

Example
Set the selection to the locked state
Sample Code

var selection = Table_1.getSelections()[0];


/sets the selection to Locked
var isSetStateSuccessful =  Table_1.getPlanning().getDataLocking().setState(sel,  DataLockingState.Locked);
Note

This API replaces the table's quick action menu Manage Data Locks.