Use Data Actions Technical Objects

As an application designer or story developer, you can use the Data Actions technical object and related script APIs to let viewers perform data actions, set and read parameter values.

Prerequisites

Before you can use the data actions technical object, there have to be data actions created already.

Please consider as well the following permissions and roles:

To create or edit a Data Actions technical object, you need the permission to edit the analytic application or story.
To select a data action in the Data Action Configuration side panel, you need the read permission for it.
To execute a data action, viewers need the execute permission for it.

Context

Data action is a flexible planning tool for making structured changes to a version of model data, such as copying data from one model to another.

There're two ways for you to use this feature:

Using the Data Action Trigger widget

For how to add a data action trigger to your analytic application or story and configure related settings, refer to Set Up Planning Triggers.
Using the Data Actions technical object and related APIs
You can do the following:
- Setting parameter values of data actions
- Reading parameter values of data actions
- Executing data actions

Procedure

To add a data actions technical object, in the Scripting section of the Outline panel, (for analytic applications) choose right next to Data Actions, or (for optimized stories) choose Data Actions.

The side panel Data Action Configuration opens.
From the Data Action dropdown, select one of the data actions that have been created already. The related parameters are displayed below.
Enter the values for the parameters by either using the member selection or choosing the default value that was set in the data actions designer.
Note
- To execute a data action successfully, you need to enter the values of all parameters, either in Data Action Configuration panel or via the API setParameterValue.
- The design of the data action itself can't be changed in Data Action Configuration, but you can adjust it by setting parameter values there.
Select Done.

After adding the technical object, you can leverage the following APIs to work with data actions in your application or story:

Executing data actions
- As a blocking operation. Other scripts won't be running until the data actions execution is complete.
  Code Syntax
  execute(): DataActionExecutionResponse;
- As a non-blocking operation. Other scripts can be running at the same time without waiting for the data actions execution to complete.
  Code Syntax
  executeInBackground(executionName: string): DataActionBackgroundExecutionResponse;
  The API returns the execution status, either accepted or error, and a unique execution ID.
  In this case, the onExecutionStatusUpdate event of data actions technical object can be called when the execution status changes:
  Code Syntax
  // Called when an asynchronous Data Action execution changes its status. The new status parameter value can be Running, Error, Success or Cancelled. onExecutionStatusUpdate(status: DataActionExecutionResponseStatus, executionId: string, executionName: string): void

Getting parameter values

Code Syntax

getParameterValue(parameterId: string): DataActionParameterValue;

Setting parameter values

In the following example, a set of dimension member filters is assigned to the parameters of a data action. The scripts collect the relevant single value and multiple value dimension member filters into an array before the assignment operation. Exclusive filters are ignored as they're not supported by data actions.

Sample Code

var filters = table.getDataSource().getDimensionFilters(dimensionId);
var filteredMemberIds = ArrayUtils.create(Type.string);

for(var i = 0; i < filters.length; i++) {
                if (filters[i].type === FilterValueType.Single) {
                               var singleFilter = cast(Type.SingleFilterValue, filters[i]);
                               if (!singleFilter.exclude) {
                                               filteredMemberIds.push(singleFilter.value);
                               }
                } else if (filters[i].type === FilterValueType.Multiple) {
                               var multiFilter = cast(Type.MultipleFilterValue, filters[i]);
                               if (!multiFilter.exclude) {
                                               filteredMemberIds = filteredMemberIds.concat(multiFilter.values);
                                }
                }
}

dataAction.setParameterValue(parameterId, {
                type: DataActionParameterValueType.Member,
                members: filteredMemberIds
});