Provision harmon.ie Mobile to all users

harmon.ie Knowledge Base - iOS and Android

This article explains how to provision harmon.ie for Mobile, Enterprise Edition.

What can be centrally provisioned?

The following values can be centrally provisioned:

An administrator can:

  1. Set default startup values that the user can later change.
  2. Force values for the user, which disables them in the harmon.ie app, preventing the user from changing them.

Setting default values

Setting default values enables administrators to send predefined settings to users so that all users start with the same settings. After a user has updated their mobile app with the settings, they are free to make any changes allowed by the administrator.

To set default values you add provisioning objects to the provisioning file.

Provisioning workflow

The following workflow steps describe how an administrator sets the default values for users.

An administrator can also send updated provisioning files to users.

Step 1: Enable harmon.ie to export app settings

  1. Download the enable export file and extract it to a folder on your computer.
  2. Sign the enable_export.harmonie file using the signing utility.
  3. Send the provisioning file via email to your mobile device.
  4. On the mobile device, open the file using the harmon.ie app and follow the on-screen instructions.
  5. After the provisioning file is applied, the Export App Settings button becomes visible in Settings > Advanced.

Note: This procedure does not work in Windows Phone. If you are provisioning harmon.ie for Windows Phone, skip to step 2 and follow the second method.

Step 2: Create a provisioning file for users

The provisioning file must be saved in UTF-8 format and must comply with the JSON syntax, if it is changed manually after export.

There are two methods to create a provisioning file:

  • By exporting your app settings:
    1. In the harmon.ie mobile app, define the sites, favorites and settings you would like to provision to your users.
    2. In Settings > Advanced, tap the Export App Settings button to create a new email message with the settings file attached.
    3. Send the email to yourself and save it to a folder on your computer.
    4. Open the file in a text editor and make changes as required. Read the provisioning objects section to learn what can be changed. For example, change the force values of offline documents to true in order to make those documents an emergency documents for your users.
      Note: This method does not apply to Windows Phone.
  • By changing the sample provisioning file:
    1. Download and extract the attached sample file (which was created by exporting the harmon.ie for iOS, version 3.5 settings): provisioning.zip .
    2. Open the file in a text editor and make changes as required. Read the provisioning objects section to learn what can be changed.

Note: The provisioning file must be named ios.provisioning.harmonie, android.provisioning.harmonie, or provisioning.harmonie when uploaded to the document library. harmon.ie first looks for a platform-specific provisioning file. If such is not found, then provisioning.harmonie is taken.

​Step 3: Sign the provisioning file

The provisioning file must be signed only if you choose to distribute it via email (see Method 1​ below). The file must also be signed after changes are made to it as any change to the file’s contents invalidates the signature on a previously signed file. An error message appears if you try to apply an unsigned file to the harmon.ie app.

Note: You can rename a signed file, but you must not change the file's extension, which must always be .harmonie.

How to sign a file:

  1. Ask harmon.ie support for the signing tool (SignProvisioning.exe) and key (organization.key), and save it on your computer.
    To key contains the company name to allow users to identify the provisioning file was sent by their company's administrator.
  2. Open a Command Prompt and run the following command to sign a file:
    cd <location of SignProvisioning.exe>\SignProvisioning.exe <provisioning file name> organization.key

When the file is signed, its name is changed to <originalFileName>-Signed.harmonie, and it now contains the following two additional fields:

  • orgName
  • signature

Step 4: Distribute the provisioning file

Note: It is recommended that before you distribute the provisioning file to users, you send it to your mobile device and apply it in order to validate its correctness. If required, modify (Step 2) and sign the provisioning file again (Step 3).

After performing the following you can distribute the provisioning file using one of the following methods:

Method 1

Send the provisioning file to users by email, as an attachment or with harmon.ie protocol link:

  • Attachment: A user who receives the provisioning file as attachment must open the file in harmon.ie mobile app in order to initiate the provisioning process.
  • harmon.ie protocol link format is: harmonie://<provisioning file url>?protocol={http|https}
    Example: harmonie://mydomain.com/provisioning.harmonie?protocol=https
    A user who receives the link should:
    In iOS: Tap the link.
    In Android: Tap and hold the link and select Share > harmon.ie.

