Skip to main content

Web connections

Web connection for a branch​

You can set up a Web connection for a branch to communicate with any service or third party online. This connection can be used in the process flow action with the same name: Web connection. For more information and a use case, see Web connection.

warning

The current version of Web connections does not support binary data. If you use binary data or multipart/form-data and need more control over the request body, use the process flow action HTTP connector instead. For example, setting the file name using multipart/form-data is not supported.

Set up a Web connection​

To set up a web connection:

menu Integration & AI > Web connections

  1. Enter a Web connection name.
  2. Enter the Base URL, which is the portion of the URL that points to the application you want to connect to.
  3. Select the Authentication type.
  4. Depending on the authentication type, enter the required settings.
tip

With a 3-tier Software Factory in the Universal GUI, you can store key values encrypted. See Encryption for a branch.

tip

The tab Usage shows where the web connection is being used. This can be useful when, for example, you want to change the web connection and see what impact this might have. For more information on this generic feature, see Usage.

Add Web connection parameters​

You can define parameters for use across all endpoints, such as authentication. You can use curly brackets { } to add parameters to various settings.

Example: user name as a parameter

For example, you can create a web connection parameter user_name by entering the value {user_name}. The parameter becomes an input parameter for the Web connection process action. The value for user_name is passed onto the field User name, allowing this field to be filled automatically.

To add web connection parameters:

menu Integration & AI > Web connections > tab Web connection parameters

The following settings are available:

Set up a Web connection endpoint​

To set up an endpoint:

menu Integration & AI > Web connections > tab Endpoints

  1. To add the general settings for the endpoint, go to the tab General settings. The following settings are available:

    • Method - Specifies the action to be performed.
    • Path - The part of the URL that links to the specific endpoint.
    • Body type - The structure of the data being sent in the request.

  2. Optional. You can add a query string to your endpoint URL in the tab Query strings. Here you can define additional options for an endpoint, such as a filter. You can also use {parameters}.

    The following settings are available:

    • Name
    • Value

  3. Optional. You can add a request header to your endpoint URL in the tab Request headers. This allows you to send extra information to the endpoint. You can use {parameters} here. Typical applications include identifying the sender, specifying the request format, and defining the desired response format.

    The following settings are available:

    • Name
    • Value
    • Omit when empty

Settings that can be parameterized

Web connection settings (only web connection parameters allowed):

  • Base URL
  • Username
  • Password
  • Bearer token
  • API key name
  • API key value

Endpoint settings:

  • Path
  • Body type
  • Content type
  • Form fields
    • Name
    • Value
  • Query string parameters
    • Name
    • Value
  • Request headers
    • Name
    • Value

Add Web connection input parameters​

To add input parameters for a specific endpoint:

menu Integration & AI > Web connections > tab Endpoints > tab Input parameters

The following settings are available:

Add Web connection output parameters​

To add output parameters for a specific endpoint:

menu Integration & AI > Web connections > tab Endpoints > tab Output parameters

The following settings are available:

  • Retrieve value from - Retrieve a value from a given response header.
  • Base64 decode - Decode the value from Base64.
  • Apply JSON path - Based on a JSON path, obtain the value from the response.
  • Always as array - Always return the value as an array.
  • Apply XPath - Based on an XPath, obtain the value from the response.
  • Apply Regex - Based on a regular expression, extract a value that satisfies the expression.
Override Web connections settings
  • To override these settings for a specific runtime configuration (for development and testing): menu Maintenance > Runtime configurations > tab Web connections. See Runtime configurations for more information.
  • To override these settings for an application in IAM: menu Authorization > Applications > tab Web connections. See Web connections settings in IAM.

Pre-processing web connection (input) parameters​

The field Pre-processing allows you to specify how the web connection (input) parameter value should be processed, as described in the table below.

warning

When you convert from the HTTP connector to the Web connection, the body is already in the right format. In this case, set Pre-processing for the json_body also to None.

