Skip to main content
Version: Classic

AddressService

The new generation of OneOffixx address providers performs the search on the OneOffixx server and no longer on the client.

Configuration​

All new address providers, are enclosed in a provider that serves as an interface between the new and old worlds. Example:

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true" ServiceUrl="http://localhost:41380/api/v1/Address">
  <!-- Insert configuration of server-side address providers here -->
</AddressProvider>

Parameters​

  • id GUID that identifies the AddressService. Always E10A8313-A92D-4CB2-A12B-9AEB58F39207
  • order Specifies sorting with other address providers in the recipient dialog.
  • active Indicates if the address provider is available.
  • ServiceUrl Optional. Configured in rare cases if the AddressService running in parallel from the service endpoint for synchronization should not be used.

Example​

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

NOTE
The AddressService will not work without a configured security key. This must be generated in the dashboard beforehand.

Address providers​

Excel/CSV​

Configuration​

<!-- 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>
      <!-- Insert mapping here -->
    </Mapping>
  </AddressProvider>
</AddressProvider>

Parameters​

  • id 62C19ADA-826B-4EBC-848D-B32E957D78C6
  • SearchParameter List of all possible inputs.
    • Name Unique id for the parameter. Corresponds to the column headers for CSV or for Excel files in which to search.
    • 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
  • Mapping Mapping to OneOffixx contact fields. See default contact mapping.
  • Provider Provider, either CSV or EXCEL. Specified in the Name attribute.
  • Title The title that will be displayed to the user.
  • Icon Base64 icon that will be displayed to the user in the recipient dialog.

File: CSV Provider​

Configuration​

<Provider Name="CSV">
  <HasHeaders>True</HasHeaders>
  <Delimiter>,</Delimiter>
</Provider>
  • HasHeaders Default value: True if the CSV file has headers. Otherwise False. If there are no headers, the columns will be numbered (adjust SearchParameters and mapping accordingly).
  • Delimeter Separator. Default value: ";".

File: Excel Provider​

Configuration​

<Provider Name="EXCEL">
  <HasHeaders>True</HasHeaders>
  <Sheet>Sheet 2</Sheet>
</Provider>
  • HasHeaders Default value: True, if the Excel file has headers. Otherwise False. If there are no headers, the columns will be numbered as in Excel (A, B...) (adjust SearchParameter and Mapping accordingly).
  • Sheet The Excel sheet to use. If no value is specified, the first sheet will be used.

Generic SQL​

Configuration​

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

Parameters​

  • id 7E50AA46-A035-4F11-B44F-BBCBAB4780B7
  • SearchParameter List with all possible entries.
    • *Name__ Unique id for the parameter. Corresponds to the named parameter for the sql query.
    • Label Displayed text in front of the input field Type Input type: String (Text), Long (Number), Boolean (Yes/No) or Date (Date) Length Maximum length for strings
    • Sort Sort value against the other parameters
  • Mapping Mapping to OneOffixx contact fields, see Mapping
  • ConnectionString ConnectionString. May be encoded.
  • ConnectionProvider System.Data.Odbc, System.Data.SqlClient, MySqlConnector, Oracle.ManagedDataAccess.Client.
  • Title The title that will be displayed to the user.
  • Icon Base64 icon that will be displayed to the user in the recipient dialog.

Query​

The SQL query must be in the format for the respective target database. Since all search parameters are treated as SQL parameters, the respective SQL parameter syntax of the target system must be followed.

Example: MS SQL​
SELECT FirstName, LastName FROM Users
WHERE FirstName LIKE '%' + @firstName + '%' AND LastName LIKE '%' + @lastName + '%'

Example: MySQL​
SELECT FirstName, LastName FROM Users
WHERE FirstName LIKE Concat('%', @firstName, '%') AND LastName LIKE Concat('%', @lastName, '%')
warning

CAUTION
For Oracle, Odbc and PostgreSQL the order of the placeholders in the query must match the order of the "SearchParameters!

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

Example: Odbc​
SELECT FirstName, LastName FROM Users
WHERE FirstName LIKE '%' + ? + '%' AND LastName LIKE '%' + ? + '%'

Example: PostgreSQL​
SELECT FirstName, LastName FROM Users
WHERE UPPER(FirstName) LIKE UPPER('%' || ? || '%') AND UPPER(LastName) LIKE UPPER('%' || ? || '%')
warning

CAUTION
The restriction of the sequence has the consequence that a parameter can be used exactly once in the query.

The following MS SQL query cannot be translated directly to Oracle or Odbc:

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

If a parameter needs to be compared on more than one column, then these columns can be combined in the SELECT using the respective function of the database system:

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

