Create a Custom App

Introduction

By creating a custom app you can connect Public APIs and your own APIs to our platform. These can be used within the flow designer to automate your communication process.

In this example, we are going to extend the webhook showcase. We are going to create a custom app that will make a call to our webhook in order to trigger our custom statuses, instead of making CURL requests.

These are the steps that are going to be covered:

  1. Create custom app
  2. Build the flow
  3. Test the process

Create custom app

First, we need to create a custom app. To do so, we go to the apps overview and we click on the “New App” button:

Straightaway, in the next screen, we click on the option “Create your own App”:

This will initiate the wizard process to configure our custom app, which is divided into the following steps:

  1. Information
  2. Authentication
  3. Outgoing request
  4. Parameters
  5. Test
  6. Incoming data
  7. Overview

Information

In this step, we provide general information about our custom app.

We must specify a meaningful name and a unique identifier which could be used, later on, to reference the response data of this app. Moreover, we can customize some properties such as the background color, text color, and icon.

If you want to use PDF or HTML content, which will be created within our platform, you have to enable the switchers that are shown below.

Authentication

This step allows you to set up the authentication method of the API.

There are different levels of authentication and security within an API. Depending on the API you want to connect to you choose of the following options:

  • No Auth: if you don’t need to certificate who is asking for the resource.
  • Basic Auth: with username and password.
  • OAuth 1.0: this is a deprecated authentication method but some APIs are still using it. We need to specify the Consumer Key (API Key), Consumer Secret (API Secret), Access Token and Access Token Secret.
  • OAuth 2.0: The last and secure version of this kind of authorization used from the most common APIs. We need to specify the Auth URL to send the request, Access Token URL, Client ID, Client Secret, the Scope in case we need it, choose the Grant Type and type the Access Token and the Access Token Structure.

In our case, we don’t need authentication as we are going to make a call to our own webhook URL.

Outgoing request

Next, we configure the request that is going to be performed.

  • Format: the format of the payload that is going to be sent.
  • Import from cURL: enable this if you would like to import your configuration from a CURL request.
  • URL: the URL where the request will be made to.

  • Method: select the method you are going to use to communicate with the URL.
  • Headers: if the API requires Headers, you can click on the “Add new Header” button. You can add more headers if required.
  • Payload: it’s the information that you will send within the request.

We can let the system get the parameters for us by clicking on the “Yes, get the parameters” button:

Parameters

As we mentioned in the previous step, our parameters will be automatically generated as we let the system get them for us. Anyway, it is possible to add more anytime, if needed.

The parameters make it possible to set variables while building a flow, so you only have to set it once in the code of the API. While adding a new parameter, you can label it and define its type.

The name of the parameter must be unique because within the API-request you can use this as a variable.

For instance, if you name the parameter postalcode, within the request you use the variable @object.params.postalcode@.

If we click on the “Edit” button, all the options  that we can set for a parameter will appear below:

  • Label of the param: this is the sticker before the input box that we are going to show in order to enter the value.
  • Name of the param: it has to be unique to identify this param with each other.
  • Type of param: we should choose the kind of input we will let the user fill in.
  • Required: you can choose if the field will be mandatory or not.
  • Help text: it’s a text that will be shown under the element.
  • Long Help text: it’s a text shown to the user in a new window.
  • Values: they will appear only in the case that you choose a parameter type with multiples values like Radio button, Checkboxes or List.
  • Default value: We can set a value by default in case we don’t have another one.

In our case, we are going to leave all the parameters by default.

Test

In this step, we can make sure that our API request works as expected:

We can leave the default values that are shown and we click on the “Send” button:

As you can see in the screenshot above, we can see information about the request that was sent and the response that our app received.

We can easily complete the following step by clicking on the “Save Response Variables”, which will retrieve for us all needed variables from the response.

Incoming data

Here we can set up the incoming data that this app receives. We simply select the format of the response that our app will receive and the variables that this payload will contain:

As we mentioned in the previous step, this data will be automatically generated if we let the system get it for us.

Also, it is also possible to specify the path in our data schema where these response variables will be saved.

Overview

Finally, we can see an overview of our app configuration:

Build the flow

This flow is simply going to trigger our two statuses. We are going to name it Trigger statuses. This is the configuration of both flow objects:

  1. Trigger new order: this will trigger the customer_order status.
  2. Trigger order delivered: this will trigger the order_delivered status.

Test the process

In order to test the process, we are going to send a new customer to the Webshop flow that we set up in the previous showcase. To do so, we run the following CURL request:

curl -X POST \
  https://{{platform_api_url}}/v1/batch \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-Apikey: {{put_here_your_api_key}}' \
  -H 'X-App: Webshop' \
  -H 'X-Batch-Status: ready' \
  -H 'X-Flow: Webshop' \
  -H 'X-Scopes: batch' \
  -d '[
	{
          "id": "136342354325",
          "name": "Peter Slam",
	  "email": "peter.slam@email.com"
	}
]'

Finally, we are going to trigger both statuses by inserting a new record into our new Trigger Statuses flow:

curl -X POST \
  https://{{platform_api_url}}/v1/record \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-Apikey: {{put_here_your_api_key}}' \
  -H 'X-App: Webshop' \
  -H 'X-Flow: Trigger Statuses' \
  -H 'X-Scopes: record, batch' \
  -d '{
          "id": "136342354325"
      }
'

In both cases, you must replace {{platform_api_url}} by the API URL and {{put_here_your_api_key}} by your API key.

Congratulations! You have successfully created your custom app.