Generic HTTP

Mit dem Generic-HTTP-Adressprovider können Sie auf beliebig konfigurierbare HTTP/HTTPS-Endpunkte zugreifen. In der einfachsten Konfigurationsart gibt man eine Zieladresse an und wandelt dann die resultierenden Daten in Kontakte um. Da viele Dienste eine Authentifizierung voraussetzen, ist es über den Provider möglich, eine Schrittfolge von HTTP-Anfragen zu definieren um so z. B. "Access-Tokens" oder andere Daten zu holen und diese für weitere HTTP-Anfragen weiterzuverwenden.

Konfiguration

Die folgende Konfiguration stellt ein typisches Szenario nach, bei ein "AccessToken" über UserName/Password geholt werden muss und dieses dann weiterverwendet wird.

<!-- 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>

Parameter

• id 09C886F1-4B5A-4372-8CB4-4AA6D2F7A47B
• Title Titel des Address Provider. Hier empfiehlt sich der Name des anzusprechenden Systems.
• Icon Base64-Icon, das dem Benutzer im Empfängerdialog angezeigt wird.
• SearchParameter Liste mit allen Eingabemöglichkeiten
  • Name Eindeutige Id für den Parameter. Entspricht dem Platzhalter in der Odata Query.
  • Label Angezeigter Text vor dem Eingabefeld
  • Type Eingabetyp: String (Text), Long (Zahl), Boolean (Ja/Nein) oder Date (Datum)
  • Length Maximale Länge für Strings
  • Sort Sortierungswert gegenüber den anderen Parametern
• Debug Boolean - true falls zusätzliche Informationen geloggt werden sollen (verfügbare Werte mit Namen für das Mapping, detailliertere Fehlermeldungen)
• Configuration Unter diesem Punkt wird die Abfolge an HTTP Anfragen definiert.
  • Secret Um Klartextpasswörter in Konfigurationen zu vermeiden, können Secrets als <Secret Name="..." Value="{c[...]}" /> erfasst werden. Zur Laufzeit wird das Passwort entschlüsselt und kann als Platzhalter für Requests verwendet werden.
  • Step Ein Step umfasst jeweils Request und Response. Es können beliebig viele "Steps" definiert werden. Während jedes Schrittes können Properties oder Contacts in die Resultatliste aufgenommen werden.
    • Request Über dieses Element wird die HTTP Anfrage gebaut.
      • Method (Attribut) HTTP Methode, welche genutzt werden soll (GET, POST, ...)
      • Url (Attribut) Ziel URL des Aufrufs. In der URL können Platzhalter über diese Schreibweise genutzt werden: {Placeholder}. Platzhalter werden stets URL-Encoded.
      • Header Es können beliebig viele HTTP Header angegeben werden. Es können ebenfalls Platzhalter über den {Placeholder}-Syntax genutzt werden.
      • Body Es kann ein Body definiert werden. Es können ebenfalls Platzhalter über den {Placeholder}-Syntax genutzt werden. Es findet hierbei kein Encoding statt.
      • FakeResponse Um einen Endpunkt zu testen, kann das Element FakeResponse genutzt werden um einen konfigurierbaren Rückgabewert zu definieren.
    • Response Über die Response kann auf die HTTP Antwort zugegriffen werden. Ein Response kann entweder eine oder mehrere Property-Elemente erzeugen oder ein Kontakt-Mapping vornehmen.
      • Property Über dieses Element kann man mittels eines JsonPath oder eines XPath einen bestimmten Wert aus der HTTP Antwort herauslesen. Der Wert steht dann über die {Placeholder} für weitere Anfragen unter dem konfigurierten Namen zur Verfügung.
      • Contacts Die eigentlichen Kontakte werden über dieses Element gesucht. Hierbei muss ein JsonPath oder XPath angegeben werden. Die Daten werden dann über das Kontakt-Mapping in Kontakte umgewandelt.

Zugriff auf Benutzerinformationen

Über die Platzhalter {Identity.PrimarySid} und {Identity.Name} kann auf die aktuelle Benutzer-SID bzw. den Benutzernamen zugegriffen werden.