Die neue Generation der primedocs Address Provider führt die Suche auf dem primedocs-Server aus und nicht mehr auf den Client.

Konfiguration

Alle neuen Address Provider, werden in einem Provider umschlossen, der als Schnittstelle zwischen der neuen und alten Welt dient. Beispiel:

Parameter

• id GUID, die den AddressService identifiziert. Immer E10A8313-A92D-4CB2-A12B-9AEB58F39207

• order Gibt die Sortierung mit anderen Address Provider im Empfängerdialog an.

• active Gibt an, ob der Address Provider verfügbar ist.

• ServiceUrl Optional. Wird in seltenen Fällen konfiguriert, wenn nicht der parallel von dem Service-Endpoint für die Synchronisierung laufende AddressService verwendet werden soll.

Beispiel

Address Provider

Excel/CSV

Konfiguration

Parameter

• id 62C19ADA-826B-4EBC-848D-B32E957D78C6

• SearchParameter Liste mit allen Eingabemöglichkeiten.

  • Name Eindeutige Id für den Parameter. Entspricht den Spaltenüberschriften für CSV oder für Excel Dateien in welchen gesucht werden soll.

  • Label Angezeigter Text vor dem Eingabefeld

  • Typ 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

• Mapping Mapping auf primedocs Kontaktfelder. Siehe Standard-Kontakt-Mapping.

• Provider Provider, entweder CSV oder EXCEL. Angegeben im Attribut Name.

• Title Der Titel, der dem Benutzer angezeigt wird.

• Icon Base64-Icon, das dem Benutzer im Empfängerdialog angezeigt wird.

File: CSV Provider

Konfiguration

• HasHeaders Standardwert: True, falls die CSV-Datei überschriften besitzt. Sonst False. Wenn keine Header vorhanden sind, werden die Spalten nummeriert (SearchParameter und Mapping entsprechend anpassen).

• Delimiter Trennzeichen. Standardwert: ";"

File: Excel Provider

Konfiguration

• HasHeaders Standardwert: True, falls die Excel-Datei überschriften besitzt. Sonst False. Wenn keine Header vorhanden sind, werden die Spalten wie im Excel nummeriert (A, B...) (SearchParameter und Mapping entsprechend anpassen).

• Sheet Das zu verwendende Excel-Blatt. Wird kein Wert angegeben, wird das erste Blatt verwendet.

Generic SQL

Konfiguration

Parameter

• id 7E50AA46-A035-4F11-B44F-BBCBAB4780B7

• SearchParameter Liste mit allen Eingabemöglichkeiten

  • Name Eindeutige Id für den Parameter. Entspricht den Named Parameter für den Sql 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

• Mapping Mapping auf primedocs Kontaktfelder, siehe Mapping

• ConnectionString ConnectionString. Kann verschlüsselt sein.

• ConnectionProvider System.Data.Odbc, System.Data.SqlClient, MySql.Data.MySqlClient, Oracle.ManagedDataAccess.Client

• Title Der Titel, der dem Benutzer angezeigt wird.

• Icon Base64-Icon, das dem Benutzer im Empfängerdialog angezeigt wird.

Query

Der SQL Query muss in dem Format für die jeweilige Zieldatenbank sein. Da alle Suchparameter als SQL Parameter behandelt werden, muss der jeweilige SQL Parameter Syntax der Zieldatenbank eingehalten werden.

Beispiel: MS SQL

Beispiel: MySQL

Beispiel: Oracle

Beispiel: Odbc

Beispiel: PostgreSQL

Folgende MS SQL Query kann nicht direkt zu Oracle oder Odbc übersetzt werden:

Wenn ein Parameter auf mehr als eine Spalte verglichen werden muss, dann können diese Spalten im SELECT mittels der jeweiligen Funktion des Datenbanksystems kombiniert werden:

Beispiel: Odbc

Zefix

Konfiguration

ETV Access

Konfiguration

Parameter

• id BD633F5C-816A-4B7C-9546-EEDE889B8BDA

• ServiceUser Der Benutzer, mit welchem sich der Provider beim ETV Access-Dienst anmeldet

• ServicePassword Das Passwort, mit dem sich der Provider beim ETV Access-Dienst anmeldet: kann verschlüsselt sein.

• ServiceId Die Service ID, welche der Provider beim Zugriff auf ETV Access verwendet.

• SecurityUri Optionale Service Url zum Authentifizierungs-Endpoint. Default: https://secure360.directoriesdata.ch/administration/v5/security.asmx?wsdl

