Process the current step with Rest API V2

Description
Authentication
Using the Endpoint
Path and Method
Request Parameters
Response
Success
Failure
Examples
PHP Request
API Response
Since
Source Code

Description

This endpoint allows you to process the current step for the specified entry either in whole or as an assignee.

Authentication

This endpoint requires the gravityflow_admin_actions capability. This can be adjusted using gravityflow_rest_api_capability_process_step filter.

Using the Endpoint

Path and Method

POST /gf/v2/entries/[entry_id]/workflow/steps/[step_id]/process

The path must include the specific entry ID and current step ID the entry is on in its’ workflow.

The only interactive steps which currently support this endpoint are Approval and User Input.

Request Parameters

Key	Type	Required?	Details
status	String	Yes	The status the assignee action should be set to based on step type. – User Input: in_progress or complete. – Approval: approved, rejected or revert.
gravityflow_note	String	Step Setting Controlled	Note to be added to workflow timeline. Step settings can define if it is required or in which status it is required.
assignee_key	String	No	The key for the assignee to be processed. (i.e. user_id\|1 or role\|administrator). If not specified, the API request current authenticated user will be used. If they are not an assignee on the step, the request will not be a successful result.
input_[field_id]	String	No	Specifying the field value (named in the same format as submitting the form) can be used to update the entry. If any input values are included, the values will be validated based on step settings (editable fields). A name field would use keys such as: input_1_3 = ‘FirstName’ input_1_6 = ‘LastName’

Response

Success

A successful response will contain a JSON Workflow Status object that provides the workflow status and the current active step (if appropriate).

Failure

A failed response will provide a JSON string of the error code and message.

Key	Type	Description
code	string	Error code.
message	string	Human-readable error message.
data[status]	integer	HTTP response status code

There are several failure scenarios which could be returned depending on request data provided.

Response Code and data[status]	Error Code	Message	Details
401 / 403	permission_denied	You are not allowed to view steps.	User does not have the required permissions for this endpoint.
404	entry_not_found	Invalid entry id. Entry could not be found.	Could not find an entry with the specified entry_id.
404	step_not_found	Invalid step id. Step could not be found.	Could not find a step with the specified step_id.
422	invalid_step	Step does not belong to the same form as the entry.	Step does not belong to the same form as the entry.
422	no_active_step	This entry does not have an active workflow step that can be processed.	All steps in the workflow are inactive. There is no current step to process.
422	invalid_step	You can only process the current step of a workflow	Specified step is not the current step of the workflow
422	operation_not_supported	The entry is on a workflow step type which cannot be updated via the API.	The current step is not a user input or approval step.
422	invalid_assignee	Invalid assignee key, assignee does not belong to the current step or assignee has already been processed.	Assignee status could not be updated. This could be caused by an invalid assignee key, or the assignee does not belong to the current step or assignee not being in a ‘pending’ status.
422	assignee_already_processed	The status could not be changed because this assignee has already been processed.	Assignee status could not be updated. The assignee specified in the assignee_key parameter is not in a ‘pending’ status.
422	invalid_status	The specified status is not valid. Only [valid status types] are supported by[step type] steps	User Input: in_progress complete Approval: approved rejected revert
422	status_not_updated	Assignee status could not be updated. You have either provided an invalid status or there was extra validation performed via a filter that prevented the status to be changed	This is most likely caused by an invalid status, but could be the result of the gravityflow_approval_assignee_status_feedback or gravityflow_feedback_approval filters returning false when processing the status.
422	revert_disabled	The Revert setting is not enabled for this step	Your request provided “revert” as status on an approval step that does not have the revert setting enabled.
422	in_progress_disabled	The Save Progress setting is not enabled for this step.	Your request provided “in_progress” as status on a step that does not have the Save Progress setting enabled.
422	validation_result	There was a problem while updating your form.	The validation of your submitted inputs failed. The data response object includes the Form Object that you should compare field errorMessage for further details.

Examples

PHP Request

Approval with no editable fields

//Update these variables
$entry_id = '1273';
$domain   = 'https://develop.local';
$auth_value = 'Basic replace-me-with-basic-auth-based-on-user-application-password';
$json = json_encode( array(
	'status' => 'approved'
) );

// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_post( $domain . '/wp-json/gf/v2/entries/' . $entry_id . '/workflow/steps/current/process', array(
    'headers' => array(
        'Authorization' => $auth_value,
        'Content-Type' => 'application/json',
    ),
    'body' => $json,
) );

Approval with rejection, editable fields and a specific assignee.

//Update these variables
$entry_id = '1273';
$domain   = 'https://develop.local';
$auth_value = 'Basic replace-me-with-basic-auth-based-on-user-application-password';
$json = json_encode( array(
	'status' => 'rejected',
	'assignee_key' => 'user_id|42',   
	'input_3' => 'The value for a paragraph field submitted via API',
	'input_1_3' => 'First Name',
	'input_1_6' => 'Last Name',
) );

// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_post( $domain . '/wp-json/gf/v2/entries/' . $entry_id . '/workflow/steps/current/process', array(
    'headers' => array(
        'Authorization' => $auth_value,
        'Content-Type' => 'application/json',
    ),
    'body' => $json,
) );

User Input with complete and note

//Update these variables
$entry_id = '1273';
$domain   = 'https://develop.local';
$auth_value = 'Basic replace-me-with-basic-auth-based-on-user-application-password';
$json = json_encode( array(
	'status' => 'complete',
	'gravityflow_note' => 'Assignee action marked complete via API',
) );

// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_post( $domain . '/wp-json/gf/v2/entries/' . $entry_id . '/workflow/steps/current/process', array(
    'headers' => array(
        'Authorization' => $auth_value,
        'Content-Type' => 'application/json',
    ),
    'body' => $json,
) );

User Input with in_progress and editable fields

//Update these variables
$entry_id = '1273';
$domain   = 'https://develop.local';
$auth_value = 'Basic replace-me-with-basic-auth-based-on-user-application-password';
$json = json_encode( array(
	'status' => 'in_progress',
	'input_3' => 'The value for a paragraph field submitted via API',
	'input_1_3' => 'First Name',
	'input_1_6' => 'Last Name',
) );

// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_post( $domain . '/wp-json/gf/v2/entries/' . $entry_id . '/workflow/steps/current/process', array(
    'headers' => array(
        'Authorization' => $auth_value,
        'Content-Type' => 'application/json',
    ),
    'body' => $json,
) );

API Response

See the examples in Workflow Status object for success response or the failure table above.

Since

This endpoint was added in Gravity Flow 3.0.

Note: Prior to version 3.0, the Inbox Block with Quick Actions for Approvals used an endpoint based on /wp-json/gf/v2/entries/[entry_id]/workflow/[rest_base for step type] where the step status could be updated. It has been refactored to use this endpoint for consistency.

Source Code

This endpoint is located in the gravityflow/includes/rest-api/v2/ folder with most of the route code in the class-controller-steps.php file.