Skip to main content

Celonis Product Documentation

HTTP (Action Flow)

The HTTP app provides modules for communication based on the Hypertext Transfer Protocol (HTTP). HTTP is the fundamental component of data transfer for the World Wide Web. As the backbone of information exchange between web servers and clients, HTTP allows you to download web pages, access files, make API calls, and trigger webhooks.

Make a request

The Make a request module allows you to create an HTTP request and send it to a server. The output bundle contains the HTTP response.

Evaluate all states as errors (except for 2xx and 3xx)

Use the response status to detect errors. Otherwise, the module reports only Celonis platform related errors (like mapping errors or missing required values).

URL

Enter the request URL.

Serialize URL

Encodes the API call URL with the URL encoding (encoding special characters for example).

Method

Select the HTTP method you want to use:

  • GET: to retrieve information for an entry.

  • POST: to create a new entry.

  • PUT: to update/replace an existing entry.

  • PATCH: to make a partial entry update.

  • DELETE: to delete an entry.

Headers

Enter request headers. For example, the response content type.

Caution

The HTTP app requests do not have the Accept header. If the HTTP request returns an unexpected response, try adding the Accept: */* header.

HTTP_1.png

Query String

Enter the query key-value pairs.

Body type

HTTP body contains the data transferred in an HTTP request.

Raw

The Rawbody type is suitable for most HTTP requests, even if the app documentation does not specify the data type.

Specify the data format of the body content in the Content type field.

HTTP_2.png

Application/x-www-form-urlencoded

This body type is to POST data using application/x-www-form-urlencoded.

HTTP_3.png

For application/x-www-form-urlencoded, the body of the HTTP request sent to the server is one query string. The keys and values are encoded in key-value pairs separated by & and with a = between the key and the value. For binary data, use the multipart/form-data body type instead.

Example of the resulting HTTP request format: field1=value1&field2=value2

Multipart/form-data

Use the multipart/form-data content type to send files in the HTTP request.

Add fields to the request. Each field must contain a key-value pair:

Text: Enter the key and value to send in the request body.

File: Enter the key, and specify the source file you want to send in the request body. Map the file you want to upload from the previous module (for example: HTTP > Get a File or Google Drive > Download a File), or enter the file name and file data manually.

Parse response

Enable to parse HTTP responses into bundles. With this option, you don't need to add the Parse JSON or Parse XML modules. Otherwise, the HTTP module returns the raw response data.

Before you can use parsed JSON or XML content, run the module once manually so that the module can recognize the response content and allow you to map it in subsequent modules.

HTTP_4.png

User name

Enter the user name to send the request with the basic auth.

Password

Enter the password to send the request with the basic auth.

Timeout

Specify the request timeout in seconds (1-300). Default: 40 seconds.

Share cookies with other HTTP modules

Enable to share cookies from the server with all HTTP modules in your Action Flow.

Self-signed certificate

Upload your certificate if you want to use TLS using your self-signed certificate.

Reject connections that use unverified (self-signed) certificates

Enable to reject connections that use unverified TLS certificates.

Follow redirect

Enable to follow URL redirects that return 3xx response statuses.

Follow all redirect

Enable to follow URL redirects regardless of response statuses.

Disable serialization of multiple same query string keys as arrays

Celonis platform handles multiple values for the same URL query string parameter key as arrays (e.g., www.test.com?foo=bar&foo=baz will be converted to www.test.com?foo[0]=bar&foo[1]=baz). Enable to deactivate this behavior.

Request compressed content

Enable to request compression of the response data. Adds the Accept-Encoding header.

Use Mutual TLS

Select if you want to use mutual TLS (mTLS) for the HTTP request to ensure both the client and server authenticate each other using certificates.

Example HTTP request with the Make a request module

Check the following screenshot to see how to set up the Make a request module to send a POST request with the body in the JSON data format:

HTTP_5.png

To make sure your JSON is valid, use a JSON validator (for example: https://jsonlint.com/) or use a Create JSON module to create the JSON.

HTTP_6.png

Caution

Be careful when combining JSON data with mapping variables or function directly in the Request content field. Mixing JSON with mapping can lead to an invalid JSON structure.

Make a Basic Auth request

The Make a Basic Auth request module allows you to send an HTTP request with the basic authentication. The output bundle contains the HTTP response.

Credentials

Click Add to add your credentials (user name and password) for basic authentication.

Evaluate all states as errors (except for 2xx and 3xx)

Use the response status to detect errors. Otherwise, the module reports only Make related errors (like mapping errors or missing required values).

URL

Enter the request URL.

Serialize URL

Encodes the API call URL with the URL encoding (encoding special characters for example).

Method

Select the HTTP method you want to use:

  • GET - to retrieve information for an entry.

  • POST - to create a new entry.

  • PUT - to update/replace an existing entry.

  • PATCH - to make a partial entry update.

  • DELETE - to delete an entry.

Headers

Enter request headers. For example, the response content type.

Caution

The HTTP app requests do not have the Accept header. If the HTTP request returns an unexpected response, try adding the Accept: */* header.

