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:

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true" ServiceUrl="http://localhost:41380/api/v1/Address">
  <!-- Konfiguration der serverseitigen AddressProvider hier einfügen -->
</AddressProvider>

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:

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Excel/CSV address provider -->
  <AddressProvider id="62C19ADA-826B-4EBC-848D-B32E957D78C6" Title="myCSVFile.csv">
    <SearchParameters>
      <SearchParameter Name="firstName" Label="Vorname/Name" Type="String" Length="100" Sort="1" />
    </SearchParameters>
    <FilePath>myCSVFile.csv</FilePath>
    <Provider Name="CSV"></Provider>
    <Icon></Icon>
    <Mapping>
      <!-- Mapping -->
    </Mapping>
  </AddressProvider>
</AddressProvider>

NOTE
Ohne konfigurierten Security-Key funktioniert der AddressService nicht. Dieser muss im Dashboard vorher generiert werden.

Address Provider

Excel/CSV

Konfiguration:

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Excel/CSV address provider -->
  <AddressProvider id="62C19ADA-826B-4EBC-848D-B32E957D78C6" Title="myCSVFile.csv">
    <SearchParameters>
      <SearchParameter Name="firstName" Label="Vorname/Name" Type="String" Length="100" Sort="1" />
    </SearchParameters>
    <FilePath>myCSVFile.csv</FilePath>
    <Provider Name="CSV"></Provider>
    <Icon></Icon>
    <Mapping>
      <!-- Mapping hier einfügen -->
    </Mapping>
  </AddressProvider>
</AddressProvider>

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:

<Provider Name="CSV">
  <HasHeaders>True</HasHeaders>
  <Delimiter>,</Delimiter>
</Provider>

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:

<Provider Name="EXCEL">
  <HasHeaders>True</HasHeaders>
  <Sheet>Blatt 2</Sheet>
</Provider>

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:

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside generic SQL address provider -->
  <AddressProvider id="7E50AA46-A035-4F11-B44F-BBCBAB4780B7" Title="My DB Soure">
    <SearchParameters>
      <SearchParameter Name="firstName" Label="Vorname/Name" Type="String" Length="100" Sort="1" />
    </SearchParameters>
    <ConnectionString>{ConnectionString}</ConnectionString>
    <ConnectionProvider>System.Data.SqlClient</ConnectionProvider>
    <Query>
      SELECT * FROM Users WHERE FirstName Like '%' + @firstName + '%'
    </Query>
    <Mapping>
      <Map Source="CompanyName" Target="Company_Name" />
      <Map Source="Title" Target="Person_Title" />
      <Map Source="FirstName" Target="Person_FirstName" />
      <Map Source="LastName" Target="Person_LastName" />
      <Map Source="Birthday" Target="Person_BirthDate" />
      <Map Source="Street" Target="Company_Street" />
      <Map Source="Zip" Target="Company_ZipCode" />
      <Map Source="City" Target="Company_City" />
      <Map Source="FaxBusinessDirect" Target="FaxDirect" />
      <Map Source="EmailBusinessDirect" Target="EmailDirect" />
      <Map Target="Company_CountryShortCode">
        <Map.SourceExpression>
          function main()
          {
            switch(source('Country'))
            {
              case 'Albanien': return 'AL';
              case 'Andorra': return 'AD';
              case 'Aserbaidschan': return 'AZ';
              case 'Belgien': return 'BE';
              case 'Bosnien und Herzegowina': return 'BA';
              case 'Bulgarien': return 'BG';
              case 'Dänemark': return 'DK';
              case 'Deutschland': return 'DE';
              case 'Estland': return 'EE';
              case 'Finnland': return 'FI';
              case 'Frankreich': return 'FR';
              case 'Georgien': return 'GE';
              case 'Griechenland': return 'GR';
              case 'Irland': return 'IE';
              case 'Island': return 'IS';
              case 'Italien': return 'IT';
              case 'Kasachstan': return 'KZ';
              case 'Kosovo': return 'XK';
              case 'Kroatien': return 'HR';
              case 'Lettland': return 'LV';
              case 'Liechtenstein': return 'LI';
              case 'Litauen': return 'LT';
              case 'Luxemburg': return 'LU';
              case 'Malta': return 'MT';
              case 'Mazedonien': return 'MK';
              case 'Republik Moldau': return 'MD';
              case 'Monaco': return 'MC';
              case 'Montenegro': return 'ME';
              case 'Niederlande': return 'NL';
              case 'Norwegen': return 'NO';
              case 'Österreich': return 'AT';
              case 'Polen': return 'PL';
              case 'Portugal': return 'PT';
              case 'Rumänien': return 'RO';
              case 'Russland': return 'RU';
              case 'San Marino': return 'SM';
              case 'Schweden': return 'SE';
              case 'Schweiz': return 'CH';
              case 'Serbien': return 'RS';
              case 'Slowakei': return 'SK';
              case 'Slowenien': return 'SV';
              case 'Spanien': return 'ES';
              case 'Tschechien': return 'CZ';
              case 'Türkei': return 'TR';
              case 'Ukraine': return 'UA';
              case 'Ungarn': return 'HU';
              case 'Vatikanstadt': return 'VA';
              case 'Vereinigtes Königreich': return 'GB';
              case 'Weißrussland': return 'BY';
              
              default: return 'CH';
            }
            
            return '';
          }
        </Map.SourceExpression>
      </Map>
    </Mapping>
  </AddressProvider>
</AddressProvider>

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

SELECT FirstName, LastName FROM Users
WHERE FirstName LIKE '%' + @firstName + '%' AND LastName LIKE '%' + @lastName + '%'

Beispiel: MySQL

SELECT FirstName, LastName FROM Users
WHERE FirstName LIKE Concat('%', @firstName, '%') AND LastName LIKE Concat('%', @lastName, '%')

HINWEIS

Bei Oracle, Odbc und PostgreSQL muss die Reihenfolge der Platzhalter in der Query mit der Reihenfolge der "SearchParameters" übereinstimmen!

Beispiel: Oracle

SELECT FirstName, LastName from Users
WHERE UPPER(NVL(FirstName, ' ')) Like UPPER('%' || :firstName || '%') AND UPPER(NVL(LastName, ' ')) Like UPPER('%' || :lastName || '%')

Beispiel: Odbc

SELECT FirstName, LastName FROM Users
WHERE FirstName LIKE '%' + ? + '%' AND LastName LIKE '%' + ? + '%'

Beispiel: PostgreSQL

SELECT FirstName, LastName FROM Users
WHERE UPPER(FirstName) LIKE UPPER('%' || ? || '%') AND UPPER(LastName) LIKE UPPER('%' || ? || '%')

WARNUNG

Die Einschränkung der Reihenfolge hat zur Folge, dass ein Parameter in der Query genau einmal verwendet werden kann.

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

SELECT FirstName, MiddleName, LastName FROM Users
WHERE FirstName LIKE '%' + firstName + '%' OR MiddleName LIKE '%' + firstName + '%'

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

SELECT STRING(FirstName, ' ', MiddleName) AS CompleteName, LastName FROM Users
WHERE CompleteName LIKE '%' + ? + '%'

Zefix

WARNUNG

Die SOAP/XML Zefix Schnittstelle wurde abgeschalten. Um weiterhin Adressdaten zu beziehen, muss auf den neuen Address provider (siehe unter "Zefix (HTTP)") gewechselt werden. Die Grundkonfiguration ist identisch, Anpassungen an der Id und ggf. beim Mapping müssen erstellt werden.

Konfiguration/Zefix (HTTP):

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Zefix address provider (HTTP) -->
  <AddressProvider id="DC124CDC-C2C0-4379-B9D4-079905E68DEA">
    <!-- User/password for Zefix web service-->
    <ServiceUser>info@primesoft-group.com</ServiceUser>
    <ServicePassword>{password}</ServicePassword>
    <!-- Optional Mapping -->
    <Mapping>
       <Map Source="name" Target="Company_Name" />
       <Map Source="translation" Target="Company_Supplement" />
       <Map SourceExpression="oo('address.street') + ' ' + oo('address.houseNumber')" Target="Company_Street" />
       <Map Source="address.city" Target="Company_City" />
       <Map SourceValue="CH" Target="Company_CountryShortCode" />
       <Map Source="address.swissZipCode" Target="Company_ZipCode" />
       <Map SourceValue="CompanyData" Target="AddressType" />
       <Map SourceValue="false" Target="SalutationView" />
    </Mapping>
  </AddressProvider>
</AddressProvider>

Parameter:

id DC124CDC-C2C0-4379-B9D4-079905E68DEA
ServiceUser Der Benutzer, mit welchem sich der Provider beim Zefix-Dienst anmeldet.
ServicePassword Das Passwort, mit dem sich der Provider beim Zefix-Dienst anmeldet: kann verschlüsselt sein.
Mapping: Optionales Mapping, um die abgefüllten Informationen zu individualisieren, siehe Standard-Kontakt-Mapping. Mappt vom Objekt CompanyFull. Verfügbare Eigenschaften finden Sie unter https://www.zefix.admin.ch/ZefixPublicREST/swagger-ui/index.html .

Oben finden Sie ein Beispiel für ein Mapping der gängigsten Parameter. Beachten Sie, dass Sie alle gewünschten Parameter mappen müssen.

Konfiguration/Zefix (HTTP):

WARNUNG

Diese Schnittstelle wurde abgeschalten. Wechseln Sie auf den neuen Address provider.

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Zefix address provider (Legacy SOAP/XML) -->
  <AddressProvider id="F6CA6CC9-B201-4556-886E-C6AF5F9460E4">
    <!-- User/password for Zefix web service -->
    <ServiceUser>info@primesoft-group.com</ServiceUser>
    <ServicePassword>{password}</ServicePassword>
    <EnableProxyCredentials>true</EnableProxyCredentials>
    <!-- Optional Mapping -->
    <Mapping>
      <Map Source="name" Target="Company_Name" />
      <Map Source="translation[0]" Target="Company_Supplement" />
      <Map SourceExpression="oo('address.addressInformation.street') + ' ' + oo('address.addressInformation.houseNumber')" Target="Company_Street" />
      <Map Source="address.addressInformation.town" Target="Company_City" />
      <Map Source="address.addressInformation.country" Target="Company_Country" />
      <Map Source="address.addressInformation.country" Target="Company_CountryShortCode" />
      <Map Target="Company_ZipCode">
        <Map.SourceExpression>
          <![CDATA[
            function main()
            {
              var index = 0;
              var count = oo('address.addressInformation.ItemsElementName.Length');
              
              for(;index < count; index++)
              {
                if(oo('address.addressInformation.ItemsElementName[' + index + ']') == 'swissZipCode')
                {
                  return oo('address.addressInformation.Items[' + index + ']');
                }
              }
              
              return "";
            }
          ]]>
        </Map.SourceExpression>
      </Map>
    </Mapping>
  </AddressProvider>
</AddressProvider>

Parameter:

id F6CA6CC9-B201-4556-886E-C6AF5F9460E4
ServiceUser Der Benutzer, mit welchem sich der Provider beim Zefix-Dienst anmeldet.
ServicePassword Das Passwort, mit dem sich der Provider beim Zefix-Dienst anmeldet: kann verschlüsselt sein.
Uri Optionale Service Url. Default: http://www.e-service.admin.ch/ws-zefix-1.6/ZefixService?wsdl
Mapping: Optinales Mapping, um die abgefüllten Informationen zu individualisieren. Mappt vom Objekt companyFullInfoType. Auf "untergeordnete" Eigenschaften kann via Punkt (.) zugegriffen werden. Zum Beispiel: address.addressInformation.street. Analog kann auf Aufzählung via Null-basiertem Indexer zugegriffen werden. Beispiel: translation[0].Value

ETV Access

Konfiguration:

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside ETV Access address provider -->
  <AddressProvider id="BD633F5C-816A-4B7C-9546-EEDE889B8BDA">
    <!-- User for ETV Access web service-->
    <ServiceUser>{username}</ServiceUser>
    <ServicePassword>{password}</ServicePassword>
    <ServiceId>{serviceId}</ServiceId>
    <MaxResultCount>50</MaxResultCount>
    <EnableProxyCredentials>true</EnableProxyCredentials>
    <!-- Optional Mapping -->
    <Mapping>
      <Map Source="FirstName" Target="Person_FirstName" />
      <Map Source="LastName" Target="Person_LastName" />
      <Map SourceExpression="source('StreetName') + ' ' + source('HouseNo')" Target="Person_Street" />
      <Map Source="Apartment" Target="Person_Apartment" />
      <Map Source="Floor" Target="Person_Floor" />
      <Map Source="PoBox" Target="Person_PostOfficeBox" />
      <Map Source="Zip" Target="Person_ZipCode" />
      <Map Source="LocaPostName" Target="Person_City" />
    </Mapping>
  </AddressProvider>
</AddressProvider>

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.

innosolvcity-Address Provider von Innosolv

Diese Adressschnittstelle spricht vom "BasisService" den Endpunkt "FindSubjektKontaktperson" an.

Beispielkonfiguration 1 (minimal)

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside innosolvcity address provider -->
  <AddressProvider id="28F86C73-3A64-4BFF-AD87-CBDA92ED9170">
    <NestVersion>2020</NestVersion>
    <Uri>http://services.example.com:12345/BasisService</Uri>
    <UserName>myUserName</UserName>
    <Password>myPassword</Password>
  </AddressProvider>
</AddressProvider>

Beispielkonfiguration 2 (ausführlich)

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside innosolvcity address provider -->
  <AddressProvider id="28F86C73-3A64-4BFF-AD87-CBDA92ED9170">
    <Title>innosolvcity Kontaktperson</Title>
    <NestVersion>2020</NestVersion>
    <Uri>http://services.example.com:12345/BasisService</Uri>
    <UserName>{username}</UserName>
    <Password>{password}</Password>
    <Debug>false</Debug>
    <AlleAdressartenDefault>true</AlleAdressartenDefault>
    <ActiveOnlyDefault>false</ActiveOnlyDefault>
    <SearchParameters>
      <SearchParameter Name="Vorname" Label="Vorname" Type="String" Length="100" Sort="1" />
      <SearchParameter Name="Name" Label="Nachname" Type="String" Length="100" Sort="2" />
      <SearchParameter Name="Geburtsdatum" Label="Geburtstag" Type="Date" Length="100" Sort="3" />
      <SearchParameter Name="StrasseHaus" Label="Strasse/Haus" Type="String" Length="100" Sort="4" />
      <SearchParameter Name="PLZ" Label="PLZ/Ort" Type="String" Length="6" Sort="5" />
      <SearchParameter Name="Ortsname" Label="" Type="String" Length="100" Width="130" Sort="5" />
      <SearchParameter Name="ID_Subjekt" Label="Subjekt-ID" Type="Long" Length="100" Sort="6" />
      <SearchParameter Name="AlleAdressarten" Label="Alle Adressarten" Type="Boolean" Length="100" Sort="7" />
      <SearchParameter Name="ActiveOnly" Label="Nur aktive" Type="Boolean" Length="100" Sort="8" />
    </SearchParameters>
    <Mapping>
      <!-- determine AddressType -->
      <Map Target="AddressType">
        <Map.SourceExpression>
          <![CDATA[
            function main()
            {
              let firmenname = source('Firmenname');
              let name = source('Name');
              
              let companyDataIsAvailable = firmenname !== null && firmenname !== '';
              let personDataIsAvailable = name !== null && name !== '';
              
              if (companyDataIsAvailable && personDataIsAvailable)
              {
                return 'CompanyAndPersonData';
              }
              else if (personDataIsAvailable)
              {
                return 'PersonData';
              }
              else
              {
                return 'CompanyData';
              }
            }
          ]]>
        </Map.SourceExpression>
      </Map>
      <!-- Company -->
      <If Condition="target('AddressType') === 'CompanyAndPersonData' || target('AddressType') === 'CompanyData'">
        <Map Target="Company_Name" Source="Firmenname" />
        <Map Target="Company_Street" Source="StrasseHaus" />
        <Map Target="Company_City" Source="Ort" />
        <Map Target="Company_ZipCode" Source="PLZ" />
        <Map Target="Company_Country" Source="Nation" />
        <Map Target="Company_CountryShortCode" SourceExpression="''" />
        <Map Target="Company_PhoneDirect" Source="Telefon" />
        <Map Target="Company_EmailDirect" Source="Email" />
        <Map Target="Company_FaxCentral" Source="Telefax" />
        <Map Target="Company_Mobile" Source="Mobil" />
      </If>
      <!-- Person -->
      <If Condition="target('AddressType') === 'CompanyAndPersonData' || target('AddressType') === 'PersonData'">
        <Map Target="Person_Title" Source="Titel" />
        <Map Target="Person_LastName" Source="Name" />
        <Map Target="Person_FirstName" Source="Vorname" />
        <Map Target="Person_SecondName" Source="Zusatzname" />
        <Map Target="Person_Birthday" Source="Geburtsdatum" />
        <Map Target="Person_SalutationShort" Source="Anrede" />
        <Map Target="Person_Salutation" Source="Briefanrede" />
        <If Condition="target('AddressType') === 'PersonData'">
          <Map Target="Person_Street" Source="StrasseHaus" />
          <Map Target="Person_City" Source="Ort" />
          <Map Target="Person_ZipCode" Source="PLZ" />
          <Map Target="Person_Country" Source="Nation" />
          <Map Target="Person_CountryShortCode" SourceExpression="''" />
          <Map Target="Person_PhoneDirect" Source="Telefon" />
          <Map Target="Person_EmailDirect" Source="Email" />
          <Map Target="Person_FaxDirect" Source="Telefax" />
          <Map Target="Person_Mobile" Source="Mobil" />
        </If>
      </If>
      <!-- Extended Fields -->
      <Map Target="ExtendedField_Dynamic.Adressart" Source="Adressart" />
      <Map Target="ExtendedField_Dynamic.AnzeigeName" Source="AnzeigeName" />
      <Map Target="ExtendedField_Dynamic.AdressZusatz" Source="AdressZusatz" />
      <Map Target="ExtendedField_Dynamic.StrasseZusatz" Source="StrasseZusatz" />
      <Map Target="ExtendedField_Dynamic.PostleitzahlZusatzziffer" Source="PostleitzahlZusatzziffer" />
      <Map Target="ExtendedField_Dynamic.AktivInaktiv" Source="AktivInaktiv" When="source('AktivInaktiv')" />
      <Map Target="ExtendedField_Dynamic.AktivInaktiv_Cd" Source="AktivInaktiv_Cd" When="source('AktivInaktiv_Cd')" />
      <Map Target="ExtendedField_Dynamic.ID_Subjektzuord" SourceExpression="source('ID_Subjektzuord')" When="source('ID_Subjektzuord')" />
      <Map Target="ExtendedField_Dynamic.Subjektart_Cd" Source="Subjektart_Cd" When="source('Subjektart_Cd')" />
      <!-- Address Provicer Data -->
      <Map Target="AddressProviderData_Id" Source="ID_Subjekt" />
      <Map Target="AddressProviderData_Name" SourceValue="NEST Einwohner" />
      <If Condition="source('Briefanschrift')">
        <Map Target="AddressProviderData_Label_FormattedString" Source="Briefanschrift" />
      </If>
      <!-- ContactViewOptions -->
      <Map Target="AddressTypeOption" SourceExpression="target('AddressType') === 'PersonData' ? 'Private' : 'Business'" />
      <Map Target="SalutationSeparateLine" SourceExpression="target('AddressType') === 'PersonData' ? 'true' : 'false'" />
    </Mapping>
  </AddressProvider>
</AddressProvider>

Parameter:

id 28F86C73-3A64-4BFF-AD87-CBDA92ED9170
Title Titel des Address Provider. Default: "innosolvcity Kontaktperson" (bei UI-Sprache Deutsch)
NestVersion Version vom innosolvcity-Service. 2020, falls der innosolvcity-Release 2020 (oder neuer) installiert ist.
Uri Uri des innosolvcity-Service-Endpunkts (kann verschlüsselt sein)
UserName Der Benutzer, mit welchem sich der Provider bei innosolvcity anmeldet (kann verschlüsselt sein)
Password Das Passwort, mit dem sich der Provider bei innosolvcity 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 innosolvcity-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:

Konfiguration

[...]
<Title>NEST Kontaktperson</Title>
[...]
<SearchParameters>
  <SearchParameter Name="Vorname" Label="{U[Recipients.NestAddressProvider.SearchParameterLabel.FirstName]}" Type="String" Length="100" Sort="1" />
  <SearchParameter Name="Name" Label="{U[Recipients.NestAddressProvider.SearchParameterLabel.LastName]}" Type="String" Length="100" Sort="2" />
  <SearchParameter Name="Geburtsdatum" Label="{U[Recipients.NestAddressProvider.SearchParameterLabel.Birthday]}" Type="Date" Length="100" Sort="3" />
  <SearchParameter Name="StrasseHaus" Label="{U[Recipients.NestAddressProvider.SearchParameterLabel.StreetHouse]}" Type="String" Length="100" Sort="4" />
  <SearchParameter Name="PLZ" Label="{U[Recipients.NestAddressProvider.SearchParameterLabel.ZipCodeCity]}" Type="String" Length="6" Sort="5" />
  <SearchParameter Name="Ortsname" Label="" Type="String" Length="100" Width="130" Sort="5" />
  <SearchParameter Name="ID_Subjekt" Label="{U[Recipients.NestAddressProvider.SearchParameterLabel.SubjectID]}" Type="Long" Length="100" Sort="6" />
  <SearchParameter Name="AlleAdressarten" Label="{U[Recipients.NestAddressProvider.SearchParameterLabel.AllAddressTypes]}" Type="Boolean" Length="100" Sort="7" />
  <SearchParameter Name="ActiveOnly" Label="{U[Recipients.NestAddressProvider.SearchParameterLabel.ActiveOnly]}" Type="Boolean" Length="100" Sort="8" />
</SearchParameters>
[...]

Einträge in den Globalen Übersetzungen:

Recipients.NestAddressProvider.Title
de: NEST Kontaktperson
en: NEST contact person
fr: Personne de contact de NEST
it: Persona di contatto NEST

Recipients.NestAddressProvider.SearchParameterLabel.FirstName
de: Vorname
en: First name
fr: Prénom
it: Nome

Recipients.NestAddressProvider.SearchParameterLabel.LastName
de: Nachname
en: Last name
fr: Nom de famille
it: Cognome

Recipients.NestAddressProvider.SearchParameterLabel.StreetHouse
de: Strasse/Haus
en: Street/House
fr: Rue/maison
it: strada / casa

Recipients.NestAddressProvider.SearchParameterLabel.ZipCodeCity
de: PLZ/Ort
en: Zip code/town
fr: Zip/Ville
it: Zip / Città

Recipients.NestAddressProvider.SearchParameterLabel.Birthday
de: Geburtstag
en: Birthday
fr: Date de naissance
it: Data di nascita

Recipients.NestAddressProvider.SearchParameterLabel.SubjectID
de: Subjekt-ID
en: Subject id
fr: Id du sujet
it: Id dell'oggetto

Recipients.NestAddressProvider.SearchParameterLabel.AllAddressTypes
de: Alle Adressarten
en: All address types
fr: Tous les types d'adresse
it: Tutti i tipi di indirizzo

Recipients.NestAddressProvider.SearchParameterLabel.AllAddressTypes
de: Alle Adressarten
en: All address types
fr: Tous les types d'adresse
it: Tutti i tipi di indirizzo

Recipients.NestAddressProvider.SearchParameterLabel.ActiveOnly
de: Nur aktive
en: Active only
fr: Actifs uniquement
it: Solo attivi

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/Online:

Um auf Exchange 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 mit beliebigen Namen an
In der "App" unter "Authentication" aktivieren Sie die Option "Treat application as a public client"
Ebenfalls unter "Authentication" fügen Sie urn:ietf:wg:oauth:2.0:oob als "Redirect URI" hinzu

Unter "Manifest" fügen Sie den folgenden Eintrag unter requiredResourceAccess innerhalb der eckigen Klammern ein:

{
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
        {
            "id": "3b5f3d61-589b-4a3c-a359-5dd4b5ee5bd5",
            "type": "Scope"
        }
    ]
}

Unter "Overview" kopieren Sie die ClientId

Diese Konfiguration können Sie auch in der Microsoft Dokumentation nachlesen.

Nach Abschluss der Registrierung hinterlegen Sie die ClientId als AppClientId und die TenantId als TenantId.

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Microsoft Exchange address provider -->
  <AddressProvider id="24425bd4-d6f1-4e2c-a323-3cc63fb5f07b">
    <Debug>false</Debug>
    <Title>Exchange Online</Title>
    <EWSUrl>https://outlook.office365.com/EWS/Exchange.asmx</EWSUrl>
    <AppClientId>{AppClientId}</AppClientId>
    <TenantId>{TenantId}</TenantId>
    <UserName>{username}</UserName>
    <Password>{password}</Password>
    <!-- Optional Mapping -->
    <Mapping>
    </Mapping>
  </AddressProvider>
</AddressProvider>

Konfiguration/OnPrem:

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Microsoft Exchange address provider -->
  <AddressProvider id="24425bd4-d6f1-4e2c-a323-3cc63fb5f07b">
    <Debug>false</Debug>
    <Title>Exchange OnPrem</Title>
    <EWSUrl>{HOST}/EWS/Exchange.asmx</EWSUrl>
    <UserName>{username}</UserName>
    <Password>{password}</Password>
    <IgnoreSslErrors>false</IgnoreSslErrors>
    <!-- Optional Mapping -->
    <Mapping>
    </Mapping>
  </AddressProvider>
</AddressProvider>

Konfiguration/Empfohlenes Mapping:

