Celonis s.r.o.

All information dedicated to Developers and Power Users using Make.com. such as Make API, Make white-labeled documentation, App SDK and Bridge DSK.

Make Developer Hub



## Create your custom app

When there is a service that you want to use in Make but the service is not yet available in Make, use the apps builder to create a custom app. The only requirement is that the service has to have an API.

In the apps builder, you write down a JSON configuration. This configuration is then used by the Make platform to generate all connections and app modules for you. If you are working on a complicated custom app, you can write a custom IML function with JavaScript.

There are two options directly supported by Make to write the custom app configuration:

* The web interface of your Make account instance.
* The Visual Studio Code (VS Code) extension.

The benefits of using VS Code over the Make account web interface are for example:

* first-class support for JSON format, like syntax highlighting and completion,
* automatic checking of the JSON configuration validity, notably in terms of parameter type checking and correct object context,
* predefined project structure for every custom app you create,

Follow the instructions [here](apps-sdk/) to configure the VS Code extension.

If you want to write the custom app configuration in the Make web interface, navigate to **Custom apps** in the left sidebar menu of your Make account. You might have to click on the three dots at the bottom of the left sidebar to view the **Custom apps** option.

If you are developing a custom app for the first time, check out [Your First App](basics/) section first.

## Important notes

* All modules can be tested directly in scenarios.
* Changes to communication configs are immediately active.
* You can see raw requests/responses in your browser's console.
* Changes in parameters and interface requires you to reload scenario editor page.
* We use JSONC (JSON with comments) in all sections except common data.

## Collaborative development

A custom app has always one owner account. Development in multiple people is not supported.

{% hint style="danger" %}
The following points describe workarounds to set up the development of a custom app in multiple people. These workarounds bypass some of the Make security features. If you decide to implement them, you have to manage the user access yourself.
{% endhint %}

### Development in the web Interface

If you develop in the web interface, create an account that can be shared among developers, e.g. development@myCoolDomain.com, and share the access there.

### Development in VS Code

If you use Visual Studio Code, you can share the owner's token with the development team. Read more info [here](https://docs.integromat.com/apps/apps-sdk).&#x20;


Custom Apps Documentation



The Apps platform documentation is divided into topic groups. The topic groups are structured the same way as you would navigate inside the Apps builder in Make.

## App structure

Section **APP STRUCTURE** describes how to define and configure the basic elements of a custom app.  The basic custom app elements are listed in the top menu in the custom app configuration, for example: <mark style="color:blue;">**Base**</mark>, <mark style="color:blue;">**Communication**</mark>, <mark style="color:blue;">**Modules**</mark> .

{% hint style="info" %}
### Where do I find it?&#x20;

Go to **Menu** -> **Custom apps** tab -> open your custom app.
{% endhint %}

<figure><img src=".gitbook/assets/Screen Shot 2022-09-12 at 14.44.51.png" alt=""><figcaption><p>App Structure</p></figcaption></figure>

## App blocks

Every structure element is divided into **blocks**. Some of these blocks appear in multiple places and share the same purpose, others do not.&#x20;

{% hint style="info" %}
For example, **Parameters** (static or mappable) are available everywhere apart from <mark style="color:blue;">**Base**</mark> and <mark style="color:blue;">**Functions**</mark>. Meanwhile, **Common data** exists only inside <mark style="color:blue;">**Base**</mark> and <mark style="color:blue;">**Connection**</mark>.
{% endhint %}

<figure><img src=".gitbook/assets/Screen Shot 2022-09-12 at 14.47.58.png" alt=""><figcaption><p>App Blocks</p></figcaption></figure>

## App components

_**COMPONENTS**_ are like bricks for _**APP BLOCKS**_.  Block doesn't exist without components. Multiple components - form a block.&#x20;

Pick a brick that suits your needs and use it. You can use multiple separated components or combine them together by using the `nested`property. Play around and find the best components combination for you!

{% tabs %}
{% tab title="Module" %}
<figure><img src=".gitbook/assets/Screenshot 2022-09-12 at 19.03.23.png" alt=""><figcaption><p>Module example</p></figcaption></figure>
{% endtab %}

{% tab title="Behind the scene" %}


<figure><img src=".gitbook/assets/Screen Shot 2022-09-12 at 14.51.14.png" alt=""><figcaption><p>App Components</p></figcaption></figure>
{% endtab %}

{% tab title="Example 1" %}
{% hint style="success" %}
When for a call you need to provide a name and an email -> you would use parameters **`"type": "email"`** and **`"type": "text"`**.
{% endhint %}

```javascript
[
    {
        "name": "email",
        "label": "Email",
        "type": "email"
    },
    {
        "name": "name",
        "label": "Name",
        "type": "text"
    }
]
```
{% endtab %}

{% tab title="Exaple 2" %}
{% hint style="success" %}
When for a call in _case X_ you need to provide a name and in _case **Y**_ an email-> you would use parameters **`"type": "select"`** with nested parameters **`"type": "email"`**/ **`"type": "text"`** under each option.
{% endhint %}

```javascript
[
    {
        "name": "select",
        "label": "Select",
        "type": "select",
        "options": [
            {
                "label": "Case X",
                "value": "caseX",
                "nested": [
                    {
                        "name": "email",
                        "label": "Email",
                        "type": "email"
                    }
                ]
            },
            {
                "label": "Case Y",
                "value": "caseY",
                "nested": [
                    {
                        "name": "name",
                        "label": "Name",
                        "type": "text"
                    }
                ]
            }
        ]
    }
]
```
{% endtab %}
{% endtabs %}

## Search

#### If you can't find what you are looking for, use <mark style="color:blue;">Search</mark> in the right top corner.


How to read the documentation



{% hint style="info" %}
**You can get the Make Apps Editor extension from the** [**VS Code Marketplace**](https://marketplace.visualstudio.com/items?itemName=Integromat.apps-sdk).
{% endhint %}

Make supports writing custom apps in Visual Studio Code (VS Code) with the Make Apps Editor extension. You can get the VS Code extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Integromat.apps-sdk) or install it in the **Extensions** tab in VS Code.

You write and edit the custom app configuration with the VS Code extension as you would edit a JSON file on your PC. The custom app configuration is downloaded to your PC when you open it from VS Code and uploaded to Make when you save it. The custom app configuration is stored on your PC as temporary files. The temporary files are deleted after you close the configuration. Because of this, you cannot use a local version control system (`git`, for example) to version control your custom app configuration.

The custom app configuration is associated with your account in Make. The communication with the VS Code extension and your Make account is authorized with an API key. To set up the VS Code extension you have to provide an API key with the appropriate API key scopes. Generate a new Make API key if you don't have one.

{% hint style="info" %}
If you encounter any bug in the Make Apps Editor, feel free to contact our support.
{% endhint %}


Make Apps Editor

Develop apps in Make UI

Develop apps in VS Code



This tutorial will guide you through the steps to create a custom app with a module. You will use the Make "Virtual Library Demo API."

If you want to test the Virtual Library Demo API click the link:

[http://demo-api.integrokit.com/api/v1/helloworld](http://demo-api.integrokit.com/api/v1/helloworld)

A new tab opens in your web browser with the API response in JSON format:

```json
{"result":"Hello, World!"}
```

The development of a custom app in Make is divided into several steps. These steps are described in detail in the following subpages.

{% hint style="info" %}
If you struggle with finding the app API, search on a web search page for: `API site:www.app-or-service.com`. For example, [`API site:www.eventbrite.com`](https://www.google.cz/search?q=API+site%3Awww.eventbrite.com)
{% endhint %}


Create your first app



When you want to create a custom app, you have to set up the custom app metadata, such as:

* a unique name of the custom app
* custom app label that Make displays in the scenario editor
* color of the app's modules
* app icon

This page will guide you through these settings.

1. Navigate to **Custom apps** in the left sidebar menu in your Make account. You might have to click on the three dots at the bottom of the left sidebar to view the **Custom apps** option.

    <figure><img src="../.gitbook/assets/image (57).png" alt=""><figcaption></figcaption></figure>
2. You will see a list of sample custom apps. Click **Create a new app** in the top right corner.&#x20;
3. In the **Create an app** pop-up, fill in:

* **Name**: The unique identifier of your custom app. Make uses the custom app name internally. Note the requirements under the text box.
* **Label**: The custom app label. Make will display the custom app label in the scenario editor. You can use any characters in the custom app label.
* **Description**: Description of your custom app. This field is optional.
* **Theme**:  The color that Make uses for your custom app modules and forms. Use the [hexadecimal color code](https://www.w3schools.com/colors/colors\_hexadecimal.asp).
* **Language**: The language of your custom app and its descriptions.

{% hint style="info" %}
The language setting in the custom app is informative. Make doesn't translate the custom app descriptions.
{% endhint %}

* **Audience**: This parameter has no effect currently. The custom app is accessible regardless of the user's country.
* **App icon**: Upload icon. The icon upload is optional. Make will use this icon to create your custom app logo. The icon has to:
  * be a file in `.png` format
  * have 512 x 512 px dimensions
  * have a maximum of 512 kB size

Make processes the icon file so that:

* All color pixels in the icon file are converted to white
* All transparent pixels in the icon file are converted to your theme color

For detailed guidelines on how to create the app logo check the [dedicated page](../app-logo.md).

![A Custom App Dialog](<../.gitbook/assets/create-an-app.png>)

{% hint style="info" %}
If you want to update the custom app icon, navigate to your custom app settings and click **Options** > **Edit**.
{% endhint %}

4. Click **Save changes** to confirm the custom app settings.

You created a custom app in Make. The next pages will guide you through setting up the app's base, connection, error handling, and modules.


Create your app



Click on an app in the Apps list. You will get a page with nine tabs. In this guide, we will focus on the custom app's main components:

* [Base](../app-structure/base/)
* [Connections](../app-structure/connections/)
* [Modules](../app-structure/modules/)

![App's Environment](<../.gitbook/assets/Screen Shot 2022-08-20 at 16.33.23.png>)

{% hint style="info" %}
The **App structure** section describes the components of an app in detail. You can explore it later.
{% endhint %}

Now you know the main components of a Make app. Your next step is to set up the custom app `Base`.


App's environment



Every custom app has a piece of settings that are common to all custom app modules and [remote procedures](../app-structure/rpcs/).  Use the **BASE** tab to specify settings that are inherited by all modules and remote procedures.

These common settings are:

* Base URL
* Authorization
* Error Handling
* Sanitization

[Read more about Base.](../app-structure/base/)

## Set up base for the demo API

In this step, we will set up the Base for our custom app. The custom app uses the Virtual Library Demo API.

1. Navigate to your custom app settings.
2. Click on the **BASE** tab.
3. The first code block already contains a JSON snippet:

```
{
    "baseUrl": "https://www.example.com",
    "log": {
        "sanitize": ["request.headers.authorization"]
    }
}
```

4. Replace the URL address `https://www.example.com` with the Virtual Library Demo API base URL: `http://demo-api.integrokit.com/api/v1`

5. Press `Ctrl+S` to save changes.

{% hint style="info" %}
Note that the `baseUrl` key contains the API URL without the `/helloworld` endpoint path. You specify the endpoint path in the module settings.
{% endhint %}

The base settings of your custom app look like this:

```json
{
    "baseUrl": "http://demo-api.integrokit.com/api/v1",
    "log": {
        "sanitize": ["request.headers.authorization"]
    }
}
```


Base



Modules are the key component of your app. They are basically wrappers around specific app/service functionality, which is exposed via an API endpoint.&#x20;

There are three basic types of modules: **Action**, **Search,** and **Trigger (polling)**.

<table data-header-hidden><thead><tr><th width="178">Type</th><th>Description</th></tr></thead><tbody><tr><td><a href="../app-structure/modules/action/"><strong>Action</strong></a></td><td>Use if the API endpoint returns a single response. Examples are Create a book, Delete a book or Get a Book.</td></tr><tr><td><a href="../app-structure/modules/search.md"><strong>Search</strong></a></td><td>Use if the API endpoint returns multiple items. An example is List Books that will find specific books according to search criteria.</td></tr><tr><td><a href="../app-structure/modules/trigger.md"><strong>Trigger (polling)</strong></a></td><td>Use if you wish to watch for any changes in your app/service. Examples are Watch a New Book, which will be triggered whenever a new book has been added to the library.</td></tr></tbody></table>

{% hint style="info" %}
Make works with 6 types of modules, read more about them [here](https://docs.make.com/apps/app-structure/modules).
{% endhint %}

## Setting up a new module for our demo API

### Creation of a new module

To create a new Module, click on the tab **MODULES**. The list of all modules your app consists of, will be shown (empty for now). Click the large button with the plus sign and choose **Create a new Module**.

![Empty List of Modules](<../.gitbook/assets/Screen Shot 2022-08-20 at 17.32.21.png>)

&#x20;A dialog will pop up, where you can name your module, choose its type, and provide some description. Fill the dialog as shown and click **Save**.

![Create a New Module DialogmThe new module will appear in the list. Click on the new module and a page with several tabs will be shown. ](<../.gitbook/assets/Screen Shot 2022-08-20 at 17.36.11.png>)

Make sure the tab **Communication** is active and replace the content of the text area with the following JSON and save the changes (Ctrl+S):

```javascript
{
    "url": "/helloworld"
}
```

The `url` key specifies the API endpoint path. The URL will be joined with `baseUrl` specified earlier to produce the full URL of the API endpoint: `http://demo-api.integrokit.com/api/v1/helloworld`.

{% hint style="info" %}
In order to use baseUrl specified in the `base`, the URL should start with `/`. If the URL doesn't start with `/`, the baseUrl doesn't come into use, and only the content of `url` is used instead.
{% endhint %}

Click the tab **Mappable parameters**. The JSON on this tab enables you to specify the parameters of your module that will appear in the [module settings panel](../app-blocks/expect.md). Our module does not require any parameters, so erase the content between the square brackets, leaving just empty square brackets and save the changes (Ctrl+S):

```javascript
[]
```

> _Congratulations! You have just created your first module._

### Testing the new module&#x20;

Now, we will test our new module. Open a new browser tab, login to Make, in the left main menu choose **Scenarios** and create a new scenario. Click the yet undefined “questionnaire” module to bring up a list of all the apps. Search for your new app by typing its name in the **Search** field: `Custom App`. Click your app and a list of all its modules will be shown, currently just the newly created **Hello World** module. Click the module to select it. An empty module settings panel will pop up saying “There are no configurable options for this module.”.&#x20;

![Configuration of "Hello World" Module](<../.gitbook/assets/Screen Shot 2022-08-20 at 17.49.08.png>)

Close the panel and run the scenario. Click the bubbles above the module to pop up the panel with information about processed bundles. In case you have successfully followed this tutorial, you should see the following output of your new module.

![Module's Output](<../.gitbook/assets/Screen Shot 2022-08-20 at 17.52.36.png>)

> _Perfect! You just learned how to create a new module and make it work. But we can make it better! We can make it more user friendly. Continue reading below._

### Setting up interface of the module

Since we now know the structure of the output, we can specify the `Interface`. So we can set up our scenario right away, with no need to first execute the module to learn the output's structure.

Below, you can see an example of a list of available parameters to map from **Shopify > Watch Orders** module. Notice that the Shopify module wasn't executed yet (the bubble is not displayed).

![Example Dialog with Available Parameters from Shopify Module ](<../.gitbook/assets/Screen Shot 2022-08-20 at 19.01.13.png>)

In the panel with the output, click on the button circled below and choose **Download output bundles** option.

![Download Output Bundles Option](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.00.28.png>)

Then, a new panel will appear, with the original response from the endpoint. Copy the text to your clipboard.

![Original Response from /helloworld Endpoint.](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.04.53.png>)

Go back to the tab with your app and make sure you are in the settings of the Hello World module. Select tab **INTERFACE**. You can see a JSON snippet:

```json
[
    {
        "name": "id",
        "type": "uinteger",
        "label": "User ID"
    }
]
```

In the right upper corner, click on **Options** button and choose **Generator**.

![Interface of the Hello World Module](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.11.50.png>)

A new panel will appear. There, paste the previously copied JSON from your clipboard and click **Generate**.

![Generator Panel](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.26.13.png>)

A new data structure will be generated. Copy it to your clipboard and close the panel.

![A New Data Structure](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.27.28.png>)

In the **INTERFACE**, replace the JSON structure with the new structure.

{% tabs %}
{% tab title="Old structure" %}
```
[
    {
        "name": "id",
        "type": "uinteger",
        "label": "User ID"
    }
]
```

![List of Available Parameters to Map Before](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.35.09.png>)
{% endtab %}

{% tab title="New structure" %}
```
[
  {
    "name": "result",
    "type": "text",
    "label": "Result"
  }
]
```

{% hint style="info" %}
It is recommended to add parameter `"label".` This label is then visible in the list of parameters available to map from preceding modules.
{% endhint %}

![List of Available Parameters to Map After](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.37.51.png>)
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Whenever you change **INTERFACE** in a module, you need to refresh your scenario in order to see the changes.
{% endhint %}

> _Perfect! You just learned, how to work with interface and automatically prepare a list of expected parameters from the module's output. Now, let's make it harder!_

### Adding mappable parameters

In Make modules, you can define, what data should be passed to the API. So we can create a new record or define, what should be returned.&#x20;

The Demo API endpoint `/helloworld` takes two parameters `greeting` and `name`. Click the following link to open the API response in your browser:

[http://demo-api.integrokit.com/api/v1/helloworld?greeting=Hi\&name=Johny](http://demo-api.integrokit.com/api/v1/helloworld?greeting=Hi\&name=Johny)

The API should return the following JSON response:

```javascript
{"result":"Hi, Johny!"}
```

So let’s make our **Hello World** module configurable by adding the parameter `greeting`. Switch back to the **Mappable parameters** tab, replace the empty square brackets with the following JSON and save the changes(Ctrl+S):

```javascript
[
    {
        "name": "greeting",
        "type": "text",
        "label": "Greeting"
    }
]
```

This JSON specifies that the module will have one parameter called `Greeting` of type `text`. More about parameters can be found in the [Parameters](https://integromat.github.io/apps/articles/parameters.html) documentation.

Switch to your scenario and refresh the browser window (F5). Click the Module to pop up its settings panel. The panel now contains one text field labeled **Greeting**. Fill `Hi`:

![New mappable field "Greeting"](<../.gitbook/assets/Screen Shot 2022-08-20 at 19.27.09.png>)

{% hint style="info" %}
Whenever you change **MAPPABLE PARAMETERS** in a module, you need to refresh your scenario in order to see the changes.
{% endhint %}

Press **OK** and run the scenario. Though, if you click the bubbles above the module to pop up the panel with information about processed bundles, the module’s output will be identical as in the previous run.&#x20;

You can also use [Make DevTool](https://docs.make.com/apps/make-devtool) to check the original `REQUEST` and `RESPONSE`, for further debugging. Learn more about debugging your app here.

This is how the log from the run looks like, focus on the Request Headers tab:

![Live Stream from Make DevTool](<../.gitbook/assets/Screen Shot 2022-08-20 at 19.35.35.png>)

Notice, that there is no parameter called `greetings` sent.

It is because we need to specify the structure of the request in the module. Specifically, we have to pass the content of the `greeting` parameter to the API.&#x20;

Switch back to the **MAPPABLE PARAMETERS** tab and click the **COMMUNICATION** tab. To pass the parameter `greetings` to the API, you have two options:

You can either add the parameter to the `url` key:

```javascript
{
    "url": "/helloworld?greeting={{parameters.greeting}}"
}
```

Or you can add a new key `qs` (query string) and add the parameter there:

```javascript
{
    "url": "/helloworld",
    "qs" : {
        "greeting": "{{parameters.greeting}}"
    }
}
```

Save the changes (Ctrl+S), switch to your scenario, and run the scenario. Click the bubbles above the module to pop up the panel with information about processed bundles, where you should see the modified module’s output:

![Output from the Hello World module](<../.gitbook/assets/Screen Shot 2022-08-20 at 19.45.40.png>)

Also, you can check how clear the run in DevTool looks. Finally, the parameter `greeting` is passed in QS (query string):

![Live Stream from Make DevTool](<../.gitbook/assets/Screen Shot 2022-08-20 at 19.44.20.png>)

You can now practice your skills and try to add a parameter `name` to your **Hello World** module.

> _Congratulations! You have just learned how to pass data from a module to an API. Also, you have learned how you can debug possible issues using our Make DevTool. If you are ready to learn about setting up connection in your app, continue below._



Module



APIs usually employ some sort of authentication/authorization to limit access to their endpoints.&#x20;

Make platform provides you with a list of the most used types of connections while in every each there is a code prefilled. You only need to edit it up to your and/or API's needs.

![Create a new Connection panel](<../.gitbook/assets/Screen Shot 2022-08-20 at 20.03.47.png>)

Mostly, you will need to change the URLs and names of the parameters.

## Setting up a connection for our demo API

> _While the `/helloworld` endpoint was accessible without any authentication/authorization, the other endpoints of the Demo API will require an API key._
>
> _Let’s try to call endpoint `/books` that should respond with a list of books in the library:_
>
> [_http://demo-api.integrokit.com/api/v1/books_](http://demo-api.integrokit.com/api/v1/books)
>
> _Without providing the API key, the response will contain the following error:_
>
> ```javascript
> {"error":"Invalid or missing API key"}
> ```
>
> _To enable the user of your Module to specify her/his own API key (assuming each user has got her/his own API key to access the API), you need to create a Connection._

We have covered the basics of creating a simple module. Since the `/books` endpoint will always return an array with items, you will need to create a new module type **Search**. Now, let’s see how to update our search module with a variable API token for each user.

Click the tab **Connections**. The (probably still empty) list of all your connections will be shown. Click the large button with the plus sign and choose **Create a new Connection**. A dialog will pop up, where you can name your connection and choose its type. Fill the dialog as shown and click **Save**.

![A New Connection Dialog](<../.gitbook/assets/Screen Shot 2022-08-21 at 13.04.33.png>)

The new Connection will appear in the list. Click the new Connection. A page with two tabs will be shown: **COMMUNICATION** and **PARAMETERS**.

A pre-configured communication will look like this:

```javascript
{
	"url": "https://www.example.com/api/whoami",
	"headers": {
		"x-api-key": "{{parameters.apiKey}}"
	},
	"log": {
		"sanitize": ["request.headers.x-api-key"]
	}
}
```

{% hint style="info" %}
The **COMMUNICATION** section specifies a simple request to determine whether the credentials entered by the user are valid or not. The most common way to validate the credentials is to call an endpoint to get the user’s information and/or tokens, if available. Most of the APIs have such an endpoint.
{% endhint %}

{% hint style="info" %}
There are types of connections, e. g. API Key, which don't have such an endpoint. In this case, it is recommended to call an endpoint, which will work in every case, and if possible will return the account's data, e. g. an endpoint `/about` or `/me`, etc.

Not only the credentials entered by the user will be validated, but also the account's name or email can be stored in the name of the connection (the value in brackets after the user's connection name), see the example below.
{% endhint %}

{% tabs %}
{% tab title="Occurence in a scenario" %}
![Example of Connection's Name](<../.gitbook/assets/Screen Shot 2022-08-21 at 13.45.48.png>)
{% endtab %}

{% tab title="Code" %}
```
...
"response": {
	"metadata": {
            "type": "email",
            "value": "{{body.data.user.email}}"
        }
},
...
```
{% endtab %}
{% endtabs %}

Since our Demo API doesn't have any suitable endpoint, we will not use any.

The code should be as below:

{% tabs %}
{% tab title="Communication" %}
```javascript
{
	"headers": {
	"api-token": "{{parameters.apiKey}}"
		},
	"log": {
		"sanitize": ["request.headers.api-token"]
	}
}
```
{% endtab %}

{% tab title="Parameters" %}
```javascript
[
    {
        "name": "apiKey",
        "type": "text",
        "label": "API Key",
        "required": true
    }
]
```
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Notice that there is a directive for the sanitization of API tokens. Sanitization should always be used so no personal tokens and/or keys can leak! Learn more about sanitization here.

Sanitization should always be used in both base and connection!
{% endhint %}

Once you finish the connection configuration, you can go back to your search module and click **Attach Connection**.&#x20;

![Attach Connection](<../.gitbook/assets/Screen Shot 2022-08-21 at 16.35.49.png>)

An Attach Connection dialog will appear. There, select the currently created connection.

![Selection of Connection](<../.gitbook/assets/Screen Shot 2022-08-21 at 16.40.11.png>)

When we are setting up a connection, we should not forget about the base!

As you remember, in base, there should be everything common to all modules and [remote procedures](https://docs.integromat.com/apps/app-structure/rpcs), e. g. baseUrl, authorization, sanitization, error handling, etc.

Therefore, click **BASE** tab and edit the code:

```javascript
{
    "baseUrl": "http://demo-api.integrokit.com/api/v1",
    "headers": {
        "api-token": "{{connection.apiKey}}"
    },
    "log": {
	"sanitize": ["request.headers.api-token"]
    }
}
```

{% hint style="info" %}
Notice that not only we added a new header with authorization (we mapped the `apiKey` from connection), but also edited the sanitization.
{% endhint %}

> _Awesome! You just learned how to add a new connection, attach it to an existing module, and map the connection data in base. Now, it is the right time to learn, how to make error handling, continue below._&#x20;


Connection



Since any API endpoint can return an error during an execution of a scenario, Make brought a way, how to handle such errors. Therefore, all apps in Make, custom included, should have error handling implemented. This way, the modules are more transparent as users of them exactly know, what caused the error. Also, error handling in a scenario can be used.

{% hint style="info" %}
Read more about error handling in Make:

* [Introduction to error handling](https://www.make.com/en/help/errors/introduction-to-error-handling)
* [Directives for error handling](https://www.make.com/en/help/errors/directives-for-error-handling)
* [Advanced error handling](https://www.make.com/en/help/errors/advanced-error-handling)
{% endhint %}

## Setting up an error handling for our demo API

> _When you were trying your new search module, you were probably experiencing error 401, but you didn't know why was that, if you didn't check Integromat DevTool. Since Make offers advanced error handling, you should set your app the way, so you could understand what is wrong with your module/scenario right away and use error handlers._

Enter your search module into your scenario and create a new connection with a random API key, if you haven't done so before. You should see the error:&#x20;

![Error 401 Before Implementing Error Handling](<../.gitbook/assets/Screen Shot 2022-08-21 at 17.24.20.png>)

In DevTool, you should see this output:

![Error in the DevTool](<../.gitbook/assets/Screen Shot 2022-08-21 at 17.28.49.png>)

We need to make sure the error from the body of the response is returned in the module's output as well.

As you learned before, error handling should take part in base, since it is an element, which is shared among all modules and remote procedures. Therefore, open base and replace the current code with the code below:

```javascript
{
	"baseUrl": "http://demo-api.integrokit.com/api/v1",
	"headers": {
		"api-token": "{{connection.apiKey}}"
		},
	"response": {
		 "error": {
            	     "message": "[{{statusCode}}] {{body.error}}"
        }},
	"log": {
		"sanitize": ["request.headers.api-token"]
	}
}
```

{% hint style="info" %}
Notice, that a new element `response` with `error` handling was added.&#x20;

Basically, we mapped the `error` parameter from the response body. So now, when an error is returned from the API, the error message contains the `statusCode` together with `error` wording.
{% endhint %}

Now, go to your scenario again, and execute the search module. You should now see the detailed wording of the error:

![Error 401 with Detailed Wording after Implementing Error Handling](<../.gitbook/assets/Screen Shot 2022-08-21 at 17.25.06.png>)

{% hint style="info" %}
Notice, that the wording of the error is now available. Thanks to this, you know where is an error and how to solve/handle it.
{% endhint %}

> _Voila! You just learned all the basics of custom app development in Make!_&#x20;
>
> _If you want to continue in development of your custom apps, you can explore our docs and learn more!_


Error handling



During the development of your app, you will probably experience multiple issues with your app and/or API. Therefore, you will need to use Make DevTool and/or console in order to debug your app. Continue below in order to learn how!

## Basics of debugging

You can easily debug your app using Make DevTool or Chrome DevTool's console. Learn how to use Make DevTool or Chrome DevTool's console below.

{% content-ref url="../make-devtool/" %}
[make-devtool](../make-devtool/)
{% endcontent-ref %}

## Debugging of pagination in list/search module

When the GET endpoint, which you are using, supports pagination, you need to make sure the module uses it correctly. Learn how you can test if your pagination works correctly below.

{% content-ref url="debugging-of-pagination-in-list-search-modules.md" %}
[debugging-of-pagination-in-list-search-modules.md](debugging-of-pagination-in-list-search-modules.md)
{% endcontent-ref %}

## Debugging RPC

Make apps platform has a tool for testing the behavior of your RPCs. Thanks to this tool, testing of RPCs is easy. Learn, how to test your RPCs below.

{% content-ref url="debugging-rpc.md" %}
[debugging-rpc.md](debugging-rpc.md)
{% endcontent-ref %}

## Debugging of custom IML functions

Implementing a custom IML function might get complicated, therefore, you will need to learn, how to effectively debug your custom IML functions. Learn how below.

{% content-ref url="debugging-of-custom-iml-functions/" %}
[debugging-of-custom-iml-functions](debugging-of-custom-iml-functions/)
{% endcontent-ref %}


Debugging your app



If API supports pagination, it should be implemented. In order to make sure the pagination works as intended, it is recommended to set the page size to a low number, if possible, see the example below:

```javascript
{
    "url": "/contacts/filters/{{parameters.filter_id}}",
    "method": "GET",
    "qs": {
        //"per_page": 100
	"per_page": 10 //set value for testing
    },
    "response": {
        "output": "{{item.contact}}",
        "iterate": "{{body.data.contacts}}",
        "limit": "{{parameters.limit}}"
    },
    "pagination": {
        "qs": {
            "page": "{{pagination.page}}"
        },
        "condition": "{{body.data.max_page > body.data.page}}"
    }
}
```

Then, it is needed to create as many records as one page and a few more. You can do it by using **Flow Control > Repeater** module, which also returns the ID of the repeat. Map this ID in the following module as it will help to differentiate the records.

<figure><img src="../.gitbook/assets/Screen Shot 2022-09-12 at 12.45.21.png" alt=""><figcaption><p>Creation of Testing Data Using Repeater</p></figcaption></figure>

Once the testing records are created, you can test your search module. Thanks to using the ID from the repeater, you are able to see whether the records are ordered and how, and whether the records are correctly retrieved, e. g. they are not being duplicated (1 page retrieved multiple times).

<figure><img src="../.gitbook/assets/Screen Shot 2022-09-12 at 13.58.01 (1).png" alt=""><figcaption><p>Example of Array Output</p></figcaption></figure>

In the console, you can also effectively control every retrieved page and its size.

<figure><img src="../.gitbook/assets/Screen Shot 2022-09-12 at 14.01.02.png" alt=""><figcaption><p>Example of Paginated Response</p></figcaption></figure>

Possible pagination issues:

* The stop condition `limit` set by the user doesn't work. Therefore all the records that exist in the account are retrieved (or only the first page if there is also the issue from the point below).&#x20;
* The `next page` condition isn't set correctly so the next page isn't retrieved even though it should according to the user's limit and the content of the account.&#x20;
* The `next page` condition isn't set correctly so the next pages are retrieved even though all records were already retrieved. They can either be duplicated or without any records (without looking into the console, you will not spot them).&#x20;
* The pagination is not optimized so even though there is a parameter saying “there is no other page to retrieve”, it still retrieves the next page which is empty (developer implements the pagination for offset even though he/she could implement it using the cursor parameter).&#x20;
* The value in the parameter `page` is too low therefore there are too many pages being retrieved (= too many calls).&#x20;
* Not common - the records are duplicated because the pages are overlapped (1st page  1-100, 2nd page 100-199 instead of 1-100, 101-200).



Debugging of pagination in list/search modules

---
description: >-
  In the case that you are using RPC inside your app, you might need to debug
  it. After this article, you will know how to debug RPCs on Make and be an ace
  of it!
---

# Debugging RPC

## Location of debug tool in RPC

The RPC debug tool can be found by following:&#x20;

1. Go to **Custom apps** tab
2. Select **your custom app** from the list
3. Go to the **REMOTE PROCEDURES** tab inside the custom app
4. Select an RPC you want to debug
5. &#x20;Click **Test RPC** button

<figure><img src="../.gitbook/assets/Test RPC button.png" alt=""><figcaption><p>Location of the "<strong>Test PRC</strong>" button inside every RPC<br></p></figcaption></figure>

## Navigation inside RPC

#### Compare the tabs below to understand how things work inside RPC on Make.

By default after creating a new RPC, you have a template of the communication code, which should be modified based on your needs. Check the _<mark style="color:purple;">**Customized Communication**</mark>_ tab for example.

{% hint style="info" %}
Inside RPC, you can use the relative path and the full form of the URL. However, we advise you to stick to the relative path across all your RPCs and Modules. A relative path is added to the `"baseUrl"`, that you are supposed to specify inside the App Base (Located: Your App -> **Base** tab).
{% endhint %}

{% tabs %}
{% tab title="Default Communication" %}
<figure><img src="../.gitbook/assets/RPC Communication Template.png" alt=""><figcaption><p>Default RPC communication template.</p></figcaption></figure>
{% endtab %}

{% tab title="Customized Communication" %}
<figure><img src="../.gitbook/assets/RPC Customized Communication (1).png" alt=""><figcaption><p>Example of modified RPC communication template.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

Also, there is **Parameters** tab, which by default is empty. Here you can add any parameter needed. In the same way, you can also do it in the **Mappable parameters from a module**. Check the _<mark style="color:purple;">**Customized Parameters**</mark>_ tab for an example.

{% tabs %}
{% tab title="Default Parameters" %}
<figure><img src="../.gitbook/assets/RPC parameters.png" alt=""><figcaption><p>By default RPC is created without any paramaters.</p></figcaption></figure>
{% endtab %}

{% tab title="Customized Parameters" %}
<figure><img src="../.gitbook/assets/Screenshot 2022-09-05 at 16.28.01.png" alt=""><figcaption><p>Example of RPC with parameters.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Any parameter created inside an RPC will be available only for RPC debugging.** It will not be visible inside your modules or inside scenarios.

To preview and test parameters, click on the **Test RPC** button.
{% endhint %}

{% tabs %}
{% tab title="Default Preview" %}
<figure><img src="../.gitbook/assets/Default preview RPC test.png" alt=""><figcaption><p>RPC debug tool without parameters.</p></figcaption></figure>
{% endtab %}

{% tab title="Customized Preview with Parameters" %}
<figure><img src="../.gitbook/assets/RPC with Parameters (1).png" alt=""><figcaption><p>RPC debug tool with parameters.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

## RPC debug tool&#x20;

RPC debug tool works the same way modules do.&#x20;

1. Specify the connection and other fields (i.e. _parameters_) if needed.
2. Click the **Test** button.
3. The call, which you specified before in the RPC communication, will be executed.

{% hint style="info" %}
**Notice that you will see the `output` which you specified in the RPC communication.**

If you specified output as "`label"` and `"value"`(with the purpose of using it inside a _Select_ parameter), do not expect to see the full server response there.
{% endhint %}

{% hint style="danger" %}
Sometimes you might get an empty array as a response. If that's not the response that you expected. Check that you correctly specified the path to the object, which you use inside **`iterate`**.
{% endhint %}

{% tabs %}
{% tab title="Input" %}
<figure><img src="../.gitbook/assets/RPC filled preview.png" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Output" %}
<figure><img src="../.gitbook/assets/RPC test filtered response 500h.png" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Communication code" %}
<figure><img src="../.gitbook/assets/RPC Customized Communication (1).png" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}


Debugging RPC

Debugging of Custom IML Functions

Make DevTool



Live Stream displays what is happening in the background once you've hit the _Run once_ button in your scenario.\
It allows you to view the following information for each module in your scenario:

* **Request Headers** (API endpoint URL, HTTP method, time and date the request has been called at, request headers, and query string)
* **Request Body**
* **Response Headers**
* **Response Body**

After you run a scenario, click one of the tabs in the right panel of Integromat DevTool to view the desired information.

![Live Stream - detail of a log](<../.gitbook/assets/Screen Shot 2022-08-22 at 16.32.21.png>)

**Searching Requests and Responses**

Enter the search term into the search field in the left panel of Integromat DevTool to only display requests that contain the search term.

![Searching in logs](<../.gitbook/assets/Screen Shot 2022-08-22 at 16.43.08.png>)

**Removing requests from the list**

To clear the list of requests recorded by Integromat DevTool, click the trash bin icon in the top-right corner of DevTool's left pane**l**.

![Bin button](<../.gitbook/assets/Screen Shot 2022-08-22 at 16.46.06.png>)

**Enabling console logging**

To enable logging into the console, click the computer icon (![2020-07-23\_13\_00\_07-Integration\_Google\_Sheets\_\_Google\_Calendar\_\_\_Integromat.png](https://cdn.integromat.com/s3/help/8f4b6d1c6c0e/2020-07-23-13\_00\_07-integration-google-sheets,-google-calendar-\_-integromat.png)) in the top-right corner of the DevTool's left panel.\
Logging into the console is enabled when the color of the computer icon switches to green.

![Console logging](<../.gitbook/assets/Screen Shot 2022-08-22 at 16.41.31.png>)

**Retrieving the request in the raw JSON format or cURL**

To retrieve the raw JSON content of the request, click the **Copy RAW** icon (![2020-07-23\_13\_29\_52-Integration\_Google\_Sheets\_\_Google\_Calendar\_\_\_Integromat.png](https://cdn.integromat.com/s3/help/64752d51473f/2020-07-23-13\_29\_52-integration-google-sheets,-google-calendar-\_-integromat.png)) in the top-right corner of the DevTool's right panel.

![Raw JSON](<../.gitbook/assets/Screen Shot 2022-08-22 at 16.50.18.png>)

cURL can be retrieved using the **Copy cURL** button next to the **Copy RAW** button.


Live Stream



While in Live Stream, you can't display historical logs in a scenario, in Scenario Debugger you can.

It displays the history of the scenario runs and enables you to search modules by their name or ID.

![Scenario debugger](<../.gitbook/assets/Screen Shot 2022-08-22 at 16.53.56.png>)

#### Searching modules by their name or description

To search the module by its name, enter the search term (name or module's ID) in the search field in the left panel of Integromat DevTool in the _Scenario Debugger_ section.

![Searching by module's name/description](<../.gitbook/assets/Screen Shot 2022-08-22 at 17.03.37.png>)

#### Open settings of a module

Double-click the module's name to open its settings in the scenario editor.

![Open a module's settings](<../.gitbook/assets/Screen Shot 2022-08-22 at 16.58.21.png>)

#### View request or response details

View request details by clicking the desired operation.

![Request/Response details](<../.gitbook/assets/Screen Shot 2022-08-22 at 17.00.28.png>)


Scenario Debugger



In Tools section are cool tools, which can help you in building your scenario. All of them are described in Make docs.

{% embed url="https://www.make.com/en/help/scenarios/make-devtool" %}


Tools

Best practices



## Module names

{% hint style="warning" %}
A name of a module, an RPC, or a custom IML function should not match with any reserved word in JavaScript. See the list of reserved words in JavaScript [here](https://www.w3schools.com/js/js\_reserved.asp).&#x20;
{% endhint %}

## Module labels

Every module should have a label that precisely describes the module's use. For each type of module, there is a standard naming convention. But it may change depending on the functionality of the module. The label should be composed of the verb expressing the intended action (Create, Update, Watch, etc.) and the name of the entity being processed (Customer,  Invoice,  Table, etc.).

Names of modules follow the English format - they are capitalized - Specifically, they use Title Case - refer to [Chicago Manual of Style](https://en.wikipedia.org/wiki/Title\_case#Chicago\_Manual\_of\_Style). Basically, every word is capitalized except for articles, prepositions, and conjunctions.

{% tabs %}
{% tab title="Good practice" %}
* Watch Events
* Create a Report
* Update a Record
* List Photos
* Search Files
* Add Members to a Group
* Get a Group's Info
{% endtab %}

{% tab title="Bad practice" %}
* Watch events
* Create a report
* Make a call
* List photos
* Search files
* Add members to Group
* Get group info
{% endtab %}
{% endtabs %}

### Triggers and instant triggers (webhooks) <a href="#triggers-and-instant-triggers-webhooks" id="triggers-and-instant-triggers-webhooks"></a>

These modules watch for new data in a given service and return it. Compose the label according to this pattern **Watch \<watched node>**

Examples:

* Watch Events
* Watch Photos
* Watch Deleted Files

### Actions <a href="#actions" id="actions"></a>

These modules write data into a service, modify data in the service, or retrieve a single result. Compose the label using simple verbs like **Create, Get, Update** and **Delete** and the modified or created node. Use the naming convention of the service you are implementing.

Examples:

* Create a Note
* Update a File
* Get a User
* Delete a Task

### &#x20;Searches <a href="#searches" id="searches"></a>

These modules retrieve data from the service and allow retrieving one or more results. Compose the label using simple verbs like **Search** or **List**. Use the naming convention of the service you are implementing.

Examples:

* Search Files
* List Tasks

## Module descriptions

In a few words, describe the functionality of the module. Write the description in the third person and capitalize only the first letter of the first word in the description (like a normal sentence structure).&#x20;

Example: Description for the module **Update a Time Entry:**

{% tabs %}
{% tab title="Good practice" %}
> Updates a time entry for a specific user.
{% endtab %}

{% tab title="Bad practice" %}
> Update a Time Entry for a Specific User.

{% hint style="info" %}
The description is missing "s" for word "Update". The "Time Entry" and "Specific User" should be lowercase.
{% endhint %}
{% endtab %}
{% endtabs %}

**Triggers** use the "Triggers when..." in the descriptions. For example, the description for the module **Watch New Users** should be: **"**Triggers when a new user is created."

## Names and labels of input and output parameters <a href="#names-and-labels-of-input-and-output-parameters" id="names-and-labels-of-input-and-output-parameters"></a>

For labels, try to use the same names and conventions as in the integrated service. It helps users to use the app in Make and not be confused.

For variable names, use the same names that come from the service API. It helps when debugging for both advanced Make users and support agents. Ideally, the output of the module should be the same as the response from the API.

Example:

{% tabs %}
{% tab title="Output parameters" %}
```javascript
[
    {
        "name": "id",
        "label": "ID",
        "type": "text"
    },
    {
        "name": "note",
        "label": "Note",
        "type": "text"
    },
    {
        "name": "firstName",
        "label": "First Name",
        "type": "text"
    },
    {
        "name": "shortUrl",
        "label": "Short URL",
        "type": "url"
    }
]
```
{% endtab %}

{% tab title="API response" %}
```javascript
{
    "id": "59b1396a4a22a7a3bfc78e22",
    "note": "Hey",
    "firstName": "John",
    "shortUrl": "https://trello.com/c/LdcrM4wa"
}
```
{% endtab %}
{% endtabs %}

### Abbreviations

Be sure to use the correct uppercase for abbreviated words, such as ID, IDs, URL, GPS, VAT, etc.


Names, labels & descriptions



The Base section should contain data that is common to all (or most) requests. At the very least, this should include the root URL, the authorization headers, the error-handling section, and the sanitization.

{% tabs %}
{% tab title="Right" %}
```javascript
{
    "baseUrl": "https://www.example.com/api/v1",
    "headers": {
        "Authorization": "Bearer {{connection.accessToken}}"
    },
    "response": {
        "error": {
            "message": "[{{statusCode}}] {{body.error.message}} (error code: {{body.error.code}})"
        }
    },
    "log": {
        "sanitize": [
            "request.headers.authorization"
        ]
    }
}
```
{% endtab %}

{% tab title="Wrong" %}
![](<../.gitbook/assets/Screenshot 2018-11-22 at 16.31.53.png>)
{% endtab %}
{% endtabs %}

### Base URL

{% content-ref url="../app-structure/base/base-url.md" %}
[base-url.md](../app-structure/base/base-url.md)
{% endcontent-ref %}

Make sure that the Base URL uses the URL of the API, which is shared among all modules or their majority.

{% hint style="warning" %}
In case of a request for approval of your app by Make, make sure that the base URL is a **production** **endpoint** with a domain that belongs to the app itself.&#x20;

Apps with development or staging URLs, or apps with a domain belonging to a cloud computing service, will not be approved!
{% endhint %}

When the service has a different domain for each user, the domain should be asked for in the connection and then the value should be used in the Base tab.

{% tabs %}
{% tab title="Right" %}
An example from Mailerlite app:

```
{
    "baseUrl": "https://api.mailerlite.com/api/v2"
}
```
{% endtab %}

{% tab title="Right (Different Domain)" %}
An example from Freshsales app:

```
{
    "baseUrl": "https://{{connection.domain}}.freshsales.io"
}
```
{% endtab %}

{% tab title="Wrong (Different Domain)" %}
```
{
    "baseUrl": "https://mydomain.freshsales.io"
}
```

{% hint style="info" %}
The "mydomain" should be a variable used from the Connection.
{% endhint %}
{% endtab %}

{% tab title="Wrong (app will not be approved)" %}
```
{
    "baseUrl": "https://mailerlite.heroku.com/development"
}
```
{% endtab %}
{% endtabs %}

### Authorization and sanitization

{% content-ref url="../app-structure/base/authorization.md" %}
[authorization.md](../app-structure/base/authorization.md)
{% endcontent-ref %}

{% content-ref url="../app-structure/base/sanitization.md" %}
[sanitization.md](../app-structure/base/sanitization.md)
{% endcontent-ref %}

The Base section should also have authorization, which is common for all modules. This authorization should use the API Key, Access Token, or Username and Password entered in the connection. The sanitization should hide all these sensitive parameters.

Examples of possible authorization and sanitization:

{% tabs %}
{% tab title="API Key" %}
```javascript
{
...
    "headers": {
        "Authorization": "Token {{connection.apiKey}}"
    },
    "log": {
        "sanitize": [
            "request.headers.authorization"
        ]
    }
...
}
```
{% endtab %}

{% tab title="Access Token" %}
```javascript
{
...
    "qs": {
        "access_token": "{{connection.accessToken}}"
    },
    "log": {
        "sanitize": [
            "request.qs.access_token"
        ]
    }
...
}
```
{% endtab %}

{% tab title="Basic auth" %}
```javascript
{
...
    "headers": {
        "authorization": "Basic {{base64(connection.username + ':' + connection.password)}}"
    },
    "log": {
        "sanitize": [
            "request.headers.authorization"
        ]
    }
...    
}
```
{% endtab %}

{% tab title="Secret in request body" %}
```javascript
{
...
    "body": "There is something {{parameters.secret}} hidden here.",
    "type": "raw",
    "log": {
        "sanitize": [
            "request.body<parameters.secret>"
        ]
    }
...
}
```
{% endtab %}
{% endtabs %}

### Error handling

Each service sends an error message when an error occurs. This most of the time happens when the request has wrong parameters or values or when the service has an outage. That's why error handling is required.

{% hint style="warning" %}
In case of a request for approval of your app by Make, make sure error handling is correctly implemented!
{% endhint %}

{% content-ref url="../app-structure/base/error-handling.md" %}
[error-handling.md](../app-structure/base/error-handling.md)
{% endcontent-ref %}

The error handling code should correspond to the structure of the server response.\
Let's assume that the JSON response has the following format in the cases where something goes wrong:

```
{
    "error": {
        "code": "E101",
        "message": "The company with the given ID does not exist."
    }
}
```

Here's how the error section should (and should not) look:

{% tabs %}
{% tab title="Right" %}
```javascript
"response": {
    "error": {
        "message": "[{{statusCode}}] {{body.error.message}} (error code: {{body.error.code}})"
    }
}
```

The error object in our example contains the `code` and `message` fields, but not a `text` field. It is also important to show the status code of the error, this can be accessed using the `statusCode` keyword. So in the case of HTTP error 400, the error message could look like this:

`[400] The company with the given ID does not exist. (error code: E101)`
{% endtab %}

{% tab title="Wrong" %}
```javascript
"response": {
    "error": {
        "message": "{{body.error.text}}"
    }
}
```

The error object in our example contains the `code` and `message` fields, but not a `text` field.
{% endtab %}
{% endtabs %}




Every connection should have a way how to check if the used API Key/Token is valid (Validation Endpoint). That means each connection should have a part that uses the used API Key/Token against some endpoint that requires only the API Key/Token to run. For example, User Info endpoint or any endpoint which is used to List data.

The validation endpoint is located:

* OAuth1 and OAuth2 - the `info` directive
* API Key, Basic Auth, Digest Auth, Other - the `url` which is in the Communication tab

{% hint style="info" %}
There are APIs, which don't have a validation endpoint. In this case, it is recommended to call an endpoint, which will work in every case, and if possible will return the account's data, e. g. an endpoint `/about` or `/me`, etc.
{% endhint %}

{% tabs %}
{% tab title="Right API Key" %}
![Coda (beta) connection example](../.gitbook/assets/connectionsUrlExampleOtherRight.png)

The API Key is checked against `/whoami` endpoint which in case of wrong API Key returns an error and the connection won't be created.
{% endtab %}

{% tab title="Right OAuth" %}
```
{
    "authorize": {
        ...
    },
    "token": {
        ...
    },
    "info": {
        "url": "https://api.dropboxapi.com/2/users/get_current_account",
        "method": "POST",
        "headers": {
            "authorization": "Bearer {{connection.accessToken}}"
        },
        "body": "{{null}}",
        "response": {
            "uid": "{{body.account_id}}",
            "metadata": {
                "type": "email",
                "value": "{{body.email}}"
            },
            "error": {
                "message": "[{{statusCode}}] {{if(body.error_summary, body.error_summary, body)}}"
            },
            "data": {
                "root_namespace_id": "{{body.root_info.root_namespace_id}}"
            }
        },
        "log": {
            "sanitize": [
                "request.headers.authorization"
            ]
        }
    },
    "invalidate": {
        ...
    }
}
```



An example of the "info" part of the Dropbox Oauth2 connection.
{% endtab %}

{% tab title="Wrong" %}
![](../.gitbook/assets/connectionsUrlExampleWrong.png)

There is no endpoint to check whether entered credentials like API Key, Username & Password, etc. were correct and will allow the connection to be created with anything, including wrong credentials.
{% endtab %}
{% endtabs %}

### Connection metadata

It is recommended to use the `metadata` parameter to store the account's name or email. This allows users to easily distinguish their stored connections, especially if they don't name their connections in a good manner.

{% tabs %}
{% tab title="Occurence in a module" %}
<figure><img src="../.gitbook/assets/image (21).png" alt=""><figcaption><p>Example of Connection's Name</p></figcaption></figure>

Notice the value in the brackets after the user's connection name. This value is taken from the `metadata` parameter.
{% endtab %}

{% tab title="Code" %}
```json
...
"response": {
	"metadata": {
            "type": "email", //allowed values are "email" and "text"
            "value": "{{body.data.user.email}}"
        }
},
...
```
{% endtab %}
{% endtabs %}

### Error handling

Error handling can be used from the Base tab and follows the same rules.

The only difference is where to use it in what type of connection. For example, in connection types OAuth 1.0 and OAuth 2.0, the error handling should be in the "info" part.

{% content-ref url="../app-structure/base/error-handling.md" %}
[error-handling.md](../app-structure/base/error-handling.md)
{% endcontent-ref %}


Connections



## Module types <a href="#module-types" id="module-types"></a>

Modules should be associated with the correct type, depending on their functionality. Detailed descriptions of different types of modules can be found in our [Modules](../app-structure/modules/) docs as well as in the [Best Practices](names-labels-and-descriptions.md) guide.

{% tabs %}
{% tab title="Wrong" %}
![Module of Type Action](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LC12sgBWZWwjEbbd84M%2F-LRuXwrtWjHjwWlxs\_yH%2F-LRulzHYv4JleXbJ9kkJ%2Fimage.png?alt=media\&token=8939e884-a574-4004-924e-ceea29507739)

The module can return more than one campaign object, so it should be of the type [Search](https://docs.integromat.com/apps/app-structure/modules/search).
{% endtab %}

{% tab title="Right" %}
![Module of Type Search](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LC12sgBWZWwjEbbd84M%2F-LRuXwrtWjHjwWlxs\_yH%2F-LRunBR7fs5Nfzi060G3%2FScreenshot%202018-11-22%20at%2010.41.40.png?alt=media\&token=040eafea-f976-4d57-8f93-edbf2ffaa71b)

The module can return more than one campaign object, so it should be of type [Search](https://docs.integromat.com/apps/app-structure/modules/search).
{% endtab %}
{% endtabs %}

## Universal module

Each app should have a universal module. This module is there to allow users to use not supported API endpoints using their connection created to the app.

More about this module can be found [here](../app-structure/modules/universal-module/).

Make sure this module has:

* correct label and description,
* correct `url` which starts with the base URL,
* correct connection.

## Using the base URL <a href="#using-the-base-url" id="using-the-base-url"></a>

All of the modules should build on top of `baseURL` from the Base section (simply by starting with a forward slash `/`). It is very unlikely that a single module will need to have a completely different URL than the rest.

{% tabs %}
{% tab title="Wrong" %}
![Example of Wrong URL](../.gitbook/assets/integromatModulesUrlWrong.png)

The underlined part which is the same for each module should be in the Base tab.
{% endtab %}

{% tab title="Right" %}
![Example of Correct URL](<../.gitbook/assets/integromatModulesUrlRight (1).png>)

Modules "url" should start with forward slash `/`
{% endtab %}
{% endtabs %}


Modules



Suppose you want to retrieve all users, that are registered on your service. You can’t use [**Action**](https://integromat.github.io/apps/action.html), because it returns only a single result. You will have to create a [**Search**](https://integromat.github.io/apps/searches.html) module for this.

The communication for [**Search**](https://integromat.github.io/apps/search.html) is the same as for **Action**, except **Search** has an [`iterate`](https://integromat.github.io/apps/search.html#iterate) directive, which specifies where are the items located inside the body.

For the next example, suppose that when you call `/users` on your service, you will get a list of users in `body.data`.

This example will correctly output each user that was returned:

```javascript
{
    "url": "/users",
    },
    "response": {
        "output": "{{item}}",
        "iterate": "{{body.data}}",
        "limit": "{{parameters.limit}}"
    }
}
```

## Iteration and pagination <a href="#iteration-and-pagination" id="iteration-and-pagination"></a>

An [Action](https://docs.integromat.com/apps/app-structure/modules/action) module should never contain `pagination` or the `iterate` directive. If you need to return multiple objects, create a [Search](https://docs.integromat.com/apps/app-structure/modules/search) module instead.

{% tabs %}
{% tab title="Wrong" %}
![Example of Wrong Implementation of Search Endpoint as Action Module](../.gitbook/assets/integromatIterationPaginationWrong.png)
{% endtab %}

{% tab title="Right" %}
![Example of Correct Implementation of Search Module and Pagination Directive](../.gitbook/assets/integromatIterationPaginationRight.png)
{% endtab %}
{% endtabs %}

## Pagination parameters <a href="#pagination-parameters" id="pagination-parameters"></a>

The `pagination` section should only contain parameters directly influencing the actual pagination. These will be merged with the rest of the parameters defined in the `qs` section, so there is no need to define them all again.

{% tabs %}
{% tab title="Wrong" %}
![Example of Wrong Implementation of Pagination Directive](<../.gitbook/assets/integromatPaginationParamsWrong (1).png>)

{% hint style="info" %}
The pagination directive contains `"since"`, `"until"` and `"limit"` parameters that are already defined in query string ("qs").&#x20;
{% endhint %}
{% endtab %}

{% tab title="Right" %}
![Example of Correct Implementation of Pagination Directive](../.gitbook/assets/integromatPaginationParamsRight.png)

{% hint style="info" %}
The pagination contains only the `"offset"` parameter.
{% endhint %}
{% endtab %}
{% endtabs %}

## Limiting output

The modules type Search and Trigger(polling) should return everything including by pagination. However, these modules should also allow users to limit their output, that is, how many bundles they return.

This can be achieved by setting up the [`limit`](https://docs.integromat.com/apps/structure-blocks/api/handling-responses#limit) parameter in the response. By default, this parameter is added to the Trigger (polling) modules and should be required. In Search modules, this parameter should NOT be required so if a user leaves it empty, the Search modules return everything. Its default value should be set to 10.

Search module limit example:

{% tabs %}
{% tab title="Communication" %}
```javascript
{
    "url": "/clients",
    "method": "GET",
    "qs": {
        "per_page": 100
    },
    "response": {
        "limit": "{{parameters.limit}}",
        "output": "{{item}}",
        "iterate": "{{body.clients}}"
    },
    "pagination": {
        "qs": {
            "page": "{{pagination.page}}"
        },
        "condition": "{{body.next_page}}"
    }
}
```
{% endtab %}

{% tab title="Mappable parameters" %}
```javascript
[
    {
        "name": "limit",
        "label": "Limit",
        "type": "uinteger",
        "help": "Number of clients to return",
        "default": 10
    }
]
```

{% hint style="warning" %}
The `limit` parameter should not be set to `"required":true` (except for polling trigger modules).\
The `limit` parameter should never be set to `"advanced":true`.
{% endhint %}
{% endtab %}
{% endtabs %}


Action and search modules



## Responsiveness approaches

Bear in mind that there are two approaches to responsiveness in a service.

* **Synchronous** - The service upon an action request returns a result, which can then be processed in the following modules in a scenario.
* **Asynchronous** - The service doesn't return anything at all, or doesn't return useful output, e. g. a processed file.

## Comparison of synchronous and asynchronous approaches

<table><thead><tr><th width="159">Attribute/ Approach</th><th>Synchronous</th><th>Asynchronous</th></tr></thead><tbody><tr><td><strong>Advantage</strong></td><td>The result is returned right away. Ability to proceed the result to the following modules.</td><td>Comes in handy when we need to process a large amount of data, e. g. file conversion.</td></tr><tr><td><strong>Disadvantage</strong></td><td>Regarding the type of job and its severity, the job can take too long. This might cause a timeout (default 40 sec). E. g. file conversion. The default timeout can be prolonged depending on the valid cases.</td><td>The scenario is not fluent. It is needed to create at least 2 scenarios - one for triggering the job, and another one for proceeding with the result from the first scenario. The second scenario, if possible, should start with an instant trigger that triggers once the job finishes.</td></tr><tr><td><strong>Module Example</strong></td><td><a href="https://eu1.make.com/apps/cloudconvert/2/modules/ConvertFile/communication">CloudConvert > Convert a File</a></td><td><a href="https://eu1.make.com/apps/cloudconvert/2/modules/CreateJob/communication">CloudConvert > Create a Job (advanced)</a></td></tr><tr><td><strong>Example Scenarios</strong></td><td><p><a href="https://www.make.com/en/templates/3064-convert-files-from-google-drive-in-cloudconvert-and-upload-the-output-to-google-drive">Convert files from Google Drive in CloudConvert</a> </p><p>The scenario contains <a href="https://eu1.make.com/apps/cloudconvert/2/modules/ConvertFile/communication">Convert a File</a> module, which has the synchronous logic implemented on app's side.</p></td><td><ol><li><a href="https://www.make.com/en/templates/3074-advanced-create-a-job-in-cloudconvert-archive-export-per-1-file">Create an archive job in CloudConvert</a></li><li><a href="https://www.make.com/en/templates/3062-advanced-create-a-new-job-for-export-url-tasks-download-files-from-export-url-tasks-in-cloudconvert">Download files from the job in CloudConvert</a> </li></ol><p>The first scenario contains <a href="https://eu1.make.com/apps/cloudconvert/2/modules/CreateJob/communication">Create a Job (advanced)</a> module which has asynchronous approach by default. The only result is the job's ID.</p></td></tr></tbody></table>

## Handling of asynchronous approach

When a web service doesn't support a synchronous approach and the common use case of the module requires support, it should be added on the app's side. Basically, there should be two (or more calls) executed instead of only one:

* **create a job call** - a call that requests for the job, e. g. conversion of a file, file upload,
* **periodically check the status of the job -** execute repeated calls to obtain the job's status**,**
* **ask for the result of the job -** once the status call returns the awaited status, request the result, e. g. result file.

### Example

After importing a JSON file to a web service, it requires a certain period of time to process the file. In this case, we have to keep checking if the status of the entity changed from `processing` to `completed`. In this case, when the status is `completed`, the result is already part of the response.

{% hint style="warning" %}
When the repeat directive is used, the **condition** and **limit** should always be provided to **prevent** **infinite** **loops**. Learn more about the [repeat](../app-blocks/api/making-requests.md#repeat) directive.
{% endhint %}

```javascript
[
	{
		"url": "/v3/activities/contacts_json_import",
		"method": "POST",
		"body": "{{encodeParameters(parameters)}}",
		"response": {
			"temp": "{{parseResponse(body)}}"
		}
	},
	{
		"url": "{{temp._links.self.href}}",
		"method": "GET",
		"repeat": {
			"condition": "{{body.state != 'completed'}}",
			"delay": 1000,
			"limit": 300
		},
		"response": {
			"temp": "{{body}}"
		}
	},
	{
		"response": {
			"valid": "{{length(temp.activity_errors) = 0}}",
			"error": {
				"message": "{{join(temp.activity_errors, '\n')}}"
			},
			"output": "{{parseResponse(temp)}}"
		}
	}
]
```


Action modules



## Support for query and filtering options

Certain APIs provide support for custom queries or filters when searching records, such as invoices. In Make, our goal is to offer query and filter capabilities to both regular and advanced users.

Therefore, we have implemented two methods of achieving this functionality, and ideally, users should be able to choose between the two options.

#### A predefined query

We have utilized the familiar filter setup format found in Scenario Builder. With this approach, users are not required to learn the query format. Instead, they can simply set up the query in a manner similar to configuring filters.&#x20;

When the module is executed, a custom IML function constructs the query, adhering to the specified format.

#### A custom query

Users have the option to manually compose their own queries. This feature is particularly valuable when the API supports new operators that are not yet available within the module.

To assist users in leveraging the query field effectively, the following helpful information should be provided:

* Query format: The guidelines for structuring the query.
* Example of a functional query: An illustrative sample query as reference.
* API documentation URL: Direct access to the API documentation with query specification.

{% tabs %}
{% tab title="Filters in a module" %}
<figure><img src="../.gitbook/assets/Screenshot 2023-05-17 at 12.25.59 (1).png" alt=""><figcaption><p>Example of filters</p></figcaption></figure>

{% hint style="info" %}
Notice, that the operators are grouped by a category.
{% endhint %}
{% endtab %}

{% tab title="Query in a module" %}
<figure><img src="../.gitbook/assets/Screenshot 2023-05-17 at 12.24.57.png" alt=""><figcaption><p>Example of a query</p></figcaption></figure>

{% hint style="info" %}
Notice the available `AND` rule.
{% endhint %}
{% endtab %}

{% tab title="Custom query in a module" %}
<figure><img src="../.gitbook/assets/Screenshot 2023-05-17 at 12.28.38.png" alt=""><figcaption><p>Example of a custom query</p></figcaption></figure>

{% hint style="info" %}
Notice the help containing the query pattern and the valid query example together with a link to available docs.
{% endhint %}
{% endtab %}

{% tab title="Mappable parameters" %}
```json
[
   {
      "name":"type",
      "label":"Search by",
      "type":"select",
      "required":true,
      "mappable":false,
      "options":[
         {
            "label":"field",
            "value":"filter",
            "nested":[
               {
                  "name":"filter",
                  "label":"Filter",
                  "type":"filter",
                  "grouped":false,
                  "options":{
                     "logic":"and", // --> to support AND only
                     // "logic": "or", --> to support OR only
                     // do not use "logic" parameter --> to support both
                     "store":[
                        {
                           "label":"Status",
                           "value":"Status"
                        },
                        {
                           "label":"Invoice number",
                           "value":"invoiceNumber"
                        }
                     ],
                     "operators":[
                        {
                           "label":"Text",
                           "options":[
                              {
                                 "label":"Contains",
                                 "value":"CTSTR"
                              },
                              {
                                 "label":"Equals",
                                 "value":"EQ"
                              }
                           ]
                        },
                        {
                           "label":"Number",
                           "options":[
                              {
                                 "label":"Less than",
                                 "value":"LT"
                              },
                              {
                                 "label":"More than",
                                 "value":"GT"
                              }
                           ]
                        }
                     ]
                  }
               }
            ]
         },
         {
            "label":"user-defined condition",
            "value":"query",
            "nested":[
               {
                  "name":"query",
                  "label":"Query",
                  "type":"text",
                  "help":"Example: `{FIELD_NAME}~{OPERATOR}~{VALUE}|AND|{FIELD_NAME}~{OPERATOR}~{VALUE}`. E.g. `customer_id~GT~1234|AND|status~EQ~Open`. More examples how to use filters are in [docs](https://myapi.com/how-to-use-filters).",
                  "required":true
               }
            ]
         }
      ]
   },
   {
      "name":"limit",
      "label":"Maximum number of returned invoices",
      "default":10,
      "type":"uinteger"
   }
]
```

{% hint style="info" %}
Notice the parameter `logic` that defines the logical relationship between different conditions within a query.

Supported values are `AND` and/or `OR.`
{% endhint %}
{% endtab %}

{% tab title="Communication" %}
```json
{
    ...
    "qs": {
        "filter": "{{if(parameters.type === 'filter', filter(parameters.filter), parameters.query)}}"
    },
    ...
```

{% hint style="info" %}
Notice that a custom IML function `filter` is used in order to properly build the query.
{% endhint %}
{% endtab %}

{% tab title="Custom IML Function" %}
```javascript
function filter(filter) {

    if(!filter) return;

    return filter[0].map(and => {
        if(!and.a && !and.o && !and.b) return;
        return `${and.a}~${and.o}~${and.b}`;
    }).join('|AND|');

}
```

{% hint style="info" %}
The parameters `a`, `o`, and `b` represent the following:

`a` = name of the parameter, e.g. `status`

`o` = operator, e.g. `EQ`

`b` = value, e.g. `open`

Example of the output query:

`invoiceNumber~GT~1234|AND|status~EQ~Open`
{% endhint %}
{% endtab %}
{% endtabs %}


Search modules



## Update approaches

Bear in mind that there are two approaches to updating entries in a service.

* **Partial Update** - The service updates only specified parameters sent in the API request and other empty parameters will be unchanged. This is the most common approach for APIs.
* **Full Update** - The service requires all parameters to be updated in an update request. If some parameters are omitted, then they will be cleared or overridden to default values in the service. This is extremely user-unfriendly and should be avoided.

## Handling of full update approach

If the API doesn't support a partial update approach, it is needed to add the support on the app's side. Basically, there should be two calls executed instead of only one:&#x20;

* **GET** call - a call that retrieves the current record and saves it in `temp`,
* **UPDATE** call - an update request which contains the user's input merged with the missing parameters from `temp`.

{% hint style="info" %}
Thanks to the handling of the full update approach on the app's side, the user experience will be consistent with all Make apps. Users will not have to handle full updates by themselves or experience data loss.
{% endhint %}

### Example using OR directive

If there are a few parameters available, you can use simple OR `(||)` directive, which ensures that if there is no value in the particular parameter available, the value from `temp` is mapped instead.

#### Communication

```
[
    {
        "url": "/contacts/{{parameters.id}}",
        "method": "GET",
        "response": {
            "temp": {
                "fields": "{{body}}"
            }
        }
    },
    {
        "url": "/contacts/{{parameters.id}}",
        "method": "PUT",
        "body": {
            "name": "{{parameters.name || temp.name}}",
            "email": "{{parameters.email || temp.email}}"
        },
        "response": {
            "output": "{{body}}"
        }
    }
]
```

### Example 2 - IML function

If there are a lot of parameters available, it is worth writing an IML function, which merges the parameters with the output from `temp`.

#### Communication

```javascript
[
    {
        "url": "/contacts/{{parameters.id}}",
        "method": "GET",
        "response": {
            "temp": {
                "fields": "{{body}}"
            }
        }
    },
    {
        "url": "/contacts/{{parameters.id}}",
        "method": "PUT",
        "body": {{updateContact(parameters, temp.fields)}},
        "response": {
            "output": "{{body}}"
        }
    }
]
```

#### IML Function&#x20;

```javascript
function updateContact (parameters, temp) {
     return {
         ...temp,
         ...parameters
     };
}
```

### Example 3 - considerating read-only parameters

There might be read-only parameters, which can't be updated, e. g. `CreatedAt` and `UpdatedAt` parameters. In this case, it is needed to ensure these parameters will be omitted.&#x20;

You can do it by mapping only the parameters, which are allowed, see the [Example using OR Directive](update-modules.md#example-using-or-directive). Or you can implement IML function, see below.

#### IML Function

```javascript
function updates (parameters, temp) {

     function omit(obj, ...props) {
        const result = { ...obj };
        props.forEach(function(prop) {
            delete result[prop];
        });
        return result;
    }

     temp = omit(temp, 'id', 'createdAt', 'updatedAt');
     parameters = omit(temp, 'id');
     //or you can use `iml.omit (temp, 'id', 'createdAt', 'updatedAt')`

     return {
         ...temp,
         ...parameters,
         birthday: parameters.birthday ? iml.formatDate(parameters.birthday, 'YYYY-MM-DD') : temp.birthday
         // additionally you can modify extra fields if necessary. 
     };
}
```


Update modules



## Epoch in polling trigger

The trigger module has an Epoch section that defines what "Choose where to start" looks like. This section is an RPC that uses everything in COMMUNICATION including the pagination. This means there can be an issue if the user has too many objects which could be returned by this RPC so that is why a `"limit"` parameter should be specified here.

‌ The "limit" parameter should be a static number which should be at max 300 or 3 \* number of objects per page.

{% tabs %}
{% tab title="Wrong" %}
![No "limit" parameter](../.gitbook/assets/integromatTriggerEpochWrong.png)
{% endtab %}

{% tab title="Right" %}
![](../.gitbook/assets/integromatTriggerEpochRight.png)
{% endtab %}
{% endtabs %}

## API endpoint requires `from` and/or `to` date parameters

Some API services require `date` parameters that define the interval of records to be retrieved, e.g. `from` and `to`, `fromDate` and `toDate`, etc.

In this case, it is important to handle the `date` parameters correctly.

{% tabs %}
{% tab title="Wrong" %}
<figure><img src="../.gitbook/assets/Screenshot 2023-06-22 at 15.33.27.png" alt=""><figcaption><p>From and To parameters required from the user</p></figcaption></figure>

{% hint style="info" %}
Notice the `From` and `To` parameters that are required.

Since triggers don't allow mapping/functions, the user has to "hardcode" the `From` and `To` dates. Therefore, Make will always request the same interval of records.
{% endhint %}
{% endtab %}

{% tab title="Right" %}
<figure><img src="../.gitbook/assets/Screenshot 2023-06-22 at 13.24.37.png" alt=""><figcaption><p>Start Date and End Date are not available to user</p></figcaption></figure>

{% hint style="info" %}
Notice there is no `From` or `To` available to the user.
{% endhint %}
{% endtab %}

{% tab title="Communication Code" %}
```javascript
...
"qs": {
         "from": "{{data.lastDate}}",
         "to": "{{now}}"
      },
...

```

{% hint style="info" %}
Notice  the mapped `data.lastDate` [IML variable](https://docs.integromat.com/apps/app-structure/modules/trigger#available-iml-variables) that is available in polling triggers.&#x20;

This variable is available to the user in **Choose where to start** setting.
{% endhint %}

<figure><img src="../.gitbook/assets/Screenshot 2023-06-22 at 13.41.16 (1).png" alt=""><figcaption><p>Choose where to start feature</p></figcaption></figure>

**The behavior of the supported options:**

* **From now on** - The current date will be sent.
* **Since specific date** - The date provided will be sent.
* **Choose manually** - The date of the chosen item will be sent.
* **All** - The default date `1970-01-01` will be sent.
{% endtab %}
{% endtabs %}



Trigger modules



## Use cases of RPCs

Remote procedures are used to get live data from a service. More information about remote procedures can be found [here](../app-structure/rpcs/).

Use RPCs for every field that accepts parameters like IDs and other stuff that is hard to guess or get for users.

{% tabs %}
{% tab title="Appearence in a Module" %}
<figure><img src="../.gitbook/assets/Screen Shot 2022-09-07 at 14.45.27.png" alt=""><figcaption><p>Example of RPC</p></figcaption></figure>
{% endtab %}

{% tab title="Mapping Mode" %}
<figure><img src="../.gitbook/assets/Screen Shot 2022-09-07 at 14.46.51.png" alt=""><figcaption><p>RPC set to Mapping Mode</p></figcaption></figure>

{% hint style="info" %}
Notice, that in the mapping mode, user has to enter/map option's ID instead of the label.
{% endhint %}
{% endtab %}
{% endtabs %}

Also, RPCs come in handy in a case, when a user only needs to understand the functionality of the module, mostly the list of available parameters in the interface. In this case, the aim is not to offer a complete list of all items, but a sample of the last 100 or so items the user could select from when testing the module or setting up the scenario for the first time, before replacing it with mapped data used in automation.

## Mode edit

When adding an RPC to a **Get**, **Update,** or **Delete** module, it is required to add:

```
"mode": "edit",
```

to the code so when a user first opens the module, they will be able to immediately map the value. However, if needed, they can also switch to getting the value from an RPC.

{% tabs %}
{% tab title="Good Practice" %}
```javascript
{
    "name": "userId",
    "type": "select",
    "label": "User ID",
    "options": "rpc://getUsers",
    "mode": "edit"
}
```
{% endtab %}

{% tab title="Bad Practice" %}
```javascript
{
    "name": "userId",
    "type": "select",
    "label": "User ID",
    "options": "rpc://getUsers"
}
```
{% endtab %}
{% endtabs %}

When it comes to **Search**/**List** modules, it **depends** on the hierarchy level of the entity. If the entity is up in the hierarchy, e.g. a “customer” or a “deal”, and there are not many RPCs in the input, they **should not** have the mode set to “edit”. However, if the entity is low in the hierarchy, e.g. "E-mail attachment", it **should** have the mode set to “edit” since the user will probably not want to list attachments of a single e-mail repeatedly.

<figure><img src="../.gitbook/assets/Screen Shot 2022-09-07 at 14.36.04.png" alt=""><figcaption><p>Example of List Module with RPC with Mode Edit Set</p></figcaption></figure>

Finally, a **Create** module **should not** have the mode set to "edit", **unless it contains a very large number of RPCs in its input**. This is because pre-loading a large number of RPCs would significantly increase the waiting time for the user.

## Pagination and limits

Just like modules, RPCs can use pagination to show more records than just the ones on the first page. However, limits should be also set on how many objects the RPC shows so it doesn't load forever.

The limit should be between 300-500 if the API returns 100 or more objects per page. If the API returns less than 100 per page, then the limit should be 3 times the amount of objects per page.

For example, if API returns 25 records per page, the limit should be 75. You can also set a condition for the pagination to stop further requests when no more data is needed.

{% tabs %}
{% tab title="Right" %}
```json
 {
	"url": "/contacts",
	"method": "GET",
	"qs": {
		"pageSize": 25
	},
	"response": {
		"limit": 75
		"output": {
			"label": "{{item.displayname}}",
			"value": "{{item.id}}"
		},
		"iterate": "{{body.data}}"
	},
	"pagination": {
		"condition": "{{pagination.page <= 3}}",
		"qs": {
			"page": "{{pagination.page}}"
		}
	}
}
```
{% endtab %}

{% tab title="Wrong (no limit)" %}
```json
 {
	"url": "/contacts",
	"method": "GET",
	"qs": {
		"pageSize": 25
	},
	"response": {
		"output": {
			"label": "{{item.displayname}}",
			"value": "{{item.id}}"
		},
		"iterate": "{{body.data}}"
	},
	"pagination": {
		"qs": {
			"page": "{{pagination.page}}"
		}
	}
}
```

![Example of Missing Limit](../.gitbook/assets/integromatRpcsLimitWrong.png)
{% endtab %}
{% endtabs %}


Remote Procedure Calls



The Static Parameters tab is deprecated and should be left empty. All fields should be inside the Mappable parameters.

{% tabs %}
{% tab title="Wrong" %}
![Wrongly Used Static Parameters Tab](<../.gitbook/assets/integromatStaticParametersWrong (1).png>)
{% endtab %}

{% tab title="Right" %}
![Correctly Used Static Parameters Tab](../.gitbook/assets/integromatStaticParametersRight.png)
{% endtab %}
{% endtabs %}

##


Static parameters



## Order of the mappable Parameters

The mappable parameters should follow this priority order:

1. **required** parameters
2. optional parameters
3. **advanced** parameters

{% hint style="warning" %}
**Advanced** parameters should never be **required.**
{% endhint %}

{% tabs %}
{% tab title="Wrong" %}
![Example of Wrong Mappable Parameters](../.gitbook/assets/integromatMappableParamsOrderWrong.png)
{% endtab %}

{% tab title="Right" %}
![Example of Correct Mappable Parameters](../.gitbook/assets/integromatMappableParamsOrderRight.png)
{% endtab %}
{% endtabs %}

When defining the input parameters, try to use the same order as in the integrated service. Place required parameters at the top if it is possible. Position parameters in logical groups.

{% tabs %}
{% tab title="Good practice" %}
```javascript
[
    {
        "name": "firstName"
        "type": "text",
        "label": "First Name"
    },
    {
        "name": "lastName"
        "type": "text",
        "label": "Last Name"
    },
    {
        "name": "email"
        "type": "email",
        "label": "Email"
    },
    {
        "name": "taskId"
        "type": "number",
        "label": "Task ID"
    }
]
```
{% endtab %}

{% tab title="Bad practice" %}
```javascript
[
    {
        "name": "firstName"
        "type": "text"
    },
    {
        "name": "taskId"
        "type": "number"
    },
    {
        "name": "lastName"
        "type": "text"
    },
    {
        "name": "email"
        "type": "email"
    }
]
```
{% endtab %}
{% endtabs %}

### Helps under parameters

Using a help directive, you may specify a hint of what is expected for the parameter when it is not that obvious from the label or the expected value is more complicated. The text should start with a capital letter and end with a period. Supports Markdown, such as  `_italic_`, `**bold**`, `` `monospace` ``, `\n` , or URL `[example](http://example.com)`.

Example:

{% tabs %}
{% tab title="Mappable Parameters" %}
```javascript
{
    "value": "object",
    "label": "Collection or JSON",
    "nested": [
        {
            "name": "metadata",
            "label": "Metadata",
            "help": "Map a Collection or enter JSON in format `{\"key\": \"value\"}` where value can be any type from [Intercom Event Metadata types](https://developers.intercom.com/intercom-api-reference/v1.0/reference#event-metadata-types).\nFor example:\n`{\"order_name\": \"Order123\",\"price\": {\"currency\": \"eur\", \"amount\": 12345}}`\nMaximum 5 entries.",
            "type": "any"
        }
    ]
}
```
{% endtab %}

{% tab title="Appearence in module" %}
![Example of a Help](<../.gitbook/assets/Apps Doc - helpExampleAppearenceGood.png>)
{% endtab %}
{% endtabs %}

### **Advanced parameters** <a href="#advanced-parameters" id="advanced-parameters"></a>

Services like CRMs use large amounts of input parameters. In these cases, you can mark less important parameters as **advanced**_._ When the parameter is marked as advanced, then by default it isn't shown in the GUI. It can be found in the advanced parameters instead after the user clicks on **Show advanced settings**.&#x20;

Example:

```javascript
{
    "name": "externalId",
    "label": "External ID",
    "type": "text",
    "advanced": true
}
```


Mappable parameters



## Mapping parameters

### Mapping all parameters

{% tabs %}
{% tab title="Communication - Bad practice" %}
```json
{
    ...
    "body": {
        "firstName": "{{parameters.firstName}}",
        "lastName": "{{parameters.lastName}}",
        "email": "{{parameters.email}}"
    },
    ...
}
```

{% hint style="info" %}
Notice, that you have to map every single parameter correctly.&#x20;

There is a risk of a typo or omission of a parameter.
{% endhint %}
{% endtab %}

{% tab title="Communication - Good practice" %}
```json
{
    ...
    "body": "{{parameters}}",
    ...
}
```

{% hint style="info" %}
Thanks to this approach, all parameters from the modules will be sent to the API.
{% endhint %}
{% endtab %}

{% tab title="Mapping parameters" %}
```json
[
    {
        "name": "email",
        "type": "email",
        "label": "Email address",
        "required": true
    },
	{
        "name": "firstName",
        "type": "text",
        "label": "First Name",
        "required": true
    },
    {
        "name": "lastName",
        "type": "text",
        "label": "Last Name",
        "required": true
    }
]
```
{% endtab %}
{% endtabs %}

### Using an IML function or omitting a parameter

Sometimes, you don't want to map all parameters in the `body` for some reason:

* the parameter shouldn't be sent at all (technical parameters such as selects, etc.)
* the parameter should be sent somewhere else than in the `body`, e.g. in the `url`
* the parameter has to be wrapped in an IML or custom IML function

{% tabs %}
{% tab title="Communication - Bad practice" %}
```json
{
    "url": "/contact/{{parameters.id}}",
    "method": "PUT",
    "body": {
        "email": "{{parameters.email}}",
        "firstName": "{{parameters.firstName}}",
        "lastName": "{{parameters.lastName}}",
        "registrationDate": "{{formatDate(parameters.registrationDate, 'YYYY-MM-DD')}}"
        
    },
    ...
}
```

{% hint style="info" %}
Notice, that you have to map every single parameter correctly.&#x20;

There is a risk of a typo or omission of a parameter.
{% endhint %}
{% endtab %}

{% tab title="Communication - Good practice" %}
```json
{
    "url": "/contact/{{parameters.id}}",
    "method": "PUT",
    "body": {
        "{{...}}": "{{omit(parameters, 'id', 'registrationDate')}}",
        "registrationDate": "{{formatDate(parameters.registrationDate, 'YYYY-MM-DD')}}"
        
    },
    ...
}
```

{% hint style="info" %}
Notice, that `"{{...}}"` lists all available parameters from the module and allows adding other parameters.&#x20;

The `omit()` function allows the removal of parameters, that are used somewhere else, shouldn't be used, or require special attention.&#x20;

In this case, the `id` parameter is already used in the url, and the `registrationDate` parameter is wrapped in `formatDate` IML function.
{% endhint %}
{% endtab %}

{% tab title="Mapping parameters" %}
```json
[
    {
        "name": "id",
        "type": "string",
        "label": "Contact ID",
        "required": true
    },
    {
        "name": "email",
        "type": "email",
        "label": "Email address"
    },
	{
        "name": "firstName",
        "type": "text",
        "label": "First Name"
    },
    {
        "name": "lastName",
        "type": "text",
        "label": "Last Name"
    },
    {
        "name": "registrationDate",
        "type": "date",
        "label": "Date of Registration"
    }
]
```
{% endtab %}
{% endtabs %}

## Handling arrays, nulls, and empty strings

Make and other third-party services transport values in many different formats. It is important to know how to handle the value types of _arrays, nulls, and empty strings_.

### **Bad practices**

{% tabs %}
{% tab title="Omitting of null or empty string parameteres" %}
```javascript
{
    "url": "/messages.json",
    "method": "POST",
    "body": {
        "status": "active",
        "content": "{{ifempty(parameters.content, undefined)}}"
    },
    ...
}
```

It isn't possible to send a `null` value to a service.

```javascript
{
    "url": "/messages.json",
    "method": "POST",
    "body": {
        "status": "active",
        "content": "{{if(parameters.content, paramteres.content, undefined)}}"
    },
    ...
}
```

It isn't possible to send a `null`, empty string, and 0 (zero) value to a service.
{% endtab %}

{% tab title="Omitting of empty arrays" %}
```javascript
{
    "url": "/tasks.json",
    "method": "POST",
    "body": {
        "status": "active",
        "tags": "{{if(length(parameters.tags) > 0, paramters.tags, undefined)}}"
    },
    ...
}
```

It isn't possible to send empty array to a service. _E.g. User wants to remove all tags from a task._
{% endtab %}
{% endtabs %}

Let users decide what parameters they want to send to the service. Make has a feature to show how to process values. This feature allows users to define exactly how Make should behave when the value is "empty". For example, if a user defines that they want to send a specific field  to a service even if the value is `null` , empty string, or an empty array,  it will be sent to the service. In module communication, config passes parameters without any modification.

## Date parameters

When a field is a type "date", it should be possible to use our keyword "now" as a value, which means, the field should accept ISO-8601 date format and if the service requires only the date (no time) or a different format like timestamp, this formatting should happen inside the module.

{% hint style="warning" %}
Users of the app should never be prompted to format the date inputs the way API requires! Such apps will not be approved by Make.
{% endhint %}

{% tabs %}
{% tab title="Good Practice" %}
**Communication**:

```javascript
{
    "url": "/api/users",
    "method": "POST",
    "body": {
        "name": "{{parameters.name}}",
        "birthday": "{{formatDate(parameters.birthday, 'YYYY-MM-DD')}}",
        "due_date": "{{formatDate(parameters.due_date, 'X')}}"
    },
    "response": {
        "output": "{{body}}"
    }
}
```

{% hint style="success" %}
Parameter `birthday` is required to have format YYYY-MM-DD and parameter `due_date` is required to be a timestamp by the service, so the formatting happens inside the Communication part of the module.
{% endhint %}

**Parameters**:

```javascript
[
    {
        "name": "name",
        "type": "text",
        "label": "Name"
    },
    {
        "name": "birthday",
        "type": "date",
        "label": "Birthday"
    },
    {
        "name": "due_date",
        "type": "date",
        "label": "Due Date"
    }
]
```

{% hint style="success" %}
The parameters `birthday` and `due_date` are correctly **date** typed and don't need to be formatted by the user, he can freely work with `now` keyword.
{% endhint %}
{% endtab %}

{% tab title="Bad Practice" %}
**Communication**:

```javascript
{
    "url": "/api/users",
    "method": "POST",
    "body": {
        "name": "{{parameters.name}}",
        "birthday": "{{parameters.birthday}}",
        "due_date": "{{parameters.due_date}}"
    },
    "response": {
        "output": "{{body}}"
    }
}
```



{% hint style="danger" %}
Parameter `birthday` is required to have format YYYY-MM-DD and parameter `due_date` is required to be a timestamp but nothing is done with the value.
{% endhint %}



**Parameters**:

```javascript
[
    {
        "name": "name",
        "type": "text",
        "label": "Name"
    },
    {
        "name": "birthday",
        "type": "date",
        "label": "Birthday",
        "help": "Format YYYY-MM-DD"
    },
    {
        "name": "due_date",
        "type": "integer",
        "label": "Due Date",
        "help": "Enter a timestamp"
    }
]
```

{% hint style="danger" %}
The parameter `due_date` is an incorrect type and `birthday` is required to be formated by the user.
{% endhint %}
{% endtab %}
{% endtabs %}

## Query String (QS)

The query string parameters should be defined using the `qs` object in order not to be embedded directly in the URL. Embedded parameters are those parameters that are after a question mark.

This will enforce the correct encoding of both static and dynamic parameters.

{% tabs %}
{% tab title="Wrong" %}
![Example of Wrong Implementation of Parameters in URL](../.gitbook/assets/integromatQueryStringWrong.png)
{% endtab %}

{% tab title="Right" %}
![Example of Correct Implementation of Parameters in QS](../.gitbook/assets/integromatQueryStringRight.png)
{% endtab %}
{% endtabs %}

If you need to specify a query string parameter, you can do:

```javascript
{
    "url": "http://yourservice.com/api/users/{{parameters.userId}}?includeAdvanced={{parameters.advanced}}"
}
```

But a better way is to use a special `qs` collection.

The `headers`, `qs`, and `body` collections represent request headers, query string parameters, and body payload. The key is the variable/header name and the value is the variable/header value. You don’t need to escape values inside those collections.

The above request can be rewritten as:

```javascript
{
    "url": "http://yourservice.com/api/users/{{parameters.userId}}",
    "qs": {
        "includeAdvanced": "{{parameters.advanced}}"
    }
}
```

{% hint style="info" %}
**NOTE**: `qs` and `headers` are single-level collections, meaning that you cannot specify nested objects in their parameters:
{% endhint %}

```
{
    "qs": {
        "someProp": {
            "anotherOne": {
                "and-one-more": "THIS WILL NOT WORK"
            }
        }
    }
}
```

**The example above will not work**. But if you want dot notation for some reason, you can use it directly in the parameter name:

```javascript
{
    "qs": {
        "someProp.anotherOne.and-one-more": "THIS WILL WORK"
    }
}
```

This will create a query string that looks like this: `?someProp.anotherOne.and-one-more=THIS%20WILL%20WORK`



Processing of input parameters



## How to process the API response <a href="#how-to-process-the-api-response" id="how-to-process-the-api-response"></a>

The best approach is to return the API response as it is. In many cases, the response varies based on the user who is using the app, as responses can contain different custom fields, etc. If the response returned is unchanged, and if still all the parameters aren't described in the **output parameters**, Make will automatically learn additional parameters from actual incoming data and propose them for mapping.

{% tabs %}
{% tab title="Good practice (Search)" %}
```javascript
"response": {
    "output": "{{item}}",
    "iterate": "{{body}}"
}
```
{% endtab %}

{% tab title="Bad practice (Search)" %}
```javascript
"response": {
    "output": {
        "id": "{{item.id}}",
        "name": "{{item.name}}"
    },
    "iterate": "{{body}}"
}
```
{% endtab %}

{% tab title="Good practice (Action)" %}
```javascript
"response": {
    "output": "{{body}}"
}
```
{% endtab %}

{% tab title="Bad practice (Action)" %}
```javascript
"response": {
    "output": {
        "id": "{{body.id}}",
        "name": "{{body.name}}"
    }
}
```
{% endtab %}
{% endtabs %}

## Response output <a href="#response-output" id="response-output"></a>

A module's response output should be defined for the case when a request is fulfilled successfully. The output definition should under no conditions contain error messages (this belongs in the Base section's error handling) nor the additional metadata which may arrive bundled with the actual response information.

{% tabs %}
{% tab title="Wrong" %}
No matter the module type, the output shouldn't be defined like this:

![](../.gitbook/assets/integromatResponseOutputWrong.png)
{% endtab %}
{% endtabs %}

## Showing dates correctly

{% hint style="warning" %}
Requires IML functions enabled.
{% endhint %}

There are multiple ways how a date can be returned from the service, either as a timestamp or in any format the service finds fit. It is important to parse this date to our ISO 8601 format so it is shown in an output of the module as a date using the users' localization and timezone.

Make is using ISO 8601 format: **YYYY-MM-DDTHH:mm:ss.sssZ**

Any other format, even just without milliseconds won't be shown correctly in the output and needs to be parsed using an IML function.

{% content-ref url="../app-structure/iml-functions/parsing-a-timestamp.md" %}
[parsing-a-timestamp.md](../app-structure/iml-functions/parsing-a-timestamp.md)
{% endcontent-ref %}

{% content-ref url="../app-structure/iml-functions/parsing-a-date.md" %}
[parsing-a-date.md](../app-structure/iml-functions/parsing-a-date.md)
{% endcontent-ref %}

## Interface

The interface describes the structure of output bundles and specifies the parameters which are seen in the next modules. It should contain the full response from the API, including nested parameters.&#x20;

You can generate an interface using our **Interface Generator**, learn how in [#interface-generator](../app-blocks/interface.md#interface-generator "mention") section.

{% content-ref url="../app-blocks/interface.md" %}
[interface.md](../app-blocks/interface.md)
{% endcontent-ref %}


Processing of output parameters



If the app has over 10 modules, the modules should be put into special groups. These groups should be named after the entity with which the modules work, or after the type of the job, the modules are executing.

<div>

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-26 at 18.13.30.png" alt=""><figcaption><p>Example of groups - App CloudConvert</p></figcaption></figure>

 

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-26 at 18.14.52.png" alt=""><figcaption><p>Example of groups - App SugarCRM</p></figcaption></figure>

</div>

Also, the modules inside these groups should follow this order:

1. Trigger module
2. Create module
3. Update module
4. Get module
5. Download/Upload Module
6. List/Search module
7. Delete module

The universal module should be left inside "Other" group.

More about groups can be found [here](../app-structure/groups.md).


Groups



## Custom Apps Development Training

Training with 37 lessons and 4.5 hours of video content where you can learn all the aspects of custom apps development on Make.

If you are new to custom apps on Make or want to freshen up your knowledge about apps developing on Make, enroll in the training!

{% embed url="https://partnertraining.make.com/courses/custom-apps-development-training" %}

<figure><img src=".gitbook/assets/Screenshot 2023-10-14 at 13.40.32.png" alt="" width="563"><figcaption><p>Course curriculum</p></figcaption></figure>

## Make's community - Custom Apps

Custom Apps category in community is dedicated to all Makers, especially to those who develop custom apps. If you need help, ask the community! You can participate there as well!

{% embed url="https://community.make.com/c/custom-apps" %}

## Stack Overflow

100+ questions regarding the custom apps development in Integromat/Make.

You can check if someone already asked the same question and got a response. If not, feel free to post a new question there!&#x20;

{% embed url="https://stackoverflow.com/questions/tagged/integromat" %}

## Make's channel full of useful videos:

150+ useful videos about Scenario Builder in Make and many more.

{% embed url="https://www.youtube.com/c/Integromat" %}

## Make's documentation

Documentation about Scenario Builder, apps, and many more.

{% embed url="https://www.make.com/en/help/home" %}

## Regular expressions 101

Recommended tool for experimenting with regular expressions. Just make sure to tick the `ECMAScript` (JavaScript) FLAVOR in the left panel.

{% embed url="https://regex101.com/" %}

## Regular expressions generator

Regular expressions generator for those, who struggle with regex.

{% embed url="https://regex-generator.olafneumann.org/" %}

## Free editor for images

A free editor that you can use to edit your file with a logo to be used in an app.

{% embed url="https://www9.lunapic.com/editor/" %}

## Make helpdesk&#x20;

Contact us in case you need help or you didn't find any information you need.

{% embed url="https://www.make.com/en/ticket" %}

## DEPRECATED: Open source apps

Make will introduce a different way of sharing open-source apps.&#x20;

Therefore, the Examples tab has been removed and is not available anymore.

![Custom apps > tab EXAMPLES](<.gitbook/assets/Screen Shot 2022-08-22 at 12.26.07 (1).png>)


Useful Resources



Every app on Make has its own logo and color. The combination of logo and color represents the app. With a distinct logo and color, the users quickly see which module belongs to which app.

<figure><img src=".gitbook/assets/Screen Shot 2022-11-22 at 14.25.18 (1).png" alt=""><figcaption><p>An example scenario with purple Make, green Google Sheets, and blue Microsoft 365 Email modules.</p></figcaption></figure>

## App theme

The app theme is the module color in hexadecimal format. For example, the Make module's color is `#6e21cc.`

## App logo

To add a logo to your custom app, you need to make sure that your file with the logo meets these requirements:

* an image file in `.png` format
* 512 x 512 px dimensions
* a maximum of 512 kB size
* contains transparent layers

Make processes the icon file so that:

* All original image colors are converted to white and the original image is overlayed on the background color specified in the **Theme** field.
* Transparency is preserved:
  * **fully transparent** pixels are rendered in the background color
  * **opaque** pixels are rendered in white
  * **semi-transparent** pixels are rendered in the transition color between the background color and white according to their transparency

{% hint style="warning" %}
If your file doesn't have layers with transparency, a white square will be displayed in your modules.
{% endhint %}

<figure><img src=".gitbook/assets/Screen Shot 2022-11-22 at 14.49.14.png" alt=""><figcaption><p>A white square instead of a logo</p></figcaption></figure>

{% hint style="info" %}
If you don't have any tool to edit your file with the logo, you can use the [Lunapic](https://www9.lunapic.com/editor/) free editor.&#x20;

For creating a transparent layer, you can use the [Transparent Background ](https://www9.lunapic.com/editor/?action=transparent)tool that is available in Lunapic.
{% endhint %}

## Example of a valid logo

{% file src=".gitbook/assets/Make_app_white_logo.png" %}
A file with Make logo
{% endfile %}

## Work with semi-transparent pixels

An app can have only one theme color. You can use multiple transparency levels to give your logo multiple shades of the theme color. You can create a 3D effect too.

<figure><img src=".gitbook/assets/Screen Shot 2022-11-22 at 16.49.05.png" alt=""><figcaption><p>Example apps with multi transparency levels</p></figcaption></figure>

## Updating the app's theme and/or logo

You can update the custom app's logo anytime. Navigate to your custom app settings and click **Options** > **Edit**.

{% hint style="warning" %}
If your app has been approved, the change of theme/logo is a subject of a change that needs to be approved by us.&#x20;
{% endhint %}

{% hint style="info" %}
The update of the theme/logo can take some time to appear in scenarios.
{% endhint %}


App logo



## Private app

A private app **can only be used by the author** of the app until the app is installed in an organization to which the author and other users have access.

{% hint style="info" %}
If you want to make your app available to everyone in your organization, create a new scenario with your app and save the scenario there.&#x20;

A dialog about the confirmation of installation of your app in your organization will pop up. Confirm the installation.&#x20;
{% endhint %}

![Confirmal dialog about app's installation in an organization](<.gitbook/assets/Screen Shot 2022-08-22 at 17.28.30.png>)

A private tag is displayed after your app's name on the app's page.

!["Private" tag](<.gitbook/assets/Screen Shot 2022-08-22 at 17.41.19.png>)

### Deletion of a private app

If your private app is not used in any of your scenarios, you can delete the private app.

### Deletion of a module in a private app

You can delete a module only if it is not used in any scenario. If you will try to do so, a warning dialog with a request to remove the module from a scenario first will pop up.

![Deletion dialog](<.gitbook/assets/Screen Shot 2022-08-22 at 17.53.55.png>)

### Deletion of a component in a private app (webhook, connection, RPC, custom IML function)

You can delete a component only if it is not used in any module. If you will try to do so, a warning dialog in the right-down corner will pop up.

![Warning a connection is used by a module](<.gitbook/assets/Screen Shot 2022-08-22 at 17.59.44.png>)

## Public app

If you want to share your app outside of your organization, you will need to publish your app, so the invite link is generated.

Go to your app and open your app's page. Click **Publish** in the right upper corner.

![Publishing of private app](<.gitbook/assets/Screen Shot 2022-08-22 at 17.41.19 (1).png>)

Once you publish the app, the invite link is generated. You can share it with any other Maker who will then install it in his/her organization. It doesn't matter, where the organization is located (EU1 or US1).

![Invite link](<.gitbook/assets/Screen Shot 2022-08-22 at 18.28.38.png>)

### Deletion of a public app

{% hint style="warning" %}
Once the app is published, it is not possible to delete the app or make it private again.
{% endhint %}

If you wish to have your public app deleted, contact our helpdesk and we will remove the app from your account.

### Deletion of a module or other component in a public app (webhook, connection, RPC, custom IML function)

{% hint style="warning" %}
Once the app is published, it is not possible to delete any module or component.
{% endhint %}

We recommend you change the component's label the way so that it is obvious the component should not be used, e.g. `[DO NOT USE] My unwanted module`. Make sure the module is hidden.

### Distribution control of modules in a public app

If you actively share your public app via an invite link, you can control the distribution of modules that you have in your public app by making them hidden/visible.

<figure><img src=".gitbook/assets/Screen Shot 2023-02-07 at 13.09.53.png" alt=""><figcaption><p>Switching toggles to make an app either visible or hidden</p></figcaption></figure>

If you hide an already visible module, that is currently in use in a scenario, the module will continue working in the scenario. Though, the hidden module will not be available in the app selector in a new scenario.

## Approved app (=globally available app)

If you want to have your app available to all Makers, you will need to first make sure your app follows our conditions and best practices.

{% content-ref url="app-review/how-to-pass-an-app-review.md" %}
[how-to-pass-an-app-review.md](app-review/how-to-pass-an-app-review.md)
{% endcontent-ref %}

{% content-ref url="best-practices/" %}
[best-practices](best-practices/)
{% endcontent-ref %}

Once you make sure your app follows our conditions and best practices, click **Request review** button.

![Request review button](<.gitbook/assets/Screen Shot 2022-08-22 at 18.28.38 (1).png>)

Once the app passes our review process, it becomes available for everyone to use in our App Builder. That mean's that any user on Make can add your app to his/her scenario and use it.


App visibility

App review



When you want to make your custom app public and share it with all Make users, your app has to conform to Make standards. Following Make app development standards is a prerequisite to get an app review. Make app standards encompass:

* Custom app functionality.
* Custom app code best practices.
* Testing your custom app with test scenarios.

Check out the following sections to learn more about each prerequisite.

## Check your app's functionality

In Make, we develop apps to provide value to our users. Your custom app should use a service that Make doesn't integrate yet. All apps in Make require from the user only credentials that are necessary to create a connection to the service API. If you want to make your custom app public, your app functionality has to follow the same principles:

* Your custom app uses a web service that is not already available in Make.
* Your custom app and it's modules have to connect to a web service API. Avoid duplicating the same functionality as iterators, aggregators or other tools in Make.
* Avoid using APIs that have strong dependencies on other APIs, or APIs that function as redirects to other APIs.
* Avoid using APIs that don't have their own domain, or have their domain associated with service platforms like Heroku or AWS.
* Your custom app has to use only credentials that the service requires to create a connection. Don't request any additional credentials from the user.

## Check your app's code

When developing a custom app in Make, you should first go through our [Best Practices](../best-practices/) guide and apply them to your code. By following our best practices, you will ensure that the review and publication process of your app is as smooth as possible.

{% content-ref url="../best-practices/" %}
[best-practices](../best-practices/)
{% endcontent-ref %}

Before sending an app for review, check that:

* The base and connection have [sanitization](../app-structure/base/sanitization.md) of sensitive data, e. g. API key or token.
* The base and connection have [error handling](../app-structure/base/error-handling.md).
* The [base](../app-structure/base/base-url.md) and connection use an endpoint in the app's API.
* Connection is [using a correct URL](../best-practices/connections.md). If the user uses incorrect credentials, they get an error.
* Modules have correct [labels](../best-practices/names-labels-and-descriptions.md#module-labels) and [descriptions](../best-practices/names-labels-and-descriptions.md#module-descriptions).
* The app has a [universal module](../best-practices/modules.md#universal-module).
* All modules have the [correct interface](../best-practices/processing-of-output-parameters.md#interface) depending on the output from the module.
* All dates are formatted or parsed in the [mappable parameters](../best-practices/processing-of-input-parameters.md#date-parameters) and [interface](../best-practices/processing-of-output-parameters.md#showing-dates-correctly).
* Search modules, trigger modules and [RPCs](../best-practices/remote-procedure-calls.md#pagination-and-limits) have `limit` [parameter](../best-practices/action-and-search-modules.md#limiting-output).
* Search modules, trigger modules and RPCs have the [pagination](../app-blocks/api/pagination.md), if it's supported in the service API.

{% hint style="warning" %}
The items above are mandatory for each app.
{% endhint %}

## Create test scenarios

After you check the code of your custom app, you have to create test scenarios to show that the custom app works. Use each module of the custom app in at least one testing scenario.

{% hint style="warning" %}
Make sure that the testing scenarios and their execution logs don't contain personal or sensitive data.
{% endhint %}

### Best practices for test scenarios

In order to help us with a review of your app, please, follow the best practices.

* Do not use scenarios with another app's webhook.
* It is best to have all modules in one scenario and run them all without an error. You can group your modules via the entity or create scenarios of the way, the endpoints work together, e.g. `Create a Task > Create a Subtask` (in order to create a subtask, the task has to be created first).
* Try to put all app's modules in one scenario and run the scenario without errors. Connect the app modules based on the object the modules work with or the action the modules do. For example, **Create a Task** > **Create a Subtask** (in order to create a subtask, the task has to be created first).

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-29 at 19.25.52.png" alt=""><figcaption><p>Example of a Scenario</p></figcaption></figure>

* Put the search and list modules at the end of separate scenario routes to avoid multiple runs of the subsequent modules.
* Run your search and list modules to have logs with pagination. If you don't know how to test pagination, follow the steps [here](../debugging-your-app/debugging-of-pagination-in-list-search-modules.md).
* Create a separate scenario that produces an error message. Run the scenario to get an error:

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-29 at 19.56.12.png" alt=""><figcaption><p>Example of Error</p></figcaption></figure>

Run the test scenarios right before you request the custom app review and every time you fix issues. The scenario execution logs have a data retention limit and the reviewer won't be able to access old logs.


App review prerequisites



Once you make sure that your app meets Make's [requirements](how-to-pass-an-app-review.md) and follows Make's [best practices](how-to-pass-an-app-review.md), you can request an app review:

{% hint style="danger" %}
Once you publish your app in the second step of the following procedure, you can't "unpublish" it. Check the [app visibility](../app-visibility.md) section for more details.
{% endhint %}

1. Make sure that you removed testing modules or testing connections before you publish an app. When your app is [public](../app-visibility.md#public-app), you can't [delete its modules, connections, or other components](../app-visibility.md#deletion-of-a-module-or-other-component-in-a-public-app-webhook-connection-rpc-custom-iml-function).
2. Navigate to your custom app's code and click the **Publish** button:

    <figure><img src="../.gitbook/assets/image (23).png" alt=""><figcaption></figcaption></figure>
3. Navigate to the **Modules** tab. Click the switch to set the **visible** status of each module of the app that you want to publish.

    <figure><img src="../.gitbook/assets/image (19).png" alt=""><figcaption></figcaption></figure>
4. After the first step, a new tab **Review** appeared in the top panel. Navigate to the **Review** tab:

    <figure><img src="../.gitbook/assets/Screen Shot 2022-09-08 at 15.17.59.png" alt=""><figcaption><p>The Review tab</p></figcaption></figure>
5. Fill in the form in the **Review** tab.
   * Add a link to the API documentation of the service for which you are creating a custom app.
   * Add a link to scenarios with the custom app modules. Check the testing scenarios section in the [App review prerequisites](how-to-pass-an-app-review.md).
6. Click the **Request review** button at the bottom of the page.

The data you filled in the form are sent to Make QA developers for review. At the top of the page, the **Request review** button changes to **Review process started** and becomes inactive. Also, the app status turns into **pending approval**.

<figure><img src="../.gitbook/assets/image (25).png" alt=""><figcaption></figcaption></figure>

Once you request the app review, Make sends you an e-mail with the subject: "_App review: YourApp'sName_". If you have any questions or additional information to share, reply to the e-mail.

{% hint style="info" %}
Every time you edit your app upon request from the reviewer, you should run your scenarios, so that there are new logs available.
{% endhint %}

{% hint style="info" %}
If you need to edit your links, you can update your form and submit the changes by clicking on **Update review** button.
{% endhint %}

### Review process

The review process contains 2 phases - automatic review and manual review.

#### Automatic review (beta)

Your app is first reviewed by our application. The automatic review checks the common issues and generates a PDF file with the issues found.&#x20;

The PDF file with feedback from the automatic review is sent to the existing App review email thread.

{% hint style="info" %}
The automatic review is in beta and is still in a process of improvement. Therefore, there might be inconsistencies.
{% endhint %}

#### Manual review

Once your app passes the automatic review, it is reviewed by our QA Engineer who makes sure, that your app follows our best practices and is user-friendly.&#x20;

QA Engineer shares the feedback in the existing App review email thread.

Once your app successfully passes the manual review, your app is listed in our planned release. You will be informed about the app approval as well as the app release.&#x20;


Request app review



You can check the stage of your custom app review in the **App flow** tab. The **App flow** tab contains a list of app review statuses and their description. When you click the **App flow** tab, your browser automatically scrolls and highlights the current review status of your app.

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-26 at 13.13.28.png" alt=""><figcaption><p>App Flow tab</p></figcaption></figure>

If you have published your app or requested a review for a new app or an app update, you have available the **Review** tab. You can check the **Review Status** section at the bottom of the **Review** tab to see all activity that happened during the review.

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-26 at 13.06.25.png" alt=""><figcaption><p>Review status detail in the Review tab</p></figcaption></figure>

Every entry contains 4 columns:

* **Date and Time** - When the activity happened.
* **Action** - Name of the activity.
* **Status** - Available only with action "Review status updated.". The status of the app's review.
* **Comment (manual)** - A comment with additional information or context.

<figure><img src="../.gitbook/assets/Screen Shot 2022-09-08 at 14.53.29.png" alt=""><figcaption><p>Review Status</p></figcaption></figure>

Possible actions are:

| Action                  | Explanation                                                                                |
|-------------------------|--------------------------------------------------------------------------------------------|
| App has been published. | You have published the app with the **Publish** button.                                    |
| Approval requested.     | You have submitted the review form. This action marks the start of the app review process. |
| Review form updated.    | You have updated the review form.                                                          |
| Review status updated.  | Make updated the review status.                                                            |
| App has been approved.  | Make approved your app. You app is now available to every user in Make.                    |

{% hint style="note" %}
You can check your app review status also in your email. Search for an email with the subject: "_App review: YourAppName_". Make keeps all communication about the app review in this email thread.
{% endhint %}


Review status

Approved app



When Make approves your custom app any Make user can use your custom app. You have to maintain the app to keep the app working. That involves:

* updating the custom app when a relevant part of the service API changes
* fixing bugs the users report
* submit API checkups
* checking feature requests on the Make Idea Exchange regularly

When you maintain the custom app actively, the users can use the app with confidence. The users don't have to worry that their scenarios stop working with new service updates.

## Fix reported issues

When a user reports an issue, Make validates the issue. If the issue is valid, we contact you via e-mail with a request to fix the reported issue.

{% hint style="warning" %}
At Make, we make sure that everything works for our customers. If you do not fix the validated issue or stop communicating with Make, we will access the app's code and fix it for the app's users.
{% endhint %}

## API Checkup

Make sends you a request to update the custom app's API checkup every six months. The Make API checkup helps you and Make to:

* watch changes in API and API's docs
* make sure the app is up-to-date
* manage deprecations of endpoints or API
* manage new versions of the API
* inform users about shutdowns and other cases in advance

&#x20;The API checkup form contains the  following data about the service API:

<table><thead><tr><th width="208">Parameter</th><th width="331">Specification</th><th>Example</th></tr></thead><tbody><tr><td><strong>Currently used API version</strong></td><td>The version of the API the app is currently using.</td><td><code>v1</code>, <code>2019-01</code></td></tr><tr><td><strong>Currently used API's documentation</strong></td><td>URL of the API's online documentation.</td><td>https://service.com/api/v1</td></tr><tr><td><strong>Currently used API's changelog</strong></td><td>URL of API's changelog in the API's docs.</td><td>https://service.com/api/changelog</td></tr><tr><td><strong>Currently used API deprecation date</strong></td><td>The date, when the API was or will be deprecated.</td><td>01. 02. 2023</td></tr><tr><td><strong>Currently used API shutdown date</strong></td><td>The date, when the API was or will shut down.</td><td>01. 06. 2023</td></tr><tr><td><strong>Breaking change in currently used API</strong></td><td>Information about the breaking changes in the API.</td><td><code>true</code>, <code>false</code></td></tr><tr><td><strong>Breaking change  note</strong></td><td>Note about the particular breaking changes in the API.</td><td><em>"Endpoint X has removed parameters. More info in https://...."</em></td></tr><tr><td><strong>Latest API available</strong></td><td>Is there a newer API available or not?</td><td><code>true</code>, <code>false</code></td></tr><tr><td><strong>Latest API version</strong></td><td>Version of the latest available API.</td><td><code>v2</code>, <code>2023-01</code></td></tr><tr><td><strong>Latest API's documentation</strong></td><td>URL of the latest online documentation of the API.</td><td>https://service.com/api/v2</td></tr><tr><td><strong>Note</strong></td><td>Any note that can help with the evaluation of the app's status or the next API checkup.</td><td><em>"The latest v2 version is currently in beta."</em></td></tr></tbody></table>



{% hint style="warning" %}
At Make, we make sure that everything works for our customers. If you do not submit the API checkup form or stop communicating with Make, we will take over the custom app maintainership to ensure that Make users can continue using it.
{% endhint %}

## Feature requests on Make Idea Exchange

When Make users miss a feature in an app, they can submit a new request to [App Improvement Ideas board](https://www.make.com/en/app-improvement-ideas/). We recommend you check the list of feature requests for your app regularly and respond to them. You can use the search bar for listing requests which mention your app.

<figure><img src=".gitbook/assets/make_idea_exchange_app_improvements.png" alt=""><figcaption><p>App Improvement ideas on the Make Idea Exchange</p></figcaption></figure>


Terms of approved app maintenance

Updating your app



This section explains the work with updates in [private](../app-visibility.md#private-app) or [public](../app-visibility.md#public-app) apps.

## Changes

In custom apps, which haven't been approved by Make, it is not possible to keep track of changes as there is no Diff tool available.

If you need to keep track of your changes and you are not planning to have your app approved by Make, you can export the current version of your app every time you make a change, using [VS Code](../apps-sdk/) extension, and store the files on GitHub or any similar tool.

{% hint style="warning" %}
All changes take effect immediately. Before saving a change, make sure it will not negatively affect existing scenarios.
{% endhint %}

{% hint style="warning" %}
You must ensure not to have Javascript **syntax warnings or errors** on your custom IML functions in your app.&#x20;

Otherwise, all scenarios that are using the app will throw the error message about Javascript syntax and will be stopped immediately.&#x20;

This will affect all scenarios no matter if they run the app's modules that do not contain the faulty custom IML functions.&#x20;
{% endhint %}

## &#x20;Versioning

If you find out, that there has been a new API version implemented, or there have been major changes in the current API made, you should create a new app.

This way, you will make sure that everything is consistent and that there are no breaking changes made in the current app.


Private/Public apps

Approved apps

App structure

Webhooks

Custom IML functions

App blocks



Communication is a piece of code where requests and responses are specified.

## Specification

This is a complete form of the communication object. You can find detailed information on child pages.

```javascript
{
    "url": String,
    "encodeUrl": Boolean,
    "method": Enum[GET, POST, PUT, DELETE, OPTIONS],
    "qs": Flat Object,
    "headers": Flat Object,
    "body": Object|String|Array,
    "type": Enum[json, urlencoded, multipart/form-data, binary, text, string, raw],
    "ca": String,
    "condition": String|Boolean,
    "gzip": Boolean,
    "temp": Object,
    "aws": {
        "key": String,
        "secret": String,
        "session": String,
        "bucket": String,
        "sign_version": 2|4        
    },
    "response": {
        "type": {
            "*": Enum[json, urlencoded, xml, text, string, raw, binary, automatic],
            "[Number[-Number]]": Enum[json, urlencoded, xml, text, string, raw, binary, automatic]
        },
        "temp": Object,
        "iterate": {
            "container": String|Array,
            "condition": String|Boolean
        },
        "trigger": {
            "id": String,
            "date": String,
            "type": Enum[id, date],
            "order": Enum[asc, desc, unordered]
        },
        "output": String|Object|Array,
        "wrapper": String|Object|Array,
        "valid": String|Boolean,
        "error": {
            "message": String,
            "type": Enum[RuntimeError, DataError, RateLimitError, OutOfSpaceError, ConnectionError, InvalidConfigurationError, InvalidAccessTokenError, IncompleteDataError, DuplicateDataError],
            "[Number]": {
                "message": String,
                "type": Enum[RuntimeError, DataError, RateLimitError, OutOfSpaceError, ConnectionError, InvalidConfigurationError, InvalidAccessTokenError, IncompleteDataError, DuplicateDataError]
            }
        }
    },
    "pagination": {
        "mergeWithParent": Boolean,
        "url": String,
        "method": Enum[GET, POST, PUT, DELETE, OPTIONS],
        "headers": Flat Object,
        "qs": Flat Object,
        "body": Object|String|Array
    },
    "log": {
	"sanitize": Array
    }
}

```

## Escaping

If you need to access a key with a dot (`.`) inside, you can use back-ticks (`` `key.with.dots` ``) as an escape sequence in order to access the desired key.&#x20;

### Example

{% tabs %}
{% tab title="Communication" %}
```javascript
"qs": {
    "query": "{{parameters.`key.with.dots`}}"
}
```
{% endtab %}

{% tab title="Parameters" %}
```javascript
{
    "name": "key.with.dots",
    "label": "Key With Dots",
    "type": "text"
}
```
{% endtab %}
{% endtabs %}


Communication



Parameters describe what your module or connection will receive as input from the user.

{% hint style="warning" %}
Static parameters aren't used so much, because they can't be mapped from other modules, which means that the user has to fill in values when creating the scenario. They're used rarely and when there's no reason to block mapping to a field, you should use [**mappable parameters**](expect.md) instead.
{% endhint %}

## Static parameters use [**parameters syntax**](../app-components/parameters/).





Mappable parameters unlike static parameters can be either filled in by the user or mapped from the other previous modules.

Mappable parameters use parameters syntax.

{% content-ref url="../app-components/parameters/" %}
[parameters](../app-components/parameters/)
{% endcontent-ref %}

## Example

{% tabs %}
{% tab title="Appearance" %}
<figure><img src="../.gitbook/assets/Screen Shot 2022-08-29 at 20.10.19.png" alt=""><figcaption><p>Example of Mappable Parameters</p></figcaption></figure>
{% endtab %}

{% tab title="Source" %}
```javascript
[
	{
		"name": "email",
		"type": "email",
		"label": "Email address",
		"required": true
	},
	{
		"name": "name",
		"type": "text",
		"label": "Name",
		"required": true
	},
	{
		"name": "newsletter",
		"type": "boolean",
		"label": "Send newsletter?",
		"default": false,
		"required": true
	},
	{
		"name": "size",
		"type": "select",
		"label": "T-Shirt size",
		"options": [
			{
				"label": "S",
				"value": "s"
			},
			{
				"label": "M",
				"value": "m"
			},
			{
				"label": "L",
				"value": "l"
			}
		]
	}
]
```
{% endtab %}
{% endtabs %}

## Dynamic mappable parameters using RPC

You can use RPC to generate parameters dynamically.

{% content-ref url="../app-structure/rpcs/types-of-rpcs/dynamic-fields-rpc.md" %}
[dynamic-fields-rpc.md](../app-structure/rpcs/types-of-rpcs/dynamic-fields-rpc.md)
{% endcontent-ref %}




Interface describes the structure of output bundles and specifies the parameters which are seen in the next modules.

Interface uses the syntax of the parameters.

{% content-ref url="../app-components/parameters/" %}
[parameters](../app-components/parameters/)
{% endcontent-ref %}

{% hint style="info" %}
The following basic common settings are only supported in the interface:

* `"name": <String>,`
* `"label": <String>,`
* `"type": <String>`
{% endhint %}

{% hint style="info" %}
Since Interface describes only parameters that can be used in other modules, the type will never be `Folder, File, Filter, Hidden, Path, Pkey, Select`
{% endhint %}

## Arrays and Collections

Arrays and Collections use the syntax `spec` to specify their structure.

{% tabs %}
{% tab title="Simple Array" %}
```javascript
{
	"name": "emails",
	"spec": {
		"type": "email",
		"label": "Email"
	},
	"type": "array",
	"label": "Emails"
}
```


{% endtab %}

{% tab title="Array of Collections" %}
```json
{
	"name": "emails",
	"type": "array",
	"label": "Emails",
	"spec": [
		{
			"name": "email",
			"type": "email",
			"label": "Email"
		},
		{
			"name": "source",
			"type": "text",
			"label": "Source"
		}
	]	
}
```
{% endtab %}

{% tab title="Collection" %}
```javascript
{
	"name": "address",
	"spec": [
		{
			"name": "city",
			"type": "text",
			"label": "City"
		},
		{
			"name": "street",
			"type": "text",
			"label": "Street"
		},
		{
			"name": "number",
			"type": "number",
			"label": "Number"
		}
	],
	"type": "collection",
	"label": "Address"
}

```
{% endtab %}
{% endtabs %}

#### **Arrays and collections with unknown structure**

When you have a parameter that is type **Collection** or **Array** but you don't know the structure inside, you need to specify the structure like this:

{% tabs %}
{% tab title="Array" %}
```javascript
	{
    "name": "custom_fields",
    "type": "array",
    "label": "Custom Fields"
}
```

{% hint style="info" %}
For **array**, `spec` is not specified.
{% endhint %}
{% endtab %}

{% tab title="Collection" %}
```javascript
{
    "name": "address",
    "type": "collection",
    "label": "Address",
    "spec": []
}
```

{% hint style="info" %}
For **collection**, `spec` is set to an empty array.
{% endhint %}
{% endtab %}
{% endtabs %}

This way, when the service returns any parameter inside the **Collection** or **Array**, the user will be able to map them.

## Example

{% tabs %}
{% tab title="Appearance" %}
<figure><img src="../.gitbook/assets/Screen Shot 2022-09-09 at 20.37.54.png" alt=""><figcaption><p>Example of Interface</p></figcaption></figure>
{% endtab %}

{% tab title="Output" %}
![](<../.gitbook/assets/image (48).png>)
{% endtab %}

{% tab title="Source" %}
```javascript
[
	{
		"name": "id",
		"type": "uinteger",
		"label": "User ID"
	},
	{
		"name": "createdAt",
		"type": "date",
		"label": "Created at"
	},
	{
		"name": "fullName",
		"type": "text",
		"label": "Full name"
	},
	{
		"name": "emails",
		"spec": {
			"type": "email",
			"label": "Email"
		},
		"type": "array",
		"label": "Emails"
	},
	{
		"name": "address",
		"spec": [
			{
				"name": "city",
				"type": "text",
				"label": "City"
			},
			{
				"name": "street",
				"type": "text",
				"label": "Street"
			},
			{
				"name": "number",
				"type": "number",
				"label": "Number"
			}
		],
		"type": "collection",
		"label": "Address"
	}
]
```
{% endtab %}
{% endtabs %}

## Interface Generator

Both web interface and Visual Studio Code have interface generator tool, which helps with generating the interface.

Run a module for which you want to generate an interface, then in the panel with the output, click on the button circled below and choose **Download output bundles** option.

![Download output bundles option](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.00.28.png>)

Then, a new panel will appear, with the original response from the endpoint. Copy the text to your clipboard.

![Original response from /helloworld endpoint.](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.04.53.png>)

<details>

<summary>Generator in Web Interface</summary>

Go back to the tab with your app and make sure you are in the settings of the right module. Select tab **INTERFACE**. You can see a JSON snippet:

```json
[
    {
        "name": "id",
        "type": "uinteger",
        "label": "User ID"
    }
]
```

In the right upper corner, click on **Options** button and choose **Generator**.

<img src="../.gitbook/assets/Screen Shot 2022-08-20 at 18.11.50.png" alt="Interface of the Hello World module" data-size="original">

A new panel will appear. There, paste the previously copied JSON from your clipboard and click **Generate**.

<img src="../.gitbook/assets/Screen Shot 2022-08-20 at 18.26.13.png" alt="Generator panel" data-size="original">

A new data structure will be generated. Copy it to your clipboard and close the panel.

<img src="../.gitbook/assets/Screen Shot 2022-08-20 at 18.27.28.png" alt="A new data structure" data-size="original">

In the **INTERFACE**, replace the JSON structure with the new structure.

</details>

<details>

<summary>Generator in Visual Studio Code</summary>

Go back to VS Code and make sure you are in the settings of the right module. Select tab **INTERFACE**. You can see a JSON snippet:

```json
[
    {
        "name": "id",
        "type": "uinteger",
        "label": "User ID"
    }
]
```

Click on the 'magic wand' icon.&#x20;

<img src="../.gitbook/assets/generateInterface2.png" alt="Magic Wand hiding the Generator magic" data-size="original">

Paste your data and copy the generated code. You still need to check all the labels and types, to make sure there are no errors. You might need to change some abbreviations to uppercase (such as URL, VAT, etc.).

<img src="../.gitbook/assets/generateInterface3.png" alt="JSON Generator" data-size="original">



</details>

{% tabs %}
{% tab title="Old structure" %}
```
[
    {
        "name": "id",
        "type": "uinteger",
        "label": "User ID"
    }
]
```

![List of available parameters to map before](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.35.09.png>)
{% endtab %}

{% tab title="New structure" %}
```
[
  {
    "name": "result",
    "type": "text",
    "label": "Result"
  }
]
```

![List of available parameters to map after](<../.gitbook/assets/Screen Shot 2022-08-20 at 18.37.51.png>)
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The generated code still needs to be reviewed!&#x20;

Make sure the generated **type** for dates is **date**.

The label must be grammatically correct, use Title case and uppercase for abbreviations such as UID, URL, etc.

In the case of **Search** modules, you will need to delete the pagination data `__IMTLENGTH__` and `__IMTINDEX__`.
{% endhint %}

{% hint style="info" %}
Whenever you change **INTERFACE** in a module, you need to refresh your scenario in order to see the changes.
{% endhint %}

## Dynamic Interface Using RPC

You can use RPC to generate the interface dynamically.

```javascript
"rpc://nameOfTheRPC"
```

You can also define RPC to generate just a part of the interface.

```javascript
[

	{
		"name": "id",
		"type": "uinteger",
		"label": "User ID"
	},
	"rpc://nameOfTheRPC"
]
```

You can access module parameters in remote procedures via `{{parameters.foo}}` syntax.

{% hint style="info" %}
**PRO TIP:** If you call RPC from the interface of an instant trigger, you can use `{{webhook.foo}}` syntax to access webhook's parameters.
{% endhint %}


Interface

---
description: >-
  The epoch panel is a popup window offered to the user when selecting where to
  start from when configuring a trigger.
---

# Epoch

## Specification

If the `Epoch configuration` is defined, then there will be at least 1 item available in the Epoch panel: `Select`, which will allow the user to select an item the user wants to start with. Other items depend on the trigger type. The underlying data is retrieved via the [Epoch RPC](epoch.md#retrieving-data-for-the-epoch-panel).

If the trigger `type` is `id`, then there will be one more option available: `All`, which will allow the user to process all the items from the beginning. But, if the `Epoch configuration` was not specified, then the Epoch panel will not be available to the user.

On the other hand, if the trigger `type` is `date`, then 3 additional options will be available for the user: `All`, `From date` and `From now`. `From date` will allow the user to start processing items from a specific day forward and from now is the same as `From date`, except the date is automatically set to the current date and time.

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-31 at 19.35.29.png" alt=""><figcaption><p>Epoch Panel</p></figcaption></figure>

### Retrieving Data for the Epoch Panel

You can customize how the data for the Epoch panel will be retrieved by providing specific request overrides in the `Epoch` section. These overrides will then be merged with trigger configuration to retrieve the data.

You also have to provide the labels and dates for the returned items. You can do that with the `response.output` directive. Dates are not required, but it would be better to provide them for a better user experience.

To correctly return epoch panel items from your Epoch RPC, the `output` section of `response` should contain only 2 items: `label` and `date`. The limit is used to limit the number of items displayed to the user when using the Epoch panel.

All other directives are inherited from the Triggers' communication and can be overridden by specifying them inside the Epoch RPC.

```javascript
{
    "response": {
        "limit": 500,
        "iterate": "",
        "output": {
            "label": "",
            "date": ""
        }
    }
}
```

{% hint style="info" %}
All other directives _(like url, pagination, method,...)_ are **inherited** from the Triggers' communication and can be overridden by specifying them inside the Epoch RPC.
{% endhint %}

![Example of Epoch Panel](../.gitbook/assets/screen\_78.png)

`label` is what the user sees when selecting items from the select box and `date` is when this item was created (updated), which the user will see in gray.

## Best Practices

As we can't wait too long for the epoch's output, there are best practices.

<table><thead><tr><th width="173.33333333333331">Name</th><th width="234">Recommended limit of ...</th><th>Value</th></tr></thead><tbody><tr><td><strong>Request Count</strong></td><td>... calls performed by RPC</td><td>3</td></tr><tr><td><strong>Record Count</strong></td><td>... paginated records</td><td>300 or 3 * number of objects per page</td></tr></tbody></table>

## Available IML variables

These IML variables are available for you to use everywhere in this module:

* **`now`** - Current date and time
* **`environment`** - TBD
* **`temp`** - Contains custom variables created via `temp` directive
* **`parameters`** - Contains module’s input parameters.
* **`connection`** - Contains connection’s data collection.
* **`common`** - Contains app’s common data collection.
* **`data`** - Contains module’s data collection.
* **`scenario`** - TBD
* **`metadata.expect`** - Contains module’s raw parameters array the way you have specified it in the configuration.
* **`metadata.interface`** - Contains module’s raw interface array the way you have specified it in the configuration.

Additional variables available to Response Object:

* **`output`** - When using the `wrapper` directive, the `output` variable represents the result of the `output`directive

Additional variables available after using the `iterate` directive, i.e. in `wrapper` or `pagination` directives:

* **`iterate.container.first`** - Represents the first item of the array you iterated
* **`iterate.container.last`** - Represents the last item of the array you iterated

Additional variables available to Pagination and Response Objects:

* **`body`** - Contains the body that was retrieved from the last request.
* **`headers`** - Contains the response headers that were retrieved from the last request.
* **`item`** - When iterating this variable represents the current item that is being iterated.

Additional variables available in [Attach](../app-structure/rpcs/#attach-rpc) Remote Procedure.

* **`webhook.id`** - Internal webhook ID.
* **`webhook.url`** - Webhook URL, which you need to register in the remote service.

Additional variables available in [Detach](../app-structure/rpcs/#detach-rpc) Remote Procedure and the expect/interface section of an instant trigger.

* **`webhook`** - Contains webhook’s data collection.


Epoch

---
description: Sample is an object representing one output bundle.
---

# Samples

## Specification

Samples are used to provide a sample of the outgoing bundle.

### Static samples

You can define the samples manually.

{% tabs %}
{% tab title="Apperarance" %}
<figure><img src="../.gitbook/assets/Screen Shot 2022-08-31 at 19.29.23.png" alt=""><figcaption><p>Example of Samples</p></figcaption></figure>
{% endtab %}

{% tab title="Interface" %}
```javascript
[
	{
		"name": "id",
		"type": "uinteger",
		"label": "User ID"
	},
	{
		"name": "email",
		"type": "email",
		"label": "Email"
	},
	{
		"name": "name",
		"type": "text",
		"label": "Name"
	}
]
```
{% endtab %}

{% tab title="Samples" %}
```javascript
{
	"id": 1399,
	"email": "johndoe@email.com",
	"name": "John Doe"
}
```
{% endtab %}
{% endtabs %}

### Dynamic samples

Please see [Samples RPC ](../app-structure/rpcs/#samples-rpc)on how to specify dynamic sample data.


Samples



When using OAuth, use **Scope** to define required scopes.

## Specification

Different modules require different scopes. That helps you to control the permissions of every single account. If the service supports **OAuth Scopes**, you should set corresponding scopes for each module you're writing.

Scope is an array value that is required to complete the request with a list of scopes successfully.

Example:

```javascript
[
	"identify",
	"users:read"
]
```

{% hint style="warning" %}
If a module uses RPCs which require particular scopes, the scopes should be listed in the module too.
{% endhint %}

## Extending scopes

When a module requires a scope that wasn't required elsewhere previously, a dialog for extending permissions will appear.

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-26 at 18.35.16.png" alt=""><figcaption><p>Dialog with Extend Permissions Request</p></figcaption></figure>


Scope



Scopes contain all scopes described in the human-readable format.

## Specification

Scopes object contains all available scopes used within Make providing their human-readable description.

Example:

```javascript
{
	"identify": "Allow application to confirm your identity.",
	"groups:read": "Access information about user's private channels.",
	"channels:read": "Access information about user's public channels.",
	"users:read": "Access the team member's profile information.",
	"im:read": "Access information about user's direct messages.",
	"files:write:user": "Upload and modify files as user.",
	"chat:write:bot": "Send messages as user.",
	"channels:history": "Access user's public channels.",
	"im:history": "Access user's direct messages.",
	"groups:history": "Access user's private channels.",
	"team:read": "Access basic information about the team."
}
```

## Control of granted scopes in a connection

When you want to see which scopes have been granted to a particular connection in an app, go to **Make** and open **Connections**:

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-26 at 18.47.36 (1).png" alt=""><figcaption><p>Connections tab in left menu</p></figcaption></figure>

There, find the connection which you would like to check. If you have many connections, you can use **Search** in the right top corner for faster finding your connection.

Every row with a connection has an eye icon with a number. If there are scopes available in the connection, the number is larger than 0.&#x20;

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-26 at 18.56.44.png" alt=""><figcaption><p>A connection without granted scopes</p></figcaption></figure>

When you click on the eye button, a new window will pop up, with a list of granted scopes in the connection.

<figure><img src="../.gitbook/assets/Screen Shot 2022-08-26 at 18.59.08.png" alt=""><figcaption><p>List of Granted Scopes in a Connection without Descriptions</p></figcaption></figure>


Scope List

App components

---
description: >-
  Integromat Data Types are derived from normal JSON data types, with some
  limitations and additions.
---

# Data Types

## Primitive Types

### string

A string is a statically specified piece of text, like `"Hello, world"`.

### number

A number is a sequence of digits, like `8452` or `-123`.

### boolean

A boolean is a binary type that has 2 values: `true` or `false`.

### null

A `null` is a special type, that represents an absence of a value.

## Complex Types

### Flat Object

A Flat Object is a collection of key-value pairs, where the key is a [String](types.md#string), and the value can be any [Primitive Type](types.md#primitive-types). Example:

```javascript
{
    "id": 1,
    "firstName": "James",
    "lastName": "McManson",
}
```

A Flat Object cannot contain nested collections and arrays.

### Object

An Object is a collection of key-value pairs, where the key is a [String](types.md#string), and the value can be any [Primitive](types.md#primitive-types) or [Complex](types.md#complex-types) type. Example:

```javascript
{
    "data": [{
        "id": 1,
        "url": "http://example.com"
    }, {
        "id": 2,
        "url": "http://foobar.org"
    }],
    "additional_data": {
        "total": 2,
        "next_page": false,
        "info": null
    }
}
```

### Array

An Array is a collection of [Primitive](types.md#primitive-types) and [Complex](types.md#complex-types) types.

## IML Types

IML types are special Strings or [Complex Types](types.md#complex-types) that can contain [IML](iml.md) expressions. An IML expression is a template expression that can resolve into a value.

### IML String

An IML String is a [String](types.md#string) that can contain IML expressions in between `{{` and `}}` tags. Anything between these tags is considered an expression. IML Strings are also known as Template Strings. IML String is an extension to String and, as such, can contain any value that a normal String can contain. It does not have to be just an IML expression.

Examples:

A String of a single IML expression: `"{{body.data.firstName + ' ' + body.data.lastName}}"`

A String without an IML expression: `"Hello, World"`

A String with text and IML expression: `"Hello, {{body.data.name}}"`

### IML Flat Object

An IML Flat Object is a [Flat Object](types.md#flat-object) that can additionally contain [IML Strings](types.md#iml-string) as values. Example:

```javascript
{
    "page": "{{temp.page}}",
    "limit": 1,
    "type": "{{parameters.type}}"
}
```

### IML Object

An IML Object is an [Object](types.md#object) that can additionally contain [IML Strings](types.md#iml-string) and [IML Arrays](types.md#iml-array) as values. Example:

```javascript
{
    "data": [{
        "id": "{{body.id}}",
        "name": "{{body.name}}"
    }, "{{parameters.type}}"],
    "info": {
        "pageNumber": 1
    }
}
```

### IML Array

An IML Array is an [Array](types.md#array) that can contain [IML Strings](types.md#iml-string) and [IML Objects](types.md#iml-object) as values. Example:

```javascript
[   
    {
        "id": "{{body.id}}",
        "name": "{{body.name}}",
        "data": {
            "foo": "{{temp.bar}}"
        }
    }, 
    "{{parameters.type}}",
    1,
    true,
    null
]
```


Data Types

Parameters



IML is a mustache-like markup language with support for evaluating complex expressions in javascript-like syntax. Expressions are written between mustaches: `{{body.data}}`.

## Available Operators

### Algebraic Operators

`+`, `-`, `*`, `/`, `%`

### Equality Operators

`==` (same as `=` or `===`), `!=` (same as `!==`)

{% hint style="info" %}
All equality operations are strict.
{% endhint %}

### Relational Operators

`<`, `<=`, `>`, `>=`

### Logical Operators

`&&`, `||`, `!`

## Strings Inside Expressions

you can use `'` or `"` to put strings inside IML expressions:

```
{{'Hello, ' + item.name}}
{{"Hello, " + item.name}}
```

## Conditionals

You can create conditionals with `if` and `ifempty` functions.

```
{{if(body.id > 100, body.user, false)}}
{{ifempty(body.username, body.user)}}
```

`ifempty` function returns second argument when first argument is either not defined, null or empty string. Otherwise it returns first argument.

## Retrieving Collection Properties

You can use normal JavaScript `.` (dot) notation to retrieve properties of collections, such as `parameters`: `{{parameters.input.data}}`.

If the property name contains spaces or starts with a non-alphabetic character or contains non-alphanumeric characters (except underscore `_`), you can use `` ` `` (back ticks) to retrieve such properties: ``{{headers.`X-HOOK-TYPE`}}`` or ``{{parameters.`First Name`}}``.

## Retrieving Array Items

You can use normal JavaScript `[]` brackets notation to retrieve a specific element from an array: `{{body.data[2].prop}}`. Unlike JavaScript, IML uses `1` to access the first item in an array.

You can also use `-1` to access the last element of an array, like so: `body.data[-1].prop`.

**Tip**: If you need to retrieve a property of an object, and the property name is contained in a variable, or computed, the dot `.` notation will not work. For this, you can use the `get` function, where the first argument of the function is the object you wish to retrieve the property from, and the second argument is the property name, or a variable containing a property name, or an expression that resolves to a property name: `get(body.data, 'some property')`, `get(body, parameters.fieldName)`, `get(body.data, if(body.xml == true, 'xml', 'json'))`

## Built-in IML Functions

There are plenty of **Built-in IML functions**, like:

* String functions:

<table><thead><tr><th width="182">Function</th><th>Specification</th></tr></thead><tbody><tr><td><code>ascii()</code></td><td>Removes all non-ascii characters from a text string.</td></tr><tr><td><code>base64()</code></td><td>Transforms text to base64.</td></tr><tr><td><code>capitalize()</code></td><td>Converts the first character in a text string to uppercase.</td></tr><tr><td><code>contains()</code></td><td>Verifies if text contains the search string.</td></tr><tr><td><code>decodeURL()</code></td><td>Decodes special characters in URL to text.</td></tr><tr><td><code>encodeURL()</code></td><td>Encodes special characters in a text to a valid URL address.</td></tr><tr><td><code>escapeHTML</code>()</td><td>Escapes all HTML tags in text.</td></tr><tr><td><code>indexOf()</code></td><td>Returns the position of the first occurrence of a specified value in a string. This method returns '-1' if the value searched for never occurs.</td></tr><tr><td><code>length()</code></td><td>Returns the length of a text string (number of characters) or binary buffer (buffer size in bytes).</td></tr><tr><td><code>lower()</code></td><td>Converts all alphabetical characters in a text string to lowercase.</td></tr><tr><td><code>md5()</code></td><td>Calculates the md5 hash of a string.</td></tr><tr><td><code>mime()</code></td><td>Gets MIME Type of the file from its filename with extension.<br>E.g. calling <em>mime(picture.png)</em> will return <em>image/png</em> MIME Type.</td></tr><tr><td><code>replace()</code></td><td>Replaces the search string with the new string.</td></tr><tr><td><code>sha1()</code></td><td>Calculates the sha1 hash of a string. If the key argument is specified, sha1 HMAC hash is returned instead. Supported encodings: <em>hex</em> (default), <em>base64,</em> or <em>latin1</em>.</td></tr><tr><td><code>sha256()</code></td><td>Calculates the sha256 hash of a string. If the key argument is specified, sha256 HMAC hash is returned instead. Supported encodings: <em>hex</em> (default), <em>base64,</em> or <em>latin1</em>.</td></tr><tr><td><code>sha512()</code></td><td>Calculates the sha512 hash of a string. If the key argument is specified, sha512 HMAC hash is returned instead. Supported encodings: <em>hex</em> (default), <em>base64,</em> or <em>latin1</em>. Supported key encodings: <em>text</em> (default), <em>hex</em>, <em>base64,</em> or <em>binary</em>. When using <em>binary</em> key encoding, a key must be a buffer, not a string.</td></tr><tr><td><code>split()</code></td><td>Splits a string into an array of strings by separating the string into substrings.</td></tr><tr><td><code>startcase()</code></td><td>Capitalizes the first letter of every word and lower cases of all other letters.</td></tr><tr><td><code>stripHTML()</code></td><td>Removes all HTML tags from text.</td></tr><tr><td><code>substring()</code></td><td>Returns a portion of a text string between the "start" position and "the end" position.</td></tr><tr><td><code>toBinary()</code></td><td>Converts any value to binary data. You can also specify encoding as a second argument to apply binary conversions from hex or base64 to binary data.</td></tr><tr><td><code>toString()</code></td><td>Converts any value to a string.</td></tr><tr><td><code>trim()</code></td><td>Removes space characters at the start or end of the text.</td></tr><tr><td><code>upper()</code></td><td>Converts all alphabetical characters in a text string to uppercase.</td></tr></tbody></table>

* Array functions:

<table><thead><tr><th width="192">Function</th><th>Specification</th></tr></thead><tbody><tr><td><code>add()</code></td><td>Adds values specified in parameters to an array and returns that array.</td></tr><tr><td><code>contains()</code></td><td>Verifies if an array contains the value.</td></tr><tr><td><code>deduplicate()</code></td><td>Removes duplicates from an array.</td></tr><tr><td><code>distinct()</code></td><td>Removes duplicates inside an array. Use the <em>key</em> argument to access properties inside complex objects. To access nested properties, use dot notation. The first item in an array is index 1.</td></tr><tr><td><code>first()</code></td><td>Returns the first element of an array.</td></tr><tr><td><code>flatten()</code></td><td>Creates a new array with all sub-array elements concatenated into it recursively up to the specified depth.</td></tr><tr><td><code>join()</code></td><td>Concatenates all the items of an array into a string, using a specified separator between each item.</td></tr><tr><td><code>keys()</code></td><td>Returns an array of a given object's or array's properties.</td></tr><tr><td><code>last()</code></td><td>Returns the last element of an array.</td></tr><tr><td><code>length()</code></td><td>Returns the number of items in an array.</td></tr><tr><td><code>map()</code></td><td>Returns a primitive array containing values of a complex array. Allows filtering values. Use raw variable names for keys.</td></tr><tr><td><code>merge()</code></td><td>Merges two or more arrays into one array.</td></tr><tr><td><code>remove()</code></td><td>Removes values specified in the parameters of an array. Effective only in the case of primitive arrays of text or numbers.</td></tr><tr><td><code>reverse()</code></td><td>The first element of the array becomes the last element and vice versa.</td></tr><tr><td><code>shuffle()</code></td><td>Shuffles (randomly reorders) elements of an array.</td></tr><tr><td><code>slice()</code></td><td>Returns a new array containing only selected items.</td></tr><tr><td><code>sort()</code></td><td>Sorts values of an array.</td></tr><tr><td><code>toArray()</code></td><td>Converts a collection into an array of key-value collections.</td></tr><tr><td><code>toCollection()</code></td><td>Converts an array containing objects with key-value pairs into a collection.</td></tr></tbody></table>

* Date & Time functions:

<table><thead><tr><th width="193">Function</th><th>Specification</th></tr></thead><tbody><tr><td><code>formatDate()</code></td><td>Formats a date into a specific format, e.g. <code>'YYYY-MM-DD'</code>.</td></tr><tr><td><code>parseDate()</code></td><td>Parses a date in a specific format, e.g. <code>'YYYY-MM-DD HH:mm'</code>.</td></tr><tr><td><code>addDays()</code></td><td>Returns a new date as a result of adding a given number of days to a date. To subtract days, enter a negative number.</td></tr><tr><td><code>addHours()</code></td><td>Returns a new date as a result of adding a given number of hours to date. To subtract hours, enter a negative number.</td></tr><tr><td><code>addMinutes()</code></td><td>Returns a new date as a result of adding a given number of minutes to date. To subtract minutes, enter a negative number.</td></tr><tr><td><code>addMonths()</code></td><td>Returns a new date as a result of adding a given number of months to date. To subtract months, enter a negative number.</td></tr><tr><td><code>addSeconds()</code></td><td>Returns a new date as a result of adding a given number of seconds to date. To subtract seconds, enter a negative number.</td></tr><tr><td><code>addYears()</code></td><td>Returns a new date as a result of adding a given number of years to date. To subtract years, enter a negative number.</td></tr><tr><td><code>setSecond()</code></td><td>Returns a new date with the seconds specified in parameters. Accepts numbers from 0 to 59. If a number is given outside of this range, it will return the date with the seconds from the previous or subsequent minute(s), accordingly.</td></tr><tr><td><code>setMinute()</code></td><td>Returns a new date with the minutes specified in parameters. Accepts numbers from 0 to 59. If a number is given outside of this range, it will return the date with the minutes from the previous or subsequent hour(s), accordingly.</td></tr><tr><td><code>setHour()</code></td><td>Returns a new date with the hour specified in parameters. Accepts numbers from 0 to 59. If a number is given outside of this range, it will return the date with the hour from the previous or subsequent day(s), accordingly.</td></tr><tr><td><code>setDay()</code></td><td>Returns a new date with the day specified in parameters. It can be used to set the day of the week, with Sunday as 1 and Saturday as 7. If the given value is from 1 to 7, the resulting date will be within the current (Sunday-to-Saturday) week. If a number is given outside of the range, it will return the day from the previous or subsequent week(s), accordingly.</td></tr><tr><td><code>setDate()</code></td><td>Returns a new date with the day of the month specified in parameters. Accepts numbers from 1 to 31. If a number is given outside of the range, it will return the day from the previous or subsequent month(s), accordingly.</td></tr><tr><td><code>setMonth()</code></td><td>Returns a new date with the month specified in parameters. Accepts numbers from 1 to 12. If a number is given outside of this range, it will return the month in the previous or subsequent year(s), accordingly.</td></tr><tr><td><code>setYear()</code></td><td>Returns a new date with the year specified in parameters.</td></tr></tbody></table>

* Math functions:

<table><thead><tr><th width="195">Function</th><th>Specification</th></tr></thead><tbody><tr><td><code>average()</code></td><td>Returns the average value of the numeric values in a specific array, or the average value of numerical values entered individually.</td></tr><tr><td><code>ceil()</code></td><td>Returns the smallest integer greater than or equal to a specified number.</td></tr><tr><td><code>floor()</code></td><td>Returns the largest integer less than or equal to a specified number.</td></tr><tr><td><code>formatNumber()</code></td><td>Returns a number in the requested format. A decimal point is, by default, Thousands separator is, by default.</td></tr><tr><td><code>max()</code></td><td>Returns the largest number in a specified array, or the largest number among numbers entered individually.</td></tr><tr><td><code>min()</code></td><td>Returns the smallest number in a specified array, or the smallest number among numbers entered individually.</td></tr><tr><td><code>parseNumber()</code></td><td>Parses a string with a number and returns the number.</td></tr><tr><td><code>round()</code></td><td>Rounds a numeric value to the nearest integer.</td></tr><tr><td><code>sum()</code></td><td>Returns the sum of the values in a specified array, or the sum of numbers entered individually.</td></tr></tbody></table>

* JSON functions:

<table><thead><tr><th width="195">Function</th><th>Specification</th></tr></thead><tbody><tr><td><code>createJSON()</code></td><td>Creates a JSON string inside a JSON object.</td></tr><tr><td><code>parseJSON()</code></td><td>Parses a JSON string inside a JSON object.</td></tr></tbody></table>

{% hint style="warning" %}
In the custom functions, the `JSON.stringify()` or `JSON.parse()` functions should be used instead of `createJSON()` or `parseJSON()`.
{% endhint %}

{% hint style="info" %}
See also [Custom IML Functions](../app-structure/iml-functions/)
{% endhint %}


JavaScript in Make

Other

---
description: >-
  This document describes how Make processes mapped values and how the values
  are passed to a service.
---

# Processing of 'empty' Values

{% hint style="info" %}
The new approach for processing empty values, as described in this document, is applicable only for apps with **Apps platform version 2** (apps created after 11/02/2019). Apps with **Apps platform version 1** behave according to the old rules due to backward compatibility.
{% endhint %}

In this approach, almost every input parameter of a module is ignored if there is no value. In the case where the user wants to rewrite(erase) the value of a field in service, the user has to use the `erase` keyword. Here is an example of how to erase the values for the **Query string** and **Body** fields.

![Example of erase use](../.gitbook/assets/eraseExample.png)

The processing of "empty" values is completely managed by Make. So, the developer doesn't have to implement this in his/her app. Bear in mind though that when an empty value comes to a module, then there was an intent for that and a value still has to be sent to the service.

To further explain the reason for the new processing approach, here is an example. When a user updates a task, and in the module config there is a multiple-select with labels that they leave untouched, it is unclear what action should be performed. Does this mean that they want to leave the task labels unchanged or want to remove all the labels?

The new behavior for parameter processing solves the problem mentioned above. By default, if the user doesn't select any label, Make will ignore the field. If the user wants to remove all assigned labels from the task, they have to use the `erase` keyword.

## How Make Evaluates Empty Values <a href="#how-integromat-evaluates-empty-values" id="how-integromat-evaluates-empty-values"></a>

The table below describes how Make evaluates mapped values into the module config:

| Type of empty value                        | Manifest 1.0                             | Manifest 2.0 implicit behavior                                 | Manifest 2.0 field with erase pill (map mode)                  |
| ------------------------------------------ | ---------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
| **string**                                 | `null`                                   | `undefined`                                                    | `null`                                                         |
| **string** (forced empty string using IML) | `""`                                     | `""`                                                           | ​                                                              |
| **number**                                 | `null`                                   | `undefined`                                                    | `null`                                                         |
| **boolean**                                | `undefined`                              | `undefined`                                                    | `undefined`                                                    |
| **array**                                  | `[]`                                     | `undefined`                                                    | `[]`                                                           |
| **multiple select**                        | `[]`                                     | `undefined`                                                    | `[]`                                                           |
| **select** (nothing selected)              | `null`                                   | `undefined`                                                    | ​                                                              |
| **select** (selected value is`""`)         | `null`                                   | `undefined`                                                    | ​                                                              |
| **select** (selected value is `null`)      | invalid value                            | invalid value                                                  | ​                                                              |
| **select** (map mode)                      | `null`                                   | `undefined`                                                    | `null`                                                         |
| **collection**                             | not changed (collection of empty values) | Recursively processed corresponding to the rules in this table | Recursively processed corresponding to the rules in this table |

## When the `erase` Pill is Shown <a href="#when-the-erase-pill-is-shown" id="when-the-erase-pill-is-shown"></a>

The `Erase` keyword is shown for the **update** and **universal** modules.

The type of module is defined in the metadata of a module. A **universal** module is a module without a defined module action field.

![Universal module](<../.gitbook/assets/Screenshot 2019-02-19 at 12.08.54.png>)


Processing of empty values



In Make, JSON-based APIs are natively supported. Nevertheless, some APIs may have a **JSON string** inside a **JSON object**.&#x20;

If such API returns a JSON string inside a JSON object, the data inside a JSON string is treated as text and the child parameters cannot be directly mapped.

On the contrary, if the API requires a parameter in JSON string format, Make has to send it in the required format.&#x20;

{% tabs %}
{% tab title="JSON String" %}
```
{
    "address": "{\"zip\":\"18000\",\"city\":\"Prague\",\"state\":\"Czechia\",\"country\":\"Czechia\",\"address1\":\"Menclova 2\"}",
    "id": "123",
    "name": "Make Office"
}
```

{% hint style="info" %}
Notice the `address` parameter that has value in JSON string format.
{% endhint %}
{% endtab %}

{% tab title="Occurence in a module" %}
<figure><img src="../.gitbook/assets/Screenshot 2023-06-28 at 15.04.54.png" alt=""><figcaption><p>JSON String in output</p></figcaption></figure>

{% hint style="info" %}
Notice the `address` parameter. Since the parameter is a JSON string, the content is not parsed as a collection.
{% endhint %}
{% endtab %}
{% endtabs %}

## Creating a JSON String

If the API requires a parameter to be sent as a JSON string, the `createJSON()` function can be used.

{% tabs %}
{% tab title="Communication" %}
```json
{
    ...
	"body": {
		"{{...}}": "{{omit(parameters, 'address')}}",
		"address": "{{createJSON(parameters.address)}}"
	},
    ...
}
```

{% hint style="info" %}
Notice that the `createJSON()` function is used to format the `address` value to a **JSON string.**
{% endhint %}
{% endtab %}

{% tab title="Request body" %}
```json
{
    "address": "{\"zip\":\"18000\",\"city\":\"Prague\",\"state\":\"Czechia\",\"country\":\"Czechia\",\"address1\":\"Menclova 2\"}",
    "id": "123",
    "name": "Make Office"
}
```

{% hint style="info" %}
Notice that the `address` parameter is sent in **JSON string** format.
{% endhint %}
{% endtab %}
{% endtabs %}

## Parsing a JSON String

If the API output contains a parameter in a JSON string format, the `parseJSON()` function can be used.

{% tabs %}
{% tab title="Communication" %}
```json
{
    ...
	"output": {
		"{{...}}": "{{omit(body, 'address')}}",
		"address": "{{parseJSON(body.address)}}"
	},
    ...
}
```

{% hint style="info" %}
Notice that the `parseJSON()` function is used to parse the `address` value to **JSON**.
{% endhint %}
{% endtab %}

{% tab title="Raw response body" %}
```json
{
    "address": "{\"zip\":\"18000\",\"city\":\"Prague\",\"state\":\"Czechia\",\"country\":\"Czechia\",\"address1\":\"Menclova 2\"}",
    "id": "123",
    "name": "Make Office"
}
```

{% hint style="info" %}
If the `parseJSON()` function is **not** used, the **JSON string** is returned in a raw format.
{% endhint %}
{% endtab %}

{% tab title="Parsed response body" %}
```json
[
    {
        "address": {
            "zip": "18000",
            "city": "Prague",
            "state": "Czechia",
            "country": "Czechia",
            "address1": "Menclova 2"
        },
        "id": "123",
        "name": "Make Office"
    }
]
```

{% hint style="info" %}
If the `parseJSON()` function is used, the value in `address` parameter is parsed to **JSON**. The `address` parameter is returned as a collection.
{% endhint %}
{% endtab %}
{% endtabs %}


Processing of JSON strings inside a JSON object

Apps Marketplace beta



Make Apps Marketplace is a Beta Program aimed at helping partners promote their apps as well as their companies and help users discover their apps and so realize greater value from Make as a platform.

We are super excited to launch this program together with our amazing partners! 🚀

Read more on [how-does-it-work.md](how-does-it-work.md "mention") and don’t forget about [terms-and-conditions.md](terms-and-conditions.md "mention") if you are interested in contributing your app to our marketplace.

Please, bear in mind this is a beta program and we may change anything in the program at any point in time, as well as to cancel the whole program. At the same time, we are aiming to be attentive to your feedback and continuously improve the Marketplace.


About

---
description: >-
  Disclaimer: All the answers below are our current state of thinking. Based on
  feedback from both partners and customers as well as business results we may
  adapt.
---

# How does it work



### App development

#### Is there a documentation on developing apps for Make?

Yes, there is a documentation: [https://docs.integromat.com/apps/](https://docs.integromat.com/apps/) . The apps accepted to the Apps Marketplace for Partners need to be _public_ (have an invite link generated) but not _approved_. Refer to [this](https://docs.integromat.com/apps/app-visibility) part of the documentation to understand differences.

#### Can we develop also templates for our apps?

As of now it is not possible to develop apps for custom apps.

### Submission process

#### How do I submit the app?

Submit the app by filling out the submission form: [https://tally.so/r/wdNWKo](https://tally.so/r/wdNWKo) . This form is meant for ready to be published apps.

#### Does the app need to be developed before submitting it to Make?

Yes. If you want to check with us whether certain app you haven’t developed yet would be worth your investment and see whether it’s not on our roadmap, contact your partner manager. Later we might introduce an even more transparent and self-serve way to check which apps are planned.

#### How do I know whether Make or another partner is working on an app so we can focus on really broadening the apps catalogue?

Contact your partner manager. We shall try to consolidate as complete list of intended apps by all parties as possible so we should be able to tell you. However, we don’t expect this list will ever be 100 % accurate.

#### Do we need to submit the source code?

No, you are not submitting the source code. You are going to submit (among other information):

1. your invite link so Make can see and test your app
2. landing page of your app where customers can obtain it.

#### What’s the expected approval time of an app?

Since we are only doing a business review of the app, not a technical or security review, we shall only need 2-3 business days to accept or refuse your app. However, as this is a new initiative, we may run into some bottlenecks which we shall try to remove ASAP.

### Marketing

#### How are you going to market the apps?

Make is going to display all partner apps among all other (native) apps on the [https://www.make.com/en/integrations](https://www.make.com/en/integrations) page.

![](<../.gitbook/assets/Add-on apps.webp>)

Each app will have its landing page on Make website which is going to feature versions from all partners who decided to develop and publish this app on the Marketplace. Each version will have a link to the partner’s site.

![](<../.gitbook/assets/image (2).png>)

On partner’s site partners may present any details about the app which shall help users understand its value and the way it’s used as well as any price and terms and conditions associated with its use. This information and any screenshots, videos, or even customer testimonials etc. may be crucial in customers deciding for this app.

![](<../.gitbook/assets/image (1).png>)

#### Will Make promote the apps to Make customers?

Yes. Once there is a reasonable amount of content from partners published on the marketplace (reasonable is vague and can be anywhere between 5 and 25), we are going to email all our users telling them about this exciting new source of apps.

In our community, there is a blogpost every time there are new native apps published. We shall strive for the same with Partner apps.

We may add further promotion mechanism in the later stages of the Apps Marketplace initiative.

### Installation process

#### What is the strategy on how the app will be shared with the end customers?

Partner creates and hosts his own landing page for the app where he needs to create his own mechanism for provisioning of the app to customers. It does not matter to Make whether Partner directly provides install link on their landing page (in case they are providing the app for free/open source), they require customers to send them an email, fill out a form or go through a registration and checkout process in partner’s marketplace. But at the end of the process, the app shall be installed in the customer’s Make organization.

#### How do customers install the app?

All apps submitted to the Apps Marketplace for Partners program need to be “invite link apps”. Therefore after you provide the customer with the app invite link, they need to install it into their Make organization unless you directly install the app to customer’s organization manually or via API. See also [#how-can-i-can-securely-share-access-to-my-app-with-customers-so-they-couldnt-share-it-with-other](how-does-it-work.md#how-can-i-can-securely-share-access-to-my-app-with-customers-so-they-couldnt-share-it-with-other "mention").

#### Who is hosting the app?

The app is hosted by Make, in your organization as published app with a generated invite link. However, you need to host your own landing pages for the app as of now.

### Monetization, pricing, billing

#### Is Make going to pay partners for developing apps?

No. Partners are free to monetize their apps by selling to Make customers directly.

#### Is Make going to provide the billing mechanism?

Not now. We may introduce that in the future as it would make the user journey easier and enable partners to develop faster but we are starting this initiative light. At the moment it is partner’s responsibility to bill their customers for the app usage.

#### How can I monetize my apps?

At the moment you need to create your own monetization mechanism. We have a couple suggested ways to do that. All of them require that you somehow exchange the access to the app for money.

1. Easiest to launch - Have customers write you an email, send them an invoice and then share the access with them
2. Middle way - Have customers fill out some form on your website, automatically send them an invoice, upon accepting and recognizing the payment, send them the access
3. Power way - Have customers subscribe to your service with a full checkout process and billing system. After subscribing, share access with them

#### How can I can securely share access to my app with customers so they couldn’t share it with other?

The easiest is to simply share an invite link to the app. If you simply share an invite link and have no further protection in place, you are risking that anyone who get their hands on this link can install and use your app without paying you.

Therefore, other partners often ask their customers for an access token as a parameter in the connection of the app. This token you would generate uniquely for each customer that paid for your app so sharing an app wouldn’t be as easy as you would be able to identify which token was used for sharing.

The most comprehensive way is to ask customers to generate an API key on the Make side with appropriate scopes and use this access to install the app directly into their organization, so you don’t have to share the link. See an example of how one of our partners did this [here](https://www.makemarket.io/how-to).

#### How can I price my apps?

However you want at the moment. Flat fee, monthly fee, based on consumption, based on customer size - really depends on you. We suggest that you choose a flat monthly fee with a price tag between $5 and $50 for SMB apps and between $100 and $1500 for enterprise apps.

Later, if customer feedback and data suggests that your app sells better with a lower price tag, we shall talk to you as it’s our joint goal to have as many users of your app on Make as possible while making as many dollars to you as possible.

#### How do you define SMB vs. Enterprise apps?

Based on the primary customers of the service your app is integrating with. E.g. SAP S/4 HANA is primarily focused on Enterprise customers, Pipedrive in the contrary is SMB focused CRM.

#### Is Make going to take any cut from the app price?

Not at the moment, but we are considering it for the future. Generally speaking, we are also interested in this extra revenue stream while the most important revenue stream for us is selling Make so we would definitely leave majority of the app related revenues to partners.

### Support of apps

#### Who is responsible for supporting the apps?

You as a partner are responsible for supporting the apps you submitted to the Apps Marketplace.

#### How do customers get to know who is providing support for the app?

First, when they search for the app on Make website, we are telling them that partner apps are supported by partners themselves, not us.

Second, we hope that you tell them this information yourself on your landing pages and possibly in your terms and conditions.

Third, you may make the app name in a way that it says the name of the app followed by “by XYZ”, e.g. “Salesforce by [Partner.com](http://partner.com)”. This shall emphasize it’s a partner app and where should I ask for help.

Fourth, you may add an info box to your app containing information where to ask for support so it’s visible every time a user opens some module. Example:

![](../.gitbook/assets/image.png)

Fifth, if even so a customer reaches out to Make to ask for support with your app, we are going to redirect the request to you. That is why we are asking for your support email address when you are submitting an app to the marketplace.

#### What level of support is Make expecting from us?

At the moment, we are not prescribing any specific level of support you should provide to customers. We expect you to create your own terms and conditions and we assume you are interested in keeping your customers happy as you are realizing some value from them (either they directly pay you or the app serves as a lead generator/value creator for your professional services business).

That being said, we assume that you will handle customer requests in reasonable time, especially if we redirected you a support request from our customer. We especially expect you to act promptly if we need to escalate some issue to you.

If you would repeatedly fail to address customers issues and concerns in timely manner, we may take over the app to ensure our customers can rely on our platform and apps associated with the platform as a holistic solution to their business needs. We want to make sure that our platform enables customers to continuously run their business and we expect that you are assuring this with us as a part of our ecosystem.

### Allowed apps

#### Why is Make only allowing apps not yet available as native apps?

First, we primarily want to extend the offering, not improve existing apps at this stage. Second, some 3rd party apps are massively reducing the number of operations consumed compared to our apps (e.g. Google Sheets) which impacts our business. Third, we don’t have a mechanism to clearly differentiate native and 3rd party apps at the moment if there are both of them for the same app.

That being said, we are considering it and happy to hear about apps we already have as native and you would like to introduce your version as we know that there is space for improvement in many of our native apps. In that case, contact your partner manager.

#### Can I submit an app which allows batch operations?

While we are not going to check that deeply to uncover this prior to your submission, we want to emphasize that apps should only be providing the functionality of the API. So, if there is and endpoint for batch update, then sure, go for that if you want. But you shall not artificially reduce number of operations being consumed (e.g. by leveraging IML functions to combine multiple bundles into 1 bundle) as that is impacting Make business, and so also your partner reselling business.

#### Only apps that are not currently natively in Make will be approved. What happens if a Partner app is approved and then Make develops it?

Generally we will try to avoid this situation at this stage. So, we only allow the app if we are not actively developing it yet. If we have it on roadmap but didn’t invest in it yet and we decide to allow it, then we will also not continue in internal development. If it’s published by a Partner, we will generally not decide to develop the same app unless we have strong reasons to do so, like Partner not supporting the app well enough or if the app somehow blocks growth of Make usage (e.g. partner is pricing it too high and we have feedback from users they would use it if it was cheaper/free and partner is not willing to work with us on that or something like that).

Our current strategy is not about creating revenues through selling our own apps so we are happy if partners are building apps and making money. However, we need to make sure it helps fuel our business which is based on number of customers and the operations they consume.

It is fair to say that we are also considering allowing same apps from Make and partners. If we decide to allow that and once we are ready to do that, your and our app would simply coexist and customers could choose. As you know, our apps are not always better than yours, so you can consider us at that point “just another” developer being present on the Marketplace and customers can choose what’s best for them.

#### Why are you allowing the same apps from multiple partners?

We believe there is customer value in variety and choice. Especially for complex apps there can be different modules covered or with different quality. Also, monetization model can be different. Support may be available in different time zones and localizations.

#### How are customers going to choose which app is better for them?

1. Description on partner website including modules covered
2. Monetization model and price
3. Location and localization of partner

Later:

1. Number of customers
2. Ratings and reviews

### Cancelling the Apps Marketplace Beta program

#### What happens if Make decides to cancel the beta program Apps Marketplace for Partners?

* Tell partners program was cancelled and remove their listings on our web
* Tell customers actively using 3rd party apps we cancelled this program but they can keep using the 3rd party apps which they already installed
* Tell the whole Make we did this and why

### Contacts

#### Who is my go to contact?

Your partner manager is your main point of contact.


How does it work

---
description: Submission and listing of Apps to the Make Apps Marketplace Terms & Conditions
---

# Terms and Conditions

Effective since: June 16, 2023

1. In order to post any custom applications or modules to the Make Apps Marketplace (each, a “Partner-developed App”) You must have an active Make Partnership Agreement.&#x20;
2. Your submission, and the subsequent listing, of each Partner-developed App to the Make Apps Marketplace is subject to (a) Your Make Partnership Agreement with Us and (b) these Terms & Conditions.
3. Capitalized terms used in these Terms & Conditions shall have the same meaning as in Your Make Partnership Agreement.
4. All Partner-developed App submissions are subject to review by Us prior to their being posted on the Make Apps Marketplace. We may accept or reject the submission of any Partner-developed App at Our sole discretion. We reserve the right to re-review any Partner-developed App for continued compatibility with the Make Products.
5. The Make Apps Marketplace is intended to be a promotional platform for Partner-developed Apps appearing thereupon. You shall be responsible for the actual distribution and licensing of your Partner-developed Apps to Make Products subscribers. You further agree that:
   1. You are solely responsible for the maintenance and support of Your Partner-developed Apps. In the event You fail to adequately maintain Your Partner-developed Apps, We may, at Our sole discretion remove the affected Partner-developed Apps from the Make Apps Marketplace;
   2. Nothing shall prevent Us from developing and publishing an app substantially similar or equivalent to any Partner-developed App, provided We do not use Your Confidential Information during the course of such development;
   3. We shall have sole discretion to discontinue any Partner-developed Apps and remove such Partner-developed Apps from the Make website at any time without notice; and
   4. You shall defend and/or settle, at Your expense, any third-party claim brought against Us or Our Representatives arising from or related to Your Parter-developed Apps or the description and images of the Partner-developed Apps used on the Make Apps Marketplace (“Partner-developed Apps Claim”). “Representatives” means Our, and Our Affiliates’, employees, officers, directors, advisers, agents and subcontractors. You shall indemnify Us and Our Representatives against any losses arising from or related to the Partner-developed Apps Claim or settlement amounts agreed to in writing by You in relation to such Partner-developed Apps Claim.


Terms and Conditions

Tips and tricks

Default

🟢 [PROD] Custom Apps Documentation

Make.com - Custom App Documentation

<p class="slate-p slate-indent-0" style="0px">Make Custom Apps documentation is a guide for developers looking to create their own apps for themselves or others to use on the Make platform. This documentation will walk you through how to use Make Apps Editor in Make UI and in Visual Studio Code to create and manage those custom apps, as well as best practices and common approaches for development. </p><div style="width:60%;
	min-width:60%;" class="callout-widget" data-type=info ><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p slate-indent-0" style="0px"><a href="https://developers.make.com/custom-apps-documentation/make-apps-editor/develop-apps-in-vs-code/develop-apps-collaboratively" target="_top">Collaborative development</a>, <a href="https://developers.make.com/custom-apps-documentation/make-apps-editor/develop-apps-in-vs-code/manage-testing-and-production-app-versions" target="_top">version control</a>, and <a href="https://developers.make.com/custom-apps-documentation/make-apps-editor/develop-apps-in-vs-code/local-development-for-apps" target="_top">local development</a> are now supported!</p></div></div><h2 class="slate-h2 " >Introduction to creating custom apps</h2><p class="slate-p " >When there is a service that you want to use in Make but the service is not yet available in Make, use the apps builder to create a custom app. The only requirement is that the service has to have an API.</p><p class="slate-p " >In the apps builder, you write down a JSON configuration. This configuration is then used by the Make platform to generate all connections and app modules for you. If you are working on a complicated custom app, you can write a custom IML function with JavaScript.</p><p class="slate-p " >There are two options directly supported by Make to write the custom app configuration:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">The web interface of your Make account instance.</div></li><li class="slate-li " ><div style="position:relative">The Visual Studio Code (VS Code) extension.</div></li></ul><p class="slate-p " >The benefits of using VS Code over the Make account web interface are for example:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">first-class support for JSON format, like syntax highlighting and completion,</div></li><li class="slate-li " ><div style="position:relative">automatic checking of the JSON configuration validity, notably in terms of parameter type checking and correct object context,</div></li><li class="slate-li " ><div style="position:relative">predefined project structure for every custom app you create,</div></li></ul><p class="slate-p " >Follow the instructions <a href="https://developers.make.com/custom-apps-documentation/make-apps-editor/develop-apps-in-vs-code/configure-vs-code" target="_top">here</a> to configure the VS Code extension.</p><p class="slate-p " >If you want to write the custom app configuration in the Make web interface, navigate to <strong class="slate-bold">Custom apps</strong> in the left sidebar menu of your Make account. You might have to click on the three dots at the bottom of the left sidebar to view the <strong class="slate-bold">Custom apps</strong> option.</p><p class="slate-p " >If you are developing a custom app for the first time, check out the <a href="https://developers.make.com/custom-apps-documentation/create-your-first-app" target="_top">Create your first app</a> section first.</p><p class="slate-p " ></p><h2 class="slate-h2 " >Important notes</h2><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">All modules can be tested directly in scenarios.</div></li><li class="slate-li " ><div style="position:relative">Changes to communication configs are immediately active.</div></li><li class="slate-li " ><div style="position:relative">You can see raw requests/responses in your browser&apos;s console.</div></li><li class="slate-li " ><div style="position:relative">Changes in parameters and interface requires you to reload scenario editor page.</div></li><li class="slate-li " ><div style="position:relative">We use JSONC (JSON with comments) in all sections except common data.</div></li></ul><p class="slate-p " ></p><h2 class="slate-h2 " >Collaborative development</h2><div style="width:60%;
	min-width:60%;" class="callout-widget" data-type=success ><div ><svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M7.77116 10.8968L5.72949 8.8551C5.60449 8.7301 5.45171 8.6676 5.27116 8.6676C5.0906 8.6676 4.93088 8.73705 4.79199 8.87594C4.6531 9.01482 4.58366 9.17455 4.58366 9.3551C4.58366 9.53566 4.6531 9.68844 4.79199 9.81344L7.33366 12.3551C7.45866 12.4801 7.60449 12.5426 7.77116 12.5426C7.93783 12.5426 8.08366 12.4801 8.20866 12.3551L13.2087 7.3551C13.3337 7.2301 13.3927 7.07732 13.3857 6.89677C13.3788 6.71621 13.3128 6.56344 13.1878 6.43844C13.0628 6.29955 12.9066 6.2301 12.7191 6.2301C12.5316 6.2301 12.3684 6.29955 12.2295 6.43844L7.77116 10.8968ZM9.00033 17.3343C7.81977 17.3343 6.72255 17.1225 5.70866 16.6989C4.69477 16.2752 3.81283 15.6884 3.06283 14.9384C2.31283 14.1884 1.72602 13.3065 1.30241 12.2926C0.878798 11.2787 0.666992 10.1815 0.666992 9.00094C0.666992 7.83427 0.878798 6.74399 1.30241 5.7301C1.72602 4.71621 2.31283 3.83427 3.06283 3.08427C3.81283 2.33427 4.69477 1.74399 5.70866 1.31344C6.72255 0.88288 7.81977 0.667603 9.00033 0.667603C10.167 0.667603 11.2573 0.88288 12.2712 1.31344C13.285 1.74399 14.167 2.33427 14.917 3.08427C15.667 3.83427 16.2573 4.71621 16.6878 5.7301C17.1184 6.74399 17.3337 7.83427 17.3337 9.00094C17.3337 10.1815 17.1184 11.2787 16.6878 12.2926C16.2573 13.3065 15.667 14.1884 14.917 14.9384C14.167 15.6884 13.285 16.2752 12.2712 16.6989C11.2573 17.1225 10.167 17.3343 9.00033 17.3343ZM9.00033 16.0843C11.0142 16.0843 12.6982 15.4072 14.0524 14.053C15.4066 12.6989 16.0837 11.0148 16.0837 9.00094C16.0837 6.98705 15.4066 5.30302 14.0524 3.94885C12.6982 2.59469 11.0142 1.9176 9.00033 1.9176C6.98644 1.9176 5.30241 2.59469 3.94824 3.94885C2.59408 5.30302 1.91699 6.98705 1.91699 9.00094C1.91699 11.0148 2.59408 12.6989 3.94824 14.053C5.30241 15.4072 6.98644 16.0843 9.00033 16.0843Z" fill="#06837A"></path></svg></div><div ><p class="slate-p " >The Make Apps Editor VS Code extension contains support for Git.</p><p class="slate-p " >Learn how to utilize the <a href="https://developers.make.com/custom-apps-documentation/make-apps-editor/develop-apps-in-vs-code/local-development-for-apps" target="_top">Local Development for Apps feature</a> to <a href="https://developers.make.com/custom-apps-documentation/make-apps-editor/develop-apps-in-vs-code/develop-apps-collaboratively" target="_self">develop collaboratively</a>.</p></div></div><p class="slate-p " ></p>

Make Custom Apps documentation is a guide for developers looking to create their own apps for themselves or others to use on the Make platform. This documentation will walk you through how to use Make Apps Editor in Make UI and in Visual Studio Code to create and manage those custom apps, as well as best practices and common approaches for development. 

When there is a service that you want to use in Make but the service is not yet available in Make, use the apps builder to create a custom app. The only requirement is that the service has to have an API.

In the apps builder, you write down a JSON configuration. This configuration is then used by the Make platform to generate all connections and app modules for you. If you are working on a complicated custom app, you can write a custom IML function with JavaScript.

There are two options directly supported by Make to write the custom app configuration:

The benefits of using VS Code over the Make account web interface are for example:

If you want to write the custom app configuration in the Make web interface, navigate to 

 in the left sidebar menu of your Make account. You might have to click on the three dots at the bottom of the left sidebar to view the 

If you are developing a custom app for the first time, check out the 

<p class="slate-p " >The Apps Builder documentation is divided into topic groups. The topic groups are structured the same way as you would navigate inside the Apps Builder in Make.</p><p class="slate-p " ></p><h2 class="slate-h2 " >App structure</h2><p class="slate-p " >The <a href="https://developers.make.com/custom-apps-documentation/base" target="_self">App structure</a> section describes how to define and configure the basic elements of a custom app. The basic custom app elements are listed in the top menu in the custom app configuration, for example: <span style="color:#000000"><strong class="slate-bold">Base</strong></span><strong class="slate-bold">, </strong><span style="color:#000000"><strong class="slate-bold">Communication</strong></span><strong class="slate-bold">, </strong><span style="color:#000000"><strong class="slate-bold">Modules</strong></span><span style="color:#000000">.</span></p><div style="text-align:left"><img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/83816c51-f4c8-430c-bb25-196bebdddb1e.png" style="
              width:747px;
	            height:448px;
	            aspect-ratio:747 / 448"
         /></div><div style="width:60%;
	min-width:60%;" class="callout-widget" data-type=info ><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >Where do I find it? Go to <strong class="slate-bold">Menu</strong> -&gt; <strong class="slate-bold">Custom apps</strong> tab -&gt; open your custom app.</p></div></div><p class="slate-p " ></p><h2 class="slate-h2 " >App blocks</h2><p class="slate-p " >Every structure element is divided into <strong class="slate-bold">blocks</strong>. Some of these blocks appear in multiple places and share the same purpose, others do not.</p><div style="text-align:left"><img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/e59d9e54-f70a-482e-a3a5-d4b9acaa8527.png" style="
              width:762px;
	            height:461px;
	            aspect-ratio:762 / 461"
         /></div><div style="width:60%;
	min-width:60%;" class="callout-widget" data-type=info ><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p slate-indent-0" style="0px">For example, <strong class="slate-bold">Parameters</strong> (static or mappable) are available everywhere apart from <span style="color:#000000"><strong class="slate-bold">Base</strong></span> and <span style="color:#000000"><strong class="slate-bold">Functions</strong></span>. Meanwhile, <strong class="slate-bold">Common data</strong> exists only inside <span style="color:#000000"><strong class="slate-bold">Base</strong></span> and <span style="color:#000000"><strong class="slate-bold">Connection</strong></span>.</p></div></div><p class="slate-p " ></p><h2 class="slate-h2 " >App components</h2><p class="slate-p " ><strong class="slate-bold">Components </strong>are like bricks for <strong class="slate-bold">app blocks</strong>.  A block doesn&apos;t exist without components. Multiple components - form a block. </p><p class="slate-p " >Pick a brick that suits your needs and use it. You can use multiple separated components or combine them together by using the <code class="slate-code">nested</code> property. Play around and find the best components combination for you!</p><p class="slate-p " >For example, a module may look like this:</p><div style="text-align:left"><img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/3e1cf4d1-50f6-477b-8c73-61b364d2fb92.png" style="
              width:762px;
	            height:464px;
	            aspect-ratio:762 / 464"
         /></div><p class="slate-p " >Behind the scenes looks like this:</p><div style="text-align:left"><img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/0eb32837-f0ef-4a05-9afc-c57bdee55c90.png" style="
              width:746px;
	            height:455px;
	            aspect-ratio:746 / 455"
         /></div><p class="slate-p " >One example of the parameters could be:</p><div style="width:60%;
	min-width:60%;" class="callout-widget" data-type=info ><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p slate-indent-0" style="0px">When for a call you need to provide a name and an email -&gt; you would use parameters <code class="slate-code">&quot;type&quot;: &quot;email&quot;</code> and <code class="slate-code">&quot;type&quot;: &quot;text&quot;</code>.</p></div></div><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JavaScript</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-javascript keep-markup drop-tokens"><div class="slate-code_line">[</div><div class="slate-code_line">    {</div><div class="slate-code_line">        &quot;name&quot;: &quot;email&quot;,</div><div class="slate-code_line">        &quot;label&quot;: &quot;Email&quot;,</div><div class="slate-code_line">        &quot;type&quot;: &quot;email&quot;</div><div class="slate-code_line">    },</div><div class="slate-code_line">    {</div><div class="slate-code_line">        &quot;name&quot;: &quot;name&quot;,</div><div class="slate-code_line">        &quot;label&quot;: &quot;Name&quot;,</div><div class="slate-code_line">        &quot;type&quot;: &quot;text&quot;</div><div class="slate-code_line">    }</div><div class="slate-code_line">]</div></code></pre></div><p class="slate-p " >Another example of the parameters could be:</p><div style="width:60%;
	min-width:60%;" class="callout-widget" data-type=info ><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p slate-indent-0" style="0px">When for a call in case X you need to provide a name and in case Y an email-&gt; you would use parameters <code class="slate-code">&quot;type&quot;: &quot;select&quot;</code> with nested parameters<code class="slate-code"> &quot;type&quot;: &quot;email&quot;</code>/ <code class="slate-code">&quot;type&quot;: &quot;text&quot;</code> under each option.</p></div></div><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JavaScript</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-javascript keep-markup drop-tokens"><div class="slate-code_line">[</div><div class="slate-code_line">    {</div><div class="slate-code_line">        &quot;name&quot;: &quot;select&quot;,</div><div class="slate-code_line">        &quot;label&quot;: &quot;Select&quot;,</div><div class="slate-code_line">        &quot;type&quot;: &quot;select&quot;,</div><div class="slate-code_line">        &quot;options&quot;: [</div><div class="slate-code_line">            {</div><div class="slate-code_line">                &quot;label&quot;: &quot;Case X&quot;,</div><div class="slate-code_line">                &quot;value&quot;: &quot;caseX&quot;,</div><div class="slate-code_line">                &quot;nested&quot;: [</div><div class="slate-code_line">                    {</div><div class="slate-code_line">                        &quot;name&quot;: &quot;email&quot;,</div><div class="slate-code_line">                        &quot;label&quot;: &quot;Email&quot;,</div><div class="slate-code_line">                        &quot;type&quot;: &quot;email&quot;</div><div class="slate-code_line">                    }</div><div class="slate-code_line">                ]</div><div class="slate-code_line">            },</div><div class="slate-code_line">            {</div><div class="slate-code_line">                &quot;label&quot;: &quot;Case Y&quot;,</div><div class="slate-code_line">                &quot;value&quot;: &quot;caseY&quot;,</div><div class="slate-code_line">                &quot;nested&quot;: [</div><div class="slate-code_line">                    {</div><div class="slate-code_line">                        &quot;name&quot;: &quot;name&quot;,</div><div class="slate-code_line">                        &quot;label&quot;: &quot;Name&quot;,</div><div class="slate-code_line">                        &quot;type&quot;: &quot;text&quot;</div><div class="slate-code_line">                    }</div><div class="slate-code_line">                ]</div><div class="slate-code_line">            }</div><div class="slate-code_line">        ]</div><div class="slate-code_line">    }</div><div class="slate-code_line">]</div></code></pre></div><p class="slate-p " ></p><h2 class="slate-h2 " >Search</h2><p class="slate-p slate-indent-0" style="0px">If you&apos;re having trouble finding what you need, try using the <strong class="slate-bold">Search</strong> feature at the top of the page.</p>

The Apps Builder documentation is divided into topic groups. The topic groups are structured the same way as you would navigate inside the Apps Builder in Make.

 section describes how to define and configure the basic elements of a custom app. The basic custom app elements are listed in the top menu in the custom app configuration, for example: 

. Some of these blocks appear in multiple places and share the same purpose, others do not.

.  A block doesn't exist without components. Multiple components - form a block. 

Pick a brick that suits your needs and use it. You can use multiple separated components or combine them together by using the 

 property. Play around and find the best components combination for you!

For example, a module may look like this:

email

name

Another example of the parameters could be:

select

If you're having trouble finding what you need, try using the 

<h2>Develop apps in Make UI</h2><p>The Make UI allows you to browse Example and Custom apps you previously created. </p><p>When developing an app, you can work with components such as base, connections, webhooks, modules, RPCs, and custom IML functions.</p><div><div></div></div>

The Make UI allows you to browse Example and Custom apps you previously created. 

When developing an app, you can work with components such as base, connections, webhooks, modules, RPCs, and custom IML functions.

The VS Code extension supports all jobs available in the Make UI, additionally, it empowers developers with the following capabilities:

<p>This tutorial will guide you through the steps to create a custom app with a module. You will use the Make "Virtual Library Demo API."</p><p>Click the link If you want to test the Virtual Library Demo API: <a href="http://demo-api.integrokit.com/api/v1/helloworld" target="_self">http://demo-api.integrokit.com/api/v1/helloworld</a></p><p>A new tab opens in your web browser with the API response in JSON format:</p>

This tutorial will guide you through the steps to create a custom app with a module. You will use the Make "Virtual Library Demo API."

Click the link If you want to test the Virtual Library Demo API: 

A new tab opens in your web browser with the API response in JSON format:

The development of a custom app in Make is divided into several steps. These steps are described in detail in the following subpages.

<p>During the development of your app, you will probably experience multiple issues with your app and/or API. Therefore, you will need to use Make DevTool and/or console in order to debug your app. Continue below in order to learn how!</p><p></p><h3>Basics of debugging</h3><p>You can easily debug your app using Make DevTool or Chrome DevTool's console. Learn how to use the </p>

During the development of your app, you will probably experience multiple issues with your app and/or API. Therefore, you will need to use Make DevTool and/or console in order to debug your app. Continue below in order to learn how!

You can easily debug your app using Make DevTool or Chrome DevTool's console. Learn how to use the 

Debugging of pagination in list/search module

When the GET endpoint, which you are using, supports pagination, you need to make sure the module uses it correctly. Learn how you can 

Make apps platform has a tool for testing the behavior of your RPCs. Thanks to this tool, testing of RPCs is easy. Learn how to 

Implementing a custom IML function might get complicated, so you will need to learn how to effectively 

<p>Inspect your scenarios in Integromat at a glance!</p><h3>About the DevTool</h3><p>Integromat DevTool allows you to debug your Make scenarios in a completely new way. It will add an extra panel to the Chrome Developer Tools. Using this new debugger panel you are able to check all manual runs of your scenario, review all the performed operations, and see details of every single API call perf</p>

Inspect your scenarios in Integromat at a glance!

Integromat DevTool allows you to debug your Make scenarios in a completely new way. It will add an extra panel to the Chrome Developer Tools. Using this new debugger panel you are able to check all manual runs of your scenario, review all the performed operations, and see details of every single API call performed. It also brings a whole bunch of new opportunities for the Apps development. You are able to check every single call that your app has performed. Thanks to this extension you can easily debug your scenario, see which module, operation, or even which single response causes the error, and then get your scenario back on track. Try it out and let your scenarios shine!

DevTool consists of 3 main modules - Live Stream, Scenario Debugger, and Tools. Each of them is described in detail in the next subpages.

<p class="slate-p slate-indent-0" style="0px">This document describes common approaches and naming conventions which every apps developer should follow to keep Make consistent.</p><div class="table-container" style="width:60%;
  min-width:60%;"><table class="slate-table" ><colgroup ><col style="width:0%"><col style="width:0%"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/names-labels-and-descriptions" target="_self">Names, labels & descriptions</a></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/base-1" target="_self">Base</a></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/connections-1" target="_self">Connection</a></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/modules-2" target="_self">Modules</a></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/action-and-search-modules" target="_self">Action and search modules</a></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/action-modules" target="_self">Action modules</a></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/search-modules" target="_self">Search modules</a></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/update-modules" target="_self">Update modules</a></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/trigger-modules" target="_self">Trigger modules</a></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/remote-procedure-calls-1" target="_self">Remote Procedure Calls</a></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/static-parameters-1" target="_self">Static parameters</a></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/mappable-parameters-1" target="_self">Mappable parameters</a></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/processing-of-input-parameters" target="_self">Processing of input parameters</a></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/processing-of-output-parameters" target="_self">Processing of output parameters</a></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><a href="https://developers.make.com/custom-apps-documentation/best-practices/groups-1" target="_self">Groups</a></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ></p></td></div></tr></tbody></table></div><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

This document describes common approaches and naming conventions which every apps developer should follow to keep Make consistent.

<h2 class="slate-h2 " >Module names</h2><div style="width:60%;
	min-width:60%;" data-type=warning ><div ><svg width="18" height="16" viewBox="0 0 18 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.916637 15.5009C0.791637 15.5009 0.683998 15.4732 0.59372 15.4176C0.503443 15.362 0.430526 15.2857 0.37497 15.1884C0.319415 15.0912 0.288165 14.9905 0.28122 14.8864C0.274276 14.7822 0.305526 14.6745 0.37497 14.5634L8.4583 0.605103C8.52775 0.493991 8.60761 0.41413 8.69789 0.365519C8.78816 0.316908 8.88886 0.292603 8.99997 0.292603C9.11108 0.292603 9.21178 0.316908 9.30205 0.365519C9.39233 0.41413 9.47219 0.493991 9.54164 0.605103L17.625 14.5634C17.6944 14.6745 17.7257 14.7822 17.7187 14.8864C17.7118 14.9905 17.6805 15.0912 17.625 15.1884C17.5694 15.2857 17.4965 15.362 17.4062 15.4176C17.3159 15.4732 17.2083 15.5009 17.0833 15.5009H0.916637ZM1.99997 14.2509H16L8.99997 2.1676L1.99997 14.2509ZM9.0833 13.0634C9.26386 13.0634 9.41316 13.0044 9.53122 12.8864C9.64928 12.7683 9.7083 12.619 9.7083 12.4384C9.7083 12.2579 9.64928 12.1086 9.53122 11.9905C9.41316 11.8725 9.26386 11.8134 9.0833 11.8134C8.90275 11.8134 8.75344 11.8725 8.63539 11.9905C8.51733 12.1086 8.4583 12.2579 8.4583 12.4384C8.4583 12.619 8.51733 12.7683 8.63539 12.8864C8.75344 13.0044 8.90275 13.0634 9.0833 13.0634ZM9.0833 10.7509C9.26386 10.7509 9.41316 10.6919 9.53122 10.5739C9.64928 10.4558 9.7083 10.3065 9.7083 10.1259V6.70927C9.7083 6.52871 9.64928 6.37941 9.53122 6.26135C9.41316 6.1433 9.26386 6.08427 9.0833 6.08427C8.90275 6.08427 8.75344 6.1433 8.63539 6.26135C8.51733 6.37941 8.4583 6.52871 8.4583 6.70927V10.1259C8.4583 10.3065 8.51733 10.4558 8.63539 10.5739C8.75344 10.6919 8.90275 10.7509 9.0833 10.7509Z" fill="#F1C21B"></path></svg></div><div ><p class="slate-p " >A name of a module, an RPC, or a custom IML function should not match with any reserved word in JavaScript. See the list of reserved words in JavaScript <a href="https://www.w3schools.com/js/js_reserved.asp" target="_blank">here</a>. </p></div></div><h2 class="slate-h2 " >Module labels</h2><p class="slate-p " >Every module should have a label that precisely describes the module's use. For each type of module, there is a standard naming convention. But it may change depending on the functionality of the module. The label should be composed of the verb expressing the intended action (Create, Update, Watch, etc.) and the name of the entity being processed (Customer,  Invoice,  Table, etc.).</p><p class="slate-p " >Names of modules follow the English format - they are capitalized - Specifically, they use Title Case - refer to <a href="https://en.wikipedia.org/wiki/Title_case#Chicago_Manual_of_Style" target="_blank">Chicago Manual of Style</a>. Basically, every word is capitalized except for articles, prepositions, and conjunctions.</p><p class="slate-p " ><strong class="slate-bold">Good practice</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Watch Events</div></li><li class="slate-li " ><div style="position:relative">Create a Report</div></li><li class="slate-li " ><div style="position:relative">Update a Record</div></li><li class="slate-li " ><div style="position:relative">List Photos</div></li><li class="slate-li " ><div style="position:relative">Search Files</div></li><li class="slate-li " ><div style="position:relative">Add Members to a Group</div></li><li class="slate-li " ><div style="position:relative">Get a Group's Info
</div></li></ul><p class="slate-p " ><strong class="slate-bold">Bad practice</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Watch events</div></li><li class="slate-li " ><div style="position:relative">Create a report</div></li><li class="slate-li " ><div style="position:relative">Make a call</div></li><li class="slate-li " ><div style="position:relative">List photos</div></li><li class="slate-li " ><div style="position:relative">Search files</div></li><li class="slate-li " ><div style="position:relative">Add members to Group</div></li><li class="slate-li " ><div style="position:relative">Get group info</div></li></ul><h2 class="slate-h2 " >Triggers and instant triggers (webhooks) </h2><p class="slate-p " >These modules watch for new data in a given service and return it. Compose the label according to this pattern <strong class="slate-bold">Watch <watched node></strong></p><p class="slate-p " >Examples:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Watch Events</div></li><li class="slate-li " ><div style="position:relative">Watch Photos</div></li><li class="slate-li " ><div style="position:relative">Watch Deleted Files</div></li></ul><h2 class="slate-h2 " >Actions </h2><p class="slate-p " >These modules write data into a service, modify data in the service, or retrieve a single result. Compose the label using simple verbs like <strong class="slate-bold">Create, Get, Update</strong> and <strong class="slate-bold">Delete</strong> and the modified or created node. Use the naming convention of the service you are implementing.</p><p class="slate-p " >Examples:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Create a Note</div></li><li class="slate-li " ><div style="position:relative">Update a File</div></li><li class="slate-li " ><div style="position:relative">Get a User</div></li><li class="slate-li " ><div style="position:relative">Delete a Task</div></li></ul><h2 class="slate-h2 " >Searches </h2><p class="slate-p " >These modules retrieve data from the service and allow retrieving one or more results. Compose the label using simple verbs like <strong class="slate-bold">Search</strong> or <strong class="slate-bold">List</strong>. Use the naming convention of the service you are implementing.</p><p class="slate-p " >Examples:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Search Files</div></li><li class="slate-li " ><div style="position:relative">List Tasks</div></li></ul><h2 class="slate-h2 " >Module descriptions</h2><p class="slate-p " >In a few words, describe the functionality of the module. Write the description in the third person and capitalize only the first letter of the first word in the description (like a normal sentence structure). </p><p class="slate-p " >Example: Description for the module <strong class="slate-bold">Update a Time Entry:</strong></p><p class="slate-p " ><strong class="slate-bold">Good practice</strong></p><p class="slate-p " >Updates a time entry for a specific user.</p><p class="slate-p " ><strong class="slate-bold">Bad practice</strong></p><p class="slate-p " >Update a Time Entry for a Specific User.</p><div style="width:60%;
	min-width:60%;" data-type=info ><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >The description is missing "s" for word "Update". The "Time Entry" and "Specific User" should be lowercase.</p></div></div><p class="slate-p " ><strong class="slate-bold">Triggers</strong> use the "Triggers when..." in the descriptions. For example, the description for the module <strong class="slate-bold">Watch New Users</strong> should be: **"**Triggers when a new user is created."</p><h2 class="slate-h2 " >Names and labels of input and output parameters </h2><p class="slate-p " >For labels, try to use the same names and conventions as in the integrated service. It helps users to use the app in Make and not be confused.</p><p class="slate-p " >For variable names, use the same names that come from the service API. It helps when debugging for both advanced Make users and support agents. Ideally, the output of the module should be the same as the response from the API.</p><p class="slate-p " >Example:</p><p class="slate-p " ><strong class="slate-bold">Output parameters</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">[</div><div class="slate-code_line">    {</div><div class="slate-code_line">        "name": "id",</div><div class="slate-code_line">        "label": "ID",</div><div class="slate-code_line">        "type": "text"</div><div class="slate-code_line">    },</div><div class="slate-code_line">    {</div><div class="slate-code_line">        "name": "note",</div><div class="slate-code_line">        "label": "Note",</div><div class="slate-code_line">        "type": "text"</div><div class="slate-code_line">    },</div><div class="slate-code_line">    {</div><div class="slate-code_line">        "name": "firstName",</div><div class="slate-code_line">        "label": "First Name",</div><div class="slate-code_line">        "type": "text"</div><div class="slate-code_line">    },</div><div class="slate-code_line">    {</div><div class="slate-code_line">        "name": "shortUrl",</div><div class="slate-code_line">        "label": "Short URL",</div><div class="slate-code_line">        "type": "url"</div><div class="slate-code_line">    }</div><div class="slate-code_line">]</div></code></pre></div><p class="slate-p " ><strong class="slate-bold">API response</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">    "id": "59b1396a4a22a7a3bfc78e22",</div><div class="slate-code_line">    "note": "Hey",</div><div class="slate-code_line">    "firstName": "John",</div><div class="slate-code_line">    "shortUrl": "https://trello.com/c/LdcrM4wa"</div><div class="slate-code_line">}</div></code></pre></div><h2 class="slate-h2 " >Abbreviations</h2><p class="slate-p " >Be sure to use the correct uppercase for abbreviated words, such as ID, IDs, URL, GPS, VAT, etc.</p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

Every module should have a label that precisely describes the module's use. For each type of module, there is a standard naming convention. But it may change depending on the functionality of the module. The label should be composed of the verb expressing the intended action (Create, Update, Watch, etc.) and the name of the entity being processed (Customer,  Invoice,  Table, etc.).

Names of modules follow the English format - they are capitalized - Specifically, they use Title Case - refer to 

. Basically, every word is capitalized except for articles, prepositions, and conjunctions.

Triggers and instant triggers (webhooks) 

These modules watch for new data in a given service and return it. Compose the label according to this pattern 

These modules write data into a service, modify data in the service, or retrieve a single result. Compose the label using simple verbs like 

 and the modified or created node. Use the naming convention of the service you are implementing.

These modules retrieve data from the service and allow retrieving one or more results. Compose the label using simple verbs like 

. Use the naming convention of the service you are implementing.

In a few words, describe the functionality of the module. Write the description in the third person and capitalize only the first letter of the first word in the description (like a normal sentence structure). 

Updates a time entry for a specific user.

 use the "Triggers when..." in the descriptions. For example, the description for the module 

 should be: **"**Triggers when a new user is created."

Names and labels of input and output parameters 

For labels, try to use the same names and conventions as in the integrated service. It helps users to use the app in Make and not be confused.

For variable names, use the same names that come from the service API. It helps when debugging for both advanced Make users and support agents. Ideally, the output of the module should be the same as the response from the API.

note

firstName

shortUrl

Be sure to use the correct uppercase for abbreviated words, such as ID, IDs, URL, GPS, VAT, etc.

<p class="slate-p " >The Base section should contain data that is common to all (or most) requests. At the very least, this should include the root URL, the authorization headers, the error-handling section, and the sanitization.</p><p class="slate-p " ><strong class="slate-bold">Correct</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{
    "baseUrl": "https://www.example.com/api/v1",
    "headers": {
        "Authorization": "Bearer {{connection.accessToken}}"
    },
    "response": {
        "error": {
            "message": "[{{statusCode}}] {{body.error.message}} (error code: {{body.error.code}})"
        }
    },
    "log": {
        "sanitize": [
            "request.headers.authorization"
        ]
    }
}</div></code></pre></div><p class="slate-p " ><strong class="slate-bold">Incorrect</strong></p><div style="text-align:left"><img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/816544e7-7e89-4584-973d-f2680c2e2a62.png" style="
              width:1052px;
	            height:229px;
	            aspect-ratio:1052 / 229"
         /></div><h2 class="slate-h2 " >Base URL</h2><p class="slate-p " >Make sure that the <a href="https://developers.make.com/custom-apps-documentation/apps-builder-documentation/app-structure/base/base-url" target="_self">Base URL</a> uses the URL of the API, which is shared among all modules or their majority.</p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=warning ><div ><svg width="18" height="16" viewBox="0 0 18 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.916637 15.5009C0.791637 15.5009 0.683998 15.4732 0.59372 15.4176C0.503443 15.362 0.430526 15.2857 0.37497 15.1884C0.319415 15.0912 0.288165 14.9905 0.28122 14.8864C0.274276 14.7822 0.305526 14.6745 0.37497 14.5634L8.4583 0.605103C8.52775 0.493991 8.60761 0.41413 8.69789 0.365519C8.78816 0.316908 8.88886 0.292603 8.99997 0.292603C9.11108 0.292603 9.21178 0.316908 9.30205 0.365519C9.39233 0.41413 9.47219 0.493991 9.54164 0.605103L17.625 14.5634C17.6944 14.6745 17.7257 14.7822 17.7187 14.8864C17.7118 14.9905 17.6805 15.0912 17.625 15.1884C17.5694 15.2857 17.4965 15.362 17.4062 15.4176C17.3159 15.4732 17.2083 15.5009 17.0833 15.5009H0.916637ZM1.99997 14.2509H16L8.99997 2.1676L1.99997 14.2509ZM9.0833 13.0634C9.26386 13.0634 9.41316 13.0044 9.53122 12.8864C9.64928 12.7683 9.7083 12.619 9.7083 12.4384C9.7083 12.2579 9.64928 12.1086 9.53122 11.9905C9.41316 11.8725 9.26386 11.8134 9.0833 11.8134C8.90275 11.8134 8.75344 11.8725 8.63539 11.9905C8.51733 12.1086 8.4583 12.2579 8.4583 12.4384C8.4583 12.619 8.51733 12.7683 8.63539 12.8864C8.75344 13.0044 8.90275 13.0634 9.0833 13.0634ZM9.0833 10.7509C9.26386 10.7509 9.41316 10.6919 9.53122 10.5739C9.64928 10.4558 9.7083 10.3065 9.7083 10.1259V6.70927C9.7083 6.52871 9.64928 6.37941 9.53122 6.26135C9.41316 6.1433 9.26386 6.08427 9.0833 6.08427C8.90275 6.08427 8.75344 6.1433 8.63539 6.26135C8.51733 6.37941 8.4583 6.52871 8.4583 6.70927V10.1259C8.4583 10.3065 8.51733 10.4558 8.63539 10.5739C8.75344 10.6919 8.90275 10.7509 9.0833 10.7509Z" fill="#F1C21B"></path></svg></div><div ><p class="slate-p slate-indent-0" style="0px">In case of a request for approval of your app by Make, make sure that the base URL is a production endpoint with a domain that belongs to the app itself. </p><p class="slate-p slate-indent-0" style="0px">Apps with development or staging URLs, or apps with a domain belonging to a cloud computing service, will not be approved!</p></div></div><p class="slate-p slate-indent-0" style="0px">When the service has a different domain for each user, the domain should be asked for in the connection and then the value should be used in the Base tab.</p><p class="slate-p slate-indent-0" style="0px"><strong class="slate-bold">Correct</strong></p><p class="slate-p slate-indent-0" style="0px">An example from Mailerlite app:</p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{
    "baseUrl": "https://api.mailerlite.com/api/v2"
}</div></code></pre></div><p class="slate-p slate-indent-0" style="0px"><strong class="slate-bold">Correct (Different Domain)</strong></p><p class="slate-p slate-indent-0" style="0px">An example from Freshsales app:</p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{
    "baseUrl": "https://{{connection.domain}}.freshsales.io"
}</div></code></pre></div><p class="slate-p slate-indent-0" style="0px"><strong class="slate-bold">Incorrect (Different Domain)</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{
    "baseUrl": "https://mydomain.freshsales.io"
}</div></code></pre></div><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >The "mydomain" should be a variable used from the Connection.</p></div></div><p class="slate-p slate-indent-0" style="0px"><strong class="slate-bold">Incorrect (app will not be approved)</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{
    "baseUrl": "https://mailerlite.heroku.com/development"
}</div></code></pre></div><h2 class="slate-h2 " >Authorization and sanitization</h2><p class="slate-p " >The Base section should also have <a href="https://developers.make.com/custom-apps-documentation/app-structure/base/authorization" target="_self">authorization</a>, which is common for all modules. This authorization should use the API Key, Access Token, or Username and Password entered in the connection. The <a href="https://developers.make.com/custom-apps-documentation/app-structure/base/sanitization" target="_self">sanitization</a> should hide all these sensitive parameters.</p><p class="slate-p " >Examples of possible authorization and sanitization:</p><p class="slate-p slate-indent-0" style="0px"><strong class="slate-bold">API key</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{
...
    "headers": {
      "Authorization": "Token {{connection.apiKey}}"
    },
    "log": {
        "sanitize": [
            "request.headers.authorization"
         ]
      }
...
}</div></code></pre></div><p class="slate-p slate-indent-0" style="0px"><strong class="slate-bold">Access Token</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">...</div><div class="slate-code_line">    "qs": {</div><div class="slate-code_line">        "access_token": "{{connection.accessToken}}"</div><div class="slate-code_line">    },</div><div class="slate-code_line">    "log": {</div><div class="slate-code_line">        "sanitize": [</div><div class="slate-code_line">            "request.qs.access_token"</div><div class="slate-code_line">        ]</div><div class="slate-code_line">    }</div><div class="slate-code_line">...</div><div class="slate-code_line">}</div></code></pre></div><p class="slate-p slate-indent-0" style="0px"><strong class="slate-bold">Basic auth</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">...</div><div class="slate-code_line">    "headers": {</div><div class="slate-code_line">        "authorization": "Basic {{base64(connection.username + ':' + connection.password)}}"</div><div class="slate-code_line">    },</div><div class="slate-code_line">    "log": {</div><div class="slate-code_line">        "sanitize": [</div><div class="slate-code_line">            "request.headers.authorization"</div><div class="slate-code_line">        ]</div><div class="slate-code_line">    }</div><div class="slate-code_line">...    </div><div class="slate-code_line">}</div></code></pre></div><p class="slate-p slate-indent-0" style="0px"><strong class="slate-bold">Secret in request body</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">...</div><div class="slate-code_line">    "body": "There is something {{parameters.secret}} hidden here.",</div><div class="slate-code_line">    "type": "raw",</div><div class="slate-code_line">    "log": {</div><div class="slate-code_line">        "sanitize": [</div><div class="slate-code_line">            "request.body<parameters.secret>"</div><div class="slate-code_line">        ]</div><div class="slate-code_line">    }</div><div class="slate-code_line">...</div><div class="slate-code_line">}</div></code></pre></div><h2 class="slate-h2 " >Error handling</h2><p class="slate-p slate-indent-0" style="0px">Each service sends an error message when an error occurs. This most of the time happens when the request has wrong parameters or values or when the service has an outage. That's why <a href="https://developers.make.com/custom-apps-documentation/app-structure/base/error-handling" target="_self">error handling</a> is required.</p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=warning ><div ><svg width="18" height="16" viewBox="0 0 18 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.916637 15.5009C0.791637 15.5009 0.683998 15.4732 0.59372 15.4176C0.503443 15.362 0.430526 15.2857 0.37497 15.1884C0.319415 15.0912 0.288165 14.9905 0.28122 14.8864C0.274276 14.7822 0.305526 14.6745 0.37497 14.5634L8.4583 0.605103C8.52775 0.493991 8.60761 0.41413 8.69789 0.365519C8.78816 0.316908 8.88886 0.292603 8.99997 0.292603C9.11108 0.292603 9.21178 0.316908 9.30205 0.365519C9.39233 0.41413 9.47219 0.493991 9.54164 0.605103L17.625 14.5634C17.6944 14.6745 17.7257 14.7822 17.7187 14.8864C17.7118 14.9905 17.6805 15.0912 17.625 15.1884C17.5694 15.2857 17.4965 15.362 17.4062 15.4176C17.3159 15.4732 17.2083 15.5009 17.0833 15.5009H0.916637ZM1.99997 14.2509H16L8.99997 2.1676L1.99997 14.2509ZM9.0833 13.0634C9.26386 13.0634 9.41316 13.0044 9.53122 12.8864C9.64928 12.7683 9.7083 12.619 9.7083 12.4384C9.7083 12.2579 9.64928 12.1086 9.53122 11.9905C9.41316 11.8725 9.26386 11.8134 9.0833 11.8134C8.90275 11.8134 8.75344 11.8725 8.63539 11.9905C8.51733 12.1086 8.4583 12.2579 8.4583 12.4384C8.4583 12.619 8.51733 12.7683 8.63539 12.8864C8.75344 13.0044 8.90275 13.0634 9.0833 13.0634ZM9.0833 10.7509C9.26386 10.7509 9.41316 10.6919 9.53122 10.5739C9.64928 10.4558 9.7083 10.3065 9.7083 10.1259V6.70927C9.7083 6.52871 9.64928 6.37941 9.53122 6.26135C9.41316 6.1433 9.26386 6.08427 9.0833 6.08427C8.90275 6.08427 8.75344 6.1433 8.63539 6.26135C8.51733 6.37941 8.4583 6.52871 8.4583 6.70927V10.1259C8.4583 10.3065 8.51733 10.4558 8.63539 10.5739C8.75344 10.6919 8.90275 10.7509 9.0833 10.7509Z" fill="#F1C21B"></path></svg></div><div ><p class="slate-p " >In case of a request for approval of your app by Make, make sure error handling is correctly implemented!</p></div></div><p class="slate-p slate-indent-0" style="0px">The error handling code should correspond to the structure of the server response.
Let's assume that the JSON response has the following format in the cases where something goes wrong:</p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">{
    "error": {
        "code": "E101",
        "message": "The company with the given ID does not exist."
    }
}</div></code></pre></div><p class="slate-p slate-indent-0" style="0px">Here's how the error section should (and should not) look:</p><p class="slate-p " ><span style="background-color:transparent;color:color-mix(in srgb,var(--dark-DEFAULT),transparent calc(100% - 100% * .64))"><strong class="slate-bold">Correct</strong></span></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">"response": {</div><div class="slate-code_line">    "error": {</div><div class="slate-code_line">        "message": "[{{statusCode}}] {{body.error.message}} (error code: {{body.error.code}})"</div><div class="slate-code_line">    }</div><div class="slate-code_line">}</div></code></pre></div><p class="slate-p slate-indent-0" style="0px">The error object in our example contains the <code class="slate-code">code</code> and <code class="slate-code">message</code> fields, but not a <code class="slate-code">text</code> field. It is also important to show the status code of the error, this can be accessed using the <code class="slate-code">statusCode</code> keyword. So in the case of HTTP error 400, the error message could look like this:</p><p class="slate-p slate-indent-0" style="0px"><code class="slate-code">[400] The company with the given ID does not exist. (error code: E101)</code></p><p class="slate-p " ><strong class="slate-bold">Incorrect</strong></p><div class="code-block-wrapper"  style="width:60%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block" data-content=''><code class="language-json keep-markup drop-tokens"><div class="slate-code_line">"response": {</div><div class="slate-code_line">    "error": {</div><div class="slate-code_line">        "message": "{{body.error.text}}"</div><div class="slate-code_line">    }</div><div class="slate-code_line">}</div></code></pre></div><p class="slate-p slate-indent-0" style="0px">The error object in our example contains the <code class="slate-code">code</code> and <code class="slate-code">message</code> fields, but not a <code class="slate-code">text</code> field.<a href="" target="_blank"><span style="background-color:color(srgb 1 1 1);color:color(srgb 0.120353 0.120353 0.120353)">
</span></a></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

The Base section should contain data that is common to all (or most) requests. At the very least, this should include the root URL, the authorization headers, the error-handling section, and the sanitization.

 uses the URL of the API, which is shared among all modules or their majority.

When the service has a different domain for each user, the domain should be asked for in the connection and then the value should be used in the Base tab.

, which is common for all modules. This authorization should use the API Key, Access Token, or Username and Password entered in the connection. The 

 should hide all these sensitive parameters.

Examples of possible authorization and sanitization: