App Actions

Overview

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.

App 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 App Actions:

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

Create an App Action

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

1. Log in 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 type field, select either Endpoint or Function Invocation:

   • Endpoint: Provide an Action URL to specify where requests should be sent when the App Action is triggered. The URL must be public and secured with HTTPS.

   • Function Invocation: Choose a previously uploaded Function that accepts the appaction.call invocation type. For more details on creating and managing functions, refer to the Function documentation.

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 Actions calls

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:

• App 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.

• App 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.

• App 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.

• App 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.

Call an App Action

After your app action is created, you can call, or invoke the app action by calling the CMA.

To call, or invoke the function, make a request to the Contentful CMA.

To view explanations for common app actions calls errors, check Contentful CMA reference.

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.

To view the list and get all App Actions categories, check Contentful CMA reference.