Folgendes Mapping wird empfohlen, kann jedoch beliebig angepasst werden.

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Microsoft Exchange address provider -->
  <AddressProvider id="24425bd4-d6f1-4e2c-a323-3cc63fb5f07b">
    <!-- other settings for OnPrem or Cloud -->
    <Mapping>
      <Map Source="GivenName" Target="Person_FirstName" />
      <Map Source="Surname" Target="Person_LastName" />
      <Map Source="JobTitle" Target="Person_Position" />
      <Map Source="Profession" Target="Person_Profession" />
      <Map Source="MiddleName" Target="Person_SecondName" />
      
      <Map Source="CompanyName" Target="Company_Name" />
      <Map Source="Department" Target="Company_Department" />
      <Map Source="Contact.Address.Street" Target="Company_Street" />
      <Map Source="Contact.Address.City" Target="Company_City" />
      <Map Source="Contact.Address.PostalCode" Target="Company_ZipCode" />

      <Map Source="Contact.Phone.Business" Target="Company_PhoneDirect" />
      <Map Source="Contact.Phone.CompanyMainPhone" Target="Company_PhoneCentral" />
      <Map Source="Contact.Fax.Business" Target="Company_FaxDirect" />
      <Map Source="Contact.Phone.Mobile" Target="Company_Mobile" />
      
      <Map Source="Mailbox.Address" Target="Company_EmailDirect" />
              
      <Map Target="Company_CountryShortCode">
        <Map.SourceExpression>
          function main() {
          switch(source('Contact.Address.CountryOrRegion')) {
            case 'Albania': return 'AL';
            case 'Andorra': return 'AD';
            case 'Azerbaijan': return 'AZ';
            case 'Azerbaidzhan': return 'AZ';
            case 'Belgium': return 'BE';
            case 'Bosnia and Herzegovina': return 'BA';
            case 'Bulgaria': return 'BG';
            case 'Denmark': return 'DK';
            case 'Germany': return 'DE';
            case 'Estland': return 'EE';
            case 'Finland': return 'FI';
            case 'France': return 'FR';
            case 'Georgia': return 'GE';
            case 'Greece': return 'GR';
            case 'Ireland': return 'IE';
            case 'Iceland': return 'IS';
            case 'Italy': return 'IT';
            case 'Kazakhstan': return 'KZ';
            case 'Kazakstan': return 'KZ';
            case 'Kosovo': return 'XK';
            case 'Croatia': return 'HR';
            case 'Latvia': return 'LV';
            case 'Liechtenstein': return 'LI';
            case 'Lithuania': return 'LT';
            case 'Luxembuorg': return 'LU';
            case 'Malta': return 'MT';
            case 'Macedonia': return 'MK';
            case 'Moldova': return 'MD';
            case 'Monaco': return 'MC';
            case 'Montenegro': return 'ME';
            case 'Netherlands': return 'NL';
            case 'Norway': return 'NO';
            case 'Austria': return 'AT';
            case 'Polen': return 'PL';
            case 'Portugal': return 'PT';
            case 'Romania': return 'RO';
            case 'Russia': return 'RU';
            case 'San Marino': return 'SM';
            case 'Sweden': return 'SE';
            case 'Switzerland': return 'CH';
            case 'Serbia': return 'RS';
            case 'Slowakia': return 'SK';
            case 'Slowenia': return 'SV';
            case 'Spain': return 'ES';
            case 'Czech Republic': return 'CZ';
            case 'Türkey': return 'TR';
            case 'Ukraine': return 'UA';
            case 'Hungary': return 'HU';
            case 'Vatican City': return 'VA';
            case 'United Kingdom': return 'GB';
            case 'Belarus': return 'BY';
            case 'India': return 'IN';
            case 'United States': return 'US';
            case 'Indonesia': return 'ID';
            case 'Thailand': return 'TH';
            
            default: return 'DE';
          }
            
          return '';
          }  
        </Map.SourceExpression>
       </Map>
    </Mapping>
  </AddressProvider>
</AddressProvider>

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)

HINWEIS

EWS liefert für eine Adresse nur die Länderbezeichnung, nicht aber den ISO-Code des Landes. Im primedocs Empfängerdialog muss aber der Two-Letter-ISO-Code gesetzt werden. Für das Standardmapping bedeutet dies, dass das Land nicht über den Address Provider gemappt wird, sondern mittels des DefaultCountryCode aus der allgemeinen Empfängerkonfiguration.
Ist es nötig, das Land spezifisch zu setzen, weil innerhalb des (A)AD Adressen aus unterschiedlichen Ländern vorhanden sind, dann muss dies gleich wie beim Generic SQL Address provider erledigt werden.

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:

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside SAP C4C address provider -->
  <AddressProvider id="91d36523-bae9-424e-9618-fae6162d20f7" Title="SAP C4C">
    <EndpointUrl>https://{SAPC4CUrl}/{ApiBasepath}/v{APIVersion}/{APIEndpoint}</EndpointUrl>
    <UserName>{Username}</UserName>
    <Password>{Password}</Password>
    <SearchParameters>
      <SearchParameter Name="firstName" Label="Vorname/Name" Type="String" Length="100" Sort="1" />
    </SearchParameters>
    <Query><![CDATA[$filter=FirstName eq '{firstName}']]></Query>
    <!-- Zwingendes Mapping -->
    <Mapping>
    </Mapping>
    <Icon></Icon>
  </AddressProvider>
</AddressProvider>

HINWEIS

Diese Konfiguration ist nur die Basiskonfiguration und kann alleine noch nicht verwendet werden. Da über diesen Address provider jeder beliebige Endpunkt des SAP C4C Servcices angebunden werden kann, existieren viele verschiedene Konfigurationen. Nach den Parametern sind drei Beispielkonfigrationen für die drei wichtigsten Endpunkte im Bezug auf Adressdaten aufgeführt.

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

Über die Url https://{SAPC4CUrl}/sap/c4c/odata/v1/c4codataapi/$metadata können sämtliche im Service enthaltene Entities mit ihren Properties und Navigationproperties eingesehen werden. Dies ist insbesondere für die Query und das Mapping hilfreich.

HINWEIS

Über die Url https://{SAPC4CUrl}/sap/c4c/odata/v1/c4codataapi/$metadata können sämtliche im Service enthaltene Entities mit ihren Properties und Navigationproperties eingesehen werden. Dies ist insbesondere für die Query und das Mapping hilfreich.

Die Beispiele beziehen sich auf die Entities der Api V2.

