The Action Button data type creates a button that contains a chain of actions that are activated when the button is clicked. Action buttons can be designed to perform an endless number of possible functions: because they can run almost any of the standard action types, you can use action buttons to send emails, update fields, update linked records, print documents from a template, or all of those sequentially.
See Actions for more information on the available action types.
These are just some examples of how action buttons can be applied:
- Activate document conversion to MS Word format on an attached file field containing PDFs.
- Create contract approvals. This can include a complex set of If-Then-Else action conditions that embed several conditional actions.
- Convert a ticket into a service request using a Data Conversion action.
- Create Adobe Sign or DocuSign envelopes for electronic signature.
It's often a good idea to use a "Button:" prefix when labeling action buttons. This makes it clear which fields are buttons when managing layouts. It also groups all the buttons next to one another on the Fields tab of the Table wizard, which helps to organize your fields.
- In the General tab of the setup, define the system behavior before executing the action.
- Make sure the Execute Actions check box is selected, and click Add Action.
- The Actions library opens, with the create action buttons at the top, and the list of available actions for the table displayed at the bottom. This is the same as the Actions tab in the Table wizard.
- If you want to create a new action, click the relevant button and walk through the setup for that action type.
Otherwise, select one or more actions from the list and click Finish to add them to the action button.
If you select multiple actions, they will be added in alphabetical order.
- In the And drop-down, define any additional options, and specify the system behavior after executing the actions.
Add Wait Point
The Add Wait Point button is used to force the system to wait for the preceding action(s) to complete before running the next action or moving to the final step defined in the "After executing actions" section. Wait points are automatically added after the last action in the list, but they can be placed after any of the actions in the button sequence by dragging the wait point to the desired location.
Wait points are useful if, for example, one of the actions brings up a new window for a manual conversion or runs actions on records in a related table that should be reflected in the table record before proceeding. If you add wait points, you can also define the time limit in seconds to wait before the next action runs. With multiple wait points, they all use the same time limit.
Action Button Display
In the General tab of the action button setup, you can define how the action button should be displayed. This will appear in both the record form and the table view. Action buttons in the action bar will always be displayed as plain text links.
The options are:
- Button with text - This shows a button labeled with the text you enter. This style can be configured in the Form Action Buttons settings of the Forms tab of the look and feel scheme.
- Image hyperlink - This replaces the button with an uploaded image. These images are the same ones available in the Graphics tab of the Table wizard. You can use a new image by clicking Select/manage > Upload.
- Text hyperlink - This displays a text hyperlink using the text you enter. Sometimes using a text hyperlink can be useful to align the action button with other fields, save space, or better match the style of the form.
In the Display tab, you can also define whether the button should have a description and whether it should display a label. If you do not wish to use a visible label apart from the button text, select "When viewing this field, show Neither the label nor the instruction".
The label and instructions are often not needed for action buttons, since the button text should give enough information on what will happen upon pressing. The exception to this is if you are using an image hyperlink for the button.
Action buttons can be placed in the following areas of the system:
- On the record layout, where the actions will affect the current record. They can be activated in either view or edit mode of the record.
- In Table Views, where action buttons will affect the record they are linked to.
- In the table action bar, where they will appear as hyperlinks. These actions will affect all selected records in the table view.
Because of the complexity of the possible starting points, it is important to test every method by which the button can be pressed and to take that into account when deciding whether the action button saves the record before and/or after executing the actions.
If you are executing the actions from any context other than record edit, there is no need to save before executing the actions. Even if the field option says that it should save before executing, it will not save the record. Likewise, there is no need to save afterwards, unless you want to open the record after running the actions.
Order of Operations
In the General tab of the action button setup, you can define the order of operations of how actions should run, and what operations should be done before and after the actions. This is important to understand, because triggering operations out of order can cause unintended consequences such as rules running on linked records before the record updates are complete.
Record Saving when Running Actions
Before and after running the actions, you can choose whether to save the record, with some further options on the record behavior when saving.
Saving Before Actions
If the action button will be clicked while the record is being edited, some changes made in the current editing session will only be available to the actions in the action button if the record is saved before executing the actions. Most field changes are stored in system memory and can be used by actions without saving first, but some data types are not. You should test the behavior of the button before committing to the order of operation here.
Saving After Actions
The options in the "After executing actions" section also allow you to save the record, with some choices for what to do when the record is saved.
If the action button is making changes to the record during the editing process, it is best to save afterwards and confirm that any changes made by the button are saved to the record regardless of the user's permissions or whether they decide to cancel or save the record further down the line.
You can choose whether the save should close the record, open it again in edit mode, or open it in view mode.
- If you save it and open it again, you can also define which record tab it should open to for staff and end users. This can be helpful to guide the record workflow for users, in cases where the record has a large number of tabs.
- If saving and opening it for editing, you can choose whether to validate required fields. If you deselect this option, it will act similarly to an autosave. For more information on these options, see the section below.
In other cases, you can keep the record open and trust the user to save the record. If you choose the Do Nothing option, the screen stays the same for the user; you can also use the option to "Navigate within the same record to a specified tab and position" to lead the user to the next part of the form they need to complete.
Validate Required Fields and Run Rules
By default, record saving will trigger the following operations:
- The system will check to make sure that all mandatory fields have a valid entry.
- Any rules that have a condition of being applied when the record is edited, and "Run rules" enabled, will be triggered.
- The record default values such as Date Modified will be updated.
In the action button, you can disable these operations by deselecting the "Validate required fields" and "Run rules and update default values" check boxes.
These options can be useful in cases where for instance a record contains a large number of tabs, and a user wishes to use an action button to save the current state and send something forward before the final tab, while still continuing to work on it.
In the After Executing Actions section, the "Validate required fields" option is only available when choosing to "Save and Open record for edit." This is in order to prevent the record being closed in a state where mandatory fields have not been filled in. By default, both options are selected for existing action buttons where the "Save record" option is selected.
Exercise caution when deselecting these options as there is a possibility for records to be canceled in the middle of being created, placed in a state where mandatory fields are incomplete, or prevented from being acted upon by normal table rules.
Aside from the available action types, there are a number of options that can be selected by clicking the And drop-down menu after the actions.
- Running an ActiveX script
- Opening a URL
- Making a Skype call
- Adding a Note
- Opening the Working with Email wizard to create an email
- Sending a PayPal payment
In the rest of the wizard, the Options, Permissions, and Display settings are the same as those on other action types. However, there is one unique permission on the Permissions tab.
Open a URL
If you select Open a URL, it will be opened at the specified URL and may include variables from the record. If the action button opens a script in a window with a URL that is defined by a Script action, the last script in the list of execute actions could use
to define what this URL should be.
If you enter the URL manually, the URL must use special syntax and, in some cases, a formula.
- If you want to open a static URL, enter your URL enclosed in double quotes, such as "http://www.agiloft.com" or "http://www.customurl.com."
- If you want to open a URL where the main address depends on some record data, concatenate the parts of the URL by enclosing the static parts in double quotes and placing plus signs in front of field or variable names that are prefixed by a "$" sign. For example, if your record contains a field named “company,” you could specify a URL like "http://www." + $company + ".com" to go to the company site. Note that you should not use
urlEncode()in this case, which is discussed next.
- If you want to open a URL where parameters that occur after the main address depend on record data, concatenate the parts of the URL by enclosing the static parts in double quotes and enclosing the field or variable names in
urlEncode(), placing "$" signs in front of the field or variable names and plus signs between the different parts of the URL.
- Such URL parameters are easy to identify because they come after an equals (=) sign. For example, if you have a URL such as "http://www.agiloft.com?login=myLogin&password=myPassword," then "login" and "password" are URL parameters, with "myLogin" and "myPassword" being the parameter values.
To compose a URL where parameters occur after the main address and use fields from the current record, you could use a URL like "http://www.agiloft.com?login=" + urlEncode($myLogin) + "&password=" + urlEncode($myPassword).
Note on urlEncode()
Every web server detects parameters and their values in a URL string by locating "?," "&," and "=" characters. That means that a URL parameter value should not itself contain any of these characters, otherwise the web server will not be able to recognize the correct parameter value. To avoid this confusion, each parameter that uses a field variable with "$" should be URL-encoded so that dangerous characters in each parameter value are replaced with "safe" character sequences. The server will understand these sequences and convert them back to source characters when reading the parameters string.
If you add variables through the Formula wizard, variables are added with
urlEncode()function for you. You should always use this function if you are using the variable or field in the parameter part of a URL, such as "www.b2b.com?param=" + urlEncode($field). You should not use this function when your field or variable is used in the main address part of the URL, such as " ." + $company + ".com."
Action Button Permissions
Action buttons have admin-level permissions by default, and will operate independently of a user's permissions.
- If the user does not have permission to change the Status button, they could still press the Cancel button and change the contract status to Cancelled.
- If the user does not have permission to access a different table in the knowledgebase, they could still trigger record changes in that table through a linked field action.
- An email action could be embedded in a rule with a save condition, which would automate email sending even if the user could not access emails on the table.
This makes it important to control who has view access to an action button field, and at what stage in the record workflow it should appear. If a user can view the button, they can activate it with a few exceptions, as discussed below. The button cannot be edited, so it is not necessary to control edit permissions.
Visibility dependencies are often used with action buttons to control when they can be pressed. These dependencies persist in table views, so if the record is not in a state where the button should appear, or if the user does not have view permission, it will not appear in a view even if it is added.
View permissions for action buttons apply to both the record form and the table view, but they have a caveat when placed on the table view. If users have permission to view an action button and it's placed on the table view, it will appear for every record, even if the user doesn't have permission to edit that record. If a user clicks an action button from the table view for a record they don't have permission to edit, the action won't run and the user will receive an error message.
You can change this behavior by setting the Always Show Action Button in Views global variable to No. This forces the system to evaluate users' permissions and only display action buttons on the table view for records that they also have permission to edit. However, this may impact system performance if you have many records or complex permissions.
The Permissions tab of the Action Button wizard contains a unique setting at the bottom, aside from the normal field permissions.
This allows a group to see and therefore execute an action button on a record if they only have view access to it. If this is active for a group, the user does not need to have edit permissions or record ownership/record creator status.