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.

  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.

  5. To define parameters for use across all endpoints (for example, for authentication), go to the tab Web connection parameters. You can use curly brackets { } to add parameters to various settings.

    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 set for the parameter user_name is then passed to the User name field, allowing the field to be filled dynamically.

  6. To add an endpoint, go to the tab Endpoints. Enter the required information:

    • tab General - Enter a Method, Path, and Body type.
    • tab Query strings - Optional. Enter a Name and Value, {parameters} are allowed.
    • tab Request headers - Optional. Enter a Name and Value, {parameters} are allowed.

  7. To add input parameters for a specific endpoint, go to the tab Input parameters. The following settings are available:

    • Default constant value
    • Pre-processing - Process the parameter value, as described in the table below.
    Pre-processingDescription
    AutoAutomatically set the value based on where the input 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.
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.

  1. To add output parameters for a specific endpoint, go to the 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.

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?