On this page

The Automated Actions tab

Supercharge your app with App Builder's automated Actions. Changing values, sending emails or update other App records when your defined conditions are true. Power are given back to instant app developers to alter app records even though they don't have access to the backend.

App developers may set up one or many conditions for an action and use AND or OR logic to aggregate those conditions. Action is only executed when the aggregated result is True. Condition starts with an input, a value and an operator to compare the input with the value

Condition Input

Condition input can be an event such as when record is created/updated, a record's property, a record's subapp's property, a record's property's value stored in the database or a temporary variable. Here are all the condition inputs:

  • {{record}}: use this to compare when the record is {{created}} / {{updated}} or {{posted}} (both cases)
  • {{poster}}: the user updating the record, may compare with {{creator}} (the user first created the record) or {{supervisor}} (staff who can manage the record)
  • $: a special variable which can be used to set temporary value, use $ when assigning a value and {{$$}} when accessing its value.
  • Record property (e.g: name, status): all record's properties can be used as the input. The input's value (which is submitted when the record is saved) will be used to compare with the specified condition value.
  • Record property's previous value (e.g: _previous.status): the value which is stored in the database for a record's property will be used to compare with the specified condition value.
  • Subapp's property (e.g: comment.name): the subapp's input value (which is submitted when the record is saved) will be used to compare with the specified condition value.

Condition Value

