Use setUserInput and submitData Planning APIs

As an application designer or story developer, you can use setUserInput and submitData APIs to enable end users to change the value of a cell in a table in view time.

There're following prerequisites:

  • You've assigned a planning model to the table - either a SAP BPC model or an SAP Analytics Cloud planning model.

  • You've set the table to planing-enabled. Just check whether you've selected the table property Planning enabled.

The setUserInput and submitData APIs work together.

Work with Booked and Unbooked Cells

When you change a booked value, the leaf members that aggregate up to that value are adjusted proportionally to reflect your change. When you enter a new value in an unbooked cell, which displays a dash character (-) instead of a value, values are also booked to one or more leaf members for each dimension that aggregates up to the cell.
Note

Be aware that you can’t use the setUserInput API for planning on a null cell displaying a # character for SAP BPC models as it's currently not supported.

Use setUserInput API

This API updates the cell of a table with a specified value and returns true if the operation was successful and false if the operation failed.
Sample Code
Table_1.getPlanning().setUserInput(selection: Selection, value: string):boolean
The selection must be a selection from the table, and the value must be supplied according to the user formatting settings. It can be one of the following:

  • A string representing a number

    Note

    When setting a value for a key figure of a BPC model, in addition to using a string that represents a number, you can use digits, letters, and special characters in the value.

    The string can have 17 characters at maximum.

    If you attempt to use anything else than a number for a value, an error message mentioning that the value is invalid is displayed. For example:

    • If you use an empty string like Table_1.getPlanning().setUserInput({<selection>}, "");.

    • If you try to reset the value of a cell like Table_1.getPlanning().setUserInput({<selection>}, "-");

    • If you use an empty space for planning like Table_1.getPlanning().setUserInput({<selection>}, " ");

  • A scalar of the form *[multiplying factor]

    The scalar can have seven characters at maximum.

Use submitData() API

This API submits the updated cell data with all the modified data and triggers the refresh of data. It returns true if the operation was successful and false if the operation failed.
Sample Code
Table_1.getPlanning().submitData();

The submitData API should be called after all the desired cells have been planned. Just call submitData() once to observe the results on the planned table.

Example

The example is based on a table called Table_1 that has an underlying planning model.

Method Sample Code

Planning a cell with the selection object

Even if the table is hidden, it's still possible to plan a cell.

Sample Code
Table_1.getPlanning().setUserInput({<selection>}, "5000000");
Table_1.getPlanning().submitData();

Planning a cell with the selection from the table
Sample Code
Table_1.getPlanning().setUserInput(Table_1.getSelections()[0], "500000000.99");
Table_1.getPlanning().submitData();

Planning a cell with the value from an input field

In this example, there's an input field widget called InputField_1.
Sample Code
Table_1.getPlanning().setUserInput({<selection>}, InputField_1.getValue());
Table_1.getPlanning().submitData();

Useful Details

When you work with the APIs, note the following information:

  • If you add a new dimension using an API, you must first expand the dimension to be able to plan the cell.

  • If you plan a cell with the same value, the API returns true and overwrites the existing value.

  • If you plan setUserInput() with an invalid value, an error message is displayed and the API returns false.

  • If there's more than one table with the same underlying model, all the tables are updated once you plan a cell.

Note

After calling setUserInput(), it's best to immediately submit your input with Planning.sumbitData(). Otherwise, unexpected results may occur. For example, if other operations are performed in scripts or by user interaction that lead to the refresh of the planning table before your input submission, your input could be discarded.

Related Information