The Workflow Step Framework

The Gravity Flow Workflow Step Framework allows developers to add new step types quickly and with minimum effort.

The Gravity_Flow_Step abstract class is used as the base class to create new step types. Extend this class to add custom step types to the workflow step settings.

As a general design pattern:

  • Workflow steps don't communicate with other steps and they don't control the flow of the process by triggering the end or the start of (other) steps.
  • Try to avoid depending on other steps and allow the Workflow Orchestration API to handle the flow.
  • While the Gravity Forms add-on framework architecture is well supported, and a big part of how Gravity Flow itself is built, custom steps do not need to an add-on or feed to extend from. The Gravity_Flow_Step class should be sufficient for most custom step types to extend from.

A simple step.

Here's an example of a step in its simplest form that will perform a custom process when the step is reached in the workflow.

/**
 * Wait until Gravity Flow is ready before declaring the step class.
 */
add_action( 'gravityflow_loaded', function(){
    class Gravity_Flow_Step_Simple_Process extends Gravity_Flow_Step {
    	// Make this unique
        public $_step_type = 'simple_process';
	
	/**
	* Returns the label for the step type.
	*
	* @return string
	*/
        public function get_label() {
            return 'My Custom Step';
        }

        /**
        * Process the step. 
	* 
        * @return bool Is the step complete?
        */
        public function process(){
        	// Do something here.
        }
    }
    // Register the step
    Gravity_Flow_Steps::register( new Gravity_Flow_Step_Simple_Process() );
});

This will add a new step type in the workflow step setting page like this:

Notice that, although we didn't add any settings, some setting appear automatically. That's because the settings you see here are applicable to all steps and can't be removed. So all steps can be scheduled, all steps can have conditional logic, and all steps will have at least one Next Step setting.

The most important function is process(). This function will be called automatically when the step is reached in the workflow so this is the place to put your custom logic.

Adding settings to the step

Settings can be added to step with the  Gravity Forms Add-On Framework Settings API. In the case of step settings, you just need to return a section of settings. For example:

public function get_settings() {
			return array(
				'title'  => 'My Custom Step',
				'fields' => array(
					array(
						'name'     => 'custom_setting',
						'required' => true,
						'label'    => 'Custom Setting',
						'type'     => 'text',
					),
				),
			);
		}

When you add the above code to the simple step class it will render a settings section that looks like this:

Values of the settings can be accessed like this: $this->setting_name where $this is your step class. For example, to use the setting created above you can do this:

/**
* Process the step.
 *
* @return bool Is the step complete?
*/
public function process(){
	// Do something here.
	var_dump( 'Setting: ' . $this->custom_setting );
}

Ready to start developing your own custom step?

  • Look within the gravityflow plugin for the includes/steps folder. Any file that starts with class-step is a step that you could look to the source code for some inspiration.
  • The GF library is a collection of code snippets that help modify the default behavior with each being a standalone file as a separate plugin. It already includes multiple custom steps (such as restart the current step for a different form entry) which may provide a smaller scope practical example.