Gravity_Flow_Step

Introduction

The Gravity_Flow_Step class is a base class that each step type will extend/override such as the Approval, User Input and Notification step types. It is located in /includes/steps/class-step.php

Override Methods

Methods defined in this section are commonly ones which a specific step type will override. The bare minimum which must be overriden are get_label and process along with defining the public $_step_type. Refer to The Workflow Step Framework for more details.

entry_detail_status_box

Displays content inside the Workflow metabox on the Gravity Forms Entry Detail page.

Source Code

public function entry_detail_status_box( $form ) { }

Parameters

ParameterTypeDescription
$formFormThe current form

Returns

None

Example

The approval step overrides this method to display the step name, status, assignees and their status.

public function entry_detail_status_box( $form ) {
		$status = $this->evaluate_status();
		?>

		<h4 style="padding:10px;"><?php echo $this->get_name() . ': ' . $status; ?></h4>

		<div style="padding:10px;">
			<ul>
				<?php
				$assignees = $this->get_assignees();
				foreach ( $assignees as $assignee ) {
					$assignee_status_label = $assignee->get_status_label();
					$assignee_status_li    = sprintf( '<li>%s</li>', $assignee_status_label );

					echo $assignee_status_li;
				}

				?>
			</ul>
		</div>
		<?php

	}

end

Ends the step cleanly and wraps up loose ends. Sets the next step. Deletes assignee status entry meta.

Source Code

public function end() { }

Parameters

None

Returns

None

Example

The approval step overrides this method to trigger status based notifications.
In most cases, the override should also call the parent::end() function within it.

public function end() {
		$status = $this->evaluate_status();
		$entry  = $this->get_entry();
		if ( $status == 'approved' ) {
			$this->send_approval_notification();
			$this->maybe_perform_post_action( $entry, $this->publish_post_on_approval ? 'publish' : '' );
		} elseif ( $status == 'rejected' ) {
			$this->send_rejection_notification();
			$this->maybe_perform_post_action( $entry, $this->post_action_on_rejection );
		}
		if ( $status == 'approved' || $status == 'rejected' ) {
			GFAPI::send_notifications( $this->get_form(), $entry, 'workflow_approval' );
		}
		parent::end();
}

get_status_config

Returns an array of the configuration of the status options for this step. These options will appear in the step settings. Override this method to add status options.

Source Code

