App Actions

App Action is an entity that allows communication between apps. An app can expose actions that the other apps can call to trigger specific behaviors. App Actions can also be triggered manually by a user.

Apps Actions are asynchronous and don't return a payload. One can think about an App Action as an asynchronous function that doesn't return a value. As such, App Actions can take arguments and they are defined by means of the parameters property.

Here are some examples of how you can use Apps Actions:

• Sending notifications, e.g. emails, chat messages, SMSes.
• In your CI/CD pipeline, e.g. triggering website builds.

How Apps Actions work

To call an action on your app, a consumer app needs to query the CMA. Contentful will then send a signed request to your application. This comes with a few features out of the box:

• Apps Actions are secured by request verification, meaning that your app can check the integrity of every request and only accept calls coming from Apps in Contentful.

• Apps Action parameters are pre-validated (with a provided schema) by Contentful, meaning that you don't need to implement payload validation, once the request is verified.

• Apps Actions are subject to the same rate limiting as the other CMA endpoints, meaning that you won't need to implement rate limiting, if you're happy with the limits CMA runs upon.

• Apps Actions can be triggered only if both ActionConsumer and ActionProvider apps are installed in the same environment, meaning that only authorized apps can act on your data.

  Notes

• ActionConsumer is a backend app that triggers behaviours in other apps.

• ActionProvider is a backend app that exposes actions that other apps can trigger.

The diagram below displays an interaction between ActionProvider, ActionConsumer and CMA when an App Action is called.

An example implementation of triggering an AppAction from another app's backend:

import createApp from 'imaginary-http-framework';
import { verifyRequest } from "@contentful/node-apps-toolkit";

import { sendNotification } from './service/imaginary';
import { signingSecret } from './secure-storage';

const app = createApp();

app.post('/send_notification', async (req, res, next) => {
    const canonicalRequest = {
        method: req.method,
        path. req.url,
        headers: req.headers,
        body: req.body,
    }

    if (!verifyRequest(signingSecret, canonicalRequest)) {
        next(new Error('Forbidden'))
    }

    const response = await sendNotification(req.body);

    res.send(200)
})

app.listen(3000)

For a more detailed demonstration, check out our examples.

Create an App Action

AppAction can be created while editing the app definition for a particular app as seen in the screenshot below:

1. Go to the Contentful web app.

2. In the top pane, click Apps and select Manage apps.

3. Select Your Custom apps

4. Go to the required app and under the actions menu select Edit app definition.

5. Click Add action. A "Create action" window is displayed.

6. Enter a custom name for your App Action in the Action name field.

7. In the Action URL field, enter a custom URL to send requests to when the App Action is called. The URL must be public and use HTTPS.

8. Under the Schema area, select the required App Action category according to the following options:

• Entries - Select this option for your App Action to operate on a list of entry IDs.
• Notification - Select this option for your App Action to send notifications to an external service.
• Custom - Selecting this option activates Add input parameter button. Click on it to start setting up one or multiple custom input parameters for your custom App Action.

9. Click Save action. Your action is saved.

App Action calls

Calls to trigger actions are always mediated by Contenful. You can read the the previous section to understand why.

Errors

• 403 - Forbidden - This error is returned if the subject is not an authorized user.

• 404 - NotFound - This error is returned if the resource doesn't exist.

• 409 - Conflict This error is returned if the provider has a missing or invalid signing secret.

Request

POST /spaces/{space_id}/environments/{environment_id}/app_installations/{app_installation_id}/actions/{app_action_id}/calls
Authorization: Bearer <cma_token>
Content-Type: application/vnd.contentful.management.v1+json
{
  "parameters": {
    "recipient": "Alice <alice@my-company.com>",
    "message_body": "Hello from Bob!"
  }
}

Response

{
  "sys": {
    "type": "AppActionCall",
    "space": {
      "sys": {
        "type": "Link",
        "linkType": "Space",
        "id": "yadj1kx9rmg0"
      }
    },
    "environment": {
      "sys": {
        "type": "Link",
        "linkType": "Environment",
        "id": "staging"
      }
    },
    "appDefinition": {
      "sys": {
        "type": "Link",
        "linkType": "AppDefinition",
        "id": "<app_definition_id>"
      }
    },
    "action": {
      "sys": {
        "type": "Link",
        "linkType": "AppAction",
        "id": "<app_action_id>"
      }
    },
    "createdAt": "1970-01-01T00:00:00.000Z",
    "createdBy": {
      "sys": {
        "type": "Link",
        "linkType": "AppDefinition",
        "id": "6FfrUHfsHdvhsLi9czfji"
      }
    },
    "updatedAt": "1970-01-01T00:00:00.000Z",
    "updatedBy": {
      "sys": {
        "type": "Link",
        "linkType": "AppDefinition",
        "id": "6FfrUHfsHdvhsLi9czfji"
      }
    }
  }
}

App Action categories

Common use cases would require you to rewrite the same App Action over and over. With App Action categories you can simply reference one of the pre-defined schemas, without having to redefine the same parameters multiple times.

Let's assume your app needs to perform an operation and needs to trigger a notification to different services. Utilising categories, you can simply call App Actions whose category is Notification and ultimately integrate with all of them at once: you will only rely on the Notification and you are good to go.

Additionally, App Actions with some specific App Action Categories will show up in specific locations of the user interface.

App Action Categories are versioned in a semantic way: the first digit indicates a breaking change and the second digit all the other changes.

List of App Action categories

Entries - An action that operates on a list of entry IDs. Appears in Content tab of the Contentful web app.

Notification - An action that sends notifications to an external service

Custom - A custom action like deploying a website

Request

GET /organizations/{orgId}/app_actions_categories
Authorization: Bearer <cma_token>
Content-Type: application/vnd.contentful.management.v1+json

Response

{
  "sys": {
    "type": "Array"
  },
  "total": 1,
  "skip": 0,
  "limit": 100,
  "items": [
    {
      "sys": {
        "id": "ActionCategoryId",
        "type": "ActionCategoryType",
        "version": "v1.0",
        "name": "Action category name",
        "description": "Action category description",
        "parameters": [
          {
            "id": "App Action category identifier",
            "name": "App Action category name",
            "description": "App Action category description",
            "type": "Symbol",
            "required": true
          }
        ]
      }
    }
  ]
}