• SearchAddressUri Optionale Service Url zum Adresssuche-Endpoint. Default: http://service360.directoriesdata.ch/search/v5/searchaddress.asmx?wsdl

• Mapping: Optinales Mapping, um die abgefüllten Informationen zu individualisieren. Mappt vom Objekt EntryAdd. Verfügbare Eigenschaften finden Sie im XSD, welches unter http://service360.directoriesdata.ch/search/v5/output/AddressData.xsd verfügbar ist. Auf "untergeordnete" Eigenschaften kann via Punkt (.) zugegriffen werden.

Im Beispiel oben finden Sie ein Mapping der gängigsten Parameter eines privaten Kontakts. Beachten Sie, dass Sie alle gewünschten Parameter mappen müssen.

in­no­sol­vcity (ehemals NEST)

innosolvcity-Address Provider von Innosolv. Diese Adressschnittstelle spricht vom "BasisService" den Endpunkt "FindSubjektKontaktperson" an.

Konfiguration

Parameter

• id 28F86C73-3A64-4BFF-AD87-CBDA92ED9170

• Title Titel des Address Provider. Default: "in­no­sol­vcity Kontaktperson" (bei UI-Sprache Deutsch)

• NestVersion Version vom in­no­sol­vcity-Service. 2020, falls der in­no­sol­vcity-Release 2020 (oder neuer) installiert ist.

• Uri Uri des in­no­sol­vcity-Service-Endpunkts (kann verschlüsselt sein)

• UserName Der Benutzer, mit welchem sich der Provider bei in­no­sol­vcity anmeldet (kann verschlüsselt sein)

• Password Das Passwort, mit dem sich der Provider bei in­no­sol­vcity anmeldet (kann verschlüsselt sein)

• Debug true falls zusätzliche Informationen geloggt werden sollen (Request und Response)

• AlleAdressartenDefault false, falls der "AlleAdressarten"-Suchparameter deaktiviert sein soll. Durch den SearchParameter "AlleAdressarten" (falls konfiguriert) kann der Benutzer diese Option für die aktuelle Suche ändern.

• ActiveOnlyDefault true, falls der "ActiveOnly"-Suchparameter aktiv sein soll. Durch den SearchParameter "ActiveOnly" (falls konfiguriert) kann der Benutzer diese Option für die aktuelle Suche ändern.

• SearchParameters Hier kann die Such-Maske konfiguriert werden (siehe Beispielkonfiguration). Wenn dieses Element nicht konfiguriert wird, wird eine Standard-Suchmaske angezeigt (verfügbar in DE, EN, FR, IT; CheckBox "AlleAdressarten" wird nicht angezeigt). Bei der in­no­sol­vcity-Suche können folgende Parameter verwendet werden:

  • Vorname

  • Name

  • Geburtsdatum (Date)

  • StrasseHaus

  • PLZ (ab NEST 2018)

  • Ortsname (ab NEST 2018)

  • ID_Subjekt (Long)

  • AlleAdressarten (Boolean) (ab NEST 2018)

  • ActiveOnly (Boolean) (ab NEST 2020)

• Mapping Optionales Kontaktmapping, siehe Standard-Kontakt-Mapping. Mögliche Source-Felder, welche von NEST abgerufen und für das Mapping zur Verfügung gestellt werden:

  • Adressart

  • AdressZusatz

  • AktivInaktiv (ab NEST 2020)

  • AktivInaktiv_Cd (ab NEST 2020)

  • Anrede

  • AnzeigeName

  • Briefanrede

  • Briefanschrift

  • Email

  • Firmenname

  • Geburtsdatum

  • ID_Subjekt

  • ID_Subjektzuord (ab NEST 2020)

  • Mobil

  • Name

  • Nation

  • Ort

  • PLZ

  • PlzOrt

  • PostleitzahlZusatzziffer

  • StrasseHaus

  • StrasseZusatz

  • Subjektart_Cd (ab NEST 2020)

  • Telefax

  • Telefon

  • Titel

  • Vorname

  • Zusatzname

Suchparameter mit übersetzten Beschriftungen:

Microsoft Exchange

Dieser Adressprovider ermöglicht es auf Kontakte in Microsoft Exchange über die EWS-Schnittstelle zuzugreifen. Hierfür wird ein "Service Account" aus Ihrem Active Directory benötigt.

Konfiguration

Parameter

• id 24425bd4-d6f1-4e2c-a323-3cc63fb5f07b