public function get_status_config() {

Parameters

None.

Returns

Array

Example

The outgoing webhook step overrides this method to define how 200/400/500 HTTP response codes associate to step status.

public function get_status_config() {
		return array(
			array(
				'status'                    => 'complete',
				'status_label'              => __( 'Success', 'gravityflow' ),
				'destination_setting_label' => esc_html__( 'Next Step if Success', 'gravityflow' ),
				'default_destination'       => 'next',
			),
			array(
				'status'                    => 'error_client',
				'status_label'              => __( 'Error - Client', 'gravityflow' ),
				'destination_setting_label' => esc_html__( 'Next Step if Client Error', 'gravityflow' ),
				'default_destination'       => 'complete',
			),
			array(
				'status'                    => 'error_server',
				'status_label'              => __( 'Error - Server', 'gravityflow' ),
				'destination_setting_label' => esc_html__( 'Next Step if Server Error', 'gravityflow' ),
				'default_destination'       => 'complete',
			),
			array(
				'status'                    => 'error',
				'status_label'              => __( 'Error - Other', 'gravityflow' ),
				'destination_setting_label' => esc_html__( 'Next step if Other Error', 'gravityflow' ),
				'default_destination'       => 'complete',
			),
		);
	}

get_actions

Returns an array of quick actions to be displayed on the inbox. The default return is an empty array.

Source Code

public function get_actions() {

Parameters

None

Returns

Array

Example

The approval step overrides the get_actions method to provide Approve and Reject actions.

public function get_actions() {
		return array(
			array(
				'key'             => 'approve',
				'label'           => __( 'Approve', 'gravityflow' ),
				'icon'            => $this->get_approve_icon(),
				'show_note_field' => in_array( $this->note_mode, array(
						'required_if_approved',
						'required_if_reverted_or_rejected',
						'required',
					)
				),
			),
			array(
				'key'             => 'reject',
				'label'           => __( 'Reject', 'gravityflow' ),
				'icon'            => $this->get_reject_icon(),
				'show_note_field' => in_array( $this->note_mode, array(
						'required_if_rejected',
						'required_if_reverted_or_rejected',
						'required',
					)
				),

			),
		);
	}

get_label

Returns the label for the step. Override this method to return a custom label.

Source Code

public function get_label() { }

Parameters

None.

Returns

String

Example

The outgoing webhook step overrides this method to return an escaped label ‘Outgoing Webhook’ that can be translated.

public function get_label() {
		return esc_html__( 'Outgoing Webhook', 'gravityflow' );
	}

get_icon_url

Override this method to set a custom icon in the step settings. The default size is 32px x 32px.

The

Source Code

public function get_icon_url() { }

Parameters

None

Returns

String

Example

The notification step type returns html markup which will present a font-awesome icon.

public function get_icon_url() {
		return '<i class="fa fa-envelope-o"></i>';
	}

get_settings

Override this method to add settings to the step. Use the Gravity Forms Add-On Framework Settings API.

Source Code

public function get_settings( ) { }

Parameters

None

Returns

Array

Example

This example shows how the Gravity_Flow_Step_Feed_Add_On step type provides settings based on the feed type it is associated with.

public function get_settings() {
		if ( ! $this->is_supported() ) {
			return array();
		}

		return array(
			'title'  => $this->get_label(),
			'fields' => array( $this->get_feeds_setting() ),
		);
	}

is_complete

Override this method to check whether the step is complete in interactive and long running steps.

Source Code

public function is_complete() {
		$status = $this->evaluate_status();

		return $status == 'complete' || $status == 'expired';
}

Parameters

None

Returns

Boolean

Example

This example shows how the outgoing webhook step uses its’ evaluate_status function to determine if the step is complete or not in comparison to ongoing statuses of pending or queued.

public function is_complete() {
		$status = $this->evaluate_status();

		return ! in_array( $status, array( 'pending', 'queued' ) );
	}

maybe_filter_validation_result

Override this to implement a custom filter for this steps validation result.

Source Code

public function maybe_filter_validation_result( $validation_result, $new_status ) {
		return $validation_result;
}

Parameters

ParameterTypeDescription
$validation_resultArrayThe validation result and form currently being processed.
$new_statusStringThe new status for the current step.

Returns

Array

Example

The Approval step type overrides this method to include a filter specific to its’ step type gravityflow_validation_approval

public function maybe_filter_validation_result( $validation_result, $new_status ) {
		return apply_filters( 'gravityflow_validation_approval', $validation_result, $this );
	}

maybe_process_status_update

Handles POSTed values from the workflow detail page.

Source Code

public function maybe_process_status_update( $form, $entry ) {
		return false;
	}

Parameters

ParameterTypeDescription
$formFormThe current form.
$entryEntryThe current entry.

Returns

String / Boolean / WP_Error

Examples

maybe_process_token_action

Process token action if conditions are satisfied.

Source Code

	public function maybe_process_token_action( $action, $token, $form, $entry ) {
		$step_id = rgars( $token, 'scopes/step_id' );
		if ( empty( $step_id ) ) {
			$feedback = new WP_Error( '', esc_html__( 'Error: This URL is no longer valid.', 'gravityflow' ) );
			return $feedback;
		}

		if ( $step_id != $this->get_id() ) {
			$non_current_step = gravity_flow()->get_step( $step_id, $entry );
			if ( $non_current_step && $non_current_step->processed_step_messageEnable ) {
				$feedback = new WP_Error( 'step_already_processed', $non_current_step->processed_step_messageValue );
			} else {
				$feedback = new WP_Error( 'step_already_processed', esc_html__( 'This step has already been processed.', 'gravityflow' ) );
			}
			return $feedback;
		}

		return false;
	}

Parameters

ParameterTypeDescription
$actionArrayThe action properties.
$tokenArrayThe assignee token properties.
$formFormThe current form.
$entryEntryThe current entry.

Returns

Boolean or WP_Error

Example

The Approval step type overrides this method to potentially handle one-click links and provide the gravityflow_feedback_approval_token filter that allows the user feedback to be modified after processing the token action.

process

Process the step which is the core activity which the step is designed for.
For example, assign to a user, send to a service, send a notification or trigger a feed for completion.

Source Code

public function process() {
	return true;
}

Parameters

None

Returns

Boolean

Examples

The outgoing webhook step triggers its send_webhook function.

The approval and user input step types trigger their assign functions to determine assignees for their interactive steps.

process_assignee_status

Process a status change for an assignee.

Source Code

public function process_assignee_status( $assignee, $new_status, $form ) {
	$assignee->update_status( $new_status );
	$note = $this->get_name() . ': ' . esc_html__( 'Processed', 'gravityflow' );
	$this->add_note( $note );

	return $note;
}

Parameters

ParameterTypeDescription
$assigneeAssigneeThe assignee properties.
$new_statusStringThe assignee status.
$formFormThe current form.

Returns

String or Boolean – Return a success feedback message safe for page output or false.

Example

The User Input step type overrides this method to handle complete vs in progress statuses and providing the gravityflow_feedback_message_user_input filter before adding a note to the timeline based on assignee activity. This is then used in its maybe_process_status_update method.

if ( $assignee->is_current_user() ) {
	$feedback = $this->process_assignee_status( $assignee, $new_status, $form );
	 break;
}

rest_callback

Process the REST request for an entry. This is not implemented for the default step type.
i.e. A custom step will have to override this method to identify how the orchestration API should handle a request related to the step type.

Source Code

public function rest_callback( $request ) {
	return new WP_Error( 'not_implemented', __( ' Not implemented', 'gravityflow' ) );
}

Parameters

ParameterTypeDescription
$requestWP_REST_RequestFull data about the request.

Returns

WP_REST_Response or mixed.
– If response generated an error, WP_Error
– If response is already an instance, WP_HTTP_Response
– otherwise returns a new WP_REST_Response instance.

Example

The Approval step type provides a rest callback with approve / reject actions.

status_evaluation

Override this to perform custom evaluation of the step status.

Source Code

public function status_evaluation() {
	return 'complete';
}

Parameters

None

Returns

String

Example

This example shows how the Gravity_Flow_Step_Feed_Add_On step type overrides the method to ensure the step is only complete when all the feeds for this step have been added to the entry meta processed_feeds array.

public function status_evaluation() {
	$add_on_feeds = $this->get_processed_add_on_feeds();
	$feeds        = $this->get_feeds();

	$form  = $this->get_form();
	$entry = $this->get_entry();

	foreach ( $feeds as $feed ) {
		$setting_key = 'feed_' . $feed['id'];
		if ( $this->{$setting_key} && ! in_array( $feed['id'], $add_on_feeds ) && $this->is_feed_condition_met( $feed, $form, $entry ) ) {
			return 'pending';
		}
	}

	return 'complete';
}

validate_status_update

Base method for validating a status update. Override to perform custom validation.

Source Code

public function validate_status_update( $new_status, $form ) {
	return true;
}

Parameters

ParameterTypeDescription
$new_statusStringThe new status for the current step.
$formFormThe form currently being processed.

Returns

Boolean

Example

The User Input step type will override this method and use validate_note and get_validation_result to determine if the status update is valid or not.

public function validate_status_update( $new_status, $form ) {
	$valid = $this->validate_note( $new_status, $form );

	return $this->get_validation_result( $valid, $form, $new_status );
}

validate_note_mode

Override this with the validation logic to determine if the submitted note for this step is valid.

Source Code

public function validate_note_mode( $new_status, $note ) {
	return true;
}

Parameters

ParameterTypeDescription
$new_statusStringThe new status for the current step.
$formStringThe submitted note.

Returns

Boolean

Example

The User Input step type will override this method and determine if the note is valid based on some of its note mode setting options (required, required if in progress, required if complete).

public function validate_note_mode( $new_status, $note ) {
	$note = trim( $note );

	$valid = true;

	switch ( $this->note_mode ) {
		case 'required' :
			if ( empty( $note ) ) {
				$valid = false;
			}
			break;

		case 'required_if_in_progress' :
			if ( $new_status == 'in_progress' && empty( $note ) ) {
				$valid = false;
			};
			break;

		case 'required_if_complete' :
			if ( $new_status == 'complete' && empty( $note ) ) {
				$valid = false;
			};
	}

	$valid = apply_filters( 'gravityflow_note_valid', $valid, $note, $new_status, $this );

	return $valid;
}

workflow_detail_box

Displays content inside the Workflow metabox on the workflow detail page.

Source Code

public function workflow_detail_box( $form, $args ) { }

Parameters

ParameterTypeDescription
$formFormThe current form which may contain validation details.
$argsArrayAdditional args which may affect the display.

Returns

None

Examples

At a minimum, any step that has requires user interaction will display its’ own workflow details box.

  • The Approval step type includes the approve/reject/revert buttons along with assignee statuses.
  • The User Input step type will display the save/submit buttons or radio buttons based on step settings.
  • The Sliced Invoices Feed step type will display sliced invoices including edit/preview links.

Helper Functions

Method NameReturn TypeParameterParameter Type(s)Description
add_noteNone$note
$is_user_event
$deprecated
String
Boolean
Boolean
Adds a note to the timeline. The timeline is a filtered subset of the Gravity Forms Entry notes.
assignBooleanNoneNoneSet the assignee status to pending and trigger sending of the assignee notification if enabled.
assignees_hashStringNoneNoneReturns an MD5 hash of the assignees of the given step plus the assignee policy.
can_set_workflow_statusBooleanNoneNoneReturns TRUE if this step can alter the current and final status. If the only status option available for this step is ‘complete’ then, by default, the step will not set the status. The default final status for the workflow is ‘complete’.
end_if_completeBooleanNoneNoneEnds the step if it’s complete.
evaluate_routing_ruleBoolean$routing_ruleArrayEvaluates a routing rule.
evaluate_statusStringNoneNoneEvaluates the status for the step.
get_assigneeAssignee$argsString or ArrayRetrieve the assignee object for the given arguments.
get_assignee_argsArray$assignee_key$assignee_keyCreates an array containing the assignees id and type from the supplied key.
get_assignee_keysArrayNoneNoneRetrieve an array containing the assignee keys for this step.
get_assigneesArray of AssigneesNoneNoneReturns an array of assignees for this step.
get_base_urlStringNoneNoneReturns the Gravity Flow base URL.
get_common_settings_api
Gravity_Flow_Common_Step_Settings
NoneNoneGet the API for preparing common settings such as those which appear on notification tabs.
get_current_assignee_keyBoolean or StringNoneNoneGet the assignee key for the current access token or user.
get_current_assignee_statusBoolean or StringNoneNoneGet the status for the current assignee.
get_current_role_statusArrayNoneNoneGet the current role and status.
get_due_date_timestampBoolean or IntegerNoneNoneReturns the expiration timestamp calculated from the expiration settings.
get_editable_fieldsArrayNoneNoneOverride to return an array of editable fields for the current user.
get_entryEntry or NullNoneNoneIf set, returns the entry for this step.
get_entry_idIntegerNoneNoneReturns the ID for the current entry object. If not set the lid query arg is returned.
get_entry_metaArray$entry_meta
$form_id
Array
Integer
Optionally override this method to add additional entry meta. See the Gravity Forms Add-On Framework for details on the return array.
get_entry_timestampInteger or StringNoneNoneReturns the value of the entries workflow_timestamp property.
get_entry_urlString$page_id
$assignee
$access_token
Integer or Null
Assignee
String
Returns the entry URL.
get_expiration_status_keyStringNoneNoneReturn the value of the status expiration setting.
get_expiration_timestampBoolean or IntegerNoneNoneReturns the expiration timestamp calculated from the expiration settings.
get_feed_metaArrayNoneNoneRetrieves the feed meta for the current step.
get_formFormNoneNoneReturns the Form object for this step.
get_form_idIntegerNoneNoneReturns the ID of the Form object for the step.
get_idIntegerNoneNoneReturns the Step ID.
get_inbox_urlString$page_id
$assignee
$access_token
Integer or Null
Assignee
String
Returns the inbox URL.
get_nameStringNoneNoneReturns the user-defined name of the step.
get_next_step_idInteger or StringNoneNoneReturns the ID of the next step.
get_notificationArray$typeStringRetrieves the properties for the specified notification type; building an array using the keys required by Gravity Forms.
get_notification_assigneesArray$typeStringRetrieve the assignees for the current notification
get_required_capabilitiesArrayNoneNoneGet required capabilities for the step.
get_rest_baseStringNoneNoneReturns the resource slug for the REST API.
get_role_statusBoolean or String$roleStringReturns the status for the given role.
get_schedule_timestampBoolean or IntegerNoneNoneReturns the schedule timestamp (UTC) calculated from the schedule settings.
get_settingMixed$settingStringReturns the correct value for the step setting for the current context – either step settings or step processing.
get_statusBoolean or StringNoneNoneRetrieves the step status from the entry meta.
get_status_keyString$assignee
$type
String
Boolean or String
Returns the status key
get_status_labelString$statusStringReturns the translated label for a status key.
get_status_timestamp_keyString$assignee_key
$type
String
Boolean or String
Returns the status timestamp key
get_step_settingsArrayNoneNoneGet the settings for the current step. Defaults to empty get_settings() method.
get_step_timestampBoolean or IntegerNoneNoneReturns the step timestamp from the entry meta.
get_timestamp_dateBoolean or Integer$setting_typeStringReturns the timestamp for the date based expiration or schedule or due date.
get_timestamp_date_fieldBoolean or Integer$setting_typeStringReturns the timestamp for the date field based expiration or schedule or due date.
get_timestamp_delayBoolean or Integer$setting_typeStringReturns the timestamp for the delay based expiration or schedule or due date.
get_typeStringNoneNoneReturns the step type.
get_user_statusBoolean or String$user_idInteger or BooleanReturns the status for a user. Defaults to current WordPress user or authenticated email address.
get_validation_resultArray or Boolean or WP_Error$valid
$form
$new_status
Boolean
Form
String
Get the validation result for this step.
get_workflow_url_access_tokenString$atts
$assignee
Array
Assignee
Get the access token for the workflow_entry_ and workflow_inbox_ merge tags.
gpdf_add_notification_attachmentArray$notification
$gpdf_id
Array
String
If Gravity PDF is enabled we’ll generate the appropriate PDF and attach it to the current notification
is_activeBooleanNoneNoneIs the step active? The step may have been deactivated by the user in the list of steps.
is_assigneeBoolean$assignee_keyStringDetermines if the supplied assignee key belongs to one of the steps assignees.
is_condition_metBoolean$formFormProcesses the conditional logic for the entry in this step.
is_expiredBooleanNoneNoneDetermines if the step has expired.
is_overdueBooleanNoneNoneReturns TRUE if this step is past the defined due date.
is_queuedBooleanNoneNoneIs the step currently in the queue waiting for the scheduled start time?
is_supportedBooleanNoneNoneIs this step supported on this server? Override to hide this step in the list of step types if the requirements are not met.
is_user_assigneeBooleanNoneNoneChecks whether the current user is an assignee of this step.
log_debugNone$messageStringLogs debug messages to the Gravity Flow log file generated by the Gravity Forms Logging.
log_eventNone$step_event
$step_status
$duration
String
String
Integer
Add a new event to the activity log.
maybe_add_assigneeNone$argsArray or StringAdds the assignee to the step if certain conditions are met.
maybe_add_routing_assigneesNoneNoneNoneAdds the assignees when the ‘assign to’ setting is set to ‘routing’.
maybe_add_select_assigneesNoneNoneNoneAdds the assignees when the ‘assign to’ setting is set to ‘select’.
maybe_add_user_noteStringNoneNoneAdds a user submitted note.
maybe_adjust_assignmentNone$previous_assigneeAssigneeRemoves assignees from and/or adds assignees to a step. Call after updating entry values. Make sure you call get_assignees() to get the assignees before you update the entry before you update the entry or the previous assignees may not get removed.
maybe_process_post_fieldsNone$form
$post_id
Form
Integer
Process any post fields on this step, if they exist.
maybe_send_assignee_notificationNone$assignee
$is_reminder
Assignee
Boolean
Sends the assignee email if the assignee_notification_setting is enabled.
maybe_send_notificationNone$typeStringSend the applicable notification if it is enabled and has assignees.
process_status_updateBoolean or or String or WP_Error$form
$entry
Form
Entry
Handles POSTed values from the workflow detail page.
purge_assigneesNoneNoneNonePurges assignees from the database.
refresh_entryEntry or NullNoneNoneIf set, returns the entry for this step.
remove_assigneeNone$assigneeAssignee or BooleanRemoves assignee from the step. This is only used for maintenance when the assignee settings change.
replace_variablesString$text
$assignee
String
Assignee
Override this method to replace merge tags. Important: call the parent method first. $text = parent::replace_variables( $text, $assignee );
replace_workflow_cancel_variablesString$text
$assignee
String
Assignee
Replace the {workflow_cancel_link} and {workflow_cancel_url} merge tags.
replace_workflow_url_variablesString$text
$assignee
String
Assignee
Replace the {workflow_entry_link}, {workflow_entry_url}, {workflow_inbox_link}, and {workflow_inbox_url} merge tags.
rest_permission_callbackBoolean or WP_Error$requestWP_Rest_RequestCheck if a REST request has permission.
restart_actionNoneNoneNoneOverride this to perform any tasks for the current step when restarting the workflow or step, such as cleaning up custom entry meta.
send_assignee_notificationNone$assignee
$is_reminder
Assignee
Boolean
Sends the assignee email.
send_notificationNone$notificationNotificationSends an email.
send_notificationsNone$assignees
$notification
Array of Assignees
Notification
Sends a notification to an array of assignees.
send_workflow_notificationNoneNoneNoneSends the workflow notification, if enabled.
set_next_step_idNone$idInteger or StringSets the next step.
startBooleanNoneNoneAttempts to start this step for the current entry. If the step is scheduled then the entry will be queued.
supports_due_dateBooleanNoneNoneOverride to indicate if the current step supports due date.
supports_expirationBooleanNoneNoneOverride to indicate if the current step supports expiration.
update_step_statusNone$statusBoolean or StringUpdates the status for this step.
update_user_statusNone$user_id
$new_assignee_status
Boolean or Integer
Boolean or String
Updates the status for the given user.
validate_noteBoolean$new_status
$form
String
Form
Determine if the note is valid and update the form with the result.
validate_scheduleBooleanNoneNoneValidates the step schedule.