Zefix​

caution

WARNING
The SOAP/XML Zefix interface has been deactivated. To continue to receive address data, it is necessary to switch to the new address provider (see "Zefix (HTTP)"). The basic configuration is identical, adjustments to the Id and possibly to the Mapping must be made.

Configuration​

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

Parameters

  • id DC124CDC-C2C0-4379-B9D4-079905E68DEA
  • ServiceUser The user with which the provider logs into the Zefix service.
  • ServicePassword The password with which the provider logs into the Zefix service: may be encrypted.
  • Mapping: optional mapping to customize the filled information, see default contact mapping. Mapped from object CompanyFull. Available properties can be found at https://www.zefix.admin.ch/ZefixPublicREST/swagger-ui/index.html .

Above is an example of mapping the most common parameters. Note that you must map all the desired parameters.

Zefix (Discontinued SOAP/XML option)​

caution

WARNING
This interface has been deactivated. Switch to the new 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@oneoffixx.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>

Parameters

  • id F6CA6CC9-B201-4556-886E-C6AF5F9460E4
  • ServiceUser The user with which the provider logs into the Zefix service.
  • ServicePassword The password with which the provider logs into the Zefix service: may be encrypted.
  • Uri Optional service url. Default: http://www.e-service.admin.ch/ws-zefix-1.6/ZefixService?wsdl
  • Mapping: Optinal mapping to customize the filled information. Mapped from the object companyFullInfoType. "Subordinate" properties can be accessed via dot (.). For example: address.addressInformation.street. Similarly, enumeration can be accessed via zero-based indexer. Example: translation[0].Value.

ETV Access​

Configuration​

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

Parameters​

The example above shows a mapping of the most common parameters of a private contact. Note that you must map all the desired parameters.

in­no­sol­vcity (formerly NEST)​

innosolvcity address provider by Innosolv. This address interface addresses the "FindSubjectContactPerson" endpoint from the "BasisService".

Configuration​

Example 1 (simple)

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside in­no­sol­vcity 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>

Example 2 (detailed)

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside in­no­sol­vcity address provider -->
  <AddressProvider id="28F86C73-3A64-4BFF-AD87-CBDA92ED9170">
    <Title>in­no­sol­vcity 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>

Parameters​

  • id 28F86C73-3A64-4BFF-AD87-CBDA92ED9170
  • Title Title of the address provider. Default: "in­no­sol­vcity Kontaktperson" (for UI language German).
  • NestVersion Version of the in­no­sol­vcity service. 2020, if the in­no­sol­vcity release 2020 (or newer) is installed.
  • Uri Uri of the in­no­sol­vcity service endpoint (may be encrypted).
  • UserName The user with which the provider logs into in­no­sol­vcity (may be encrypted).
  • Password The password with which the provider logs into in­no­sol­vcity (may be encrypted).
  • Debug true whether additional information should be logged (request and response)
  • AllAddressTypeDefault false if the "AllAddressType" search parameter should be disabled. By using the "AllAddressTypes" search parameter (if configured), the user can change this option for the current search.
  • ActiveOnlyDefault true if the "ActiveOnly" search parameter should be active. The "ActiveOnly" search parameter (if configured) allows the user to change this option for the current search.
  • SearchParameters Here the search mask can be configured (see sample configuration). If this element is not configured, a default search mask is displayed (available in DE, EN, FR, IT; checkbox "AllAddressTypes" is not displayed). The following parameters can be used in the in­no­sol­vcity search:
    • First name
    • Last Name
    • Date of birth (Date)
    • StreetHouse
    • Postal code (from NEST 2018)
    • Place name (from NEST 2018)
    • ID_Subject (Long)
    • AllAddressTypes (Boolean) (from NEST 2018)
    • ActiveOnly (Boolean) (from in­no­sol­vcity 2020)
  • Mapping Optional contact mapping, see default contact mapping. Possible source fields which are retrieved by in­no­sol­vcity and made available for mapping:
    • AddressType
    • AddressAddition
    • ActiveInactive (from in­no­sol­vcity 2020)
    • ActiveInactive_Cd (from in­no­sol­vcity 2020)
    • Salutation
    • DisplayName
    • Letter salutation
    • Letter address
    • Email
    • Company Name
    • Date of birth
    • ID_Subject
    • ID_Subject_assignment (from in­no­sol­vcity 2020)
    • Mobile
    • Name
    • Nation
    • City
    • POSTCODE
    • PostcodeCity
    • PostcodeAdditional digit
    • StreetHouse
    • StreetAddition
    • SubjectType_Cd (from in­no­sol­vcity 2020)
    • Telefax
    • Telephone
    • Title
    • first name
    • Additional name