Notes:

  • Make sure the <provisioning file url> location does not require an authentication and is available to all users.
  • When you choose this method to provision sites, favorites, and setting, users can choose whether or not to receive the provisioning update.
  • This method does not apply to Windows Phone.

Method 2

Upload the provisioning file to the harmon.ieFiles Document Library, which is automatically created during the SharePoint server setup.

A user who adds the SharePoint site on which the Enterprise solution was deployed to the harmon.ie mobile app will also initiate the provisioning process.
Note:​ When you choose this method to provision sites, favorites, and setting, users cannot choose to decline the provisioning update.

Method 3

If you are working with BlackBerry (formerly Good) or with MobileIron (ME), you can insert the provisioning file URL to the MDM management app.

Here is how you can do it for BlackBerry and MobileIron (ME).

Updating values

The administrator can send users new provisioning files with updated values at any time.

These updated provisioning files need only include new objects (name and values) and do not have to include objects that do not change. The only exception, however, is that objects on the user's device that were previously set with "force": true, and do not exist in the new provisioning file, automatically become editable.

To create and send updated provisioning files to users proceed as follows:

  1. Create a provisioning file for users.
  2. Sign the provisioning file.
  3. Distribute the provisioning file

Provisioning objects

The tables below describe each of the objects - their default value options and a brief description of each name - included in the provisioning file.

In addition, each object has a force name that enables you to force values for users.

Note: The default values are case-sensitive and lower case values must be used.

Sites

The table below lists the names/values that are used to set a single site for users. These names/values should be nested under the sites array.

NAME VALUE DESCRIPTION FROM VER (iOS) FROM VER (Android)
url Example:
"http://MyCompanySharePoint.com"
The URL of the site. 2.3 2.3
displayName Entered value The display name for the site. 2.3 2.3
useWebApps true to display the option to view, edit or create documents using Office Online,
or
false to not display the option.
Controls the ability to use Office Online for viewing, editing or creating documents.
Supported in SharePoint 2013 and later, and Office 365, tablets only.
2.3 2.3
mySiteHost Example:
"http://MySiteHost.com"
The URL of My Site Host. 2.3 2.3
action update to add a new site or update the site settings (if the site is already configured on the device),
or
delete to delete the site from the device (if the site is configured on the device).
Determines the action that will take place when applying the provisioning file. 2.3 2.3
authMode sso, browse, or auto. The default authentication mode used to connect to this site. See also the authModes global key. 3.8.4  

Favorites

The table below lists the names/values that are used to set a single favorite for users. These names/values should be nested under the favorites array.

NAME VALUE DESCRIPTION FROM VER (iOS) FROM VER (Android)
uniqueIdentifier Example:
"http://MyCompanySharePoint.com/sites/marketing/shared documents"
The URL of the favorite location. 2.3 2.3
title Entered value. The title of the favorite location. 2.3 2.3
isOffline true to save a local copy of the favorite document,
or
false to not save a local copy.
Controls whether a document will be available while the device is offline or not. 2.3 2.6
followScope recursiveAll to include sub-folders when following a favorite location,
or
default not to include sub-folders.
Controls what is included when following a favorite location. 2.3 2.3
type web – sub site,
or
library – document library or list,
or
folder – a folder in a document library,
or
document – a document, or list item,
or
documentset – a document set within a document library,
or
newsfeed – a Site's Newsfeed.
Defines the type of favorite. 2.3 2.3
listType document-library – for all item types apart from lists and list item,
or
announcement-list – for Announcement lists and list items,
or
contact-list – for Contact lists and list items,
or
custom-list – for Custom lists and list items,
or
event-list – for Event lists and list items,
or
issue-list – for Issue lists and list items,
or
link-list – for Link lists and list items,
or
task-list – for Task lists and list items,
or
wiki-library – for Wiki libraries.
Defines the type of a favorite list or list item. 2.4 2.5
action update to add a new favorite or update the favorite settings (if the favorite is already on the device),
or
delete to delete the favorite from the device (if the favorite is on the device).
Determines the action that will take place when applying the provisioning file. 2.3 2.3

Settings

The table below lists the objects that are used to set settings for users. These objects are nested under the settings object.

