Generic HTTP

The Generic HTTP Address Provider allows you to access arbitrary configurable HTTP/HTTPS endpoints. In the simplest configuration mode, you specify a destination address and then convert the resulting data into contacts. Since many services require authentication, it is possible to define a step sequence of HTTP requests to fetch via the provider, for example, "access tokens" or other data and reuse it for further HTTP requests.

Configuration

The following configuration simulates a typical scenario where an "AccessToken" must be fetched via UserName/Password and this is then reused.

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Generic HTTP address provider -->
  <AddressProvider id="09C886F1-4B5A-4372-8CB4-4AA6D2F7A47B" Title="HTTP Provider">
	<SearchParameters>
      <SearchParameter Name="company" Label="Firma" Type="String" Length="100" Sort="1" />
      <SearchParameter Name="firstName" Label="Vorname/Name" Type="String" Length="100" Sort="2" />
      <SearchParameter Name="lastName" Label="" Type="String" Length="100" Sort="2" Width="90" />
      <SearchParameter Name="street" Label="Strasse" Type="String" Length="100" Sort="3" />
      <SearchParameter Name="zip" Label="PLZ/Ort" Type="String" Length="6" Sort="4" />
      <SearchParameter Name="city" Label="" Type="String" Length="100" Width="130" Sort="4" />
    </SearchParameters>
    <Configuration>
		<Secret Name="EncryptedPassword" Value="{c[D44PNifWCI9jk+khvrGC06y6UMPzCYx+b1FP6U28XUEB2vY9hS6iuC9WmWiJeAoW]}" />
		<Step>
			<Request Method="Post" Url="https://sampleservice.local/Auth">
				<Body>UserName=API_User&amp;Password={EncryptedPassword}</Body>
			</Request>
			<Response>
				<Property Name="AccessToken" JsonPath="$.access_token" />
			</Response>
		</Step>
		<Step>
			<Request Method="Get" Url="https://sampleservice.local/Contacts?company={company}&amp;firstname={firstName}&amp;lastname={lastName}&amp;street={street}&amp;zip={zip}&amp;city={city}">
				<Header Name="Access-Token" Value="{AccessToken}" />
				<Header Name="Accept" Value="application/json" />
				<Body>hello=world</Body>
			</Request>
			<Response>
				<Contacts JsonPath="$.results">
					<Mapping>
						<Map Source="companyName" Target="Company_Name" />
						<Map Source="companyStreet" Target="Company_Street" />
						<Map Source="companyCity" Target="Company_City" />
						<Map Source="companyZip" Target="Company_Zip" />
					</Mapping>
				</Contacts>
			</Response>
		</Step>
	</Configuration>
  </AddressProvider>
</AddressProvider>

Parameters

• id 09C886F1-4B5A-4372-8CB4-4AA6D2F7A47B
• Title Title of the address provider. The name of the system to be addressed is recommended here.
• Icon Base64 icon that will be displayed to the user in the recipient dialog.
• SearchParameter List of all possible inputs
  • Name Unique id for the parameter. Corresponds to the placeholder in the Odata Query.
  • Label Displayed text in front of the input field
  • Type Input type: String (text), Long (number), Boolean (Yes/No) or Date
  • Length Maximum length for strings
  • Sort Sort value against the other parameters
• Debug Boolean - whether additional information should be logged (request and response).
• Configuration In this part 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. An unlimited number of steps can be defined. During each step Properties or Contacts 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 (attribute) Target URL of the request. Placeholders can be used in the URL using this notation: {Placeholder}. Placeholders are always URL-encoded.
      • 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.
      • FakeResponse To test an endpoint, the FakeResponse element can be used to define a configurable return value.
    • Response The Response can be used to access the HTTP response. A Response can either create one or more Property elements or perform a contact mapping.
      • Property This element can be used to read a specific value from the HTTP response using a JsonPath or a XPath. The value is then available via the {Placeholder} for further requests via the configured name.
      • Contacts The actual contacts are searched for via this element. A JsonPath or a XPath must be specified here. The data is then converted into contacts via the contact mapping.

Access to user information

The {Identity.PrimarySid} and {Identity.Name} placeholders can be used to access the current user SID and user name respectively.