Condition value can be a number, a string, property's value ( {{$property_name}} ) or a dynamic placeholder (e.g: {{placeholder}} ) which will be changed to a value during the comparison process. Here are all the dynamic placeholder:

  • {{created}}: true when {{record}} is created only
  • {{updated}}: true when {{record}} is updated only
  • {{posted}}: true when {{record}} is either created/updated
  • {{empty}}: true when input is empty, null or zero (like PHP's empty() function)
  • {{creator}}: true when the user is the one created the record
  • {{supervisor}}: true when the user is a supervisor who has permissions to manage the record.

Condition Operator

Condition operator is the operator to be used to compare the value of the input with the specified condition value. Here are all supported operators:

  • is/equals: true when the input value is/equals to the condition value
  • not equal: true when the input value does not equal to the condition value
  • is either: true when the input value is one of the condition values separated by comma
  • is neither: true when the input value is not one of the condition values separated by comma
  • greater/less than: true when the input value is greater/less than the condition value (number)
  • greater/less than or equals: true when the input value is greater/less than or equals to the condition value (number)
  • contains: true when the input value contains the condition value (non empty string/number)
  • starts with: true when the input value starts with the condition value (non empty string/number)
  • ends with: true when the input value ends with the condition value (non empty string/number)

Multiple Conditions Evaluation

To evaluate multiple conditions within a combo of conditions and actions, AND or OR logic can be used exclusively (no mixing AND, OR). Using AND requires all conditions are true while using OR just requires one of the conditions is true. By default, AND logic is used but app developers may opt to use OR.

In some situations, several combinations of conditions and actions can be used together by leveraging the temporary variable $. Each combination may change the value of $ to a unique value and the last combination will use $ as the input to compare with the unique value and take actions accordingly. Please note that the system will evaluate all combinations from top to bottom so the last combination always has precedence.

Changing Value Action

When the condition(s) are evaluated to True, the value of the record's properties (e.g: status, name), subapp's properties (e.g: comment.name) and the temporary variable $ can be changed to replace the values submitted by users or to be set if the value if it is not submitted or the user does not have permission to set it (hidden field/property).

The value can be a number, string or dynamic value such as:

  • {{ip}} is the user's IP address
  • {{site.url}} is the URL of the current site
  • {{system.url}} is the URL of the system
  • {{timestamp}} is the timestamp when the action is executed
  • {{$property_name}} is the current value of the property (just submitted)
  • {{$_previous.property_name}} is the value of the property stored in the database
  • {{$_public.property_name}} is the value previously calculated by the automation and stored in the database. Values for the target _public.property_name can be saved by the automation even when the user does not have permissions to update the main page.
  • {{$subapp.property_name}} is the current value of the subapp property (just submitted)
  • {{$parent__id}}, {{$parent__name}}, {{$parent__slug}}, {{$parent__type}}, {{$parent__subtype}}, {{$parent__creator}} can be used when creating a subapp record via the main app (app linking). They are not available when creating app/subapp record directly.
  • {{$$}} is the value of the temporary variable
  • {{$var1+$var2}} is replaced by the value of $var1 + $var2
  • {{$var1-$var2}} is replaced by the value of $var1 - $var2
  • {{$var1*$var2}} is replaced by the value of $var1 * $var2
  • {{$var1/$var2}} is replaced by the value of $var1 / $var2. Can also use {{$var1/$var2, n}} to round the value to 'n' decimal digits, the rounding also applies to other arithmetic calculations.
  • {{$var1 & $var2}} concatenates the values of $var1 and $var2
  • For the expressions above, $var can also be a constant (e.g: 99) or any variable starting with $ (e.g: $_previous.sum, $_public.view, $comment.rating).

This action is a pre-action which is executed before the data is saved to the database. As it is a pre-action, at the time it is executed for a new record, the record is not yet created and the record ID is not available. However, the record ID {{$id}} can be set as a value for a subapp's property because subapp data is processed after the record is created. If there are other actions in the same rule, those actions are also executed before the data is saved and the record ID may not be available to them. If the record ID is required, those actions should be moved to another rule that does not contain a 'Change Value" action.

Updating Another App Action

App may change the input data for its SubApps using the Change Value action above. It can go further by creating or updating other Apps' record using Update App action, this action is run as the user submitting the record so the success of this action depends on the user's permissions.

The target of the action should be set to App (including instant, remote and standard app) and the first param should be the app name (App ID). The second param should be a property or a subapp's property of the App to be updated and the third param is the value of that property. This value can be a number, string or a dynamic value (like the values for the Change Value action above). Use the next param inputs (4th/5th, 6th/7th, ...) to add more property/value pairs. If the property "id" is not specified, a new record will be created, to update an existing record, the "id" needs to be specified and valid (can be retrieved using dynamic value)

Notifying Staff Action

After the input data is saved to the database and the condition(s) are evaluated to True, the system can use the Notify Staff action to let targeted staff know of the record by showing a popup link at the staff dashboard. The target for the action may be set to the following:

  • {{creator}}: notify the staff who created/owns the record
  • {{supervisor}}: notify all staff having permission to manage the record
  • an app's custom property (e.g: assignee). The value of this property will be evaluated, if it is a
    • Staff ID, array of Staff IDs: notify the staff specified by the ID(s)
    • permission: notify all staff having the permission

You may specify the notification category e.g: New Task as the first parameter of the action.

Showing Message Action

You may enter a message into the target input to show it on the screen. 

Sending Email Action

After the input data is saved to the database and the condition(s) are evaluated to True, the system can send an email to a target using Send Email action. The target may be set to the following:

  • {{creator}}: send email to the user created the record
  • {{supervisor}}: send email to all staff having permission to manage the record
  • an app's custom property (e.g: assignee). The value of this property will be evaluated, if it is a
    • email address: send email to this email address
    • permission: send email to all staff having the permission
    • User/Staff ID, array of User/Staff IDs: send email to the user/staff specified by the ID(s)

There are 2 parameters that need to be specified for the Sending Email action. The first one is the email subject and the second one is the name of the email template (already exist in the email template folder or created using Templates in the builder).

Sending HTTP Request/Web Hook

App may send HTTP POST/GET request to an external website or API endpoint. The target should be a secure HTTPS website/endpoint and the 1st param should be either POST or GET to indicate the request type. The second param should be a field name and the third param is the value of that field. This value can be a number, string or a dynamic value (like the value for the Change Value action above). Use the next param inputs to add more field/value pairs. 

If you wish to use HTTP Header, you may use a field name starting with Header__ and a value (e.g: Header__Authorization will send header Authorization) to send headers with the request.

Trigger Event/Hook point

This action will trigger an event specified in the target field e.g: Account::create. Any hook scripts/apps listens/subscribes to that event will receive the current record data (1st param) and also the previously stored record data (2nd param) to continue to process on their own. No changes can be made to the record data.

Retrieve Value

This is a post-action that is executed after the record has been saved. This action is similar to the Change Value pre-action but it is more simplified, it will retrieve the value from the submitted data or saved data (if not in the submitted data) and assign it as another property of the record. Then you can refer to this property in other actions just like other properties of the record. This will help preparing data to send via HTTP/Webhook easier. 

While this action cannot change the data for the main record, it is able to change/empty the data for SubApp's records as the Automated Post-Actions for the main App are triggered after the main record is stored but before any data for SubApps is saved.

Add To Cart Action

This action will add a product to the shopping cart and show the cart to the user. Use the target input to specify the product's variant ID to add and use the 1st param to set a static/dynamic value associated with the purchase. If the product allows dynamic pricing, a static/dynamic value can be specified using the 2nd param to set the product's price to a desired value. Here is an example of using Add to Cart: a job board allows their users to advertise jobs by paying a listing fee, when an user post a job listing, they will be redirected to make payment for a Listing service (Fulfillment Processor is Listing). An Add to Cart action is utilized in this case to select a Listing service variant and associate the target job ID to the shopping cart. After the payment is made, the Listing processor will be able to locate the Job ID and run necessary steps to list the Job. 

Flatten Array

If a property of the record is a multidimensional array and you want to get a value at the level 3 or 4, you will have to flatten the array into a 1-dimension array before you can retrieve the value. SiteGUI flattens using "__" as the separator between each level, for example: flattening the array $array["level1"]["level2"]["level3"] = 1 will produce the array $array["level1__level2__level3"] = 1. Now if you want to get the value of level3, you may retrieve it using the property level1__level2__level3

UnFlatten

Unflatten is simply the reversal process of Flatten, it can convert a flatten property back to an array property, for example: unflattening the property $page["level1__level2__level3"] will produce/overwrite the property $page["level1"]["level2"]["level3"] with the value of $page["level1__level2__level3"]

Array to JSON

If a property is an array and you want to send the value via the Send HTTP action, you may want to convert it to a JSON string before sending

JSON to Array

You may assign a JSON string to a property and then use this action to convert the JSON string into an array.