Task actions ​

Managing tasks and to-dos is an integral part of knowledge management. Capacities' task actions allow you to send tasks from Capacities to your task manager of choice. This way, you can keep track of your tasks in your dedicated task manager, rather than having them distributed throughout different apps.

Task actions are a first step towards a holistic approach to task management in Capacities. Task actions are great for you if you want a dedicated place to manage your tasks, organize them in projects, boards, and lists, and collaborate with your team.

Capacities currently support first-class integrations to the following task management apps:

• Todoist
• TickTick
• Things
• Apple Reminders
• Google Tasks
• Microsoft To Do

How does it work? ​

Get a 5 minute video introduction to task actions here. You can find more details below.

To set up your task actions you need to follow a few steps. Some apps require an active connection to Capacities (see task manager specific instructions below). After you set up a connection to your task manager, you can define different task actions. For apps that don't require an active connection you can directly define your task action. Task actions have different settings, like the name of the action, the project you want your task to be saved in, or the behavior after a task was sent.

After you have defined your task actions a small paper plane icon will appear next to each To-Do in Capacities. You can create a to-do block by typing /todo + enter" or "[] + space". You can click on the icon (or on the dropdown if you defined multiple task actions) to send the To-Do to your task manager.

You can also quickly use the shortcut Option + Enter (Mac) or Alt + Enter (Windows) to send the To-Do to your default task manager or Option + Shift + Enter (Mac) or Alt + Shift + Enter (Windows) to open the dropdown and select a task action.

Setup ​

To set up your task actions, go to Settings > Task integrations and follow the instructions there. You can also find more detailed instructions for each task manager here.

Task manager connections ​

If your task manager requires an active connection, you need to connect your task management app to Capacities first. In this step, you give Capacities access rights to save tasks in your task manager.

To set up a connection to your task manager, you need to have an account with the task manager. You can then connect Capacities to your task manager from within the settings.

Simply click on the task manager you want to connect to and follow the instructions. You need to accept the permissions for Capacities for the integration to work properly. After you have connected your task manager, you should see it appear as an active connection in the settings.

Task actions ​

You can define a task action for each task manager you have connected. You can also define multiple task actions for each task manager. This allows you to send tasks to different projects, boards, or lists. If your task manager is not supported, you can still use webhook actions.

All task actions include the following settings:

• Follow-up action: Define what happens after your task has been sent. You can choose between Mark as done and Delete. If you choose Mark as done, the to-do block will be marked as done after the task has been sent to your task manager. If you choose Delete, the to-do block will be deleted after the task has been sent to your task manager.

• Space constraint: You make your task action available in all spaces or only in a specific space. If you want to make your task action available in multiple specific spaces, you can create multiple task actions with a space constraint.

Adding multiple task actions ​

If you have multiple projects or lists that you wish to use task actions for, then set up multiple task actions, assigning a project to each one. You can name the task action the same as your project.

Todoist ​

To create a task action for Todoist, you need to have an active connection to Todoist. You can then create a task action by clicking on the Add task action button and selecting Todoist. You can then define the settings of your task action. Besides the general settings you can define the following settings:

• Project: If you have multiple projects in Todoist, you can select the project you want to save your task to. You can select from all the projects you have in Todoist.

• Labels: You can define a list of labels that should be added to your task. Add all labels you want to add as a comma-separated list. Your labels need to exactly match the labels you have in Todoist. If you, for example, have labels called Important and Urgent, you can add them like this: Important, Urgent.

Note: You can currently connect Capacities only to a single Todoist account. If you want to connect Capacities to multiple accounts, you can use webhook actions.

When you send a todo block to Todoist, you can additional add the following properties:

• Due date: By linking a date in your block (e.g. by typing @today) you can set a due date for your task.

