Actions: The Essentials

Actions perform specific operations. Actions can be extremely helpful in accomplishing a variety of different tasks with your app, from email to copying a row. It's also possible to execute a sequence of actions.

There are four types of actions included in an app definition, as described in Action types.

• Navigation: Navigate to a different view within an app
• Data-change: Modify (add, delete, update) data in your app
• External: Interact with an external service, such as opening the phone app on a device to start a call or sending information to an external service (such as a push notification or an SMS message
• Grouped: Execute a sequence of actions in a specific order.

Besides the actions you can create in your app, other actions are automatically created. You can learn more about system actions and how to control them.

Not only can you create actions, you can also configure them to run when certain view navigation events happen using view events.

The following sections provide more information about actions:

• Where do actions appear?
• Where can an action run?
• When does an action run?
• How to show, hide, or reorder actions in a view
• Create an action
• Configure an action
• Reorder actions in your app
• Add an action to your favorites
• Action types

Where do actions appear?

Quick actions

In the detail view, a button is shown for each action in your app. When the button is tapped, the action is triggered.

Bulk actions

In the table, deck, and gallery views, actions can be applied in bulk across many rows simultaneously. See Use bulk actions.

Where can an action run?

All AppSheet apps run on a device or in a browser. However, all apps are actually hosted from the AppSheet cloud service (also called the AppSheet backend) so some actions can also run in the cloud service, as follows:

• Navigation actions can only run in the app on the device or in a browser.
• Data- change actions can run in the app or in the cloud service. The app data is accessible and can be changed at either location.
• External actions only run in the client. For example, the External: Start an email action opens the email app on the device running the AppSheet app, it doesn't actually send the email. 

When does an action run?

Every data action has to be triggered by some event that causes it to run. As the app creator, you control the trigger, as follows:

• Explicit user invocation: Create an action to be shown as a visual icon or button. When the user taps or clicks on the icon or button, the app invokes the action.
• Implicit user invocation: Every view in the app has some standard behaviors when a user interacts with the data in the view. For example, when a user taps on a row in a tabular view, that specific row is shown in detail in a detail view. By default, the Row selected event triggers a system-defined UI Navigation action that takes the user to the new view. As the app creator, you can control a subset of the triggering events associated with each view. See Run actions based on view events.
• Automatic invocation in the cloud service: Define automation bots that run in the cloud service and execute actions when specific changes occur or on a schedule. See AppSheet automation: The Essentials.

How to show, hide, and reorder actions in a view

To show, hide, and reorder actions in a view, do one or more of the following:

• Create an action that will display for views that use the table.
• Reorder actions in your app.
• Create a group action to run a set of actions, one-by-one, in order.
• Configure the Only if this condition is true setting in the Behavior section for a view to control which rows show the actions and the order they are displayed.
  For example:
  • To show an action for detail views only, you can configure the setting as follows: SHOW_IF = CONTEXT("VIEWTYPE")="Detail"
  • To order actions as ABC for detail views and ACB for all other views, you can configure the setting for each action as follows:
    • Action A: Leave blank
    • Action B:  SHOW_IF = CONTEXT("VIEWTYPE")="Detail"
    • Action C:  Leave blank
    • Action B (duplicate): SHOW_IF = NOT(CONTEXT("VIEWTYPE")="Detail")
• Add a slice to filter specific actions in views. See Slice actions.
• For deck views, configure the action bar.
• Hide system actions.

Create an action

To create an action for a table:

1. Open the app in the app editor.
2. Go to Actions, click + in the top header of the Actions panel, and select one of the suggestions or click Create a new action.
    We've made some improvements to the app editor.
   You are opted in to the new editor by default, but you can switch back to the legacy editor at any time.

   If you are using the legacy navigation

   Go to Behavior > Actions and click + New Action or select one of the suggestions, if provided.

3.  Configure the action.

4. Save the app.

Configure an action

Configure an action by using the settings described in the following table, and optionally the following sections:

• Display
• Behavior
• Documentation
• Inputs

Setting	Description
Action name	Displayed name of the action.
For a record of this table	Table to which the action applies.
Do this	Action to be performed. Select an action from the drop-down list. See Action types. Based on the type selected, additional configuration options may be displayed, and are described with the action type descriptions.
Position	Control the position of the action or hide it from the display. Valid values are: Primary - Display independently of scrolling, such as floating buttons on mobile devices and at the top of a view on desktop browsers. Prominent - Display in detail views as a button at the top of the screen (most common). Inline - Display alongside the associated column. Hide - Don't display in any view. The following illustration provides an example of the location of an action based on this setting. Note: For table views, if an action is set to Display inline for a specific column, the action replaces the column content instead of displaying alongside it. If you want to see both the action and the content, you should create another column to attach the action to. For example, attach the action to the Email column so that both the  Name column contents and the action item display in the table row, as shown in the following figure.

 Display

All actions have configurable display options. The display options affect how the view is presented in the navigation bar along the bottom of the app display, and in the app's main menu.

Configure the action display by using the settings defined in the following table.

Setting	Description
Display name	Name displayed for the action. Enter a fixed value (T) or to a text expression (flask). If Display name is not specified or if set to an expression that evaluates to a blank value, the action's name is used.
Action Icon	Icon to be displayed along with the action's Display name (see above). Choose an icon from the predefined list. Custom icons are not allowed. Every action must have an icon. If no icon is selected, a type-specific default will be used.

Behavior

All actions have configurable behavior options that control which rows to display the action and whether or not it requires confirmation before being applied.

Configure the action behavior by using the settings defined in the following table.

Setting	Description
Only if this condition is true	Expression that controls which rows display the action.
Needs confirmation?	Toggle that controls whether or not the action requires confirmation.
Confirmation Message	Confirmation message to display if Needs confirmation? is enabled.

Documentation

Expand the Documentation section and enter a descriptive comment for the action that will enable collaborators to easily understand its purpose.

Inputs

This section is available to the Data: set the value for some columns in this row data-change action only. 

You can add inputs to dynamically configure an action, as follows:

• When the action is used in the app, a dialog displays to prompt the app user to enter values for the specified inputs.
• When this action is invoked from a referenced action (whether in the running app or in an automation), the referenced action can specify a binding expression using the input values. 
• When the action is used in the Run a data action step type and Set row values is selected, the app creator can set input values when configuring the step.

In the action, use the following expression to access the input values: [_INPUT].[inputname]

Let’s assume we want to ask the app user to provide the notes that will be saved in the Details column. To do so, for the Change Status action, expand the Advanced section and add an input value, such as Notes, with an initial value of n/a. For example:



Then, you can use the input value to set the value of the Details column by using the expression: [_INPUT].[Notes]



When the app user clicks the Change Status button, they will be prompted with a dialog that asks them to provide the details. 

Don't use nested expressions, such as [Amount]+[_INPUT].[Amount]. If you specify a nested expression, the user prompt won't be displayed.

For more information and examples, see Set input values dynamically in data-change actions.

To add inputs that can be used to dynamically configure the action:

1. Expand the Advanced section.
2. Click Add adjacent to the Inputs setting.
3. Enter the name of the input value in the Name field.
4. Select the data type from the Type drop-down.
   Only a subset of data types are supported for inputs.
5. To add an initial value or edit any fields:
   1. Click  to open the Input dialog.
   2. Add a value or expression in the Initial value field. 
      If you don't specify an initial value, then the input value will be required. If an initial value is specified, then the input value is optional.
      Use of [_THIS] or [_INPUT] are not supported in the Initial value field.
   3. Edit other fields, as required.
   4. Click Done.
6. Repeat to add additional input values.

Reorder actions in your app

Reorder actions in your app. 

Notes: 

• The order of actions in the app editor aren't impacted; only the order of actions in your app.
• Position settings and format rules might impact the visibility of actions.

 To reorder actions in your app:

1. Open the app in the app editor.
2. Go to Actions .
3. Position your cursor over the table name associated with the actions you want to reorder and click .
   The Reorder actions for table dialog displays.
4. Click  to drag an action to a different order.
5. Repeat to reorder other actions.
6. Close the dialog.

Add an action to your favorites

To easily access frequently used actions, add them to your favorites. 

 To add an action to your favorites:

1. Open the app in the app editor.
2. Go to Actions .
3. Position your cursor over the action in the Actions panel and select More > Add to favorites.

Remove an action from your favorites by positioning your cursor over the action in your favorites and clicking x.

Action types

The following summarize actions that can be performed for each type.

• Navigation action types
• Data-change action types
• External communication action types
• Grouped action type

Navigation action types

The navigation action types are listed below.

App: copy this row and edit the copy

Copies the current row and opens it in a form view.

App: edit this row

Enables users to edit a row in the current table.

When editing content on mobile, tablet, or legacy desktop devices, the content is opened in a separate form. 

When editing content using the desktop design, you can customize the editing experience using the Desktop behavior option by selecting one of the following options:

• Edit in place: When editing content, make all fields editable in the currently displayed detail view. 
  Note: At this time, Edit in place isn't honored when the detail view is included in a dashboard view.

  

   

  Consider the following when using Edit in place for the desktop browser:

  • If there are Show_If conditions that take into account the CONTEXT(), the conditions may apply to desktop, or mobile and tablet devices, or both.
  • If you specify a different column order (by using the Column Order setting) in the form and detail views, then the two views have different functional behaviors.

• Open a form: When editing content, edit it in a separate form. This is the default setting.
  
  

App: export this view to a CSV file

Downloads the rows in the current view to a CSV file. This action only works on desktop browsers and not in iOS or Android apps.

Options:

• CSV file locale: Locale of the exported CSV file.

See the following sample templates:

• Export CSV
• Export CSV of filtered rows

To send CSV files in an email, see Use CSV templates.

App: go to another AppSheet app

Opens a different AppSheet app.

Options:

• Target: App deep link to navigate to when the action is triggered. This can be an expression to compute the value at the time the action is triggered. This uses the same structure as the app column type.

App: go to another view within this app

Navigates to another view in the current app.

Options:

• Target: View deep link to navigate to when the action is triggered. This can be an expression to compute the value at the time the action is triggered. This uses the same structure as the app column type.

App: import a CSV file for this view

Uploads the rows in a CSV file to the current view as described in Import a CSV file for this view.

App: open a form to add a new row to this table

Opens a form that enables users to add a new row to the current table.

Data-change action types

The data-change action types are described below.

Data: delete this row

Deletes the current row.

Data: execute an action on a set of rows

This bulk action option is an expression based version of bulk select. This automated version selects the rows using an expression rather than a user, such as yourself, selecting the bulk actions using your applications user interface. 

Options:

• Referenced Table: Table whose action will be executed.
• Referenced Rows: Rows to act on from the referenced table.
• Referenced Action: Action to apply to the referenced rows.

See also: SELECT()

Data: set the value of some columns in this row

With this action type, you can set or update the value of a field on the current row.

Options:

• Set these columns: Columns and values to be updated when the action is triggered. You can specify an expression to compute the value that will be run at the time the action is triggered.
• Inputs (under Advanced): Input values that can be set by the action. See Advanced configuration.

Common uses:

• Marking a task as complete
• Updating a ticket priority
• Assigning a record to someone
• Adding or subtracting a number
• Setting a date or time to the current time
• Setting a Lat/Long column to HERE()

You cannot set the value of a column that:

• is the key column
• Contains an App formula
• Is a ChangeCounter, ChangeLocation, or ChangeTimeStamp column

Check out the Maintenance Overview app for an example.

Data: add a new row to another table by using values from this row 

 By creating a new action and specifying which separate table data should be added to and defining each column added, rows of data can quickly be updated and moved across all tables in your application.

Options:

• Table to add to: Select the table you want to add the new row to.
• Set these columns: Values for the columns.

The action setup shown below produces the effect of copying the Email and Course values from the current row of the student table, and using the TODAY() and TIMENOW() expressions, to log the Email, Course, current date and time as a new row in the attendance table:

External action types

The external action types are described below.

External: go to a website

Navigate to a URL of your choosing.

Options:

• Target: URL to navigate to when the action is triggered. This can be an expression to compute the URL that will be run at the time the action is triggered.
• Launch External: Enable to launch the web site in the device's browser and not directly in the app.

Common use case:

• Google searching a value from the row: CONCATENATE("https://google.com/search?q=", [Search Column Name])

External: open a file

Opens a viewer for a file on the device running the AppSheet app.

Options:

• To: File to open. This can be an expression to compute the value at the time the action is triggered.

External: start an email

Opens the email app on the device running the AppSheet app. For an example, see Click to send email.

Options:

• To: Recipient of the email. This can be an expression to compute the value at the time the action is triggered.
• Subject: Subject of the email. This can be an expression to compute the value at the time the action is triggered.
• Body: Body of the email.

External: start a phone call

Opens the phone app on the device running the AppSheet app. For an example, see Click to send email.

Options:

• To: Recipient of the phone call. This can be an expression to compute the value at the time the action is triggered.

External: start a text message

Opens the messaging app on the device running the AppSheet app. For an example, see Click to send email.

Options:

• To: Recipient of the message. This can be an expression to compute the value at the time the action is triggered.
• Message: Message to send. This can be an expression to compute the value at the time the action is triggered.

Grouped action type

The grouped action type is described below.

Grouped: execute a sequence of actions

Run a set of actions, one-by-one, in order. This can be used to do multiple things when an action button is pressed.

Options:

• Actions: Actions to run, in order of execution.

For an example,  see the Go to Resource action in the Resource Portal sample template.