Introduction
Gravity Flow was written to make it as easy as possible for developers to interact with installations and extend the base functionality. In addition to the Gravity Flow action and filter hooks developers can use the PHP API to interact with a local installation (on the same server) and the Web API to interact with a remote installation. It's also easy for developers to create step types so users can add their custom steps at any point in the workflow.
One important thing to remember when you're working with the API is that Gravity Flow is very opinionated about the way the status is handled. This means that for some projects it's not suitable. For example, if you have a legacy system set up based around a status field, it's still possible to migrate, but you find it tricky to change your mindset at first. Gravity Flow handles status changes by taking the entry on a process, routing to the next step, logging all the changes and triggering connected events like notifications, so changing a status is more like pressing a button than just changing the value of a field. The job of the API is to orchestrate the process by pushing the entry around - it doesn't handle the lower level actions of changing the value of a status field.
All the APIs are in active development so if you there's anything you need, either get in touch and ask or send a pull request.
Note: This documentation is in progress and may make reference to feature that are currently available only currently available in the development version.
Filter and Action Hooks
Gravity Flow exposes a series of filters and actions which allow developers to make changes to the way the plugin works without having to edit the core files. You can read more about action and filter hooks in the WordPress documentation. The recommended way to add actions and filters to your site is to create a plugin and add them there. Alternatively, a popular, though not ideal, way is to add the code to the functions.php file of your current theme.
The Workflow Orchestration API
The Orchestration API, the Gravity_Flow_API class, is the starting point for interaction with a local installation. Here are some things you can do with the Orchestration API:
- Add workflow steps to a form
- Get all the steps for a form
- Get the current step
- Check the current workflow status of an entry
- Cancel a workflow
- Restart a workflow
- Restart a step
- Send an entry to a different step
The Web/REST API
The Web/REST API can be used to interact with a remote installation of Gravity Flow. For example, it can be used in JavaScript on the same site to interact with the server or it could be used on a different server and accessed using the WordPress HTTP API or it could be used in a mobile application. Here are some examples of some of the things that can be done with the Web/REST API:
- Get all the assignees for the current step of a specific entry.
- Process a status update for one of the assignees.
- Get all the steps for the specified form.
- Get all the steps for the specified entry.
The Gravity Flow Web/REST API extends the Gravity Forms Web/REST API so authentication is handled by Gravity Forms.
Creating Custom Step Types
The Gravity_Flow_Step Class is the starting point for creating new step types. Your custom step type will appear in the list of available step types. When your custom step is reached your custom logic will run automatically. Override the methods of the base class to add or customise functionality.
The Gravity Flow Codex
The Gravity Flow Codex contains technical documentation for developers wishing to write an extension for Gravity Flow or interface with an existing installation. It is automatically generated from the source code every time a new version is built.