Data-Change actions are logical operations that modify data values. The desired new values are defined by expressions. In many cases, that value is constant (eg: an action to ApproveOrder sets the status of the Order to "Approved") or it has a well-defined expression (eg: an action to EstimateDeliveryDate sets the estimated delivery date of the Order to the maximum of the delivery dates of each of its sub-orders).
However, there are also situations that need a dynamic input specified either by the user via an app dialog, or specified by another invoking action. This is where the INPUT() function can be used.
Let’s consider an app with Orders and Customers. Let us say there is a "ChangeStatus" action on an Order that changes a status to "Complete" and also records a comment. This would be implemented in AppSheet as a SetColumnValue action with two columns that are set by expressions (Status: “Complete”, and Notes: “n/a”). For the app user, this action shows up as a “ChangeStatus” button in their app.
Let’s assume we want to ask the app user to provide the notes that will be saved. To do so, the ChangeStatus action would set the value of Notes to INPUT("NotesInput", "n/a"). This means it is a special text input called "NotesInput" with a default value of "n/a". When the app user clicks the ChangeStatus button, they will be prompted with a dialog that asks them to provide the notes.
Now let’s also assume we occasionally want to cancel a customer’s account. In that case, we want a single CancelAccount action on the Customer record that will go to all the orders of that customer and set their status to “Complete” with the notes saying “Account cancelled”. To do this, a Reference Action that can be defined on the Customer. This action can specify a set of Orders to be acted on (those that are created for this customer) and an action to invoke on them (ChangeStatus). Now in order to pass the desired values (“Account Cancelled”) for the notes column to the ChangeStatus action, the Reference Action definition has the ability to bind the NotesInput value to an expression (in this case, constant text "Account Cancelled", but in general, it can be any expression that is appropriate in the context of a Customer).
Here is an example of an action that sets the value of a column. It uses an Input function.
Here is an example of an action that references another action and binds its inputs to dynamic values.
At the moment, the INPUT() function and the ability to bind the inputs to dynamic values is in a beta release mode. The INPUT function can be used in any expression but will always evaluate to its default value except for the specific usage scenarios below.
In a Data Change Action that sets the value of a column, the INPUT function must be used as the top-level expression (eg: Notes assigned to INPUT("NotesInput", "n/a"))
When this action is invoked via a user button click in the app user interface, it will prompt a dialog that asks the user to provide the value
When this action is invoked from a Reference Action (whether in the running app or in an automation), the Reference Action can specify a binding expression
This list of usage scenarios will grow over time as we broaden this capability. Some of these broader scenarios will include:
Use in Add Row Actions
Use in Grouped (multi-step) Actions
Use in Tasks and Processes invoked from automation bots (with the ability to bind the inputs used by one task to the results from a previous step in the automation process)
Use in actions that modify UserSettings