Version: 4.1 (2026-H2)

HttpDataProvider

With the HttpDataProvider you can access arbitrarily configurable HTTP/HTTPS endpoints. In the simplest kind of configuration, you specify a destination address and then convert the resulting data into contacts. Since many services require authentication, the provider allows you to define a sequence of HTTP requests in order to fetch, for example, "access tokens" or other data and reuse it for further HTTP requests.

Configuration

In addition to the Mapping and SearchParameters configuration, which all DataProviders of the Data interface require, the HttpDataProvider must be configured via the Configuration element:

<HttpDataProvider DisplayName="Kundenadressen">
  <Configuration>
    ...
  </Configuration>
  ...
</HttpDataProvider>

Configuration This is where the sequence of HTTP requests is defined.

Secret To avoid plain text passwords in configurations, secrets can be added as <Secret Name="..." Value="{c[...]}" />. At runtime the password is decrypted and can be used as a placeholder for Requests.
Step A step comprises a Request and a Response. Any number of steps can be defined. During each step, Properties or Data elements can be added to the result list.
- Request This element is used to build the HTTP request.
  - Method (attribute) HTTP method to be used (GET, POST, ...)
  - Url Target URL of the request. Placeholders can be used in the URL using this notation: {Placeholder}. Placeholders are always URL-encoded.
  - UrlBuilder If the URL of the request cannot be built using the simple {Placeholder} syntax, this element is available. It uses JavaScript to generate the URL. For more information, see the "Url-/BodyBuilder" section.
  - Header Any number of HTTP headers can be specified. Placeholders can also be used via the {Placeholder} syntax.
  - Body A body can be defined. Placeholders can also be used via the {Placeholder} syntax. No encoding is done here.
  - BodyBuilder If the body of the request cannot be built using the simple {Placeholder} syntax, this element is available. It uses JavaScript to generate the body. For more information, see the "Url-/BodyBuilder" section.
    Either Body or BodyBuilder can be used. Defining both is a misconfiguration.
  - FakeResponse To test an endpoint, the FakeResponse element can be used to define a configurable return value.
  - Polling This function instructs the request to access the URL repeatedly at a given Interval until a specific target value is found via a JsonPath or XPath, or the maximum time (MaxDuration) is reached.
- Response The Response can be used to access the HTTP response. A Response can either create one or more Property elements or perform a mapping on the data.
  - Note: This element is optional if only a Request is to be triggered.
  - Property This element can be used to retrieve a specific value from the HTTP response using a JsonPath or an XPath. The value is then available via the {Placeholder} for further requests under the configured name.
  - Data The actual data is searched for via this element. A JsonPath or an XPath must be specified here. The data is then converted via the Mapping for the Schema of the Object / ObjectCollection.

Polling

The HttpDataProvider can contain multiple steps (Step). In theory, it is possible, for example, to start a call with one Step and access the result in the next Step.
However, if the result is not immediately available, you have to wait for it.
The Polling feature can be used for this:

...
<Step>
  <Request Method="Get">
    <Url><![CDATA[https://sampleservice.example.com/api/reports/status/{ReportId}]]></Url>
    <Polling Interval="500" MaxDuration="30000" JsonPath="$.status" SuccessValue="Completed"/>
    <!-- Interval in ms / MaxDuration in ms -->
  </Request>
  <Response>
    <Data JsonPath="$">
      <Mapping>
        <Map Source="id" Target="FirstName"/>
      </Mapping>
    </Data>
  </Response>
</Step>
...

note

The target URL must also be reachable during polling and must not return an HTTP error.

Interval Defines the time intervals at which the Request is executed against the Url.
MaxDuration Defines the maximum time, after which the request is aborted and an error is returned.
JsonPath and XPath Specification of a JsonPath or XPath to find the success condition.
SuccessValue Specification of the successful value that ends the polling.

Placeholders

The {Placeholder} syntax can be used to access configured SearchParameters or generated Property values.

Example for SearchParameters:

  ...
  <SearchParameters>
    <Text Id="What" Label="SearchTerm" />
  </SearchParameters>
  ...
  <Request Method="Get">
        <Url>https://sample/api/?query={What}...</Url>
  </Request>

Example for Property:

...
<Step>
	<Response>
		...
		<Property Name="AccessToken" JsonPath="$.access_token" />
    </Response>
</Step>
<Step>
	<Request ...>
		...
		<Header Name="Authorization" Value="Bearer {AccessToken}" />
	</Request>
</Step>
...

In addition, the placeholders {Identity.PrimarySid} and {Identity.Name} can be used to access the current user SID or the user name respectively.

Url-/BodyBuilder

For more complex queries, or if, for example, a YesNo field has to be converted into 1 or 0, the Builder elements can be used. With them, you can access all placeholders via JavaScript using the syntax $("PLACEHOLDER").

Important: If a method definition is used, a main() function and a string as the return type are required.

Example UrlBuilder:

<UrlBuilder><![CDATA[
     function main() {
   const what = $("what");
   const where = $("where");
   let getParameters = what === null || what === undefined
   ? "where=" + encodeURIComponent(where)
   : "what=" + encodeURIComponent(what) + "&where=" + encodeURIComponent(where);
   return "http://example.com/search?" + getParameters;
 }
]]></UrlBuilder>

Example BodyBuilder:

<BodyBuilder><![CDATA[
function main() {

  const person = {
                 firstName: $("something"),
                 lastName: $("withSpaces"),
                 age: 30 };

  return JSON.stringify(person);
}
]]></BodyBuilder>

Example XML configuration

"Tel-Search" example:

<HttpDataProvider DisplayName="TelSearch">
  <SearchParameters>
    <Text Id="What" Label="Suchbegriff" />
  </SearchParameters>
  <Configuration>
    <Step>
      <Request Method="Get">
        <Url><![CDATA[https://tel.search.ch/api/?was={What}&key=[Key]&maxnum=100]]></Url>
      </Request>
      <Response>
        <Data XPath="*[local-name()='feed']/*[local-name()='entry']">
          <Mapping>
            <Map Source="*[local-name()='name']" Target="CompanyName" />
            <Map Target="Street">
              <Map.SourceExpression><![CDATA[
                function main()
                {
                  const street = source("*[local-name()='street']");
                  const streetno = source("*[local-name()='streetno']");
                  return street + " " + streetno; 
                }
              ]]></Map.SourceExpression>
            </Map>
            <Map Source="*[local-name()='zip']" Target="PostalCode" />
            <Map Source="*[local-name()='city']" Target="City" />
            <Map SourceValue="CH" Target="Country" />
          </Mapping>
        </Data>
      </Response>
    </Step>
  </Configuration>
</HttpDataProvider>

Configuration​

Polling​

Placeholders​

Url-/BodyBuilder​

Example XML configuration​

Configuration

Polling

Placeholders

Url-/BodyBuilder

Example XML configuration