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 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 settings 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. 

Define your own settings

In the case of custom 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:

Adding editable fields to interactive steps

As of Gravity Flow 2.9, if your custom step needs to let assignees edit specific fields, adding the Edtiable_Fields trait to the class will connect all the relevant functions to allow editable fields to be defined and handled on your custom step.

/**
 * 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 {

    	// Add this trait
    	use Editable_Fields;

    	// Make this unique
        public $_step_type = 'simple_process';

    	// Rest of class definition as in example above.
  }
    // Register the step
    Gravity_Flow_Steps::register( new Gravity_Flow_Step_Simple_Process() );
});

Your step settings will also need to have the standard assignee field settings

public function get_settings() {
	$settings_api = $this->get_common_settings_api();
	return array(
		'title'  => 'My Custom Step',
		'fields' => array(
			$settings_api->get_setting_assignee_type(),
			$settings_api->get_setting_assignees(),
			$settings_api->get_setting_assignee_routing(),
			array(
				'name'       => 'custom_setting',
				'required'  => true,
				'label'         => 'Custom Setting',
				'type'          => 'text',
			),
		),
	);
}

The editable fields setting would then get added after the assignees field depending on if the configurator has selected the assignee type of 'Select' or 'Conditional Routing'

Accessing step settings

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.