HTTP_1.png

Query String

Enter the query key-value pairs.

Body type

HTTP body contains the data transferred in an HTTP request.

Raw

The Rawbody type is suitable for most HTTP requests, even if the service documentation does not specify the data type.

Specify the data format of the body content in the Content type field.

HTTP_2.png

Application/x-www-form-urlencoded

This body type is to POST data using application/x-www-form-urlencoded.

HTTP_3.png

For application/x-www-form-urlencoded, the body of the HTTP request sent to the server is one query string. The keys and values are encoded in key-value pairs separated by & and with a = between the key and the value. For binary data, use the multipart/form-data body type instead.

Example of the resulting HTTP request format: field1=value1&field2=value2

Multipart/form-data

Use the multipart/form-data content type to send files in the HTTP request.

Add fields to the request. Each field must contain Key-Value pair:

Text: Enter the key and value to be sent within the request body.

File: Enter the key, and specify the source file you want to send in the request body. Map the file you want to upload from the previous module (for example: HTTP > Get a File or Google Drive > Download a File), or enter the file name and file data manually.

Parse response

Enable to parse HTTP responses into bundles. With this option, you don't need to add the Parse JSON or Parse XML modules. Otherwise, the HTTP module returns the raw response data.

Before you can use parsed JSON or XML content, run the module once manually so that the module can recognize the response content and allow you to map it in subsequent modules.

HTTP_4.png

Timeout

Specify the request timeout in seconds (1-300). Default: 40 seconds.

Share cookies with other HTTP modules

Enable to share cookies from the server with all HTTP modules in your Action Flow.

Self-signed certificate

Upload your certificate if you want to use TLS using your self-signed certificate.

Reject connections that use unverified (self-signed) certificates

Enable to reject connections that use unverified TLS certificates.

Follow redirect

Enable to follow URL redirects that return 3xx response statuses.

Follow all redirect

Enable to follow URL redirects regardless of response statuses.

Disable serialization of multiple same query string keys as arrays

Celonis platform handles multiple values for the same URL query string parameter key as arrays (e.g., www.test.com?foo=bar&foo=baz will be converted to www.test.com?foo[0]=bar&foo[1]=baz). Enable to deactivate this behavior.

Request compressed content

Enable to request compression of the response data. Adds the Accept-Encoding header.

Use Mutual TLS

Select if you want to use mutual TLS (mTLS) for the HTTP request to ensure both the client and server authenticate each other using certificates.

Make an API key Auth request

The Make an API key Auth request module allows you to send API calls to apps that require API key authorization. The module also supports "Bearer" authorization.

The output bundle contains the HTTP response.

Create an API key connection for the Make an API key Auth request module

Check out the following example if you want to set up a connection for the Make an API key Auth request module:

  1. In the Make an API key Auth request module settings, click the Add button. The Add a new keychain window pops up.

  2. Fill in:

    1. Name: The label for your API key connection.

    2. Key: The API key to authorize the HTTP calls. If the API uses "Bearer" or "Token" authorization, add the word before the API key.

      Example: Bearer 1234-5678-abcd-efgh

      Note

      You can use the eye icon at the edge of the box to reveal the API key and the text you add to it. If you do, make sure that you are the only one viewing the content.

    3. API key placement: Select if you want the authorization in the request header or query string.

    4. API key parameter name: The name of the parameter that contains the API key.

  3. Click Create to create the connection.

