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.
-
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.
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.
Table_1.getPlanning().setUserInput(selection: Selection, value: string):boolean
-
a string representing a number
NoteWhen 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.
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(); |
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.
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.