Was this page helpful?

Task automation with webhooks

Introduction

Tasks are the building blocks to set up editorial workflows on your content. They allow editorial teams to distribute work with clear accountability.

We are currently investigating different alternatives to allow users to create predefined set on tasks for entries. This is a powerful improvement since it would allow admins and content modelers to setup lightweight workflows in their space. This document presents an experiment with which users can automate the creation of tasks using only Contentful webhooks.

Disclaimer

This feature is currently in alpha and is under active development. It may undergo major changes or may be retired, therefore it's not recommended for production use.

Share your thoughts, ideas, and feedback using the feedback button.

Give feedback

Automate tasks creation with webhooks

Pre-requisite

  • Task automation with webhooks is only available on enterprise space types.

With this experiment you will be able to automatically create and assign tasks when an entry is created in a space. To do this we leverage the existing webhook functionality to call the Tasks API with a predefined task body and assignee. Note that you can only create one task per webhook definition. Create multiple webhook definitions if you need more than one task to be created automatically.

Getting Started

  1. Login to your Contentful account and open the space where you want to create tasks automatically.
  2. Navigate to Settings > Webhooks.
  3. Click Add webhoook to create the webhook that will create the task. You should see something similar to the picture below.

Setting up the webhoook

  1. Pick a name for your webhook. For example Task automation: create copy for main body.

  2. In the URL field:

    • choose POST as the method

    • use https://api.contentful.com/spaces/SPACE_ID/entries/{ /payload/sys/id }/tasks as the webhook url. Replace SPACE_ID with the id your space.

  3. In the triggers field check Select specific triggering events. In the revealed matrix pick the combination Entry/Create.

  4. Click on Filters if you want to limit the creation of this task to entries of a specific content type. On the first dropdown select Content Type ID and input the id of the content type in the text box.

  5. Click on + Add secret header. Use Authorization as the key and Bearer AUTH_TOKEN as the value. Replace AUTH_TOKEN with your access token. If you don't have an access token you can generate it navigating to Settings > API Keys > Content management tokens.

  6. In the Payload field select Customize the webhook payload and copy & paste the following.

    • replace TASK_BODY with the body of the task.

    • replace USER_ID with the id of the user you want to assign the task to. See the appendix to learn how you can get the ids of the users in the space.

    {
      "status": "active",
      "body": "TASK_BODY",
      "assignedTo": {
        "sys": {
          "id": "USER_ID",
          "linkType": "User",
          "type": "Link"
        }
      }
    }
  7. If you want to avoid sending a notification to the assignee when the task is automatically created, see the section "Disabling email notifications when creating a task" just below.

After completing these steps, save your webhook and create an entry (remember that it might have to be of an specific content type) which will have a task created automatically. If the setup was successful you will see the webhook calls to create tasks in the Activity log tab of each of your webhooks.

Repeat the previous steps if you want to automate the creation of more tasks.

Disabling email notifications when creating a task

In some cases you might not want Contentful to send a notification to the task assignee when the task is automatically created together with the entry. Think for example of tasks like Translate the description field to spanish which only make sense after the description has been filled in. In this example, the user assigned to the Translate the description field to spanish might be confused if she receives a notification saying that she has been assigned to a task but she can't action it yet because some other work has to be done beforehand (e.g. fill the description field in English).

To accomodate use cases like these we have added to this experiment the possibility to disable the delivery of emails when a task is created. To disable email notifications when a task is created from a webhook take the following steps:

  1. In the webhook settings page click on + Add custom header.
  2. Add x-contentful-enable-alpha-feature as the key and disable-email-notification as the value.
  3. Save the webhook.

With this header, your users won't recieve an email when tasks are created using this webhook. Users can in any case find all the tasks that are assigned to them by clicking the Pending tasks link on the user dropdown menu.

Appendix

Getting the user ids

Tasks have to be assigned to a user in the space. To assign a task to a user set the assignedTo task property with a link to the user.

To get the ids of the available users in a space use the /space_members endpoint. This endpoint returns all the members of a space but by default doesn't include the user details (i.e. email, name, ...) of each member. To get those details we have to use the include=sys.user query parameter. Lastly notice that this endpoint is still on alpha so the header 'x-contentful-enable-alpha-feature: teams-api' is required to use it.

This is an example of the usage of the endpoint to get the user details. Notice the includes.User array where the included users details are returned:

➡ curl \
 -H 'Authorization: Bearer AUTH_TOKEN' \
 -H 'x-contentful-enable-alpha-feature: teams-api' \
'https://api.contentful.com/spaces/1234abc/space_members?include=sys.user'
{
  "total":1,
  "limit":25,
  "skip":0,
  "sys":{
    "type":"Array"
  },
  "items":[
    {
      "admin":true,
      "sys":{
        "type":"SpaceMember",
        "id":"1234abc-2T4JQZGOuHn2xzFE3Nht1J",
        "createdAt":"2018-06-28T12:56:28Z",
        "updatedAt":"2019-12-12T05:23:49Z",
        "space":{
          "sys":{
            "type":"Link",
            "linkType":"Space",
            "id":"1234abc"
          }
        },
        "user":{
          "sys":{
            "type":"Link",
            "linkType":"User",
            "id":"2T4JQZGOuHn2xzFE3Nht1J"
          }
        }
        "relatedMemberships":[
          {
            "sys":{
              "type":"Link",
              "linkType":"SpaceMembership",
              "id":"4ElhitdgCoOJF2QgccNjh6"
            }
          }
        ],
      },
      "roles":[]
    }
  ],
  "includes":{
    "User":[
      {
        "firstName":"Farruco",
        "lastName":"Sanjurjo",
        "avatarUrl":"www.example.com/cat",
        "email":"johndoe@contentful.com",
        "activated":true,
        "signInCount":386,
        "confirmed":true,
        "2faEnabled":false,
        "sys":{
          "type":"User",
          "id":"2T4JQZGOuHn2xzFE3Nht1J",
          "version":475,
          "createdAt":"2014-10-07T08:25:08Z",
          "updatedAt":"2019-12-12T05:23:49Z"
        }
      }
    ]
  }
}

A task like the one below would be assigned to the above user (id 2T4JQZGOuHn2xzFE3Nht1J):

{
  "status": "active",
  "body": "Translated english copy to spanish",
  "assignedTo": {
    "sys": {
      "id": "2T4JQZGOuHn2xzFE3Nht1J",
      "linkType": "User",
      "type": "Link"
    }
  }
}