• Title Titel des Address Provider. Default: "Exchange"

• EWSUrl Uri des Exchange-Service-Endpunkts. Für Exchange Online ist dies immer "https://outlook.office365.com/EWS/Exchange.asmx"

• UserName Der Benutzer, mit welchem sich der Provider bei Exchange anmeldet

• Password Das Passwort, mit dem sich der Provider bei Exchange anmeldet (kann verschlüsselt sein)

• AppClientId Die AppClient ID der im AAD konfigurierten EWS-App (Nur Exchange Online)

• TenantId Die TenantId des AAD (Nur Exchange Online)

• Debug true falls zusätzliche Informationen geloggt werden sollen. Geloggt werden die vorhandenen Werte welche für das Mapping verwendet werden können.

• IgnoreSslErrors Ungültige SSL Zertifikate ignorieren oder nicht. Default: false. Nur bei OnPrem Variante teilweise nötig.

• Mapping Optionales Mapping, um die abgefüllten Informationen zu individualisieren.
  Folgende Daten können über das Standard-Kontakt-Mapping abgegriffen werden:

  • DisplayName

  • GivenName

  • Initials

  • CompanyName

  • EmailAddresses

    • Dictionary vom Typ EmailAddressDictionary und Enum EmailAddressKey als Key

  • PhysicalAddresses

    • Dictionary vom Typ PhysicalAddressDictionary und Enum PhysicalAddressKey als Key

  • PhoneNumbers

    • Dictionary vom Typ PhoneNumberDictionary und Enum PhoneNumberKey als Key

  • ContactSource

  • Department

  • JobTitle

  • Manager

  • Surname

  • Alias

  Bestimmte Werte aus den Dictionaries werden für das Mapping bereits extrahiert und als einfache Werte angeboten:

  • PhysicalAddressDictionary[PhysicalAddressKey.Business]

    • City → Contact.Address.City

    • Street → Contact.Address.Street

    • PostalCode → Contact.Address.PostalCode

    • State → Contact.Addess.State

    • CountryOrRegion → Contact.Address.CountryOrRegion

  • PhoneNumberDictionary

    • PhoneNumberKey.BusinessPhone → Contact.Phone.Business

    • PhoneNumberKey.CompanyMainPhone → Contact.Phone.CompanyMainPhone

    • PhoneNumberKey.Mobile → Contact.Phone.Mobile

    • PhoneNumberKey.BusinessFax → Contact.Fax.Business

  • MailBox

    • MailBox.Address → MailBox.Address

    • MailBox.Name → MailBox.Name

• Standard Mapping Das Standard-Mapping welches greift, wenn kein Mapping definiert ist, umfasst folgende Eigenschaften (Feldnamen aus Exchange):

  • GivenName

  • Surname

  • JobTitle

  • Profession

  • MiddleName

  • CompanyName

  • Department

  • BusinessPhone

  • CompanyMainPhone

  • BusinessFax

  • MobilePhone

  • PhysicalAddress.Business

    • City

    • PostalCode

    • Street

  • Mailbox.Address (Primary Email)

SAP C4C (Cloud for Customer)

Mit dem SAP C4C Address provider können Sie auf Ihre Kontaktdaten in der SAP Cloud for Customer zugreifen. Hierfür wird ein "Service Account" in der entsprechenden SAP C4C Cloud benötigt.

Konfiguration

Parameter

• id 91d36523-bae9-424e-9618-fae6162d20f7

• Title Titel des Address Provider. Default: "SAP C4C"

• EndpointUrl Url des SAP-C4C-Service-Endpunkts.

• UserName Der Benutzer, mit welchem sich der Provider am SAP C4C Service anmeldet

• Password Das Passwort, mit dem sich der Provider am SAP C4C Service anmeldet (kann verschlüsselt sein)

• 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

• Query Die Query für die Abfrage am Service wird mit OData v2 geschrieben. Die Suchparameter können mittels {SearchParamId} innerhalb der Query referenziert werden. An dieser Stelle wird auf eine weitere Dokumentation der Query verzichtet, da im Anschluss drei Beispiele für eine Konfiguration gezeigt werden.

• Mapping Das zu definierende Mapping ist ein Standard-Kontakt-Mapping, welches als SourceAttribute den Namen des Properties der entsprechenden Entität enthalten muss. Das Mapping muss zwingend Konfiguriert werden. Es gibt kein Standardmapping das greift, wenn nicht explizit eines definiert wurde.

