Build Integration Recipes

Quickstart Guide: Integration Recipes

Use this guide to create a simple recipe with monday trigger and a custom action

Buildyourfirstintegrationthumbnail

Intro to Integration Recipes

All integrations in monday.com have one or more recipes associated with it.

A recipe consists of two parts: a trigger and an action. These are both found in a sentence that ties them together. A trigger is an event that happens either in monday.com or another service. The action is the result of this trigger.

In monday.com, you have the ability to use triggers and actions already in the platform as well as your own custom ones. This provides you with the flexibility to create any workflow you could imagine. A few examples of recipes you can build with integrations are:

  • When a lead is created in salesforce > create an item in monday
  • When status changes to something > send email to user
  • Each time period > create and share report from a board

In this quickstart guide, we'll build a simple integration that automatically manipulates data from a text column into another text column. The app will do the following things:

  • Use a monday trigger to notify your app when a column data has changed
  • Use a custom action to write the manipulated text to a column value

Tip: Don't have a monday.com account, or need one for testing? Sign up for a free developer account here.

Part 1: Build your first integration recipe

In this article we are going to build a recipe that will be triggered by the update of one text column. The action will then transform the text in this text column to update another column.

Tip: Download the starter code for this guide here.

In the the end it will look similar to this:

example

Add an integration to your monday app

To add an integration to your monday app, simply go to the features section of your app and create a new integration feature.

In the feature editor you can add a title and description to your integration. When a user finds your integration in the integrations center, they will see the title and description you entered.

Set up a monday trigger for your recipe

To set up the trigger for your recipe, go to the "Recipes" section and add a new recipe. Here is where you will create new recipes for users to use and configure before they are active on their board.

Click “Choose trigger” and select “When a column changes” from the trigger left panel.

Note: This specific monday trigger fires whenever a value of a specific column on your board changes. That is just the beginning of the many monday triggers that are available. for you at the start. Explore them later!

Define trigger sentence

Here you can define the first part of the recipe users will see when they enter the integrations to create a recipe. You can add various fields to the sentence to make it easily configurable for each user as they look to add the recipe to their board.

In order to add a field to your sentence use {FIELD_LABEL, FIELD_KEY} format:
Type “When {text column, columnId} changes” in your trigger sentence field.

Configure trigger input fields

In order to create the trigger for your recipe, you will need to configure input fields. Input fields define configuration for the trigger.

In this case, we'll define which board and column your recipe will watch for the column change event. Configure the input field in the trigger ‘input field settings section’:

  • boardId - Context - the board where the recipe was created
  • columnId - Recipe Sentence - the column that will be selected by the user. Here you will choose a text column as our recipe will support only text.

Note: If you are interested in learning how to create a custom trigger, you can learn how to do so here

Part 2: Build your own custom action

Here is where we will create the action for the recipe we outlined previously in the article.

This action will call the endpoint of our server that will manipulate the text and update the column. We will add the column as part of the sentence that will be configured by the user

Create a new action

  1. Click choose action
  2. Click create new action
  3. Name your action: Transform text
  4. Run URL - type "https://{NGROK_URL}/transformation/transform"

We will change {NGROK_URL} part later when we will bring up our local server

  1. Add the following input field that our action will need in order to run: input field

Now you can create your action and add it to your recipe by choosing it from the left panel.

Note: The custom actions you create can be used in more than one recipe in your integrations

Define action sentence

Now let's define the second part of the recipe sentence that will be displayed for the user. As with creating the trigger sentence, the action sentence also allows you to add various fields as part of the action sentence.

Type “transform to {another column, targetColumnId}” in your action sentence field.

Configure action input fields

The input fields section is where you will choose an action to state where the value is coming from. You can choose from 3 options:

  • Context - the context of the specific action execution, such as userId, accountId, etc.
  • Trigger Output - all the fields, which the trigger of your recipe defined as the output fields. For this field, you will need to define the specific trigger output field key.
  • Recipe Sentence - all the fields that the action defined as part of the sentence. In our specific case, the target ColumnId

Here is the list of input fields you will need to configure in the 'Input fields settings':

  • boardId - Trigger Output -> boardId - the board where the recipe was created
  • itemId - Trigger Output -> itemId - the item that triggered the recipe
  • sourceColumnId - Trigger Output -> columnId - the column that was chosen by the user in the trigger sentence part
  • targetColumnId - Recipe Sentence - the column that was chosen by the user

action set up

Click "Create Recipe". Congrats! We finished creating a recipe.

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.

Part 3: Point your action to work with your local environment

After we configured our action, we left a placeholder for the Run URL field to be filled later. Now we will run a local server and point our action to use it.

Set up your development environment

We will be using the monday-cli package to set up our local environment. To set up your dev environment, follow these steps:

  1. Run the following command in your terminal. This command will download the project quickstart-integrations to your current folder, install the dependencies (npm install), and run the project locally (npm run start).
npx @mondaydotcomorg/monday-cli scaffold run ./ quickstart-integrations
  1. Wait for the installation process to finish. It may take a few minutes.
  2. After installing the project, you will get the message "Your app is served from this URL" with a link to your application, e.g. https://1c782a05.ngrok.io

  3. Navigate to the "quickstart-integrations" folder

  4. Add your app's signing secret to the .env file as MONDAY_SIGNING_SECRET. You can find this in the application's basic information:
  5. Add your API token to .env file as API_TOKEN. You can find your API token in the "My Tokens" section:

  6. Save your .env file. Now you are ready to connect your monday Custom Action to your local server and transform the text!

Note: To run your application manually in the future: terminate the CLI command, navigate to the folder with the project (quickstart-integrations), and run "npm run start" command. If you want to run your app in debug mode, run separately in 2 different terminal windows: npm run server-with-debugger and npm run expose

Direct action to your local server

Your action can define the Run URL, which is the URL monday.com will send a request to when the integration is triggered. The Run URL will have this structure: {URL}/{endpoint}.

Open the action that we created before, and change {NGROK_URL} to the value that you got in the previous step. In our specific case it will be: 1c782a05.ngrok.io, so the full URL will be https://1c782a05.ngrok.io/transformation/transform

Your endpoint will get a HTTP POST request from monday.com with the next structure in the body (for example):

{ 
  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
  }
}

Congrats Builder!

You've now built a simple monday app that transforms data automatically and is configurable by the user.

You can add your new recipe to any of your boards and try it for yourself!

Read this next

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