SETTING NAME NAME VALUE DESCRIPTION FROM VER (iOS) FROM VER (Android)
Sites
Social Server socialSiteURL Example:
"http://MyCompanySharePoint.com"
The URL of the social server used to resolve people in SharePoint. 2.3 2.3
Show OneDrive showMySite true to show OneDrive,
or
false to hide OneDrive.
Controls the visibility of OneDrive in the Sites list. 2.3 2.3
Sites I'm Following followedSites true to show followed sites, or
false not to show.
Controls the visibility of Sites I'm Following in the sites list. 2.9 2.9
Updates
Interval updatesPollingInterval # (in minutes).
Possible values: 15, 30, 60, -1
Sets the time in minutes to check for new updates and changes to Sites and Favorites.
Set to -1 for manual check upon refreshing those views.
2.3 2.3
Disable 30 days Cleanup updatesCleanup true to enable 30 day cleanup of old updates,
or
false to disable 30 day cleanup.
Controls the option to automatically perform a cleanup for old updates after 30 days. 2.3 2.3
Enable Yammer showYammerFeed true to enable Yammer,
or
false to disable Yammer.
Controls the availability of Yammer integration. 2.3 2.3
Default Feed defaultYammerFeed following to show the conversations involving people, groups or topics that you are following,
or
all to show all the conversations in your network.
If Yammer is enabled, this option controls the Yammer conversations you want shown. 2.3 2.3
Locations
Locations historyAmount # (number of items).
Possible values: between 2 and 20
Controls the number of last visited locations that are shown under Locations > History. 2.3 2.3
Sites and Favorites shareLocations true to share locations, or
false to not share locations.
Controls the ability to share sites and favorite locations across harmon.ie clients. 2.3 2.3
Navigation
Default View useDefaultView true to use the default SharePoint view,
or
false not to use the default SharePoint view.
Controls whether the default SharePoint view is used when browsing to a Document Library. 2.3 2.3
Action On Tap actionOnTap Details to open the Document Info,
or
Open, to open the document.
Controls the default action taken when tapping a document. 3.1 2.9.6
Default App View defaultAppView Remember to open the app in the last view,
or
Sites, Updates, People, or Locations to select a specific app view.
Controls in which view harmon.ie opens when launched. 3.1 2.9.6
Passcode Lock
Use Passcode usePasscode true to use a passcode, or
false to not use a passcode.
Controls the ability to use a 4-digit passcode to lock the app. 2.3 2.3
Connection
Validate validateSSLCertificate true to validate the SSL certificate,
or
false to not validate the SSL certificate.
Controls whether the SSL certificate is validated when connecting to a SharePoint site. 2.3 2.3
Proxy Settings proxyType system to use the system’s proxy settings,
or
manual to manually enter the proxy settings,
or
none to use a direct connection.
Controls the type of proxy settings to use when connecting to a SharePoint site.   2.3
Host proxyHost The host URL of the proxy server. The URL of the proxy server used for network connections.   2.3
Port proxyPort The port number of the proxy server. The port number used to connect to the proxy server.   2.3
Default Timeout (seconds) connectionTimeout Number of seconds. The number of seconds until connection with the server times out.
Minimum: 20
Maximum: 600
2.7 2.9
Protocol Discovery useOfficeProtocolDiscovery true to use protocol discovery, or
false not to use protocol discovery.
If adding an Office 365 server using browser authentication fails, try setting this key to false. Obsolete from 3.8 2.3
Preferred Office 365 Protocol office365Protocol idcrl (default), or
sts, or
Sts Discovery.
Sets the protocol to connect to Office 365 SharePoint sites. If you fail to connect to an Office 365 server, try setting this key to sts, or Sts Discovery.
Note: If you set this key to Sts, you must also set the office365STSURL key.
3.8  
Logs
General logGeneral true to write general issues to the app log files,
or
false to not write general issues.
Controls whether the log file sent via the "Send Logs to Support" button will include general issues. 2.3 2.3
Network logNetwork true to write connectivity issues to the app log files,
or
false to not write connectivity issues.
Controls whether the log file sent via the "Send Logs to Support" button will include connectivity issues. 2.3 2.3
User Interface logUI true to write app UI issues to the app log files,
or
false to not write app UI issues.
Controls whether the log file sent via the "Send Logs to Support" button will include app UI issues. 2.3 2.3
Language
Select Language language "en" for English, or
"fr" for French, or
"de" for German, or
"" to match the device's language.
Controls the app language. 3.1 3.5
Offline
Add Favorite defaultOfflineFavoriteAction ask to ask if the favorite document should be saved offline,
or
always to always save the favorite document offline,
or
never to not ask if the favorite document should be saved offline.
Controls if the document is to be available offline after you add it to your favorites. 2.3 2.3
Document Size (MB) maxOfflineDocumentSize Entered value (in Megabytes).
Possible values: between 5 and 200 (steps of 5).
Controls if a warning is shown in case the document size (in megabytes) exceeds the specified size when saving an offline copy. 2.3 2.3
Only on Wi-Fi updateOfflineOnlyOnWifi true to update offline copies over Wi-Fi only,
or
false to update offline copies at any time.
Controls if the offline copies are only updated when connected to a Wi-Fi network. 2.3 2.3
Update On updateOfflineOn details to automatically update a document’s offline copy when viewing its details,
or
open to automatically update a document’s offline copy when the document is opened.
Controls whether to automatically update a document's offline copy when viewing its details or only when the document is opened for reading/editing. 2.3 2.3
Update Interval updateOfflineInterval 1440 to update offline copies daily,
60 to update offline copies hourly,
-1 to never update offline copies.
Controls how often (in minutes) harmon.ie updates all offline copies.
Set to -1 to allow only manual update of offline copies via the "Update Offline Copy" action.
2.3 2.3
Connectivity Interval deleteOfflineConnectivityInterval Entered value (in days).
Possible values: 1, 5, 15, 30, -1
Sets the number of days of no site connectivity before a site's offline copies are automatically deleted.
Set to -1 to never automatically delete offline copies.
2.3 2.3
Advanced
Cache Expiration (minutes) spCacheTimeout Entered value (in minutes).
Possible values: between 0 and 180 (steps of 5).
Controls the time interval (in minutes) between fetching the information from SharePoint (the amount of time items are saved in cache). 2.3 2.3
Cache Size (MB) spCacheMaxSize Entered value (in Megabytes).
Possible values: between 0 and 20 (steps of 1).
Controls the amount of memory (in megabytes) that is allocated for displaying items. 2.3 2.3
Client Page Size clientPageSize Entered value (number of items).
Possible values: between 20 and 200 (steps of 10).
Controls the number of items to render per page. 2.3 2.3
Server Page Size serverPageSize Entered value (number of items).
Possible values: between 50 and 1000 (steps of 50).
Controls the number of items to retrieve per request. 2.3 2.3
Memory Items Limit listItemsLimit Entered value (number of items).
Possible values: between 1000 and 20000 (steps of 1000).
Controls the maximum number of items to retrieve for the server. 2.3 2.3
Yammer Domain mappingYammerDomain Yammer email domain.
"MyEmailDomain.com"
The Yammer domain is the text to the right of the "@" in the Yammer email address.
Used together with "Company Domain" in case Yammer and company email domains are different.
2.3 2.3
Company Domain mappingCompanyDomain Company email domain.
"MyEmailDomain.com"
The Company domain is the text to the right of the "@" in your Company email address.
Used together with "Yammer Domain" in case Yammer and company email domains are different.
2.3 2.3

