Version: Classic

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 makes it possible to define a sequence of HTTP requests in order to, for example, fetch "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 Under this point 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 respectively. 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 call. Placeholders can be used in the URL via this notation: {Placeholder}. Placeholders are always URL-encoded.
  - UrlBuilder If the URL of the request cannot be created via the simple {Placeholder} syntax, this element is available. Here JavaScript is used to generate the body. For more information, see the section "Url-/BodyBuilder".
  - 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 takes place here.
  - BodyBuilder If the body of the request cannot be created via the simple {Placeholder} syntax, this element is available. Here JavaScript is used to generate the body. For more information, see the section "Url-/BodyBuilder".
    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 Via this function, the request can be instructed to access the URL multiple times at an Interval until a certain target value has been found by means of a JsonPath or XPath, or the maximum time (MaxDuration) has been 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 several 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 directly available, it is necessary to wait for the result.
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

Via the {Placeholder} syntax, configured SearchParameters or generated Property values can be accessed.

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 current user SID and user name can be accessed via the placeholders {Identity.PrimarySid} and {Identity.Name} respectively.

Url-/BodyBuilder

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

Important: If a method definition has been made, it requires a main() function and a string as the return type.

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