02.1. Minimum system version
EBF Contacts will run on both iOS / iPadOS version 15 and above.
For Android EBF Contacts works on Android 12 and up.
02.2. Caller Identification
For caller identification to work properly it is important for the phone numbers stored in all data sources to be in standard international format (e.g. Germany +49 221 474550).
02.3. AppConfig
It is mandatory for EBF Contacts to receive an AppConfig or a Managed-AppConfig from an UEM System (e.g. MobileIron, Microsoft Intune, Jamf).
The AppConfig can/must contain the following key/value pairs, where all values are of type “string”:
| Key | Value / Description |
| customerName | Ex.: “EBF GmbH”.
This key is mandatory. |
| licenseKey | A valid license key that is being assigned to the customer which contains a validity end date. If the end date is reached, an error will pop-up when opening the app. You can contact our Sales team to receive valid license keys.This key is mandatory. |
| licenseCount | Ex.: 150 The licenseCount results from the number of devices that will use the app.This key is mandatory. |
| endpoint | For On-Premise Server the Exchange Server URL is needed here (including protocol http/https). Example:https://my-exchange-server.com For O365 the Azure Application ID is needed here. Example: 610fc6a9-2659-842e-8733-5ceb3aeda4ac
If a customer is using an ADFS for authentication to Azure he must make sure that “forms-based authentication” is activated for the authentication to succeed on the device. Otherwise he could see a message like “ This key is mandatory. |
| tenant | Example: ebf.de
Only needed for O365 tenant set is mandatory. else (Multitenant) tenant set is not mandatory.
|
| deltaEnabled | By default EBF Contacts will use the “delta” feature when fetching contact data from O365. After a full list on first usage, next synchronization attempts will only fetch changed data items, which reduces data and sync time.
In some environments it can be helpful to deactivate this feature, because O365 can block the delta API, until uncommitted changes are fully processed. “delta” is always deactivated for fetching organization contacts (see “readOrganizationContact”), because it would not deliver phone numbers in this case. default = true Only needed (optionally) for O365. |
| office365UserFilter | Use this parameter to define a custom filter for reading contact data from O365 global address list. “deltaEnabled” parameter must be set to “false” to use this parameter.
default = „proxyAddresses/any(x:startswith(x,’smtp:‘))and UserType eq ‚Member‘ and AccountEnabled eq true and ShowInAddressList ne false“ Only needed (optionally) for O365. |
| office365PageSize | With this parameter the admin can change the package size for data fetched from O365. This parameter is only respected, if “deltaEnabled” is “false”. If “deltaEnabled” is true O365 uses a fixed package size of 200 for the GAL and 20 for personal contacts.
Value between 100 – 999. default = 100 Only needed (optionally) for O365. |
| selectedGroups | For O365 it is possible to filter the contact list by related Azure AD groups. Value must be in JSON format. Please check 02.6. for more details.Requires additional permissions in Azure application ID (see “endpoint”). |
| hubSpotToken | HubSpot application token. Please check 02.10. for more details.
Mandatory, if you want to use HubSpot as data source. |
| zipUrl | EBF Contacts can read contact data from a downloadable ZIP file. This ZIP file should contain one or more CSV or JSON data exports in a defined format from any data source.
See chapter 02.11. for more information on creating export files for EBF Contacts. Example: https://my-server.com/ContactsExport.zip Mandatory, if you want to use a ZIP file as data source. |
| zipPassword | The ZIP file given in zipUrl parameter may be protected by a password that you need to send in this parameter. Currently EBF Contacts supports ZipCrypto encryption method.
See chapter 02.11. for more information on creating export files for EBF Contacts. |
| username | Username used for the login to Exchange for an automated login (prefilled username).
Only needed for Exchange On-Premise Server. |
| password | Password used for the login to Exchange. Not recommended, only for technical accounts.
Only needed for Exchange On-Premise Server. |
| primaryColor | Value as hex code for the color of the buttons of the app.
default = #2494C5 |
| readPersonalContacts | Key value to show or hide personal contacts (true/false).
Personal contacts are external contacts which each user can save in their address book. default = false |
| readOrganizationContacts | Key value to show or hide contacts from the O365 contact list which mostly holds external contacts data managed by an admin (true/false).
Requires additional permissions in Azure application ID (see “endpoint”). default = false |
| exportContact | Only available for iOS/iPadOS. Key value to enable contact data export to personal address book function in contact details page (true/false).
default = false |
| allowCustomCert | Key value for Exchange On-Premise Server to allow a custom SSL certificate (true/false).
default = false |
| encryptUserImage | Key value to encrypt all user images (true/false).
default = true |
| mailClient | Key value to optionally use Outlook or Email+ for the “send email” feature in the contact details page, in case your standard email client is not the iOS native mail app.
default = native mail app |
| addressListIds | In an Exchange On-Premise environment EBF Contacts will read the Global Address List (GAL). The admin can change this to read one or multiple specific address lists instead (using the id of each address list) Value must be in JSON format. Example: { „values“ : [ „790e6929-4b1d-4026-8929-9aadd06ca033“, „790e6929-4b1d-4026-8929-9aadd06ca034“] } |
| encryptionPasswordPolicy | Value must be in JSON format. Please check chapter 02.9. for more details. |
| prefixCombinations | Please check chapter 02.4. for more details.
Only needed for Exchange On-Premise Server. |
| callerIdStructure | By default EBF Contacts displays givenname, surname and company name on incoming calls and in the call list of iOS. Using this parameter the admin can configure, which fields will be shown in a given order and length limitations.
This value is expected in JSON format. The following example uses all available fields with name fields having unlimited length: Example: |
| settingsPermissions | Parameters are reflected in the App settings page. Admins can activate or deactivate those settings and can allow or deny changes to these settings using the “…Allowed” parameters explained below.
Example: { „showUserImageAllowed“: true, „showUserImageActivated“: true, „showUserImageOnlyInDetailAllowed“: true, „showUserImageOnlyInDetailActivated“: false, „biometricsAllowed“: false, „biometricsActivated“: true, „synchronizationAllowed“: false, „synchronizationActivated“: true, „mobileDataAllowed“: false, „mobileDataActivated“: true, „standardCallAllowed“: true, „faceTimeCallAllowed“: true, „teamsCallAllowed“: true, Explanation:
0 ==> synchronize again earliest after 8 hours |
| logging | Set this value to “debug” to show additional debug logs in the log file of EBF Contacts |
An example AppConfig XML file and plist is available below:
<managedApplicationConfiguration>
<version>1.7.0</version>
<bundleId>de.ebf.contacts</bundleId>
<dict>
<string keyName="customerName">
<defaultValue>
<value>customer name</value>
</defaultValue>
</string>
<string keyName="licenseKey">
<defaultValue>
<value>license keys</value>
</defaultValue>
</string>
<string keyName="endpoint">
<defaultValue>
<value>Office 365 or url</value>
</defaultValue>
</string>
<string keyName="tenant">
<defaultValue>
<value>tenant only for Office 365</value>
</defaultValue>
</string>
<string keyName="licenseCount">
<defaultValue>
<value>license count</value>
</defaultValue>
</string>
<string keyName="office365PageSize">
<defaultValue>
<value>999</value>
</defaultValue>
</string>
<string keyName="selectedGroups">
<defaultValue>
<value>{ "values" : [ "Name of AD group 1", "Name of AD group 2"] }</value>
</defaultValue>
<string keyName="callerIdStructure">
<defaultValue>
<value>{"givenName": -1,"surname": -1,"custom": "-","jobTitle": 10,"department": 10,"companyName": 18,"officeLocation": 15}</value>
</defaultValue>
</dict>
</managedApplicationConfiguration>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>customerName</key>
<string>EBF GmbH</string>
<key>licenseKey</key>
<string>97MtLkThSDFo39kmkj6pW/aTR20Rbj5nPiIa4IKYWB2YZ3orT8ms5rVkXLQHc9NcGLnv5ZiC172cJQsPx6Q4l/pLs=</string>
<key>endpoint</key>
<string>9f12e12e-ea6b-42db-8712-ea1040aa9999</string>
<key>tenant</key>
<string>ebf.de</string>
<key>licenseCount</key>
<string>200</string>
<key>office365PageSize</key>
<string>500</string>
<key>selectedGroups</key>
<string>{ "values" : [ "Name of AD group 1", "Name of AD group 2"] }</string>
<key>callerIdStructure</key>
<string>{"givenName": -1,"surname": -1,"custom": "-","jobTitle": 10,"department": 10,"companyName": 18,"officeLocation": 15}</string>
</dict>
</plist>
02.4. Prefix Combination Explanation (Only Exchange On-Premise)
Since there is a limit for EWS (Exchange Web Services) when reading out contact data, it may be necessary, especially for organizations with many contacts, to split the data over several queries by adjusting the configuration. This can ensure that all records are synchronized and displayed to the users.
For EWS, a maximum of 100 records can be returned in response to a query. The identification of the records is done via the e-mail address of the contact.
By default EBF contacts will try to iterate through the contacts DB step by step, but this might take time on first usage of the app assuming a large database.
When this process is completed and the app restarted once, the log file shows a compressed string.
This string can be shared with other users via “prefixCombinations” parameter to speed up synchronization for all users. Only the compressed string is accepted by the app via parameter.
Example:
prefixCombinations=fVvdmqO6rnyXdb2Tr8F20jzL/s4FSSD8Q2ySzMzTH6iysZiV3RctlQnIkl…
02.5. Default filtering behavior on synchronisation of contacts data
There are several basic attributes and conditions, that EBF Contacts will take into account to decide, whether a contact record should be shown in the list.
For O365 the following criteria are relevant for a contact to be shown:
- Contact must be of usertype “member”
- Related user account must be enabled
- Attribute showInAddressList must be empty (null) or true
- Contacts must have either an email address or a mobile or business phone number (private phone numbers are not synchronized)
An admin can override this default filter by using the config parameter “office365UserFilter”.
For Exchange On-Premise the following rules apply:
- Contact must no have the “Hide from Address lists” flag set
- Contacts must have either an email address or a mobile or business phone number (private phone numbers are not synchronized)
02.6. Filtering via selectedGroups (only O365)
EBF Contacts support filtering of contacts by Azure AD groups.
You may define a list of Azure AD group names in the configuration parameter “selectedGroups” to select only specified contacts records from the given groups.
If the parameter is missing or empty, EBF Contacts will load all contact records by default.
There is a limit of max. 50 groups to be used for filtering.
Example:
{
"values" : [ "HR Team", "DEV Team"]
}
02.7. AppTunnel/VPN
EBF Contacts uses server port 443 for data synchronization.
You may need to implement a VPN solution on the device to secure access to the Exchange server.
It is recommended to use an UEM system’s VPN solution in that case.
02.8. Authentication and permissions
EBF Contacts currently allows user authentication via basic authentication and NTLM.
On-Premise users need to have permission to access EWS (Exchange Web Services).
When activating personal contacts usage (readPersonalContacts) in the config, the app also needs access to Exchange Rest-API.
02.9. Encryption password policy
By default EBF Contacts does not force a policy for the encryption password. By using this parameter you can establish a policy.
Character classes that can be used are “upper case”, “lower case”, “numbers”, “special character”.
MaxLength: Maximum length of the password
MinLength: Minimum Length of the password
Complexity:
0 = no restriction
1 = 2 out of 4 character classes must be used
2 = 3 out of 4 character classes must be used
3 = 4 out of 4 character classes must be used
Example:
{
"MaxLength": 16, "MinLength": 3, "Complexity": 0
}
02.10. HubSpot setup
EBF Contacts supports synchronization of contact data from HubSpot CRM application. For this to work you need to create a private application in the HubSpot admin portal.
Go to “Settings” → “Account Setup” → “Integrations” → “Private Apps”
Create a new application and enter an application name. Then select the scope (permission): crm.objects.contacts.read
After creating the application an Access token will be shown, that needs to be provided in the EBF Contacts configuration in the “hubSpotToken” parameter.
Example:
hubSpotToken=pat-eu1-xxxxxxxx-xxxxxxxx-xxxxxxxx
02.11. CSV and JSON data source in ZIP archive
EBF Contacts support fetching contact data from one or multiple CSV or JSON files. Those files must be packaged in a compressed ZIP file and uploaded to a web server, that can be reached by EBF Contacts.
A ZIP file may be secured by a password (ZipCrypto) that needs to also be provided to the app.
Please provide the complete URL to this file in the config parameter “zipURL”.
EBF is pleased to support customers on creating Powershell or other scripts to create valid export files.
The format of the CSV and JSON files is defined by EBF. The only mandatory fields in these files are DISPLAY NAME, EMAIL ADDRESS and PHONE or MOBILE PHONE.
Please find valid example files below.
[
{
"DISPLAY NAME": "Adele Vance",
"TITLE": "Retail Manager",
"EMAIL ADDRESS": "adele.vance@ebf.com",
"OFFICE": "18/2111",
"FIRST NAME": "Adele",
"LAST NAME": "Vance",
"DEPARTMENT": "Retail",
"COMPANY": "EBF GMBH",
"PHONE": "+1 425 555 2222",
"MOBILE PHONE": "+1 425 555 3333",
"IMAGE URL": "https://picsum.photos/200/300.jpg",
"MANAGER EMAIL": ""
},
{
"DISPLAY NAME": "Grady Archie",
"TITLE": "Designer",
"EMAIL ADDRESS": "grady.archie@ebf.com",
"OFFICE": "18/2111",
"FIRST NAME": "Grady",
"LAST NAME": "Archie",
"DEPARTMENT": "R&D",
"COMPANY": "EBF GMBH",
"PHONE": "+1 425 555 4444",
"MOBILE PHONE": "+1 425 555 5555",
"IMAGE URL": "https://picsum.photos/200/300.jpg",
"MANAGER EMAIL": "adele.vance@ebf.com"
}
]
"DISPLAY NAME","EMAIL ADDRESS","COMPANY","DEPARTMENT","FIRST NAME","LAST NAME","OFFICE","PHONE","MOBILE PHONE","TITLE","MANAGER EMAIL","IMAGE URL" "Adele Vance","adele.vance@ebf.com","EBF GmbH","Retail","Adele","Vance","18/2111","+1 425 555 2222","+1 425 555 3333","Retail Manager","","https://picsum.photos/200/300.jpg" "Grady Archie","grady.archie@ebf.com","EBF GmbH","R&D","Grady","Archie","18/2111","+1 425 555 4444","+1 425 555 5555","Designer","adele.vance@ebf.com","https://picsum.photos/200/300.jpg"
02.12. Android specifics
For Android devices EBF Contacts will store the contact data also in the system’s contacts store to allow for caller identification on incoming calls. The admin must make sure EBF Contacts is installed and used in an Android Enterprise Work Profile only to avoid leaking data to other unmanaged apps.
The admin needs to make sure a browser app is installed in the device’s Work Profile to allow EBF Contacts to open a web view internally for the user to login to O365.
Contacts will be kept in the Work Profile also after uninstallation of EBF Contacts. To remove the contacts completely an admin either needs to remove the Work Profile or – before uninstall – the user must take the manual step of “Logout” from EBF Contacts to clean the system contact DB.