Hidden Settings

The objects below are not displayed to users in the harmon.ie app interface. These objects are nested under the settings objects.

NAME VALUE DESCRIPTION FROM VER (iOS) FROM VER (Android)
SharePoint sites
authModes An array of the required authentication modes.
The optional modes are:
auto
sso
browse
Sets the authentication modes for add/edit sites, in the order in which they should appear. The first mode is set as the default for adding a new site. See also the per-site authMode key.
Example:
"authModes": {"value": ["browse", "auto" ]}
2.6 2.6
enableDNSLookup true to show the SharePoint Site Lookup section on the app start page,
or
false to hide the SharePoint Site Lookup section.
Controls if users will be able to use the lookup feature to dynamically retrieve SharePoint URL. 2.3 2.3
hideInaccessibleSites true to hide inaccessible sub-sites,
or
false to show inaccessible sub-sites.
Controls the visibility of sub-sites with limited or no access. 2.3 2.3
hideSocialFromNavigation true to hide the social server from navigation, or
false to show it.
Controls the visibility of the social server in the Sites view. 3.5 2.9.6
personalSite Personal site name (string).
Default: OneDrive
Name to replace all occurrences of OneDrive in harmon.ie. 2.3 2.3
showOffice365Groups true to show group documents, or
false not to show.
Controls showing documents from Office 365 groups of the social server in the sidebar's Sites view. 3.7  
office365App {clientId: <app ID>,
redirectUri: <redirect URI>,
server: <server URL>}
Used to connect with the native app registered with Azure. Set to the registered app parameters. For more information, read Enable Office 365 Groups. 3.7  
Documents
enableOfficeApps true (default) to show Office Apps in the Open menu,
or
false, to hide Office Apps.
Controls the visibility of Office Apps in harmon.ie's Open menu. 2.3 2.3
enableOpenIn true to enable opening documents in external applications (default),
or
false to disable.
Controls whether documents can be opened in external applications, such as Docs2Go, or only in internal viewers and apps (Open > Quick Look, Open PDF or Office Online). 2.9 2.9
supportPreview true to enable preview mode (default),
or
false to disable.
Controls whether to show a document preview, when selecting a document. iPad only. 3.2  
maxPreviewMemorySizeMB # in MB. Default is 30. Sets the maximum document size, in MB, for which to show a document preview. iPad only. 3.2  
tilesMaxItems #. Default is 800. Sets the number of items that can be displayed when in Tiles view. The value must be a number between 100 and 1500, in multiples of 100 (e.g. 100, 200, 300, etc). 3.8  
manualLoadMetadata true to show the Load Properties button on the Document Info page,
or
false to show the document properties.
Controls if the document properties are displayed, or if the Load Properties button is shown. 2.3 2.3
hiddenLibraries An array of libraries and lists to hide. Example:
"hiddenLibraries": {"value": ["Site Assets","harmon.ie Mobile Users","Customized Reports","Form Templates","Style Library"]}
2.5 2.5
Email
sendLinkAllowed true to allow users to send a document as a link,
or
false to not allow sending document as a link.
Controls if users are allowed to send a document as a link. 2.3 2.3
enableSendingAttachments true to enable sending documents as attachments (default),
or
false to disable.
Controls the availability of the Send Email > Send as Attachment option for sending documents in email. If set to false, documents can only be sent as links. 2.9 2.9.6
Upload
maxItemsToUpload # Sets the maximum number of images that can be uploaded using the Camera action, or from the Photos app in iOS, in a single upload operation. The default value is 20. 3.2 3.5
Yammer
YammerOauthUrl https://www.yammer.com/dialog/oauth?client_id={0}&redirect_uri={1}&response_type=token
Where {0} should be replaced with the Client ID, and {1} with the Redirect URI.
Sets your own Yammer app ID, if third party applications are blocked in your organization. Read Configure Yammer integration with harmon.ie for more information. 2.8 2.9
Offline
enableOffline true to enable all offline features (default),
or
false to disable.
Controls whether offline features are available in harmon.ie or not. If set to false, uploading multiple images to harmon.ie is disabled as well. 2.9 2.9
General
emailAdmin Default: None. Controls the email address that appears in the To field of the email when users tap the Contact Administrator button in error messages. 2.3 2.3
emailSupport Default: support@harmon.ie Controls the email address that appears in the To field of the email when users tap the Contact Support button in error messages. 2.3 2.3
splashUrl The URL of the splash screen.

Sets another splash screen to display when harmon.ie starts. Add a harmonieVersion query string to be able to update the page (if the version changes, the page is updated in the app when you provision the same URL).

Example: "splashUrl": {"value": "http://mydomain.com/Sample_Splash.html?harmonieVersion=1"}
Read Replace harmon.ie's splash screen for more information.
3.1  
silentProvisioning true for silent provisioning of harmon.ie, or
false for provisioning with prompts (default).
Allows silent provisioning of harmon.ie, when working with server provisioning or MDM provisioning. To cancel a previously-configured silent provisioning, set this key to false. 3.8  
office365STSURL <STS Url>. Set this key to the STS URL if you set office365Protocol to sts. Example: https://login.microsoftonline.com/extSTS.srf. 3.8  
useHarmonieUserAgent true to use harmoln.ie as the User-Agent value, or
false to use Mozilla (default).
Set this key to true if Mozilla should not be used as the User-Agent value in harmon.ie's internal browser. 3.8  

Forcing values for users

To force a value for the users, and disable the ability to change it in the harmon.ie application on their device, define the "force": true value.

Note: By default, the force value for each object is set to false.