Description
This endpoint allows you to cancel the active workflow for the specified entry.
Authentication
For available methods to authenticate to the API, refer to our REST API v2 Authentication guide.
The capability gravityflow_admin_actions is required to use POST requests at this endpoint.
This can be filtered using gravityflow_rest_api_capability_cancel_workflow
Using the Endpoint
Path and Method
POST /wp-json/gf/v2/entries/[entry_id]/workflow/cancel
The path must include the specific entry ID that you wish to cancel the workflow for.
Request Parameters
There are no required or optional properties for this endpoint.
Response
Success
A successful response will contain a JSON Workflow Status object that confirms the workflow cancel operation was completed. The current_step property in it would be null as a result.
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 cancel workflows. | 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 and entry with the specified entry_id |
| 422 | no_workflow | This entry does not have an active workflow. | The form that the entry belongs to does not have any workflow steps defined. |
| 422 | no_active_step | This entry does not have an active workflow step. Workflow cannot be cancelled. | The entry was already completed or cancelled. |
Usage
PHP Request
//Update these variables
$entry_id = '1729';
$domain = 'https://develop.local';
$auth_value = 'Basic replace-me-with-basic-auth-based-on-user-application-password';
// {@see https://codex.wordpress.org/HTTP_API}
$response = wp_remote_post( $domain . '/wp-json/gf/v2/entries/' . $entry_id . '/workflow/cancel', array(
'headers' => array(
'Authorization' => $auth_value,
),
) );
if ( ! is_wp_error( $response ) ) {
// The request went through successfully, check the response code against
// what we're expecting
if ( 200 == wp_remote_retrieve_response_code( $response ) ) {
// Do something with the response
// $body = wp_remote_retrieve_body( $response );
// $headers = wp_remote_retrieve_headers( $response );
} else {
// The response code was not what we were expecting, record the message
$error_message = wp_remote_retrieve_response_message( $response );
}
} else {
// There was an error making the request
$error_message = $response->get_error_message();
}
Since
This endpoint was added in Gravity Flow 3.0.
Source Code
This endpoint is located in the gravityflow/includes/rest-api/v2/ folder with most of the route code in the class-controller-workflows.php file.