Creating tasks via the todo.vu code API
Connectors are configurable API endpoints for creating tasks. You can create as many connectors as you like. Each connector has its own unique endpoint URL, this is the URL to which data is posted along with a key for security.
Connectors can be configured either to explicitly set task properties and routing or to accept properties from the API post.
Connectors accept data in an HTTP POST with authentication provided by an Authorization header and data provided in a typical JSON data payload. The response will be in JSON format. If the call is successful then the response will contain the newly created task ID and if not then it will contain an error message explaining what went wrong.
Managing API connectors
Workspace admin users can create and manage the API connectors by clicking on the workspace name (top left) and choosing the “API connectors” option in the workspace menu.
Note that API Connectors are a premium feature and are only fully functional on a paid plan. However you can create connectors and experiment with them on any plan so you can get to know how they work. On non-paid plans connectors are rate-limited to only accept 1 task every 30 hours.
Once you get to the API Connectors page, any existing connectors will be shown as tiles that you can click on for more details.
You can click on the [Add connector] button to create a new connector.
Connectors have 3 tabs of settings – Settings, Code, and Activity.
Under the Settings tab, you can configure the connector to either accept specific properties from the data post or preset them within the connector. You can also configure how the task is routed to assignees and categorised by client, project and labels.
Deciding on the task creator if the contact is unknown
Because all tasks must have a ‘creator’ within the workspace we need to decide how to deal with tasks that come from addresses that are unknown. Connectors can act as users within the workspace or act on behalf of other users. So your three options are:
- reject the task entirely,
- accept the task and create a new contact based on the information sent
- accept the task but allow the connector to be the task creator and store any contact information on the task
Client, project and assignee
You can either preset these values on the connector or you can allow them to be dynamically calculated based on the contact information posted to the connector and default workspace routing rules.
If you do not set these explicitly, then once the task is created and the creator is determined, then the task will be routed to the assignee and client/project similar to how incoming email tasks or tasks from contacts are handled.
New task settings
For all of the task settings, you can either pass them via code to the connector or you can preset them explicitly.
You can set almost any property on a task via the connector settings or the API payload. You can set labels, add followers, choose the initial workflow state and even set a due date on the task.
The due date option can be configured to be relative to the task creation date for example ‘tomorrow’ would set the due date one day after the task is accepted.
If you set a value explicitly then it can not be passed in the JSON payload – if you try to do so then the task will not be created and it will result in an error.
The benefit of setting values explicitly is that you can modify the settings easily over time. Less programming and decision making is required at the code level.
This code example is dynamic and will vary depending on your connector configuration to help you understand the impact of the settings.
For settings that reference existing data (followers, labels) you will need to pass the IDs in your code. We provide lookup tools to help you find these values under the Code tab.
On the Activity tab, you can find links to tasks and records created from this connector. This is handy for debugging and reporting activity.
We have already developed a new Add Task Zap in Zapier specifically for the todo.vu task connectors. This Zap is not yet publicly available but you can request access by contacting our support team or going to the private zapier page. The connector provides a full user interface for routing data into a connector, thus providing integration opportunities with many hundreds of applications.
It is expected that you would set up different connectors for a range of purposes. You may decide to set up connectors for specific projects or staff or more generic connectors that are controlled by the API data.
Some suggested use cases include:
Incoming support requests from a web form – in this scenario you may build a web form on your website which collects information from customers. You then prepare this before posting to a todo.vu connector. You may choose to explicitly route all tasks to a specific project (in-house/support) intended for incoming requests and assign them to someone who then delegates the work.
Alerts from automated systems – you may want to develop simple scripts that check your servers for disk space or pending security updates and then generate tasks that are sent to your sys-admin staff to deal with these alerts.
Sales orders from a shopping cart – similar to the web form but more specific, you may choose to post information in the form of a task directly into todo.vu. For instance, WooCommerce provides webhooks that can be configured to post data to a todo.vu connector. If the orders require specific actions for the fulfilment, this may be a handy way to automatically notify and delegate and track orders.