The API Widget

An API (Application Programming Interface) is a set of rules and protocols that enable different software applications to communicate and exchange data with each other. In other words, an API acts as an intermediary between two applications or services. It defines how these systems can interact and share information securely.

1. What is the API brick?

The Api brick enables administrators to create API calls during a call-out. This allows you to send and receive information, so that it can be displayed in your end-of-project reports.

2. Setting the API connection

2.1. Authorize user role

1. Go to your user's role section. In the "Integration" section, activate the option: Show integration menu.

Once this option is ticked, a new section called "Integration" will appear in ermeo's main menu.

2.2. Create a new connection

1. Click on the button: New connection
2. Fill in the general information relating to the API to which you wish to connect (Name, Base URL).
3. Select your authentication.

You will have 4 possible choices:

• Without authentication (None): you can validate your connection directly.

• Basic authentication: You will need to enter a user name and password in the second stage.

• Header auth: You fill in one or more headers with their associated key and value.

• Query Parameters: As with header auth, you will need to fill in your url parameters, with their associated key and value.

• Oauth2 : To finalise your authentication, you will need to fill in the following information: the Oauth 2 authentication url, the Oauth2 token url, your client id and secret, and your scope, as shown in the video below

For your information, the redirection url to be used by your api can be found at the bottom of the modal, in ‘Connection information’:

💡

Notes

• The base url must end with a "/" at the end, if this is not the case, it will be added automatically.
• If you have query params in the url, these will need to be entered in your path when you configure the query in the studio.
• With an Oauth2 connection, your refresh token may expire after a period of inactivity for your connection, which varies depending on your API (check your documentation for details). If this happens, you will need to reconnect to continue using it:

2.2. Modify the connection

You can modify your connection if you wish by clicking on "Modify" on the chosen connection.

If you are modifying a Basic authentication connection, you only need to enter the password if you wish to change it.

2.3. Delete the connection

You can delete an API connection you have created.

If this connection is used in the configuration of your API bricks, you will see the number of bricks using this connection.

3. Set the API widget in the form

3.1. Set the API request

1. Go to your form editing studio.
2. Drag and drop the API brick from the "Workflows" section.
3. In the brick settings, start configuring your request

4. Select a connection configured on your "Integrations" page.

5. Enter the chosen method: POST, GET, PUT, DELETE
6. You can then complete the path of your url, and add any tags present in your form. If you have query params, you will need to enter them in your path.
7. Choose the format of the query between JSON and XML

8. You can include headers in your request, as well as a body. The value of a header and the body can contain tags.

9. In step 4, choose the expected response format between JSON and XML
10. Finally, you can test your query and save its creation:

• If you have added tags to your query, and you wish to test it, you will need to enter a value for each tag by clicking on the "Enter tags" button.
• You can also validate the creation of your query without testing it. However, we recommend that you test it to avoid any configuration errors.

11. Finalise the settings for your API brick options:

You will be able to automate the click on your API brick, so that the person responding to the form doesn't have to click on the button that launches your API call, and you will also be able to hide this new brick from the user.

However, to be able to ‘Automate the click’, you will need to have poster conditions on your API brick.

3.2. Configure your API tag to display the response to your request in another brick

3.2.1. The format of your API path

The format to fill in a default value for another brick in order to display the result of your request is as follows: ##api_tag:apipath()##

• api_tag = The id of your API brick
• Between the () : You enter the response required by the api

3.2.2. Set up your tag according to the desired response

• In a default value, title or description, you can select the tag for your API brick.
• Once selected, click on the little pencil to the right of the tag:

• A configuration dialog box opens, prompting you to enter your path:

• You can then preview what you have set up in the studio and publish it:

3.3. Conditions d’affichage sur la brique API

As part of this functionality, you can display other tasks if the API brick request was successful and/or if it failed.

Example: I only display my text brick 3 if the call has been made and my request is valid. This means that if my request is invalid, my text task will not be displayed.

If you simply want the call to be made, regardless of whether the request is valid or invalid, you can select ‘Task completed’:

3.4. Displaying a call that has failed on the application

It can happen that your API call fails for various reasons, such as a configuration error, a tag value incorrectly entered by a user, a lack of Internet connection at the time of the call, or a permission problem on the API used...

In this case, even if it is hidden, the API brick will be displayed in the application and will indicate that there has been an error, enabling the call to be restarted.

Two types of message may be displayed:

• If the user does not have internet access, the call cannot be made. By clicking on the ‘Load data’ button when there is a network connection, the API call can be made again (see screenshot 1).
• In the event of any other type of error, a second message will be displayed (see screenshot 2). This message invites the user to check the information entered, particularly if the error is linked to the tags, and to try again. If the error persists, users are advised to contact their administrator, as it may be a configuration error.

4. Cas studies

4.1. Gathering external information during the operation

This example describes a scenario where you are going to retrieve the name of a commune based on the postcode that will be entered during the intervention.

The objective of the api brick in this case is to retrieve the name of the municipality from this external source.

1. First, create your connection from the "Integrations" section.

For this test, you can use the connection: https://geo.api.gouv.fr/ and choose "Without authentication" as the authentication type.

2. Once your form has been created, drag and drop :

• A number brick (which will be used to define the postcode)
• The API brick with the HTTP logo (the api brick that will retrieve the name of the commune)
• A text brick (which will display the name of the commune)

3. To configure the request for your api brick, click on "Configure the request".
4. Select the connection you created earlier.
5. Choose "GET" as the HTTP method
6. Copy the following URL: communes?codePostal=tag from the number brick.

For example: communescodePostal=##number_jXKVLmOK##

In this example, we don't need to fill in the query body. You can go straight to the query test stage.

7. To check that the query is working correctly, enter a postcode using the "Enter tags" button and then click "test".
8. If your test is valid, click on "Validate".
9. You can now preview the results of your settings. The video below describes the steps involved in this case study.

4.2. Schedule a job automatically on Ermeo while another job is being carried out

📌

Prerequisites In advance, we recommend that you consult our documentation to better understand how to communicate with the Causeway Ermeo API:

Create an intervention | API Documentation

Create an intervention according to the body sent with this request. Powered by Stoplight.

ermeo.stoplight.io

4.2.1. Create your connection in your integration page

1. The url you will use is: https://api.ermeo.com/
2. Select the "None" authentication type.

💡

Notes

• For the moment, oauth2 authentication is not available, which is why we are selecting without authentication. Eventually, you will select "Oauth2" (Available in September)

4.2.2. Studio configuration

1. Configure your form and place the API brick where you want the intervention to be created, as in the video below:

1.1. Drag and drop your API brick into the studio and click on ‘Configure the request’.

1.2. Select the connection created.

1.3. Set up your request (video below):

2. Hide your brick if you do not want it to be visible once the form has been published.
3. On the application, the creation of the task is transparent to the field operator.

4. In your task tab, the new task created by the operator.