Search parameters with translated labels:

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

Entries in the Global Translations:

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​

This address provider allows to access contacts in Microsoft Exchange via the EWS interface. For this a "Service Account" from your Active Directory is required.

Configuration​

Online

To access Exchange Online, authentication via OAuth is required. For this, an "App Registration" in Azure Active Directory is required. Follow these steps:

  • Log in via the Azure Portal.
  • Select your Azure Active Directory & copy the TenantId.
  • In "App registrations" create a new one with any name you want.
  • In the "App" under "Authentication" enable the "Treat application as a public client" option.
  • Also in "Authentication" add urn:ietf:wg:oauth:2.0:oob as a "Redirect URI"
  • Under "Manifest" insert the following entry under requiredResourceAccess within the square brackets:
{
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
        {
            "id": "3b5f3d61-589b-4a3c-a359-5dd4b5ee5bd5",
            "type": "Scope"
        }
    ]
}
  • In "Overview" copy the ClientId.

You can also read this configuration in the Microsoft Documentation.

After completing the registration, store the ClientId as AppClientId and the TenantId as 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>

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>

Recommended mapping

The following mapping is recommended, but can be customized as desired.

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

Parameters​

  • id 24425bd4-d6f1-4e2c-a323-3cc63fb5f07b.
  • Title Title of the address provider. Default: "Exchange"
  • EWSUrl Uri of the Exchange service endpoint. For Exchange Online this is always "https://outlook.office365.com/EWS/Exchange.asmx"
  • UserName The user with which the provider logs on to Exchange.
  • Password The password with which the provider logs on to Exchange (can be encrypted).
  • AppClientId The AppClient id of the EWS app configured in AAD (Exchange Online only)
  • TenantId The TenantId of the AAD (Exchange Online only)
  • Debug true whether additional information should be logged. Logged are the existing values which can be used for mapping.
  • IgnoreSslErrors Ignore invalid SSL certificates or not. Default: false. Only partially necessary for OnPrem option.
  • Mapping Optional mapping to customize the filled information.
    The following data can be accessed via the default contact mapping:
    • DisplayName
    • GivenName
    • Initials
    • CompanyName
    • EmailAddresses
    • PhysicalAddresses
    • PhoneNumbers
    • ContactSource
    • Department
    • JobTitle
    • Manager
    • Surname
    • AliasCertain values from the dictionaries are already extracted for the mapping and offered as simple values:
    • 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
  • Default Mapping The default mapping which takes effect if no mapping is defined includes the following properties (field names from Exchange):
    • GivenName
    • Surname
    • JobTitle
    • Profession
    • MiddleName
    • CompanyName
    • Department
    • BusinessPhone
    • CompanyMainPhone
    • BusinessFax
    • MobilePhone
    • PhysicalAddress.Business
      • City
      • PostalCode
      • Street
    • Mailbox.Address (Primary Email)
note

NOTE
EWS provides only the country name for an address, but not the ISO code of the country. In the OneOffixx recipient dialog, however, the two-letter ISO code must be set. For the default mapping this means that the country is not mapped via the address provider, but using the DefaultCountryCode from the general recipient configuration.
If it is necessary to set the country specifically, because addresses from different countries exist within the (A)AD, then this must be done the same way as for the Generic SQL address provider.

SAP C4C (Cloud for Customer)​

With the SAP C4C address provider you can access your contact data in the SAP Cloud for Customer. This requires a "Service Account" in the corresponding SAP C4C Cloud.

Configuration​

<!-- 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="First name/Name" Type="String" Length="100" Sort="1" />
    </SearchParameters>
    <Query><![CDATA[$filter=FirstName eq '{firstName}']]></Query>
    <!-- Mandatory mapping -->
    <Mapping>
    </Mapping>
    <Icon></Icon>
  </AddressProvider>
</AddressProvider>
note

NOTE
This configuration is only the basic configuration and cannot be used alone. Since any endpoint of the SAP C4C service can be connected via this address provider, a lot of different configurations exist. After the parameters, three example configurations are listed for the three most important endpoints in relation to address data.