You created an API key connection. You can now use the connection in the Make an API key Auth request module.

Make an OAuth 2.0 request

In order to make HTTP(S) requests that require an OAuth 2.0 authorization, you need to create an OAuth connection first.

Create an OAuth 2.0 Connection

To configure the app inCelonis platform, you need to create OAuth 2.0 credentials in the app developer portal or settings and enter them in the HTTP module in Action Flows.

Note

Celonis platform supports two flows:

  • Authorization code: enter an Authorize URL and Token URL from the app API documentation.

  • Implicit: enter the Authorize URL from the app API documentation.

Prerequisites

  • An app account

  • Access to a developer portal or settings

  • A Redirect URL (sometimes called a Callback URL).

Obtaining credentials in the app

  1. Create an OAuth client in the app that you want to connect with Celonis platform. To do this, enter the developer portal or settings.

    1. Specify a Redirect URL: https://www.integromat.com/oauth/cb/oauth2

    2. Obtain the Client ID and Client Secret. Sometimes the app calls them App Key and App Secret.

    3. Save the Client ID and Client Secret in a safe place. You will need them when building a Action Flow in Celonis platform.

  2. Find the Authorize URL and Token URL in the app API documentation. These are the addresses through which Celonis platform communicates with the app.

Establishing the connection in Celonis platform

Once you have your credentials from the app, you can enter them in the app's configuration in Celonis platform

  1. Go to a Celonis platform Action Flow.

  2. Add the HTTP - Make an OAuth 2.0 request module.

  3. Click Create a connection.

  4. Optional: In the Connection name field, enter a name for the connection.

  5. In Flow type, select the flow.

  6. In Scopes, add API scopes. Refer to the app API documentation to get scopes.

  7. In Client ID and Client Secret enter the credentials you saved previously.

  8. Click Save to create an OAuth 2.0 connection.

You have created an OAuth 2.0 connection. Now you can use the connection in the Make an OAuth 2.0 request module.

Check the advanced settings for creating a connection:

Scope separator

Select the separator for the list of scopes you entered above. Check the app API documentation for the format of the list of scopes.

If the separator is not set correctly, Celonis platform will be unable to create the connection, and you will receive an invalid scope error.

Authorize parameters

Enter additional authorization request parameters as a key-value pair:

  • response_type: code for the Authorization code flow and token for the Implicit flow.

  • client_id: The Client ID you entered when creating an account.

Access token parameters

Enter additional access token request parameters as key-value pairs.

Standard parameters:

  • grant_type: authorization_code

  • redirect_uri: https://www.integromat.com/oauth/cb/oauth2

  • client_id: The Client ID you entered when creating an account.

  • client_secret: The Client Secret you entered when creating the account.

  • code: The code returned by the authorization request.

Refresh token parameters

Enter the additional refresh token request parameters as key-value pairs.

Standard parameters:

  • grant_type: refresh_token

  • refresh_token: The Refresh token obtained together with the Access token.

  • client_id: The Client ID you entered when creating the account.

  • client_secret: The Client Secret you entered when creating the account.

Custom Headers

Specify any custom headers to send in the request.

Token placement

Select whether to send the token in the header, query string, or both.

Header token name

Enter the name of the authorization token in the header. Default: Bearer.

Query string parameter name

Enter the name of the authorization token in the query string. Default: access_token.

Module settings
Make a client certificate authentication request

Sends an HTTP(S) request to apps that require a client certificate authorization.

Get a file

Downloads a file from a URL.

URL

Enter the URL of the file you want to download. You can use the file (map the file data) in other modules in the Action Flow.

Resolve a target URL

Enter the URL you want to resolve. The output bundle contains the link to which the original URL redirects in the location response header.

This module helps you to get a direct URL to a resource instead of a redirect URL. For example, links for sharing files in storage apps like Dropbox redirect you before you reach the target file. The module navigates through the redirect chain and returns the target URL.

URL

Enter the URL you want to resolve.

Method

Select the method you want to use.

Retrieve Headers

Returns each header (name and value) from the specified HTTP module in a separate bundle.

Source Module

Select the module you want to retrieve headers from.

