Custom actions are the bread and butter of rules. When you create a custom action in the rules ACP, it immediately does two things.
- Custom actions can be triggered or scheduled like any other action from the "Actions" tab in existing rules.
- New rules can be created which use the custom action as the event for which they are triggered.
Therefore custom actions make it possible to build entirely new "processing routines" of rules which can be invoked as a single action. In effect, you decide WHEN the custom action should be taken using a rule, and then you also get to choose WHAT HAPPENS when the custom action is taken using more rules.
Creating A New Custom Action
To create a custom action, visit the "Custom Actions" link under the [ System -> Rules ] section of your ACP. Click the "Create New" button to create a new custom action. You will need to give your custom action a name and an optional description. The name and description can always be updated in the future once you have worked out all the details of what your custom action actually does.
As soon as your custom action has been created, it is available to add in the "Actions" tab of existing rules, and is also available as an event to create new rules for. However, you will usually want to create an event argument or two which will allow you to pass variable data to your custom action. In order to add a new argument for your custom action; After it has been created, click the "plus" icon in the control strip of the custom action in the ACP titled "Add Action Argument".
- Argument Name: This is the name for the argument that will be used in rules configuration forms
- Description: A short description of what the data should represent
- Argument Type: The type of data that should be supplied for the argument
- Value Type: If you have selected "object" or "array" as the argument type, then you may choose a type of object(s) that should be provided
- Required: Indicate whether your custom action will require this data to actually do its job
Using A Custom Action
Once you have set up a custom action and any arguments that it will need, you can begin creating rules which will determine what actually happens when the action is taken. There will be a new event available for your custom action in the events list when you create a new rule; which is what you will use to program the functionality for your custom action. You can create as many rules, rule groups, and/or rule sets as is necessary to complete the purpose of your custom action.
In order to invoke your custom action, simply add it to the "Actions" tab of any existing rule for which you want the custom action to be taken.