Skip to main content

Celonis Product Documentation

Configuring request parameters

When creating a custom extractor, request parameters can be configured in the Configure Request step as part of the definition of your API endpoint and allow you to apply filters to your API requests.

request_response.png

When creating a new request parameter, you can select between two different types:

Static request parameters

When you select the option to Define a static value for the parameter, you need to provide a static value for this parameter.

request_param_1.png

With every extraction request, all static parameters will be added to the Base URL of your endpoint as follows:

 {EndpointURL}/?{Parameter}={ParameterValue}.

For example:

{Connection.API_URL}/my-endpoint-url?my-first-parameter=5&my-second-parameter=12
request_param_2.png
Dynamic request parameters

When you select the option to Get the value as a filter in the extraction configuration, the value of your parameter is assigned dynamically based on the filter that you specify in extraction. You only need to define the data type of the parameter (Datetime, Date, Float, String, Integer, Unix Time) in accordance with your source system’s API documentation.

For the following example, we are creating a dynamic parameter lastModifiedFromDate and specify the Datetime Format according to how it is expected by the API.

dynamic_request.png

The dynamic request parameters, will be added to the Extraction request in the same way as the static parameters:

{EndpointURL}/?{Parameter}={ParameterValue}

The requirement is that a value for the parameter is specified in the Extraction filter. If that is not the case, the parameter will not get appended to the request.

You can assign a value to the parameter via the Extraction filter (the filter configurations for that table will only become visible once you have defined a dynamic request parameter on the respective endpoint):

  • By assigning a fixed value to the parameter:

    dynamic_request_2.png

  • By assigning a value based on an extraction parameter for delta filters. This allows you to use this request parameter as a dynamic delta filter for your extraction.

    dynamic_request_3.png

You can only assign a specific value to the parameter with =. Operations like > or < are not supported because you need to assign a specific value to the request parameter. This means delta filters are by design only possible if the API supports a request parameter that allows filtering for these (e.g., lastModifiedFromDate).

Note

If the request parameter is mandatory, we recommend configuring the endpoint response using a static value for the parameter and switching the parameter to a dynamic one in the end.

Nested request parameters

Some APIs require the filtering parameters to be passed within a dedicated parameter (placeholder). For example:

  • /my-endpoint/?q=...

  • /my-endpoint/?$filter=...

Such syntax can be reflected by using nested parameters.

You can create a nested parameter, by enabling the nested parameter flag when creating it. When activating this option, the parameter will not be appended to the API request as a query parameter. Instead, you are able to reference it within another parameter via a placeholder.

nested_request_1.png

In the following example, we have set-up 2 nested parameters which are both accessible via dedicated placeholders:

  • Vendor - placeholder: {Request.Vendor}

  • lastModifiedFromDate - placeholder: {Request.lastModifiedFromDate}

We are referencing both parameters, in another parameter which is defined as a static request parameter. The placeholders are referenced in the static value.

nested_request_2.png

The overall set-up including 2 nested and 1 static parameters looks as follows:

nested_request_3.png

The values for Vendor and lastModifiedDate are both dynamically retrieved from the extraction filter (see section for dynamic request parameters). Its values are not appended directly to the request, but used within the q parameter. For the example, the API request will look as follows:

{Connection.API_URL}/my-endpoint-url?q=’Vendor = ABC AND lastModifiedFromDate = 2022-01-01 00:00:00’

Assuming that the values ABC and 2022-01-01 00:00:00 are being passed via the extraction filter. When you don’t define a value for one of the nested parameters in the Extraction filter, the parameter will not be appended to the API request.