Beispiel/CorporateAccount

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="0" active="true">
  <!-- serverside SAP C4C address provider -->
  <AddressProvider id="91d36523-bae9-424e-9618-fae6162d20f7" Title="SAP C4C – Kunden">
    <EndpointUrl>https://{SAPC4CUrl}/sap/c4c/odata/v1/customer/CorporateAccountCollection</EndpointUrl>
    <UserName>{Username}</UserName>
    <Password>{Password}</Password>
    <SearchParameters>
      <SearchParameter Name="company" Label="Firma" Type="String" Length="100" Sort="1" />
      <SearchParameter Name="street" Label="Strasse" Type="String" Length="100" Sort="3" />
      <SearchParameter Name="plz" Label="PLZ/Ort" Type="String" Length="6" Sort="4" />
      <SearchParameter Name="city" Label="" Type="String" Length="100" Width="130" Sort="4" />
      <SearchParameter Name="country" Label="Land" Type="String" Length="100" Sort="5" />
    </SearchParameters>
    <Query><![CDATA[$filter=substringof('{company}', Name) and substringof('{street}', Street) and substringof('{city}', City) and substringof('{plz}', StreetPostalCode) and substringof('{country}', CountryCodeText)]]></Query>
    <Mapping>
      <Map Source="Name" Target="Company_Name"/>
      <Map Source="CountryCode" Target="Company_CountryShortCode" />
      <Map Source="City" Target="Company_City"></Map>
      <Map Source="StreetPostalCode" Target="Company_ZipCode"></Map>
      <Map SourceExpression="source('Street') + source('HouseNumber')" Target="Company_Street"></Map>
      <Map Source="Phone" Target="Company_PhoneCentral"></Map>
      <Map Source="Floor" Target="Company_Floor"></Map>
      <Map Source="Email" Target="Company_EmailCentral"></Map>
      <Map Source="WebSite" Target="Company_Homepage"></Map>
      <Map Source="Fax" Target="Company_FaxCentral"></Map>
      <Map Source="POBox" Target ="Company_PostOfficeBox" ></Map>
      <Map Source="POBoxPostalCode" Target="Company_PostOfficeBoxCity_ZipCode"></Map>
      <Map Source="POBoxDeviatingCity" Target="Company_PostOfficeBoxCity"></Map>
      <Map Source="CareOfName" Target="Company_CareOf"></Map>
      <Map SourceValue="CompanyData" Target="AddressType"></Map>
    </Mapping>
  </AddressProvider>
</AddressProvider>

Beispiel/IndividualCustomer

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="0" active="true">
  <!-- serverside SAP C4C address provider -->
  <AddressProvider id="91d36523-bae9-424e-9618-fae6162d20f7" Title="SAP C4C – Privatkunden">
    <EndpointUrl>https://{SAPC4CUrl}/sap/c4c/odata/v1/customer/IndividualCustomerCollection</EndpointUrl>
    <UserName>{Username}</UserName>
    <Password>{Password}</Password>
    <SearchParameters>
      <SearchParameter Name="firstName" Label="Vorname/Name" Type="String" Length="90" Sort="0" />
      <SearchParameter Name="lastName" Type="String" Length="90" Width="90" Sort="0" />
      <SearchParameter Name="street" Label="Strasse" Type="String" Length="100" Sort="3" />
      <SearchParameter Name="plz" Label="PLZ/Ort" Type="String" Length="6" Sort="4" />
      <SearchParameter Name="city" Label="" Type="String" Length="100" Width="130" Sort="4" />
      <SearchParameter Name="country" Label="Land" Type="String" Length="100" Sort="5" />
    </SearchParameters>
    <Query><![CDATA[$filter=substringof('{firstName}', FirstName) and substringof('{lastName}', LastName) and substringof('{street}',Street) and substringof('{city}', City) and substringof('{plz}', StreetPostalCode) and substringof('{country}', CountryCodeText)]]></Query>
    <Mapping>
      <Map Source="FirstName" Target="Person_FirstName"/>
      <Map Source="AcademicTitleCodeText" Target="Person_Title"></Map>
      <Map Source="LastName" Target="Person_LastName"></Map>
      <Map Source="CountryCode" Target="Person_CountryShortCode" />
      <Map Source="City" Target="Person_City"></Map>
      <Map Source="StreetPostalCode" Target="Person_ZipCode"></Map>
      <Map SourceExpression="source('Street') + source('HouseNumber')" Target="Person_Street"></Map>
      <Map Source="Phone" Target="Person_PhoneDirect"></Map>
      <Map Source="Mobile" Target="Person_Mobile"></Map>
      <Map Source="Fax" Target="Person_FaxDirect"></Map>
      <Map Source="Email" Target="Person_EmailDirect"></Map>
      <Map Source="POBox" Target="Person_PostOfficeBox" ></Map>
      <Map Source="POBoxPostalCode" Target="Person_PostOfficeBoxCity_ZipCode"></Map>
      <Map Source="POBoxDeviatingCity" Target="Person_PostOfficeBoxCity"></Map>
      <Map Source="CareOfName" Target="Person_CareOf"></Map>
      <Map SourceValue="PersonData" Target="AddressType"></Map>
    </Mapping>
  </AddressProvider>
</AddressProvider>

