Using the Planning APIs setUserInput and submitData

With the setUserInput and submitData APIs, you can enable the application user to change the value of a cell in a table at runtime.

The following prerequisites must be met:

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

  • You have set the table to planing- enabled ( just check the table property Planning enabled).

The setUserInput and submitData APIs work together.

Working 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 an unbooked cell or a null cell displaying a (#) character for SAP BPC models as it is currently not supported.

setUserInput(selection, value)
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.
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 these:

  • 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 maximum.

    If you attempt to use anything else than a number for a value, an error message mentioning that the value is not valid, is displayed. Examples that trigger an error message:

    • 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>}, " ");

    Example of cases that shall trigger an error:

  • a scalar of the form *[multiplying factor]

    The scalar can have 7 characters maximum.

submitData()
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. 
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 is 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

This example assumes the existence of 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, please 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 is more than one table with the same underlying model, all the tables will be 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 a refresh of the planning table before submitting your input, then your input could be discarded.