• Icon Base64-Icon, das dem Benutzer im Empfängerdialog angezeigt wird.

Mit der ODataQuery können auch abhängige Entitäten geladen werden. Dabei muss beachtet werden, dass abhängige Entitäten immer als Array vom Service zurückgegeben werden. Dies bedeutet, dass für das SourceAttr

Beispiele

Die Beispiele beziehen sich auf die Entities der Api V2.

SharePoint Online

Mit dem SharePoint Online Adressprovider können Sie auf Ihre SharePoint Listen zugreifen.

Konfiguration

Um auf SharePoint Online zuzugreifen, ist die Authentifizierung über OAuth nötig. Hierfür benötigt es eine "App Registration" im Azure Active Directory. Führen Sie folgende Schritte aus:

• Melden Sie sich über das Azure Portal an.

• Wählen Sie Ihr Azure Active Directory aus & kopieren Sie die TenantId.

• Unter "App registrations" legen Sie eine neue App mit beliebigen Namen an.

• Unter "API permissions" fügen Sie die Microsoft Graph Sites.Read.All Berechtigung hinzu (benötigt Admin Consent).

• Unter "Certificates & secrets" fügen Sie ein neues Client Secret hinzu.

Parameter

• id 5da866b2-e63a-11eb-ba80-0242ac130004

• Title Titel des Address Provider. Default: "SharePoint"

• HostUrl Host-Url des SharePoint Online (ohne https://) z. B. firma.sharepoint.com

• TenantId Die TenantId des AAD

• ClientId Die AppClient ID der im AAD konfigurierten App

• ClientSecret Client Secret der im AAD konfigurierten APP (kann verschlüsselt werden)

• Site Name der Site in welcher die Liste erstellt ist

• List Name der Liste

• 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

• Query Die Query für die Abfrage am Service wird mit OData v4 geschrieben. Aus der Lister der unterstützten Operationen sind folgende möglich: expand, filter, orderby, select, top. Die Spalten aus der Liste sind immer unter fields/ abgelegt, daher ist es wichtig, das bei allen Operationen (ausser top) stets der Präfix 'fields/' aufgeführt ist. z. B. <Select>fields/Vorname</Select>. Die Suchparameter können mittels {SearchParamId} innerhalb der Query referenziert werden.

  • Expand Mit dem Expand Operator können mehrdimensionale/verlinkte Felder erweitert werden. Klassische Beispiele dafür sind verknüpfte Personen und die Adresse. Standard ist fields.

  • Filter Mit dem Filter Operator können die Einträge anhand der eingegebenen Suchwerte gefiltert werden. Liste der Vergleichsoperatoren. Achtung, Einschränkungen weiter unten beachten.

  • OrderBy Mit dem OrderBy Operator können die Einträge nach bestimmten Spalten sortiert werden. Standard ist unsortiert.

  • Select mit dem Select Operator können die zurückgegebenen Spalten/Informationen eingeschränkt werden. Standardmässig werden alle Informationen selektiert.

  • Top Mit dem Top Operator kann die maximale Anzahl zurückgegebener Resultate limitiert werden. Standard ist 50.

• Debug Boolean - true falls zusätzliche Informationen geloggt werden sollen (verfügbare Werte mit Namen für das Mapping, detailliertere Fehlermeldungen)

• Mapping Für SharePointlisten muss zwingend ein Standard-Kontakt-Mapping definiert werden. Ohne Mapping können die Einträge nicht verarbeitet werden. Für das Mapping werden die Spaltennamen als SourceAttribute verwendet. Ausnahme dabei sind Felder vom Typ Ort und Link.

  • Ort

    • Ortschaftsangaben werden durch Sharepoint automatisch auf mehrere Spalten aufgeteilt. Diese enthalten dann nicht den Spaltennamen, sondern die englische Bezeichnung: Street, PostalCode, City usw. Die komplette Adresse wird mit DispName hinzugefügt. Sind mehrere Spalten vom Typ Ort in einer Liste vorhanden, so werden diese von links nach rechts durchnummeriert, beginnend bei der zweiten Adresse mit 0, z. B. Street, Street0, Street1 bei drei Adressen.

    • primedocs bereitet die Adressen auch noch selbst auf. Dies mit SpaltenName.address.City usw.

  • Link

    • Links werden durch SharePoint in Url und Anzeigename aufgeteilt zurückgegeben: SpaltenName.Url, SpaltenName.Description

• Icon Base64-Icon, das dem Benutzer im Empfängerdialog angezeigt wird.

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.

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.