How to generate JSON Web Tokens (JWT)

If you need to connect to an API or send messages that requires JWT authentication, you can create a JWT via the HTTP module using the HS256 or HS512 algorithms. Celonis platform allows creating a JWT with the help of custom or built-in functions.

Generating a JWT via a custom function

You can create a HS256 or HS512 JWT with the help of Celonis platform custom functions.

Note

Custom functions are available to the Enterprise plan users only.

Follow the steps to create a JWT:

  1. Go to Functions and create a custom function using the following body:

    function readableJWTencode(payload, secret, header = '{"alg":"HS256","typ":"JWT"}') {
    let formattedHeader = iml.replace(iml.replace(iml.replace(iml.base64(header), "=", ""), "+", "-"), "/", "_")
    let formattedPayload = iml.replace(iml.replace(iml.replace(iml.base64(payload), "=", ""), "+", "-"), "/", "_")
    let signature = iml.sha256(formattedHeader + "." + formattedPayload, "base64", secret)
    let formattedSignature = iml.replace(iml.replace(iml.replace(signature, "=", ""), "+", "-"), "/", "_")
    let jwt = formattedHeader + "." + formattedPayload + "." + formattedSignature
    return jwt
}

    Note

    Replace HS256 with HS512 and sha256 with sha512 in the custom function above to create a HS512 JWT.

    The example custom function has the jwtEncode name embedded onto the function body. If you want to use another name, change it in the body too.

  2. Start your Action Flow with the Set multiple variables module and add three items:

    1. Item 1:

      1. In Variable name, enter header.

      2. In Variable value, enter the following function:

        {"alg":"HS256","typ":"JWT"}

        Note

        Replace HS256 with HS512 to create a HS512 JWT.

    2. Item 2:

      1. In Variable name, enter payload.

      2. In Variable value, enter the following function:

        {"var1":1,"var2":"text"}

    3. Item 3:

      1. In Variable name, enter secret.

      2. In Variable value, enter your 256-bit or 512-bit secret.

  3. Add another Set multiple variables module to generate the JWT.

  4. Optional: In Variable name, enter the name for the token.

  5. In Variable value, enter the following function:

    {{jwtEncode(11.payload; 11.secret)}}

    Note

    Make sure to take into account the module number in the code. In the example above, the header, payload and secret are in the 11th module in the Action Flow. It may vary from one Action Flow to another.

If you run the Action Flow, you will receive the HS256 or HS512 JWT in the second module's output.

JWT.png

You can connect to an API or send messages that requires JWT authentication.

Generating a JWT via built-in functions

To generate a JWT with the help of built-in functions, do the following in your Action Flow:

  1. Start your Action Flow with the Set multiple variables module and add three items:

    1. Item 1:

      1. In Variable name, enter header.

      2. In Variable value, enter the following function:

        {{replace(replace(replace(base64("{""alg"":""HS256"",""typ"":""JWT""}"); "="; emptystring); "+"; "-"); "/"; "_")}}

        Note

        Replace HS256 with HS512 to create a HS512 JWT.

    2. Item 2:

      1. In Variable name, enter payload.

      2. In Variable value, enter the following function:

        {{replace(replace(replace(base64("{""var1"":1,""var2"":""text""}"); "="; emptystring); "+"; "-"); "/"; "_")}}

    3. Item 3:

      1. In Variable name, enter secret.

      2. In Variable value, enter your 256-bit or 512-bit secret.

  2. Add another Set multiple variables module to generate the HS256 or HS512 JWT.

  3. Optional: In Variable name, enter the name for the token.

  4. In Variable value, enter the following function:

    {{5.header}}.{{5.payload}}.{{replace(replace(replace(sha256(5.header + "." + 5.payload; "base64"; 5.secret); "="; emptystring); "+"; "-"); "/"; "_")}}

    Note

    Use the sha512 function to create a HS512 JWT.

    Make sure to take into account the module number in the code. In the example above, the header, payload and secret are in the 5th module in the Action Flow. It may vary from one Action Flow to another.

If you run the Action Flow, you will receive the HS256 or HS512 JWT in the second module's output.

JWT.png

You can connect to an API or send messages that requires JWT authentication.