Beispiel/Contact

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="0" active="true">
  <!-- serverside SAP C4C address provider -->
  <AddressProvider id="91d36523-bae9-424e-9618-fae6162d20f7" Title="SAP C4C – Ansprechpartner">
    <EndpointUrl>https://{SAPC4CUrl}/sap/c4c/odata/v1/contact/ContactCollection</EndpointUrl>
    <UserName>{Username}</UserName>
    <Password>{Password}</Password>
    <SearchParameters>
      <SearchParameter Name="firstName" Label="Vorname/Name" Type="String" Length="90" Sort="0" />
      <SearchParameter Name="lastName" Type="String" Length="90" Width="90" Sort="0" />
      <SearchParameter Name="street" Label="Strasse" Type="String" Length="100" Sort="3" />
      <SearchParameter Name="plz" Label="PLZ/Ort" Type="String" Length="6" Sort="4" />
      <SearchParameter Name="city" Label="" Type="String" Length="100" Width="130" Sort="4" />
      <SearchParameter Name="country" Label="Land" Type="String" Length="100" Sort="5" />
    </SearchParameters>
    <Query><![CDATA[$filter=substringof('{firstName}', FirstName) and substringof('{lastName}', LastName) and substringof('{street}', BusinessAddressStreet) and substringof('{city}', BusinessAddressCity) and substringof('{plz}', BusinessAddressStreetPostalCode) and substringof('{country}', BusinessAddressCountryCodeText)]]></Query>
    <Mapping>
      <Map Source="FirstName" Target="Person_FirstName"/>
      <Map Source="LastName" Target="Person_LastName"></Map>
      <Map Source="AcademicTitleCodeText" Target="Person_Title"></Map>
      <Map Source="FunctionCodeText" Target="Person_Position"></Map>
      <Map Source="JobTitle" Target="Person_Profession"></Map>
      <Map Source="BusinessAddressCountryCode" Target="Company_CountryShortCode" />
      <Map Source="BusinessAddressCity" Target="Company_City"></Map>
      <Map Source="AccountFormattedName" Target="Company_Name"></Map>
      <Map Source="DepartmentCodeText" Target="Company_Department" ></Map>
      <Map Source="BusinessAddressStreetPostalCode" Target="Company_ZipCode"></Map>
      <Map SourceExpression="source('BusinessAddressStreet') + source('BusinessAddressHouseNumber')" Target="Company_Street"></Map>
      <Map Source="Phone" Target="Company_PhoneDirect"></Map>
      <Map Source="Mobile" Target="Company_Mobile"></Map>
      <Map Source="Fax" Target="Company_FaxDirect"></Map>
      <Map Source="Email" Target="Company_EmailDirect"></Map>
      <Map SourceValue="CompanyAndPersonData" Target="AddressType"></Map>
    </Mapping>
  </AddressProvider>
</AddressProvider>

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.

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside SharePoint Online address provider -->
  <AddressProvider id="5da866b2-e63a-11eb-ba80-0242ac130004" Title="SharePoint">
    <HostUrl>{HostUrl}</HostUrl>
    <TenantId>{TenantId}</TenantId>
    <ClientId>{ClientId}</ClientId>
    <ClientSecret>{ClientSecret}</ClientSecret>
    <Site>{SiteName}</Site>
    <List>{ListName}</List>               
    <SearchParameters>
      <SearchParameter Name="firstName" Label="Vorname/Name" Type="String" Length="100" Sort="1" />
      <SearchParameter Name="street" Label="Strasse" Type="String" Length="100" Sort="2" />
    </SearchParameters>
    <Query>
      <Filters>
        <Filter>substringof('{street}', fields/Street)</Filter>
        <Filter>substringof('{firstName}', fields/Vorname)</Filter>
      </Filters>                  
      <OrderBy>fields/Vorname</OrderBy>
      <Top>30</Top>
      <Expand>fields(expand=LinkedPerson)</Expand>
      <Select>fields/Vorname, Fields/Name, fields/SpaltenName</Select>
    </Query>                            
    <Debug>true</Debug>    
    <Mapping>
      <Map Source="Name" Target="Person_LastName"></Map>
      <Map Source="Vorname" Target="Person_FirstName"></Map>
      <Map Source="Adresse.address.street" Target="Person_Street" />
      <Map Source="Adresse.address.city" Target="Person_City"></Map>
      <Map Source="Adresse.address.postalCode" Target="Person_ZipCode"></Map>
    </Mapping>
  </AddressProvider>
</AddressProvider>

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

WARNUNG

Für die Filterquery gibt es einige Einschränkungen:

Es kann nur in indexierten Spalten gesucht werden MS-Dokumentation zum Hinzufügen indexierter Spalten.
Entgegen der Dokumentation der Vergleichsoperatoren von Microsoft funktioniert der contains(FieldName, 'SearchValue') Vergleichsoperator nicht! Es muss stattdessen substringof('SearchValue',FieldName) verwendet werden.
Leere Werte gelten bei substringof nicht als Teil des Inhaltes. Dies hat als Konsequenz, dass wenn nicht alle Suchparameter einen Wert haben, kein Eintrag gefunden wird. Aus diesem Grund wurde die Filterquery so aufgebaut, dass innerhalb des <Filters></Filters> mehrere <Filter></Filter> definiert werden können. Ein <Filter></Filter> wird nur dann beachtet, wenn für jeden darin enthaltenen Suchparameter ein Wert eingegeben wurde:

<Filters>
 <Filter>substringof('{street}', fields/Street)</Filter> <!-- Wird nur ausgeführt, wenn street ausgefüllt ist -->
 <Filter>substringof('{firstName}', fields/Vorname) and substringof('{street}', fields/Street)</Filter> <!-- Wird nur ausgeführt, wenn street und firstName ausgefüllt sind -->
</Filters>

Generic HTTP

Mit dem Generic-HTTP-Adressprovider können Sie auf 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 Authentifzierung vorraussetzen, 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 - bei true werden serverseitig weitere Daten geloggt
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 bliebig 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 Kontaktmapping vornehmen.
    - Property Über dieses Element kann man mittels eines JsonPath 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.
    - Contact Die eigentlichen Kontakte werden über dieses Element gesucht. Hierbei muss ein JsonPath 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.

EN AddressService

Konfiguration

Parameter

Address Provider

Excel/CSV

File: CSV Provider

File: Excel Provider

Generic SQL

Beispiel: MS SQL

Beispiel: MySQL

Beispiel: Oracle

Beispiel: Odbc

Beispiel: PostgreSQL

Zefix

Konfiguration/Zefix (HTTP):

Konfiguration/Zefix (HTTP):

ETV Access

in­no­sol­vcity-Address Provider von Innosolv

Microsoft Exchange

SAP C4C (Cloud for Customer)

Beispiel/CorporateAccount

Beispiel/IndividualCustomer

Beispiel/Contact

SharePoint Online

Generic HTTP

innosolvcity-Address Provider von Innosolv