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
Parameter | Type | Description |
---|---|---|
$form | Form | The 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
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
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
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
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
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
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
Parameter | Type | Description |
---|---|---|
$validation_result | Array | The validation result and form currently being processed. |
$new_status | String | The new status for the current step. |
Returns
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
Returns
Examples
- The Approval step type overrides this method to handle one-click approval links and providing the gravityflow_post_status_update_approval action.
- The User Input step type overrides this method to handle save vs submit status and potentially sending out additional notifications.
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
Parameter | Type | Description |
---|---|---|
$action | Array | The action properties. |
$token | Array | The assignee token properties. |
$form | Form | The current form. |
$entry | Entry | The current entry. |
Returns
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
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
Parameter | Type | Description |
---|---|---|
$assignee | Assignee | The assignee properties. |
$new_status | String | The assignee status. |
$form | Form | The 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
Parameter | Type | Description |
---|---|---|
$request | WP_REST_Request | Full 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
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
Parameter | Type | Description |
---|---|---|
$new_status | String | The new status for the current step. |
$form | Form | The form currently being processed. |
Returns
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
Parameter | Type | Description |
---|---|---|
$new_status | String | The new status for the current step. |
$form | String | The submitted note. |
Returns
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
Parameter | Type | Description |
---|---|---|
$form | Form | The current form which may contain validation details. |
$args | Array | Additional 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 Name | Return Type | Parameter | Parameter Type(s) | Description |
---|---|---|---|---|
add_note | None | $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. |
assign | Boolean | None | None | Set the assignee status to pending and trigger sending of the assignee notification if enabled. |
assignees_hash | String | None | None | Returns an MD5 hash of the assignees of the given step plus the assignee policy. |
can_set_workflow_status | Boolean | None | None | Returns 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_complete | Boolean | None | None | Ends the step if it’s complete. |
evaluate_routing_rule | Boolean | $routing_rule | Array | Evaluates a routing rule. |
evaluate_status | String | None | None | Evaluates the status for the step. |
get_assignee | Assignee | $args | String or Array | Retrieve the assignee object for the given arguments. |
get_assignee_args | Array | $assignee_key | $assignee_key | Creates an array containing the assignees id and type from the supplied key. |
get_assignee_keys | Array | None | None | Retrieve an array containing the assignee keys for this step. |
get_assignees | Array of Assignees | None | None | Returns an array of assignees for this step. |
get_base_url | String | None | None | Returns the Gravity Flow base URL. |
get_common_settings_api Gravity_Flow_Common_Step_Settings | None | None | Get the API for preparing common settings such as those which appear on notification tabs. | |
get_current_assignee_key | Boolean or String | None | None | Get the assignee key for the current access token or user. |
get_current_assignee_status | Boolean or String | None | None | Get the status for the current assignee. |
get_current_role_status | Array | None | None | Get the current role and status. |
get_due_date_timestamp | Boolean or Integer | None | None | Returns the expiration timestamp calculated from the expiration settings. |
get_editable_fields | Array | None | None | Override to return an array of editable fields for the current user. |
get_entry | Entry or Null | None | None | If set, returns the entry for this step. |
get_entry_id | Integer | None | None | Returns the ID for the current entry object. If not set the lid query arg is returned. |
get_entry_meta | Array | $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_timestamp | Integer or String | None | None | Returns the value of the entries workflow_timestamp property. |
get_entry_url | String | $page_id $assignee $access_token | Integer or Null Assignee String | Returns the entry URL. |
get_expiration_status_key | String | None | None | Return the value of the status expiration setting. |
get_expiration_timestamp | Boolean or Integer | None | None | Returns the expiration timestamp calculated from the expiration settings. |
get_feed_meta | Array | None | None | Retrieves the feed meta for the current step. |
get_form | Form | None | None | Returns the Form object for this step. |
get_form_id | Integer | None | None | Returns the ID of the Form object for the step. |
get_id | Integer | None | None | Returns the Step ID. |
get_inbox_url | String | $page_id $assignee $access_token | Integer or Null Assignee String | Returns the inbox URL. |
get_name | String | None | None | Returns the user-defined name of the step. |
get_next_step_id | Integer or String | None | None | Returns the ID of the next step. |
get_notification | Array | $type | String | Retrieves the properties for the specified notification type; building an array using the keys required by Gravity Forms. |
get_notification_assignees | Array | $type | String | Retrieve the assignees for the current notification |
get_required_capabilities | Array | None | None | Get required capabilities for the step. |
get_rest_base | String | None | None | Returns the resource slug for the REST API. |
get_role_status | Boolean or String | $role | String | Returns the status for the given role. |
get_schedule_timestamp | Boolean or Integer | None | None | Returns the schedule timestamp (UTC) calculated from the schedule settings. |
get_setting | Mixed | $setting | String | Returns the correct value for the step setting for the current context – either step settings or step processing. |
get_status | Boolean or String | None | None | Retrieves the step status from the entry meta. |
get_status_key | String | $assignee $type | String Boolean or String | Returns the status key |
get_status_label | String | $status | String | Returns the translated label for a status key. |
get_status_timestamp_key | String | $assignee_key $type | String Boolean or String | Returns the status timestamp key |
get_step_settings | Array | None | None | Get the settings for the current step. Defaults to empty get_settings() method. |
get_step_timestamp | Boolean or Integer | None | None | Returns the step timestamp from the entry meta. |
get_timestamp_date | Boolean or Integer | $setting_type | String | Returns the timestamp for the date based expiration or schedule or due date. |
get_timestamp_date_field | Boolean or Integer | $setting_type | String | Returns the timestamp for the date field based expiration or schedule or due date. |
get_timestamp_delay | Boolean or Integer | $setting_type | String | Returns the timestamp for the delay based expiration or schedule or due date. |
get_type | String | None | None | Returns the step type. |
get_user_status | Boolean or String | $user_id | Integer or Boolean | Returns the status for a user. Defaults to current WordPress user or authenticated email address. |
get_validation_result | Array or Boolean or WP_Error | $valid $form $new_status | Boolean Form String | Get the validation result for this step. |
get_workflow_url_access_token | String | $atts $assignee | Array Assignee | Get the access token for the workflow_entry_ and workflow_inbox_ merge tags. |
gpdf_add_notification_attachment | Array | $notification $gpdf_id | Array String | If Gravity PDF is enabled we’ll generate the appropriate PDF and attach it to the current notification |
is_active | Boolean | None | None | Is the step active? The step may have been deactivated by the user in the list of steps. |
is_assignee | Boolean | $assignee_key | String | Determines if the supplied assignee key belongs to one of the steps assignees. |
is_condition_met | Boolean | $form | Form | Processes the conditional logic for the entry in this step. |
is_expired | Boolean | None | None | Determines if the step has expired. |
is_overdue | Boolean | None | None | Returns TRUE if this step is past the defined due date. |
is_queued | Boolean | None | None | Is the step currently in the queue waiting for the scheduled start time? |
is_supported | Boolean | None | None | Is 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_assignee | Boolean | None | None | Checks whether the current user is an assignee of this step. |
log_debug | None | $message | String | Logs debug messages to the Gravity Flow log file generated by the Gravity Forms Logging. |
log_event | None | $step_event $step_status $duration | String String Integer | Add a new event to the activity log. |
maybe_add_assignee | None | $args | Array or String | Adds the assignee to the step if certain conditions are met. |
maybe_add_routing_assignees | None | None | None | Adds the assignees when the ‘assign to’ setting is set to ‘routing’. |
maybe_add_select_assignees | None | None | None | Adds the assignees when the ‘assign to’ setting is set to ‘select’. |
maybe_add_user_note | String | None | None | Adds a user submitted note. |
maybe_adjust_assignment | None | $previous_assignee | Assignee | Removes 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_fields | None | $form $post_id | Form Integer | Process any post fields on this step, if they exist. |
maybe_send_assignee_notification | None | $assignee $is_reminder | Assignee Boolean | Sends the assignee email if the assignee_notification_setting is enabled. |
maybe_send_notification | None | $type | String | Send the applicable notification if it is enabled and has assignees. |
process_status_update | Boolean or or String or WP_Error | $form $entry | Form Entry | Handles POSTed values from the workflow detail page. |
purge_assignees | None | None | None | Purges assignees from the database. |
refresh_entry | Entry or Null | None | None | If set, returns the entry for this step. |
remove_assignee | None | $assignee | Assignee or Boolean | Removes assignee from the step. This is only used for maintenance when the assignee settings change. |
replace_variables | String | $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_variables | String | $text $assignee | String Assignee | Replace the {workflow_cancel_link} and {workflow_cancel_url} merge tags. |
replace_workflow_url_variables | String | $text $assignee | String Assignee | Replace the {workflow_entry_link}, {workflow_entry_url}, {workflow_inbox_link}, and {workflow_inbox_url} merge tags. |
rest_permission_callback | Boolean or WP_Error | $request | WP_Rest_Request | Check if a REST request has permission. |
restart_action | None | None | None | Override this to perform any tasks for the current step when restarting the workflow or step, such as cleaning up custom entry meta. |
send_assignee_notification | None | $assignee $is_reminder | Assignee Boolean | Sends the assignee email. |
send_notification | None | $notification | Notification | Sends an email. |
send_notifications | None | $assignees $notification | Array of Assignees Notification | Sends a notification to an array of assignees. |
send_workflow_notification | None | None | None | Sends the workflow notification, if enabled. |
set_next_step_id | None | $id | Integer or String | Sets the next step. |
start | Boolean | None | None | Attempts to start this step for the current entry. If the step is scheduled then the entry will be queued. |
supports_due_date | Boolean | None | None | Override to indicate if the current step supports due date. |
supports_expiration | Boolean | None | None | Override to indicate if the current step supports expiration. |
update_step_status | None | $status | Boolean or String | Updates the status for this step. |
update_user_status | None | $user_id $new_assignee_status | Boolean or Integer Boolean or String | Updates the status for the given user. |
validate_note | Boolean | $new_status $form | String Form | Determine if the note is valid and update the form with the result. |
validate_schedule | Boolean | None | None | Validates the step schedule. |