Run Actions – Getting Started

The Run Actions add-on needs to be installed and activated to see the features mentioned in this documentation.

The Run Actions processor will take an array of submission data and pass it to the hook indicated in the processor settings. This add-on gives experienced developers a way to execute custom code from the form builder UI.

Adding the Run Action Processor

In the form you want to add a Run Actions processor to, click the Processors tab, and Add Processor

Then select the Run Action processor.

The Run Actions processor will now appear as an available processor under the Processors tab of the form.

Setting Up the Run Action Processor

The Run Action has 3 configurable options:

1. Position

Defines when the processor will run:

• Pre-process: Used for any process that is required to be successful for the submission to be complete.
• Process: Runs after pending entry is created. Provides an opportunity to return errors, after all pre-processing is complete.
• Post-process: Runs before final entry saving is performed and emails are sent. Useful for modifying field values, or adding extra meta data to entry.

2. Type

Choose between an Action or a Filter. If you’re not certain of the difference between them, read more here.

3. Action/Filter

Enter the name of the action or filter that you want to run here. Enter the name of the action or filter.

Actions and filters are also referred to as “hooks.” If you’re unfamilar with hooks, actions and filters, please read this post for a gentle introduction. If you’re not sure where to put the code for your hook, please learn from this article on our blog.

Note: The action or filter must already be present in your code and properly constructed to be functional here. While we love helping you do all the things, support for Run Actions is limited to ensuring that the processor properly calls the action or filter indicated, not that the action or filter itself is properly constructed and present in your code.

Example: Save Form Submission Data To Another Table

In this example, a post-process action “my_text_action” would be configured in the settings. As a result, on sucessful form submissions, we will save one field’s value to user meta:

<?php
add_action( 'my_text_action', 'my_test_function');
function my_test_function( $data ) {
    if( get_current_user_id() ) {
         update_post_meta( get_current_user_id(), 'meta_key_name', strip_tags( $data[ 'field_id_with_meta_value' ] )  );
    }
}

All field values are availble in this array. You could use similar code to send it to a remote API or save it in other tables of your MySQL database.

Example: Triggering An Error

Preprocessors are generally used to validate data. If they return any data, it will be break processing of a form. Here is an example where an error message is conditionally returned, using a preprocessor. If you choose a filter, at the pre-process, you can conditionally return an array representing an error. The “note” key of the array will be displayed above the form and form submission will not complete:

<?php

add_filter( 'my_custom_pre_filter', 'my_custom_pre_filter' );
function my_custom_pre_filter( $data ) {
    if ( 'something' != $data[ 'something' ] ) {
        return array(
            'type' => 'error',
            'note' => __( 'Something is not right', 'my-text-domain' )
        );
        
    }
 
}

Triggering The Processor Conditionally Based On Form Input

Each Run Action processor can be set to execute or not execute based on user input into the form itself, or based on a specific value within the form.

1. In the processor settings, click the Conditions tab.
2. Select Use (execute if) or Don’t Use (do not execute if)
3. Choose the field or system meta to use as a condition, and the value to look for to meet that condition.