Pre-processingDescription
AutoAutomatically set the value based on where the parameter is used. This means that if the endpoint body type is JSON, it will be treated as a JSON string value. If the same parameter is used in the URL path, it will be treated as a Query string value.
Query string valueConvert the value to a query string. Special characters will be encoded. For example, the character & will become %26 because it has a special meaning.
JSON string valueConvert the value to a JSON string. The character " will be escaped to \" to ensure it can be used as a JSON value.
XML string valueConvert the value to an XML string. Special characters will be encoded. For example, the character < will become &lt; so it can be used as an XML text value.
Base64 encodeEncode the value in Base64. The value Thinkwise will become VGhpbmt3aXNl.
NoneDo not pre-process the value.

Use cases​

The following topics describe some typical use cases for Web connections, including setting up the input parameters and using the Pre-processing setting.

Use case: Web connection parameters with JSON variables​

This use case describes a Web connection endpoint with the body type set to JSON. The body structure is known beforehand and static; it only contains some specific parameters in places that can be modeled. The body is configured with a JSON object that contains a customer_id, customer_name, description, and search_term in curly brackets, as in this example:

{
  "customer_id": {customer_id},
  "customer_name": "{customer_name}",
  "description": "{description}",
  "url": "https://google.nl?q={search_term}"
}
  • The customer_id, customer_name, and description are input parameters for the endpoint that will be replaced in the body. They can be configured by setting Pre-processing to Auto or JSON string value.
  • The search_term input parameter must be configured differently for use in JSON, but it is part of a URL query string. For this reason, do not set Pre-processing to Auto or JSON string value but instead to Query string value. This ensures that the value is encoded correctly for a query string.

When the parameters are configured with the following values:

  • customer_id is set to 123
  • customer_name is set to Thinkwise
  • description is set to Company creating "Never Legacy" software.
  • search_term is set to Thinkwise Software "Never Legacy"

Then, the parameters will be replaced in the body as follows:

{
  "customer_id": 123,
  "customer_name": "Thinkwise",
  "description": "Company creating \"Never Legacy\" software.",
  "url": "https://google.nl?q=Thinkwise%20Software%20%22Never%20Legacy%22"}"
}

Note:

  • For customer_name and description, you need to add the surrounding quotes. The process flow action Web connection does not add these automatically. Any quotes within the value of description will be escaped automatically to ensure the JSON remains valid.
  • The search_term is encoded differently. Special characters are encoded: a space ( ) is replaced with %20, and a double quote (") is replaced with %22.

You can configure the input variables in the process flow for the process action Web connection. Ensure the input parameters are set to use the process variables.

Use case: Web connection parameter with JSON body​

This use case describes a Web connection endpoint with the body type set to JSON. The body structure is dynamic and can contain any parameter. The body is configured with only a variable between curly brackets, as in this example:

{json_body}

The json_body is an input parameter for the endpoint. Set Pre-processing for the json_body:

  • If you provide it with a JSON structure, including the escaping of the string values, it will be replaced in the body without any pre-processing. In this case, set Pre-processing for the json_body to None.
  • When Pre-processing is set to JSON string value, but the JSON was already provided correctly, it will be escaped, rendering the JSON invalid.

You can create valid JSON structures in the process flow by using FOR JSON PATH in SQL and configuring the use of this process variable.

SELECT customer_id, name, description
FROM customer
WHERE customer_id = 1
FOR JSON PATH, WITHOUT_ARRAY_WRAPPER;

The input variable for json_body can be configured in the process flow using the process action Web connection. Set the input parameters to use this process variable.

Use case: Web connection parameters with XML body​

This use case describes a Web connection endpoint with the body type set to XML. The body structure is known beforehand and static; it only contains some specific parameters. The body is configured with an XML structure that contains an author and a book-title in curly brackets.

<root>
  <book author="{author}">{book_title}</book>
</root>

The author and book_title are input parameters for the endpoint. These are the parameters that will be replaced in the body. They can be configured with Pre-processing set to Auto or XML string value.

When the author is set to Thinkwise, and the book_title is set to Never Legacy, the body will be:

<root>
  <book author="Thinkwise">Never Legacy</book>
</root>

The Web connection will escape the special characters in the value to keep the XML valid.

Was this article helpful?