Custom actions

Introduction to Custom Actions

In this guide we will cover what an action is, and how to build a custom one for your own integration recipes!

📘

NOTE

Prior to reading this guide, we recommend checking out our Quickstart Integrations article as it will be used as an example.

What is an action?

An action is a type of workflow block (which is a part of an integration recipe) that will "do something" after a trigger is invoked. It accomplishes what you’re looking to do with your recipe. It can change your monday data and initiate changes on other platforms too.

Examples of actions are:

• Create an item in monday.com
• Change an item's status in monday.com
• Send an email using Gmail
• Create a row in a spreadsheet

If you take a look at any integration recipe in the features section of one of your apps, you can choose a built-in action:

There are two types of actions: Built-in actions and Custom actions.

Custom actions allow you to perform any kind of actions that are not supported by our built-in blocks.

You can use either built-in, or custom triggers to perform your desired manipulation and final action (e.g. a Status change on a board can populate some data into your own -- or any third party -- system).

In this guide, we will discuss the configuration necessary for a custom action.

Mechanisms Behind Custom Actions

What actually happens when an action is triggered in your custom integration recipe? The monday apps server will send a POST request to the run URL configured in your custom action block.

This Run URL will receive an HTTP POST request from monday with a body such as this:

{ 
  "payload": { 
    "blockKind": "action",
    "inboundFieldValues": {
      "boardId": 1234567890, 
      "columnId": "text"
      "itemId": 9876543210
    },
     "inputFields": { // input fields are based on the input fields configuration of your action and depend on the field type
        "boardId": 1234567890,
        "itemId": 9876543210,
        "columnId": "text"
      },
      "recipeId": 123456, //unique ID of the recipe for your app. if multiple accounts are using the same recipe, the same recipe ID will be sent
      "integrationId": 123456 //unique ID of the integration recipe added to your board
  }, 
  "runtimeMetadata": {
    "actionUuid": "a6676dzce11zd50b25c4871417e1zez1", // uuid that represents the execution of the action
    "triggerUuid": "z607d55cc428bb438ba02cbbcde6a25e" // uuid that represents the execution of the entire automation (same as run id in the activity log)
  }
}

Receiving this payload, your program should respond with a status of 200 indicating that the action was performed successfully. If your server responds with any other status, or doesn’t respond within a minute, the monday platform will retry calling your endpoint every minute for 30 minutes.

Keep in mind the custom actions you create can also be used in more than one recipe in your custom app! This is important as your actions should be designed for reusability. Some examples of custom actions include: “create a lead in Salesforce,” or “update a status in JIRA,” or even “send SMS via Twilio.”

Configuring Your Custom Action

To set up a custom action for one of your recipes, just go into the "Workflow Blocks" tab of one of your apps’ integration features.

📘

TIP

For the sake of this example, we’re going to reference the recipe included in the Quickstart Integrations template. As such, it would be a good idea to go through the steps in that article beforehand so you can follow along.

Define action sentence

Your action sentence describes what action or event your app will accomplish. The example from the Quickstart Integrations template is “translate it into {text column, targetColumn}.”

Your action sentence can contain fields that are configurable by the user. In order to add a field to your sentence, use the {FIELD_LABEL, FIELD_KEY} format.

For example, “When {text column, columnId} changes, translate it {to, transformationType} into {text column, targetColumn}”.

Configure action input fields

The output fields in the trigger block feed into the input fields of your action block. In this way, we are mapping the relevant trigger output fields directly into your action’s input fields.

The “types” of input fields for your custom action are dictated by where the field is coming from. In the dropdown menu for any input field, you can see there are three options:

• Context - Get the value of this field from the context in which the action is executing (for example the userId of the user who set up the recipe, or the boardId of the board in which the recipe was set up).
• Trigger Output - Get the value of this field from one of the output fields of your recipe trigger (for example the itemId of the item whose Status column was used to trigger the recipe).
• Recipe Sentence - Get the value of this field from the configuration chosen by the user in the recipe sentence.

The input fields of this Quickstart Integration recipe action (i.e. the ‘input field settings section’) are as follows:

This is what it will look like in the action configuration:

📘

NOTE

The max character limit for a custom trigger or action is 255 characters for each one - meaning they can be used together for a total of 510 characters on the entire recipe. As a best practice we recommend making recipes short and easily configurable, breaking the logic into multiple recipes if necessary.

Congratulations Builder!

Once you've finished this article, read these to learn more about key concepts:

• Custom Triggers
• Quickstart Guide: Integration Recipes
• Authorization for Integration Recipes
• OAuth and Permissions
• Frequently Asked Questions
• Developers community

📘

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