Build Integration Recipes

Custom Actions

Learn how to build custom actions that will listen to your integration triggers and carry out the action of your choosing.

Intro to 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 here.

What is an action?

“Actions” are a part of an integration recipe that accomplish what you’re looking to do. They can change your monday data and initiate changes on other platforms too.

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

action options

Built-in actions, much like built-in triggers, are offered by our monday apps framework for you to create recipes that will affect a monday account data in a predetermined way (the account of whomever is using the app). While this reduces the amount of set-up and coding on your end, you are also limited by the types of actions available.

Alternatively, custom actions allow you to have full customizability of which actions you want to take place. 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.

Mechanism 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: { 
    // input fields are based on the input fields configuration of your action
    inputFields: { 
      // fields structure depends on the type of the specific field
      boardId: 345345345,
      itemId: 456456456,
      columnId: 'text_1',
      targetColumnId: 'text_2',
      transformationType: { 
        title: 'to lower case', 
        value: 'TO_LOWER_CASE' 
    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

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 "Recipes" section of one of your apps’ integration features. Here is where you can create new recipes.

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:

Field Key Type Description
boardId Context The board where the recipe was created
itemId Trigger Output The item that was selected, and consequently outputted in your trigger
sourceColumnId Trigger Output The first text column selected in your recipe
targetColumnId Recipe Sentence The second text column the user will choose
transformationType Recipe Sentence The type of transformation the user selects for this recipe (either turning their text into uppercase or lowercase)

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

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.

Congrats Builder! You've just finished learning all about setting up custom actions.

Read this next

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