Parameters​

  • id 91d36523-bae9-424e-9618-fae6162d20f7
  • Title Title of the address provider. Default: "SAP C4C"
  • EndpointUrl Url of the SAP C4C service endpoint.
  • UserName The user with which the provider logs on to the SAP C4C service.
  • Password The password with which the provider logs on to the SAP C4C service (can be encrypted).
  • SearchParameter List with all possible entries.
    • *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 (date) Length Maximum length for strings
    • Sort Sort value against the other parameters
  • Query The query for the request at the service is written using OData v2. The search parameters can be referenced using {SearchParamId} within the query. At this point, further documentation of the query is omitted, as three examples of configuration are shown below.
  • Mapping The mapping to be defined is a default contact mapping, which must contain the name of the property of the corresponding entity as SourceAttribute. The mapping must be configured. There is no default mapping that takes effect if one has not been explicitly defined.
  • Icon Base64 icon that is displayed to the user in the recipient dialog.

The ODataQuery can also be used to load dependent entities. It must be noted that dependent entities are always returned as an array by the service. This means that for the SourceAttribute the index of the array must also be specified: RelatedEntityCollection[0].RelatedEntityPropertyName.

note

NOTE
Via the url https://{SAPC4CUrl}/sap/c4c/odata/v1/c4codataapi/$metadata all entities contained in the service can be viewed with their properties and navigation properties. This is especially helpful for the query as well as the mapping.

Examples​

These examples refer to the entities of the Api V2.

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>

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>

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​

With the SharePoint Online address provider you can access your SharePoint lists.

Configuration​

To access SharePoint Online, authentication via OAuth is required. This requires an "App Registration" in Azure Active Directory. Perform the following steps:

  • Log in via the Azure Portal.
  • Select your Azure Active Directory & copy the TenantId.
  • In "App registrations" create a new app with any name you like.
  • In "API permissions" add the Microsoft Graph Sites.Read.All permission (requires Admin Consent).
  • In "Certificates & secrets" add a new client secret.
<!-- 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>

Parameters​

  • id 5da866b2-e63a-11eb-ba80-0242ac130004*.
  • Title Title of the address provider. Default: "SharePoint"
  • HostUrl Host-Url of SharePoint Online (without https://) e.g. company.sharepoint.com.
  • TenantId The TenantId of the AAD
  • ClientId The AppClient ID of the App configured in the AAD
  • ClientSecret Client Secret of the APP configured in the AAD (can be encrypted).
  • Site Name of the site in which the list is created.
  • List Name of the list
  • SearchParameter List with all input options
    • 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 (date)
    • Length Maximum length for strings
    • Sort Sort value against the other parameters
  • Query The query for the query on the service is written with OData v4. From the list of supported operations the following are possible: expand, filter, orderby, select, top. The columns from the list are always stored in fields/, so it is important that all operations (except top) always have the prefix fields/. E.g. <select>fields/firstname</select>. The search parameters can be referenced within the query using {SearchParamId}.
    • Expand The Expand operator can be used to expand multi-dimensional/linked fields. Classic examples are linked persons and address. Default is fields.
    • Filter The Filter operator can be used to filter the entries based on the entered search values. List of comparison operators. Caution, note restrictions below.
    • OrderBy The OrderBy operator can be used to sort the entries by specific columns. Default is unsorted.
    • Select with the Select operator the returned columns/information can be restricted. Default is all information selected.
    • Top The Top operator can be used to limit the maximum number of returned results. Default is 50.
  • Debug true whether additional information should be logged (available values with names for the mapping, more detailed error messages).
  • Mapping For SharePoint lists it is mandatory to define a default contact mapping. Without mapping the entries cannot be processed. For mapping the column names are used as SourceAttribute. Exceptions are fields of type location and link.
    • Location
      • Locality information is automatically split by Sharepoint into several columns. These then do not contain the column name, but the English designation: Street, PostalCode, City etc.. The complete address is added with DispName. If there are several columns of type location in a list, they will be numbered from left to right, starting with the second address with 0, e.g. Street, Street0, Street1 for three addresses.
      • OneOffixx also prepares the addresses itself with ColumnName.address.City and so on.
    • Link
      • Links are returned by SharePoint splitted into url and display name: ColumnName.Url, ColumnName.Description.
  • Icon Base64 icon displayed to the user in the recipient dialog.
caution

WARNING There are some restrictions for the filter query:

  • Only indexed columns can be searched. MS documentation on adding indexed columns
  • Contrary to Microsoft's comparison operator documentation, the contains(FieldName, 'SearchValue') comparison operator does not work! You have to use substringof('SearchValue',FieldName) instead.
  • Empty values are not considered part of the content when using substringof. This has as consequence that if not all search parameters have a value, no entry will be found. For this reason, the filter query was built in such a way that several <Filters></Filters> can be defined within the <Filter></Filter>. A <Filter></Filter> is only considered if a value has been entered for each search parameter it contains:
substringof('{street}', fields/Street) substringof('{firstName}', fields/Vorname) and substringof('{street}', fields/Street) ```xml

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.