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).
Also, identification works on iOS (iPhones) and Android (phones and tablets).
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 https).
Example: https://my-exchange-server.com/EWS/Exchange.asmx For O365/Azure the Azure Application ID is needed here. Example: 610fc6a9-2659-842e-8733-5ceb3aeda4ac There are two different ways of connecting to O365 with EBF Contacts:
For an Application ID using authentication with user credentials the mandatory permissions, all of type “Delegated” are:
When using anonymous authentication without user credentials (see parameter “office365Secret”) but with an App ID secret you must provide the following permissions all of type “Application”:
The Application ID may also require optional permissions:
For generating an Application ID please refer to the official Microsoft documentation: It is mandatory for the app registration to have set the Azure App Registration Settings to:
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 “An error occurred. Contact your administrator for more information.“ This key is mandatory, if you are using Exchange On-Premise or O365 data source. |
| 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. |
| 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"]
}
|
| allowContactMerge | Activating this feature will merge contact phone numbers in one entry, if the same contact is found in multiple data sources. Identification of identical contacts is done by email address.
default = false |
| allowCopy | Allows to copy phone numbers and email addresses from the contact details view.
If deactivated this also will override the “exportContact” setting to “false”. default = true |
| allowCustomCert | Key value for Exchange On-Premise Server and for ZIP data source to allow a custom SSL certificate (true/false).
default = false |
| appName | Allows to set a different app title in the main screen.
default = EBF Contacts |
| callerIdStructure | By default EBF Contacts displays givenname, surname and company name on incoming calls and in the call list of iOS/Android. 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: {
"givenName": -1,
"surname": -1,
"jobTitle": 10,
"department": 10,
"companyName": 18,
"officeLocation": 15
}
|
| deactivateAppEncryption | With his parameter the Administrator can deactivate the need for defining and entering an encryption password on startup of EBF Contacts. If deactivated, the contact data is still encrypted on the device.
default = false |
| delayAfterFailedRequest | Time in milliseconds to wait before another request is sent to the Exchange On-Premise server after an error occured for a request.
Only needed for Exchange On-Premise Server. default = 15000 (value in milliseconds, allowed values between 1000 and 60000) |
| 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. |
| encryptionPasswordPolicy | Value must be in JSON format. Please check chapter 02.9 for more details. |
| encryptUserImage | Key value to encrypt all user images (true/false).
default = true |
| exportContact | Only available for iOS/iPadOS. Key value to enable contact data export to personal address book function in contact details page (true/false).
You need to make sure “allowCopy” is also activated for this to work. default = false |
| ignoreZipFilter | By default, EBF Contacts will only import entries from ZIP file, that have an email address and the email is unique. Subsequent entries with the same email address will be omitted. When activating this switch the app will import all ZIP entries. Keep in mind that CallerId will only allow a phone to be included once in the list.
default = false |
| isGroupFetchingNewFlow | For O365 in combination with “selectedGroups” parameter. This will allow to fetch all the contacts for each group. Makes sense for big address lists, where only small portions for given groups are fetched.
default = false |
| logging | Set this value to “debug” to show additional debug logs in the log file of EBF Contacts.
The log file can be exported in the Settings screen of the Application (if any log entries exist). |
| mailClient | Key value to optionally use a specific mail app for the “send email” feature in the contact details page, in case your standard email client is not the native mail app.
default = native mail app |
| 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. |
| office365Secret | Use this parameter to activate O365 anonymous authentication without user credentials. The user must not authenticate to O365 in this case.
Example: JtS7Q~JtPjfVGOcdysm4inuhJi576fihn(=jdf3py Please be aware that using this parameter in combinaiton with “readPersonalContacts” is not possible. 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. |
| onPremRequestCount | Quantity of parallel requests that are sent to the Exchange On-Premise server.
Only needed for Exchange On-Premise Server. default = 20 allowed when “useFindPeople” is false or not used Allowed values between 1 and 25 |
| password | Password used for the login to Exchange. Not recommended, only for technical accounts.
Only needed for Exchange On-Premise Server. |
| prefixCombinations | Please check chapter 02.4. for more details.
Only needed for Exchange On-Premise Server. |
| primaryColor | Value as hex code for the color of the buttons of the app.
default = #2494C5 |
| 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 |
| 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. This parameter can conflict with Exchange On-Premise servers using “Extended Protection” which is in many cases blocking communication via REST-API. In this case personal contacts can not be fetched from the server. default = false |
| requestTimeOut | Time in seconds to wait for a server response before dismissing the API request.
Only needed for Exchange On-Premise Server. default = 15 (allowed values between 1 and 60) |
| 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. Filter will be applied locally after reading all contacts from server.Only needed (optionally) for O365.Requires additional permissions in Azure application ID (see “endpoint”). |
| 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.
Please be aware that all parameters in this JSON structure need to be provided in the configuration. {
"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,
"teamsVideoCallAllowed": true, "syncIntervalAllowed": false, "autoSyncIntervalIndex": 3
}
Explanation:
0 ==> synchronize again earliest after 8 hours |
| showPresenceStatus | Show presence of users (O365 only) in the contact list. Requires additional permissions in Azure application ID (see “endpoint”)Only needed (optionally) for O365.default = false |
| showContactAddress | Setting this value to “true” will show business address information for personal contacts in the contact details.
default = false |
| tenant | Example.: ebf.de
Only needed for O365
|
| useFindPeople | Set this to “true” to use a different endpoint to read contacts data from Exchange On-Premise server. This is mandatory, if you want to use parameter “addressListIds” to filter for specific contacts of an existing address list.
Only needed (optionally) for Exchange On-Premise. default = false |
| username | The username parameter can be used for the login to Exchange for an assisted or automated login (prefilled username field).
Also, this parameter must be used to activate the QR code feature in EBF Contacts, if the App is used without credentials (e.g. O365 anonymous authentication, HubSpot or ZIP file). Prefill this parameter with the email address of the user for the app to identify him. |
| 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. |
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.
Please be aware, that server or ZIP address must use HTTPS protocol. Unencrypted connections are not supported.
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).
Also, a technical user can be defined and used. This user must have standard permissions and a mailbox but can be hidden from the address list.
For EBF Contacts to be able to authenticate against Exchange On-Premise “Extended Protection” in the server must be turned off (only applies to Android).
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": "",
"PHONE2": "+1 425 555 1111",
"PHONE3": "+1 425 555 6666"
},
{
"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",
"PHONE2": "+1 425 555 8888"
}
]
"DISPLAY NAME","EMAIL ADDRESS","COMPANY","DEPARTMENT","FIRST NAME","LAST NAME","OFFICE","PHONE","MOBILE PHONE","TITLE","MANAGER EMAIL","IMAGE URL","PHONE2","PHONE3" "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","+1 425 555 1111","" "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","+1 425 555 7777","+1 425 555 8888"
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.