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.

Attributes

Attribute name

Description

ConnectedServiceKey

Optional key of a Connected Service. When set, the HTTP call is authenticated via the OAuth 2.0 access token of the signed-in user: the token is inserted into the Authorization header, provided that header contains the placeholder and the target URL matches one of the URL patterns configured on the connected service. If the user is not yet signed in to the service, primedocs Web shows a sign-in prompt before execution.

Configuration

In addition to the Mapping configuration and the optional SearchParameters (see Data interface), 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. The encrypted value in {c[...]} format is produced as described under Encryption.
• 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.

Example: personal Outlook contacts (Microsoft Graph)

Via a Connected Service pointing at Microsoft Graph, the signed-in user's personal Outlook contacts can be attached as a data source. The HttpDataProvider references the service via ConnectedServiceKey; the access token is inserted through the {__ConnectedService.AccessToken__} placeholder in the Authorization header.

Two Graph endpoints are suitable:

• me/contacts — the personal Outlook contacts (no free-text search parameter; often sparsely populated, e.g. without an address).
• me/people — the People API (supports a free-text search term via $search, but returns Microsoft's automatically curated people list).

<HttpDataProvider DisplayName="Outlook contacts" ConnectedServiceKey="Graph.OAuth">
  <SearchParameters>
    <Text Id="Name" Label="Name" />
  </SearchParameters>
  <Configuration>
    <Step>
      <Request Method="Get">
        <Url><![CDATA[https://graph.microsoft.com/v1.0/me/people?$search={Name}]]></Url>
        <Header Name="Authorization" Value="Bearer {__ConnectedService.AccessToken__}" />
      </Request>
      <Response>
        <Data JsonPath="$.value[*]">
          <Mapping>
            <Map Source="displayName" Target="DisplayName" />
            <Map Source="scoredEmailAddresses[0].address" Target="Email" />
          </Mapping>
        </Data>
      </Response>
    </Step>
  </Configuration>
</HttpDataProvider>

note

The Connected Service must point at Microsoft Graph and request the appropriate scope (e.g. People.Read for me/people, Contacts.Read for me/contacts). With Graph filters, eq and startswith work reliably; contains requires the headers ConsistencyLevel: eventual and Prefer: HonorNonIndexedQueriesWarningMayFailRandomly and can still fail on larger data sets.

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>