• Labels: By adding a tag to your todo block (e.g. by typing #important) you can add a label to your task.

TickTick ​

To create a task action for TickTick, you need to have an active connection to TickTick. You can then create a task action by clicking on the Add task action button and selecting TickTick. You can then define the settings of your task action. Besides the general settings you can define the following settings:

• Lists: If you have multiple lists in TickTick, you can select the list to which you want to save your task. You can choose from all the lists you have in TickTick.

Note: You can currently connect Capacities only to a single TickTick account. If you want to connect Capacities to multiple accounts, you can use webhook actions.

When you send a todo block to TickTick, you can additional add the following properties:

• Due date: By linking a date in your block (e.g. by typing @today) you can set a due date for your task.

Things ​

You can then create a task action for Things by clicking on the Add task action button and selecting Things. You can then define the settings of your task action. Besides the general settings you can define the following settings:

• List Name: If you want to save your task to a specific list, you can enter its name here. It needs to exactly match your list name. If you leave it empty or the list does not exist, your task will be saved to your inbox.

• Tags: You can define a list of tags that should be added to your task. Add all tags you want to add to a comma-separated list. Your labels need to exactly match the labels you have in Things. If you, for example, have labels called Important and Urgent, you can add them like this: Important, Urgent. If your tag does not exist in Things, it will be ignored.

When you send a todo block to Things, you can additional add the following properties:

• Due date: By linking a date in your block (e.g. by typing @today) you can set a due date for your task. Please not that Things only supports due dates without a time.

• Tags: By adding a tag to your todo block (e.g. by typing #important) you can add a tag to your task.

Apple Reminders ​

You can then create a task action for Apple Reminders by clicking on the Add task action button and selecting Apple Reminders. You can then define the settings of your task action. Besides the general settings you can define the following settings:

• List name: If you want to save your task to a specific list, you can enter its name here. It needs to exactly match your project name. If you leave it empty or the project does not exist, your task will be saved to your inbox.

When you send a todo block to Apple Reminders, you can additional add the following properties:

• Due date: By linking a date in your block (e.g. by typing @today) you can set a due date for your task.

Google Tasks ​

To create a task action for Google Tasks, you need to have an active connection to Google Tasks. You can then create a task action by clicking on the Add task action button and selecting Google Tasks. You can then define the settings of your task action. Besides the general settings you can define the following settings:

• Lists: If you have multiple lists in Google Tasks, you can select the list to which you want to save your task. You can choose from all the lists you have in Google Tasks.

You can create connections to multiple Google accounts. Follow the instructions to connect Capacities to Google Tasks again. You can then create multiple task actions for each Google account.

When you send a todo block to Google Tasks, you can additional add the following properties:

• Due date: By linking a date in your block (e.g. by typing @today) you can set a due date for your task. Please not that Things only supports due dates without a time.

Microsoft To Do ​

To create a task action for Microsoft To Do, you need to have an active connection to Microsoft To Do. You can then create a task action by clicking on the Add task action button and selecting Microsoft To Do. You can then define the settings of your task action. Besides the general settings you can define the following settings:

• Lists: If you have multiple lists in Microsoft To Do, you can select the list you want to save your task to. You can choose from all the lists you have in Microsoft To Do.

• Labels: You can define a list of labels that should be added to your task. Add all labels you want to add in a comma-separated list. Your labels need to exactly match the labels you have in Microsoft To Do. If you, for example, have labels called Important and Urgent, you can add them like this: Important, Urgent.

You can create connections to multiple Microsoft accounts. Follow the instructions to connect Capacities to Microsoft To Do again. You can then create multiple task actions for each Microsoft account.

When you send a todo block to Microsoft To Do, you can additional add the following properties:

• Due date: By linking a date in your block (e.g. by typing @today) you can set a due date for your task. Please not that Things only supports due dates without a time.

• Labels: By adding a tag to your todo block (e.g. by typing #important) you can add a label to your task.

Webhook ​

Webhooks are a way to send data from Capacities to an internet address you define. This way, you can send task data to any service supporting webhooks (or your own server). More information about webhooks can be found here.

Webhooks are a great way to integrate any service that Capacities does not support. Further, you can add any additional logic to your task actions.

If you don't have computer science knowledge, you can use various no-code tools to receive a webhook and then plug it into your task manager of choice.

You can, for example, use one of the following tools:

• Zapier
• Make
• n8n
• Pabbly
• IFTTT
• ActivePieces
• Albato

You can create a webhook task action by clicking on the Add task action button and selecting Webhook. You can then define the settings of your task action. Besides the general settings you can define the following settings:

• Webhook URL (required): The URL to which Capacities should send the task data. You can use one of the services above or your own server. If you want to use your own server, you need to make sure that it is accessible from the internet.

  INFO

  For security reasons, Capacities has some restrictions on which webhooks work. If you're not using any of the services above and your webhook fails, we recommend using one of the services above to proxy the request. You can also create a request on our feedback board so we can review and whitelist your webhook domain.

• Authentication If you want to guarantee that a request is coming from Capacities and not an unknown service, you can verify the sender by following these steps:

  Every request includes a x-capacities-signature-hmac-sha256 header. The value of the header is an HMAC hex digest (SHA256) of the request body using the secret that is shown in your task action settings.

  You can use the signature to verify that the request comes from Capacities. Here's an example using Node.js:

  js

  const crypto = require('crypto')
  
  const SECRET = 'your-secret-from-the-task-action-settings' // do not hardcode this in your code
  const hash = request.headers['x-capacities-signature-hmac-sha256']
  const bodyStringified = JSON.stringify(request.body)
  const bodyHash = crypto.createHmac('sha256', secret).update(bodyStringified).digest('hex')
  
  if (bodyHash === hash) {
    // request is coming from Capacities
  } else {
    // request is not coming from Capacities
  }

Every webhook request is a POST request with a JSON body. Here's an example of a webhook request:

POST /webhook HTTP/1.1
Host: example.com
Content-Type: application/json
x-capacities-signature-hmac-sha256: 0a0a9f2a6772942557ab5355d76af442f8f65e01

{
  "service": "task-action",
  "titlePlain": "Write project outline", // title of the to-do block in plain text
  "titleMarkdown": "Write project outline", // title of the to-do block in markdown
  "done": false, // if the to-do block is marked as done
  "contentMarkdown": "- Define Goals\n\n- Define Requirements\n\n", // content of the to-do block in markdown
  "dueDateTime": "2021-09-30T00:00:00.000Z", // due date if you mentioned a date in ISO 8601 format (UTC) for events with and without a time else undefined
  "dueDate": "2021-09-30T00:00:00.000Z" // due date if the date is an all day event in ISO 8601 format (UTC) at 00:00:00 else undefined
  "tags": ["important", "urgent"], // additional tags added to the to-do block
  "context": {
    "type": "todo-block",
    "spaceId": "2abd7601-9deb-4aee-9d99-7aa68f29c30c",
    "contentId": "09e76b8f-062a-4b5d-8552-6da6be517d39", // id of the content the to-do block is in
    "blockId": "103ed786-d3ea-402e-9cca-aad558872737",
    "title": "Project Unicorn", // title of the content the to-do block is in
    "webLink": "http://localhost:3333/2abd7601-9deb-4aee-9d99-7aa68f29c30c/09e76b8f-062a-4b5d-8552-6da6be517d39?bid=103ed786-d3ea-402e-9cca-aad558872737", // link to the to-do block in Capacities (web version)
    "desktopLink": "capacities://2abd7601-9deb-4aee-9d99-7aa68f29c30c/09e76b8f-062a-4b5d-8552-6da6be517d39?bid=103ed786-d3ea-402e-9cca-aad558872737", // link to the to-do block in Capacities (desktop app)
    "mobileLink": "capacities://2abd7601-9deb-4aee-9d99-7aa68f29c30c/09e76b8f-062a-4b5d-8552-6da6be517d39?bid=103ed786-d3ea-402e-9cca-aad558872737", // link to the to-do block in Capacities (mobile app)
  }
}

Task action errors ​

There are many reasons why a task action can fail. If a task action fails, you will see an error message in the block.

Steps to resolve the issue:

1. Check if your task manager is still connected to Capacities. Open the settings and check if you see an error message next to your task manager connection. If you see an error message, reconnect Capacities to your task manager. Delete your connection and follow the instructions in the settings to reconnect Capacities to your task manager.

2. Check if your task action is still active. Open the settings and check if you see an error message next to your task action. If you see an error message, you need to recreate your task action. Delete your task action and create a new one.

3. If you're receiving an error code with your error message, you can find more information about the error code below.

4. If none of the above steps helped, you can create a ticket on our feedback board with as much information as possible. Please include the error message and the error code if you have one.

Common error codes and how to resolve them ​

• Code 3498

  It is very likely that you already have an active connection to Google (either with this account or another account). Go to https://myaccount.google.com/connections and remove Capacities from the list of connected apps. Then, reconnect Capacities to Google Tasks.

• Code 3089

  Your webhook request failed. This can have multiple reasons. Please check the following:

  • Check if your webhook URL is correct. If you're using a service like Zapier, you can check the logs of the service to see if the request was received.

  • Check if your webhook URL is accessible from the internet. If you're using a service like Zapier, you can check the logs of the service to see if the request was received.

  • Check if your webhook URL is whitelisted. Capacities has some restrictions on which webhooks work. If you're not using any of the services above and your webhook fails, we recommend using one of the services above to proxy the request. You can also create a request on our feedback board so we can review and whitelist your webhook domain.