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>

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, MySql.Data.MySqlClient, 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, '%')

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('%' || ? || '%')

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

Configuration:

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:

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

• ServiceUser The user with which the provider logs in to the ETV Access service.

• ServicePassword The password with which the provider logs into the ETV Access service: may be encrypted.

• ServiceId The service id that the provider uses when accessing ETV Access.

• SecurityUri Optional service url to the authentication endpoint. Default: https://secure360.directoriesdata.ch/administration/v5/security.asmx?wsdl

• SearchAddressUri Optional service url to the address search endpoint. Default: http://service360.directoriesdata.ch/search/v5/searchaddress.asmx?wsdl

• Mapping: Optinal mapping to customize the filled information. Mapped from the 'EntryAdd' object. Available properties can be found in the XSD available at http://service360.directoriesdata.ch/search/v5/output/AddressData.xsd. "Subordinate" properties can be accessed via dot (.).

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:

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:

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:

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

    • Dictionary of type EmailAddressDictionary und Enum EmailAddressKey as Key

  • PhysicalAddresses

    • Dictionary of type PhysicalAddressDictionary und Enum PhysicalAddressKey as Key

  • PhoneNumbers

    • Dictionary of type PhoneNumberDictionary und Enum PhoneNumberKey as Key

  • ContactSource

  • Department

  • JobTitle

  • Manager

  • Surname

  • Alias

  Certain 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

    • MailBox.Address → MailBox.Address

    • MailBox.Name → MailBox.Name

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

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>

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.

Examples

These examples refer to the entities of the Api V2.

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.

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 . The value is then available via the {Placeholder} for further requests via the configured name.

      • Contact The actual contacts are searched for via this element. A JsonPath 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.