Actions are your app logic, defined in literal actions.
Actions can do just about anything you want in your app. You can create an entire workflow by adding Action Events to your action, each handling their own tiny step of the flow.
Before getting there, you'll need to create the action itself. Click Actions in the Builder Bar of your application. This will open the Actions overview of your application.
If you haven't created any actions yet, this view will be empty, so let's get started!
Click + New in the top left corner (the blue button) and a tab will open.
The base settings of an action should look like this:
Turn this setting on to enable the action, allowing it to be used in your application. When turned off, the action will not execute when called upon.
Option to give the action a description/title. This value is used for default values in action buttons, selecting an action in Action events and Callback actions and is shown in the logs when executing the action.
Choose a Model from your application on which the action is executed. It's not required to choose a model, but when doing so, you can add the action as a button in the backoffice. The record in which the action is executed is then made available through the input variable record. After a model has been chosen, it can't be changed again so choose wisely.
This setting determines how the platform executes the action; Background vs. Foreground. By default, Background is checked and allows the platform for more efficient processing. We encourage you to use this whenever possible. Foreground means the application will execute the action immediately but affects the overall performance of your application.
Show notification when executing
This setting only applies to actions scheduled for background processing as they may not immediately start.
Yes: When an action is started and this setting is set to Yes, a notification window will appear in the lower-left corner of the backoffice. This only appears for the user who initiated the action. This window shows who started the action, when it was scheduled for background processing, the status and if it's waiting for other expressions to be calculated before it can continue. In case the action is successfully completed, it says Status: Finished and the window will close after a few seconds. In case the action fails, it says Status: Failed and will stay there until the user dismisses the notification.
Yes and show popup when ready: With Yes and show popup when ready, the user first gets the notification window and then receives a popup notification in the middle of the screen when the action has been completed and needs to be dismissed. Use this action if you want to make sure users in your application are notified when an action is done.
Use with caution though: If an action executes subactions within a loop event and this setting is used, the user may experience enormous amounts of popups leading to a bad user experience.
No: Pretty self-explanatory, but with this setting, the user will not see any notification. Use this when a process consists of multiple actions to minimize the number of notifications, leading to a more calm and clean User interface.
This setting only applies to actions scheduled for background processing as it affects the efficiency in which actions are processed.
Without limits: The default option. We recommend using this whenever you can. When an action is scheduled/executed multiple times, this setting allows the platform to carry out the actions in parallel. This means actions will be processed simultaneously.
Max one at a time: When an action is scheduled/executed multiple times, this setting forces the platform to carry out this action only once at a time, in serial instead parallel. Only use this if it's necessary, it tends to slow down processing.
Max one per record at a time: When an action is scheduled/executed multiple times, this setting forces the platform to execute this action only once per record at a time.
So if an action handles a record more than once, it's done in serial.
If an action handles unique records, it's done in parallel.
Sometimes the Description doesn't say enough about the action or you want to save a note on the action which doesn't affect the action in any way. That's where to use the Help text option for.
An action can have serious consequences, so you may want to reassure the user if they really meant to start the action. With the Confirmation message, you can set a custom message which is shown in a popup when the user initiates the action. They'll have to confirm this by clicking Yes or else the action won't start.
Debug action and events
Building an action and not sure why it's failing? This setting will be your best friend when developing. By turning this checkbox on, you can see the entire flow of your action from start to end in the logs. Go to /#newlogs:f=all (or click on the Logs button in the Builder bar) in your app and you'll see which action was executed at what time and who did it. Each step gets a timestamp so you'll see exactly how the action performs. You can also see what variables are available and what values they hold.
Keep in mind that using this setting affects the performance of your action. Every variable which is actively used will be parsed to the logs. Simple actions with simple variable have little impact. Complex actions with complex variables (like Collection variables and Custom models containing webservice responses) in debug mode can slow down actions up to 100%. After you've completed building your action and everything works as intended, turn it off again. Don't worry, failing actions will still be logged, but only the error itself. Turn it on again and start debugging.
Log execution of action
Similar to Debug action and events but only logs the initiation of the action. This barely affects the performance, so feel free to use this setting if you see use to it.
Additional action settings
When choosing/setting some of the settings described in the category above, extra settings will appear. Below we'll show which settings become available and what they do.
Available after: choosing Model.
Triggers define the starting point of an action; Whether it's after creating a record, manual or at a scheduled time. More information about triggers can be found here!
Available after: choosing Model saving the action.
In this setting, you can determine who'll be able to start the action. An action needs to be started by a user, but that user will need at least one of the roles chosen in this setting. The default role is admin.
Available after: choosing Model.
The Schedule setting is connected to the Scheduled option from the Triggers setting.
When you want to start a process which must be executed automatically according to a scheduled time format. This time format can be set by yourself according to the cronjob format.
Note: Scheduled actions will only be executed in production applications. In sandboxes the action won't be triggered by the cron job. For testing, you can press the green Run button on the action itself.
Available after: choosing Model.
With the Batch setting, an action is enabled for processing multiple records. When viewing a grid based on the chosen model, you'll notice checkboxes at the start of each record and a select box with all batch actions. By choosing records and starting the action, each record will be processed in a separate action/job.
Available after: choosing Batch.
By choosing Batch, the Preserve collection setting appears. Instead of processing each record in separate actions/jobs, the chosen records will be served as a collection variable and the action is only started once.
Available after: saving the action.
A button to run the action manually. This is considered a test button, as it will show [TEST] in the log message if Debug action and events is enabled. It will, however, process real data from your application, so use with caution. Use sandboxes to avoid damaging production data.
Actions consist mainly of action events, where each step of a workflow is defined. In most cases, they need some kind of data to process, or nothing much will happen. That's where Variables come in.
In the general settings of your action, you'll have 2 kinds of variables; Variables and Input variables. Let's start with the latter, as it's more important in most cases.
Input variables are values that can be passed along manually by the user or when calling the action as a subaction. When saving the action after a Model is chosen, an input variable is automatically added, called record. This variable contains the record from which the action is initiated.
You can also add more input variables from the following types:
- Collection (custom model)
- Custom model
- Date time
- Number with decimal
Some actions may require certain values to successfully complete. To make sure those values are available when executing the action, make the input variables required by checking the Required checkbox. If one of the required variables hasn't been set, the action will throw an error.
Aside from values that need to be entered manually, you can also let the platform calculate or determine certain values. That's where Variables are used for. By picking the correct type for the value you need, combined with our Expressions functionality, you can create the exact variable you need.
You can create the following variables in an action:
- Checkbox expression
- Date expression
- Date time
- Date time expression
- Filtered collection
- Number expression
- Number with decimal
- Number with decimal expression
- Regex expression
- Text expression
- Url expression
Both Variables and Input variables will be available throughout the entire action and keep the value it has when the action started. If you want to make the variable available in a specific part of the action, define the variable in the action event.
To create the most efficient construction for your workflow, we recommend dividing parts of the process in separate actions. With Callback actions, this is made possible.
For example, you execute a loop event with a subaction for each iteration. These subactions are scheduled for background processing, but you want to run a 'roundup' action after every iteration is completed. Because Callback actions only start running after every previous background job is completed, they make a perfect fit.
Feel free to use them in sequence! This way you can chain multiple actions to one big workflow and still maintain excellent performance.
Check the Enable callback action checkbox and you'll be given the option to select an existing action or stick to - New - and the platform will create a new one for you.
Should you choose an existing action with Input variables, you can assign variables from the action to the input variables on the callback action. Only variables that are defined on the action itself will be available for assignment. Callback actions will be executed, even if the previous action fails so keep that in mind when designing your workflow. More information about Callback actions can be found here!
As your actions are a part of your application, they are connected to different parts and components within the application! Some connections are more important than others and removing them can have huge consequences.
At first, you'll see how many Dependencies the action has. To see the details about these dependencies, click on the number and a table will show.
As seen in the image above, the table has 3 columns: Name, Kind and Action when Destroyed.
Name: This column described the exact part which is related to the action. If a dependency points towards a component which can be viewed on its own, click the name to open the component in a new browser window.
Kind: Shows what kind of dependency we're dealing with.
Action when destroyed: Should you choose to destroy the Action, this is what happens to the dependency.
That's about everything you could come across in the action settings! In case you have any questions or remarks about one of the settings described above: we love your feedback!