EMS Mobile App Configuration Guide EMSMobile

User Manual:

Open the PDF directly: View PDF .
Page Count: 87

Download
Open PDF In Browser	View PDF

EMS MOBILE APP
Configuration Guide
V44.1

Last Updated: March 5, 2018

EMS Software | emssoftware.com/help | 800.440.3994 | © 2018 EMS Software, LLC. All Rights Reserved.

Table of Contents
CHAPTER 1: Introduction to the EMS Mobile App Configuration Guide

System Requirements for EMS Mobile App

EMS Mobile or EMS Mobile Web App: What's the Difference?

EMS Mobile App = EMS Application for Mobile Devices

Features of EMS Mobile App That Are Not in EMS Web App

EMS Mobile App = EMS Web App on a Mobile Browser

Features of EMS Web App That are Not in EMS Mobile App

How Do I Install It?

How Do I Use It?

CHAPTER 2: Add Mobile Users
CHAPTER 3: Deploy EMS Mobile App

Public Deployment: Public App Store

Private Deployment: Private App Store

CHAPTER 4: Change EMS Mobile App Logo (Private Deployment Only)

CHAPTER 5: Configure and Re-Sign the EMS Mobile App (Private Deployment
Only)

Use Unsigned Builds

Set Custom Configuration

Re-Sign and Repackage for iOS

1. Install Fastlane

2. Install Certificate and Provisioning Profile

Provisioning Profile

Re-Sign and Repackage for Android

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private Deployment Only)

Find the config.json File

Set the API URL

Configure Authentication

Supported Authentication Configurations

Properties for the openID Section

Properties for the SAML Section

Custom URL only

Open ID with Discovery URL

Open ID Without Discovery URL

SAML With Default API SAML Endpoint

SAML with Specific API SAML Endpoint

Change Logging Location

CHAPTER 7: Assign Templates to EMS Mobile Users

CHAPTER 8: Restrict Users' Mobile App Versions

Determine EMS Mobile API and Version Compatibility

CHAPTER 9: Change the Help Link Label and URL

CHAPTER 10: Configure EMS Mobile QR Codes

CHAPTER 11: How Do I Know When To Upgrade the Mobile App and API?

Determine EMS Mobile API and Mobile App Version Compatibility

CHAPTER 12: Set EMS Mobile Parameters

CHAPTER 1: Introduction to the EMS Mobile App Configuration Guide

CHAPTER 1: Introduction to the
EMS Mobile App Configuration
Guide
EMS Mobile App, available on iOS and Android smartphones, is designed
primarily for everyday users "on the go." It allows users to make simple reservations in unmanaged spaces (i.e., spaces without services and approvals),
such as workspaces and open conference rooms.
EMS Mobile App enables easy booking and scheduling on-the-go for mobile
devices by enabling you to manage space on mobile devices, such as tablets
and smartphones. Simple touchscreen gestures on mobile devices allow you to
scan QR codes for rooms and to cancel, end, or check in to meetings.

SYSTEM REQUIREMENTS FOR EMS MOBILE APP
The EMS Mobile App—which includes the EMS Platform Services—has specific
requirements on top of the general EMS server and database requirements.

EMS Software © 2018 / V44.1 / Page 1

CHAPTER 1: Introduction to the EMS Mobile App Configuration Guide

Note: You must upgrade to EMS V44.1 (released June 30, 2016) to have the
EMS Mobile App. It is not available for earlier versions of EMS.

Supported Platforms

Android 4.4, 5.0, 6.0

iOS 9.x, 10.x, 11.x

To host and install EMS Mobile App, you will need the following:
EMS database server, web server and Platform Services (see Requirements)
Mobile phone(s)

EMS Software © 2018 / V44.1 / Page 2

CHAPTER 1: Introduction to the EMS Mobile App Configuration Guide

EMS MOBILE OR EMS MOBILE WEB APP: WHAT'S
THE DIFFERENCE?
Although their names are similar and they share the same databases, these
products have very different applications.
EMS MOBILE APP = EMS APPLICATION FOR MOBILE DEVICES
This is a separate software application EMS produces specifically to run on
mobile devices such as smartphones.

FEATURES OF EMS MOBILE APP THAT ARE NOT IN
EMS WEB APP
Ultra-compact display designed for smartphones
Two factor authentication method
QR Code functionality

EMS MOBILE APP = EMS WEB APP ON A MOBILE BROWSER
This is the EMS Web App as it displays when running on a web browser on a
mobile device, such as a tablet.

EMS Software © 2018 / V44.1 / Page 3

CHAPTER 1: Introduction to the EMS Mobile App Configuration Guide

FEATURES OF EMS WEB APP THAT ARE NOT IN
EMS MOBILE APP
Browse Events
Browse People
Act As (delegation feature)
Edit Account Details
Edit Delegates
Edit Everyday User Process templates

HOW DO I INSTALL IT?
If your organization has EMS Web Users licensing, no additional license
for EMS Mobile App is required. Your administrator will need to:

1. Download the installation files from the EMS Customer Portal.
2. Install EMS Platform Services and connect to your organization's web server.
3. Set up user authentication.
4. Once these components are in place, users at your organization can add EMS
Mobile App to their mobile devices (as a private or public deployment) and enter
your server URL and (optional) credentials to authenticate.

EMS Software © 2018 / V44.1 / Page 4

CHAPTER 1: Introduction to the EMS Mobile App Configuration Guide

HOW DO I USE IT?
Once you've logged in, you can follow the tips below to interact with your calendar and see your events. Your calendar shows only current and upcoming
events.

EMS Software © 2018 / V44.1 / Page 5

CHAPTER 2: Add Mobile Users

CHAPTER 2: Add Mobile Users
EMS Mobile App users are added as "Everyday Users" in EMS Desktop Client.
Follow the steps below to create this type of user.

NOTE: This section guides you in configuring one Everyday User at a time.
Once you have configured these users, you may need to assign them
to security templates and one or more process templates.
To assign users to Everyday User process templates, see Assign Templates to Everyday Users.
To assign multiple templates to multiple users in a single step,
see Assign Security Templates to Multiple Everyday Users.

TIP: You configure EMS Desktop Client user accounts in a different area
(under the SYSTEM ADMINISTRATION > SECURITY menu). For
instructions, see Configure EMS Desktop Client Users.
Additionally, if your organization uses EMS Human Resources Toolkit to manage Everyday User accounts, see EMS Human Resources Toolkit.

EMS Software © 2018 / V44.1 / Page 6

CHAPTER 2: Add Mobile Users

Lastly, a set of Account Management parameters control account management behavior. To view these parameters, see EMS Web App
Parameters.

Concept: EMS classifies users into two categories—Guests or Visitors and Everyday
Users. Click for more...

"Guests" or "Visitors" (unauthenticated or anonymous users) can browse
events, see details about your organization’s space, and/or submit requests.
These users can register themselves through EMS Web App and create a user
account. To enable this, you need to set certain account management parameters (see EMS Web App System Parameters) and select the Credit\Edit an
Account role for the unauthenticated user (see the Roles tab definition
in Configuring a Security Template).
"Guests" or "Visitors" (authenticated users) may also submit and manage reservations if you enable them.
You can configure these users through the EMS Desktop Client or the optional
Integrated Authentication module.

EMS Software © 2018 / V44.1 / Page 7

CHAPTER 2: Add Mobile Users

See Also: Configuring Additional Information for a Group and Configuring

Contacts. Before you configure a user, check that the user has not already been
created.
Everyday User process templates control access and behavior in EMS
Software's Everyday User Applications. If you are upgrading from an older
release of EMS, you may recognize Everyday Users as "Web Users" and
"Everyday User Process Templates" as "Web Process Templates."

1. On the EMS Desktop Client menu bar, click Configuration > Everyday User Applications > Everyday Users. The Everyday Users window opens. The number of configured users for EMS Web App shows in the upper left corner. The number of
users for which your organization is licensed shows in the top center.

EMS Software © 2018 / V44.1 / Page 8

CHAPTER 2: Add Mobile Users

2. Check that the user you wish to configure does not already exist. Enter the user
name or email address in the Find field.

TIP: This search string is not case-sensitive, but your entries must be in
the correct order. For example, if searching by Email Address, a search

EMS Software © 2018 / V44.1 / Page 9

CHAPTER 2: Add Mobile Users

string of bob returns bobworth@emssoftware.com but
not dbobbett@emssoftware.com.

You can narrow your search results by:
Group Type
City
Status
Process Template

Then Click Display . Search results show in the lower pane of the window. If your user does not already exist in EMS, proceed to the next step.

NOTE: If the EMS system parameter USERS LINKED TO GROUPS
VIA EXTERNAL REFERENCE is set to YES, then you will also see a
Group column and a City column.

EMS Software © 2018 / V44.1 / Page 10

CHAPTER 2: Add Mobile Users

3. Create a new user. Click the New button. A dialog box opens.

NOTE: If the user has confirmed membership (by responding to an
email containing an activation link), the VALIDATED checkbox highlighted below will be selected. If the user had to answer questions when
requesting an account, you can view the user's responses on the USER
DEFINED FIELDS tab.

EMS Software © 2018 / V44.1 / Page 11

CHAPTER 2: Add Mobile Users

TIP: When you configure a user, you can also specify one or more delegates for the user. A delegate is a user who can create and view reservations on behalf of another user.

EMS Software © 2018 / V44.1 / Page 12

CHAPTER 2: Add Mobile Users

4. Enter information for the new user. User name and email address are required;
password is only required if not using the optional Integrated Authentication module. All other information is optional and can be added later as needed.

The name of the user. (Maximum of 30 characters,
including spaces).

The password that the user must enter to log in to EMS
Web App. If using the optional Integrated Authentication
module, Password can be left blank since the network
password is used instead.

Enter the full email address for the user as the user must
enter this address to log in to EMS Web App.

Optional fields.

Optional field. Read-only.

EMS Software © 2018 / V44.1 / Page 13

CHAPTER 2: Add Mobile Users

External Refer-

Optional field. Links the user to an outside program such

as EMS Human Resources Toolkit if needed.

The user’s network ID.

Optional field. Select this option if you do not want the
user to receive automatic emails (such as reservation
summary emails) from EMS Web App. The user can still
receive manually sent emails.

Required field. Select the status for the user:
Active—The user can log in to EMS Web App, EMS
Mobile App, and EMS for Outlook.
Pending—The user cannot log in to EMS Web App, EMS
Mobile App, and EMS for Outlook and is informed that
he/she must check back at a later time.
Inactive—The user cannot log in to EMS Web App, EMS
Mobile App, and EMS for Outlook and is instructed to contact the EMS administrator.

EMS Software © 2018 / V44.1 / Page 14

CHAPTER 2: Add Mobile Users

Required field. This determines the user's access to the

system (i.e., the menu items the user can see and the
event information that the user can view).

Optional field. The time zone in which the user is located.
Beginning in version 44.1, it is strongly recommended
that users are assigned to a time zone for an optimal
experience on all Everyday User Applications.

When checked, users who created their own accounts
have confirmed membership (by responding to a email
containing an activation link). When unchecked, the user
will not be able to use EMS Web App.

5. Assign process templates to the new user. Open the Process Templates tab.
The process templates you assign here will appear as menu items to the user in
EMS Web App, EMS Mobile App, and EMS for Outlook.
6. Specify Groups on whose behalf the user can create and manage
reservations. Open the Groups tab. To filter the list of active groups displayed, use
the Find and Type fields and then click Display. Select one or more Groups (use

EMS Software © 2018 / V44.1 / Page 15

CHAPTER 2: Add Mobile Users

CTRL-click for multiple groups), and then click Move (>) to move the selected
groups to the Selected list.
7. Specify Delegates the user can impersonate. Open the Delegates tab; to see all
available users, click Display. To narrow the search results, use the Search
by dropdown list to search by User Name or Email Address. Select one or more
delegates (using CTRL-click for multiple delegates), and then click Move (>) to
move the selected users to the Selected list.

TIP: Click SPELLING to spell-check any information that you manually
entered for the user.

8. Click OK. The dialog box closes and returns you to the users window with the
newly configured user automatically selected.

EMS Software © 2018 / V44.1 / Page 16

CHAPTER 3: Deploy EMS Mobile App

CHAPTER 3: Deploy EMS Mobile
App
There are two ways to deploy the EMS Mobile App App for your users:

1. The standard public app store offered by Apple and Google. See Public Deployment: Public App Store.
2. A private enterprise app store. (This approach can also be integrated with your
company's Mobile Device Management system.) See Private Deployment: Private
App Store.

WARNING: It is important to understand the compatibility between the EMS
Mobile App and EMS Platform Services. The EMS Mobile App needs to be on
the same version or higher as EMS Platform Services. For example, the EMS
Mobile App Update 20 version will be compatible with EMS Platform Services
Update 19 or older. However, compatibility issues will exist if you try to install
EMS Platform Services Update 20 with an older version of the EMS Mobile
App (Update 19 or older).

EMS Software © 2018 / V44.1 / Page 17

CHAPTER 3: Deploy EMS Mobile App

PUBLIC DEPLOYMENT: PUBLIC APP STORE
To deploy via the public app store, direct your users to go to the Google
Play and Apple app stores on their mobile devices. They will be able to download the app by clicking on the link. However, they will have to manually input
the EMS Mobile API URL. They will receive a prompt to do so the first time they
open the EMS Mobile App.
If users need to change the API URL at a later date, they can:

EMS Software © 2018 / V44.1 / Page 18

CHAPTER 3: Deploy EMS Mobile App

1. Open the app, and then click About in the lower right corner.

EMS Software © 2018 / V44.1 / Page 19

CHAPTER 3: Deploy EMS Mobile App

2. Click to change the API URL.

EMS Software © 2018 / V44.1 / Page 20

CHAPTER 3: Deploy EMS Mobile App

3. Enter the API URL you provide and connect.

While this approach may be easier for your IT staff, it has definite costs:
Users will have to input the EMS Mobile App API URL on their own.
EMS will frequently deploy mobile app updates to the app store. Most users will
have this app set to automatically update, and will therefore receive updates even
if you have not yet upgraded your EMS Mobile API.

EMS Software © 2018 / V44.1 / Page 21

CHAPTER 3: Deploy EMS Mobile App

While we aim to make the Mobile API backwards- and forwards- compatible within
major updates, we may not do so all the time.
Deploying via the public app store therefore requires you to make major updates to
the EMS Mobile API as soon as they are available.

PRIVATE DEPLOYMENT: PRIVATE APP STORE
To deploy via a private enterprise app store, first download the unsigned
apk/ipa files from your EMS software portal. You then have to resign the app
and deploy it via your MDM system. This site offers some guidance on how to
sign an unsigned ipa file (i.e. for iOS), while this site does the same for Android
apk files. Deploying via a private app store allows you to control which version
of the Mobile App your users have.
As an example, here are the key steps to resign and deploy the unsigned EMS
Mobile App ipa file (following instructions provided here):

1. Download unsigned builds: .ipa and .apk files
Optional: Customizing Your Mobile App Configuration Using config.json
(Private Deployment Only), change logo

EMS Software © 2018 / V44.1 / Page 22

CHAPTER 3: Deploy EMS Mobile App

2. Configuring and Re-Signing the EMS Mobile App (Private Deployment Only)
Change the EMS Mobile App Logo (Private Deployment Only) (if using
MDM)

EMS Software © 2018 / V44.1 / Page 23

CHAPTER 4: Change EMS Mobile App Logo (Private Deployment Only)

CHAPTER 4: Change EMS
Mobile App Logo (Private Deployment Only)
For customers re-signing the application, we provide unsigned builds.

1. Store your unsigned EMS Mobile App in a new or empty directory.
2. Change the extension of the app to .zip. (e.g., IPhone.App-44.1.xxx-unsigned.ipa > IPhone.App-44.1.xxx-unsigned.zip.)
3. Un-compress/expand the new zip file.
4. To set a custom logo, replace the following logo files:

IOS
1. Rezip all of the extracted files from earlier.
2. Give the new zip file an ipa extension.
3. Using a Mac computer, install fastlane.
sudo gem install fastlane
4. Do the rest of this on the Mac.
5. Login to https://developer.apple.com and switch to team "Your Team Name."
6. Download your teams Distribution provisioning profile.

EMS Software © 2018 / V44.1 / Page 24

CHAPTER 4: Change EMS Mobile App Logo (Private Deployment Only)

7. Double click it to install it. This file should exist on your system:
~/Library/MobileDevice/Provisioning Profiles/.mobileprovision
8. Get your team's existing .p12 file with the cert and private key combined, and then
import that into Keychain (by double-clicking it) and then entering the password.
When the cert is installed successfully you should see iPhone Distribution:
in your Keychain, with a private key.
9. Assuming you have:
fastlane installed on your Mac
the cert & private key installed in Keychain
the provisioning profile mentioned above in: ~/Library....mobileprovision
10. Resign your target ipa with this command:

fastlane run resign \
ipa:path/to/your/file.ipa \
signing_identity:"iPhone Distribution: " \
provisioning_profile:$HOME/Library/MobileDevice/Provisioning Profiles/.mobileprovision \

EMS Software © 2018 / V44.1 / Page 25

CHAPTER 4: Change EMS Mobile App Logo (Private Deployment Only)

display_name:EMS-Resigned
11. If you want a bash script that will do this, you can copy this into a file (e.g., resign_
enterprise.sh):

#!/bin/bash
IPA=relative/path/to/file.ipa
IDENTITY="iPhone Distribution: "
PROFILE=$HOME/Library/MobileDevice/Provisioning Profiles/.mobileprovision
DISPLAY_NAME=EMS-Resigned
fastlane run resign ipa:"$IPA" signing_identity:"$IDENTITY" provisioning_
profile:"$PROFILE" display_name:$DISPLAY_NAME

ANDROID
1. Rezip all the extracted files from earlier.
Note that assets, res, and AndroidManifest.xml are top-level files in an .apk,
so be careful to zip the right things up.

EMS Software © 2018 / V44.1 / Page 26

CHAPTER 4: Change EMS Mobile App Logo (Private Deployment Only)

This CLI command will zip all the files in the current directory into a new zip
file in the parent directory:

zip -qr ../ems-custom-44.1.xxx.zip ./*
2. Give the new zip file an apk extension (e.g., myapp.zip -> myapp.apk).
3. Sign the new apk file.

This is the script we use to sign our app, adjust for your needs:
#!/bin/bash
APK_TO_SIGN=$1
APK_OUTPUT=$2
EMS_APK_KEYSTORE_PATH=path/to/your/app.keystore

jarsigner -verbose \
-sigalg $EMS_APK_SIG_ALG \
-digestalg $EMS_APK_DIGEST_ALG \
-storepass $EMS_APK_KEYSTORE_PASS \

EMS Software © 2018 / V44.1 / Page 27

CHAPTER 4: Change EMS Mobile App Logo (Private Deployment Only)

-keystore $EMS_APK_KEYSTORE_PATH \
$APK_TO_SIGN $EMS_APK_ALIAS_NAME

zipalign 4 $APK_TO_SIGN $APK_OUTPUT

Note: We recommend that you use an image with a 3:1 aspect ratio in order to
ensure that the image will be be properly rendered by the application.

EMS Software © 2018 / V44.1 / Page 28

CHAPTER 5: Configure and Re-Sign the EMS Mobile App (Private Deployment Only)

CHAPTER 5: Configure and ReSign the EMS Mobile App (Private Deployment Only)
This topic provides information on the following:
Use Unsigned Builds
Set Custom Configuration
IOS
Android
Re-Sign and Repackage for iOS
1. Install Fastlane
2. Install Certificate and Provisioning Profile
3. Re-Sign
Re-Sign and Repackage for Android

USE UNSIGNED BUILDS
For customers re-signing the application, we provide unsigned builds.

EMS Software © 2018 / V44.1 / Page 29

CHAPTER 5: Configure and Re-Sign the EMS Mobile App (Private Deployment Only)

1. Store your unsigned EMS Mobile App in a new or empty directory.
2. Change the extension of the app to .zip. (e.g., IPhone.App-44.1.xxx-unsigned.ipa > IPhone.App-44.1.xxx-unsigned.zip.)
3. Un-compress/expand the new zip file.

SET CUSTOM CONFIGURATION
1. Refer to Customize Your Mobile App Configuration Using config.json (Private
Deployment Only) for details on building a configuration file for EMS Mobile.
2. Replace the config.json file with your custom configuration (located as follows):

IOS
config.json (top-level file)

ANDROID
assets/config.json

RE-SIGN AND REPACKAGE FOR IOS
Follow the steps below to re-sign and repackage for iOS.

EMS Software © 2018 / V44.1 / Page 30

CHAPTER 5: Configure and Re-Sign the EMS Mobile App (Private Deployment Only)

1. INSTALL FASTLANE
Using sudo gem, install fastlane on an administrative Apple computer.

2. INSTALL CERTIFICATE AND PROVISIONING PROFILE
If your Apple computer is already configured with these items, these steps may
not be necessary.
PROVISIONING PROFILE
1. Login to https://developer.apple.com
2. Download your Distribution provisioning profile
3. Double click it to install it. This file should exist on your system:
~/Library/MobileDevice/Provisioning Profiles/.mobileprovision

CERTIFICATE
See Apple's documentation for installing and managing certificates and signing
identities. When the certificate is installed successfully, you should see iPhone
Distribution: Your Company, Inc in your Keychain, with a private key.

3. RE-SIGN
Assuming you have:

EMS Software © 2018 / V44.1 / Page 31

CHAPTER 5: Configure and Re-Sign the EMS Mobile App (Private Deployment Only)

Fastlane installed on your Apple computer
the cert and private key installed in Keychain
the provisioning profile mentioned above in ~/Library/.../.mobileprovision

...then you should be ready to re-sign the application. Before you proceed,
change the following in the command below:
Replace path/to/your/file.ipa with the real path to the ipa file
Replace iPhone Distribution: Your Company, Inc with the appropriate signing identity on your machine
Replace with the actual GUID or name of the provisioning profile you
intend to use
Replace EMS-Resigned with the display name you wish to use, or remove the parameter if you do not wish to rename the application

NOTE: Running these commands will OVERWRITE the ipa file you designate. Make a copy first if necessary.

fastlane run resign \
ipa:path/to/your/file.ipa \
signing_identity:"iPhone Distribution: Your Company, Inc" \
provisioning_profile:$HOME/Library/MobileDevice/Provisioning

EMS Software © 2018 / V44.1 / Page 32

CHAPTER 5: Configure and Re-Sign the EMS Mobile App (Private Deployment Only)

Profiles/.mobileprovision \
display_name:EMS-Resigned

(All on one line for copy/paste:)

fastlane run resign ipa:path/to/your/file.ipa signing_identity:"iPhone
Distribution: Your Company, Inc" provisioning_profile:$HOME/Library/MobileDevice/Provisioning Profiles/.mobileprovision display_name:EMS-Resigned

If you want a bash script that will do this, you can copy this into a file (e.g.,
resign_enterprise.sh):

IPA=relative/path/to/file.ipa
IDENTITY="iPhone Distribution: Your Company, Inc"
PROFILE=$HOME/Library/MobileDevice/Provisioning\ Profiles/.mobileprovision
DISPLAY_NAME=EMS-Resigned

fastlane run resign ipa:"$IPA" signing_identity:"$IDENTITY"

EMS Software © 2018 / V44.1 / Page 33

CHAPTER 5: Configure and Re-Sign the EMS Mobile App (Private Deployment Only)

provisioning_profile:"$PROFILE" display_name:$DISPLAY_NAME

RE-SIGN AND REPACKAGE FOR ANDROID
Re-zip all the extracted files from earlier
Note that assets, res, and AndroidManifest.xml are top-level files in an .apk, so
be careful to zip the right files
This CLI command will zip all the files in the current directory into a new zip file
in the parent directory:
zip -qr ../ems-custom-44.1.xxx.zip ./*

Give the new zip file an .apk extension
e.g., myapp.zip -> myapp.apk
Sign the new .apk file, for example:

APK_TO_SIGN=$1
APK_OUTPUT=$2
EMS_APK_KEYSTORE_PATH=path/to/your/app.keystore

jarsigner -verbose \
-sigalg $EMS_APK_SIG_ALG \

EMS Software © 2018 / V44.1 / Page 34

CHAPTER 5: Configure and Re-Sign the EMS Mobile App (Private Deployment Only)

-digestalg $EMS_APK_DIGEST_ALG \
-storepass $EMS_APK_KEYSTORE_PASS \
-keystore $EMS_APK_KEYSTORE_PATH \
$APK_TO_SIGN $EMS_APK_ALIAS_NAME

zipalign 4 $APK_TO_SIGN $APK_OUTPUT

EMS Software © 2018 / V44.1 / Page 35

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

CHAPTER 6: Customize Your
Mobile App Configuration Using
config.json (Private Deployment
Only)
EMS Mobile App ships with a config.json file that you can use to customize
EMS Mobile App before re-signing and distributing in your app store or similar
as follows:
Set the API URL so users do not have to type it in on their own.
Configure Authentication.

FIND THE CONFIG.JSON FILE
After unzipping the respective app files, the paths to the file for each OS are:

IOS
config.json (top-level file)

EMS Software © 2018 / V44.1 / Page 36

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

ANDROID
assets/config.json

The file looks like the example below (subject to change, per development):
{
"api_doc": [
"Configure the API here"
],
"api": {

"url_doc": [
"The API EMS Mobile App should connect to"
],
"url": ""
}
}

SET THE API URL
1. Open the config.json file in a text editor.
2. In the API section, find the URL property.

EMS Software © 2018 / V44.1 / Page 37

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

3. Set the URL property to your desired value (e.g., https://yourcompany.com/emsplatform-api).

CONFIGURE AUTHENTICATION
EMS Mobile App does not ship with an authentication configuration section by
default, but you can add it as follows.

NOTE: If you are adding authentication configuration, IT IS ALSO
NECESSARY TO SET THE API URL.

Below is an example (the ..._doc entries are omitted for brevity):
{
"api": {
"url": "https://yourcompany.com/ems-platform-api"
},
"authentication": {
"activities": "openId",
"openID": {
"discoveryURL": "https://yourcompany.com/openid",
"authorizationURL": "",
"tokenURL": "",

EMS Software © 2018 / V44.1 / Page 38

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

"clientID": "abcdefxabQijQcJstY4nImWYL5y12345",
"redirectURL": "emssoftware://oauth-callback/x"
}
}
}

SUPPORTED AUTHENTICATION
CONFIGURATIONS
OPEN ID
"authentication": {
"activities": "openId",
"openID": {
"discoveryURL": "https://yourcompany.com/openid",
"authorizationURL": "",
"tokenURL": "",
"clientID": "abcdefxabQijQcJstY4nImWYL5y12345",
"redirectURL": "emssoftware://oauth-callback/x"
}
}

EMS Software © 2018 / V44.1 / Page 39

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

Set the activities to openId
Add an openID section next to activities

PROPERTIES FOR THE OPENID SECTION
discoveryURL
if your IdP provides it, this is the URL for EMS Mobile App to automatically configure its Open ID settings
if you provide this, leave authorizationURL and tokenURL empty
authorizationURL
this is the endpoint to send the initial Open ID authorization request
tokenURL
this is the endpoint to request an Open ID access token
clientID
the client ID for the EMS Mobile App as configurd in the IdP
redirectURL
leave this set to emssoftware://oauth-callback/x for EMS Mobile App
this is the URL the IdP will redirect to during the Open ID authentication flow

EMS Software © 2018 / V44.1 / Page 40

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

SAML
"authentication": {
"activities": "saml",
"saml": {
"url": "https://yourcompany.com/ems-platform...ntication/saml`
}
}
Set the activities to saml
Add a saml section next to activities

PROPERTIES FOR THE SAML SECTION
URL
this property is optional
you can manually specifiy the initial request URL for SAML authentication
this URL will be opened in a webview in EMS Mobile App
if you do not specify this property, EMS Mobile App will assume the default
SAML endpoint for the REST API
This is one reason you must specify the URL in the api section for custom
authentication configuration (e.g., if you set the custom API URL
to https://ems.example.com/api, then EMS Mobile App will

EMS Software © 2018 / V44.1 / Page 41

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

use https://ems.example.com/api/api/v1/a...ntication/saml as its initial
SAML url)

EXAMPLES
CUSTOM URL ONLY
{
"api": {
"url": "https://yourcompany.com/ems-platform-api"
}
}

EMS Software © 2018 / V44.1 / Page 42

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

OPEN ID WITH DISCOVERY URL
{
"api": {
"url": "https://yourcompany.com/ems-platform-api"
},
"authentication": {
"activities": "openId",
"openID": {
"discoveryURL": "https://yourcompany.com/openid/discovery",
"authorizationURL": "",
"tokenURL": "",
"clientID": "abcdefxabQijQcJstY4nImWYL5y12345",
"redirectURL": "emssoftware://oauth-callback/x"
}
}
}

EMS Software © 2018 / V44.1 / Page 43

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

OPEN ID WITHOUT DISCOVERY URL
{
"api": {
"url": "https://yourcompany.com/ems-platform-api"
},
"authentication": {
"activities": "openId",
"openID": {
"discoveryURL": "",
"authorizationURL": "https://yourcompany.com/openid/authorize",
"tokenURL": "https://yourcompany.com/openid/token",
"clientID": "abcdefxabQijQcJstY4nImWYL5y12345",
"redirectURL": "emssoftware://oauth-callback/x"
}
}
}

EMS Software © 2018 / V44.1 / Page 44

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

SAML WITH DEFAULT API SAML ENDPOINT
{
"api": {
"url": "https://yourcompany.com/ems-platform-api"
},
"authentication": {
"activities": "saml"
}
}

SAML WITH SPECIFIC API SAML ENDPOINT
{
"api": {
"url": "https://yourcompany.com/ems-platform-api"
},
"authentication": {
"activities": "saml",
"saml": {
"url": "https://ems.example.com/saml"
}
}
}

EMS Software © 2018 / V44.1 / Page 45

CHAPTER 6: Customize Your Mobile App Configuration Using config.json (Private

CHANGE LOGGING LOCATION
1. Modify the logFilePath attribute:

"logFilePath": ".\\LogFiles\\api.log"

EMS Software © 2018 / V44.1 / Page 46

CHAPTER 7: Assign Templates to EMS Mobile Users

CHAPTER 7: Assign Templates
to EMS Mobile Users
EMS V44.1 allows you to select which process templates (e.g "web process
templates") will be enabled on your users' mobile devices. From the Admin
page for templates in the EMS Desktop Client, you will see an Enable for

Mobile checkbox on the first tab of the template dialog box:

EMS Software © 2018 / V44.1 / Page 47

CHAPTER 7: Assign Templates to EMS Mobile Users

NOTE: EMS Mobile App is designed to make and edit simple reservations for
users "on the go." At this time it cannot handle service requests, video conference bookings or complex workflows. Please consider this when you
decide which templates should be enabled for the EMS Mobile App. Additionally, you can only change the name and icon of the EMS Mobile App
through private deployment via MDM. Please refer to your MDM guide for

EMS Software © 2018 / V44.1 / Page 48

CHAPTER 7: Assign Templates to EMS Mobile Users

instructions on how to change the name and icon of the EMS Mobile App.

EMS Software © 2018 / V44.1 / Page 49

CHAPTER 8: Restrict Users' Mobile App Versions

CHAPTER 8: Restrict Users'
Mobile App Versions
Starting with the August 2016 release, EMS will ensure that EMS Mobile App is
both forwards- and backwards- compatible, so that the mobile app will still function even if users update it on their devices. Alternatively, if you update your API
but users do not update their app, functionality remains intact.
You may wish to force users to keep their installations up to date. For example,
you may want them to upgrade their EMS Mobile App after you upgrade the
API, or you may want to prevent them from updating their EMS Mobile App until
you upgrade the API. To enforce these restrictions, follow the steps below.

EMS Software © 2018 / V44.1 / Page 50

CHAPTER 8: Restrict Users' Mobile App Versions

1. Log in to the API admin page (previously configured here).
2. Click on Admin tab, and set the minimum and maximum app versions:

DETERMINE EMS MOBILE API AND VERSION
COMPATIBILITY
Use the matrix below to determine how you want to enforce user updates.

EMS Software © 2018 / V44.1 / Page 51

CHAPTER 8: Restrict Users' Mobile App Versions

MOBILE API
RELEASE

VERSION
VERSION

Update
1
V44.1
Update
2
V44.1
Update
3
V44.1
Update
4
V44.1

EMS Software © 2018 / V44.1 / Page 52

CHAPTER 8: Restrict Users' Mobile App Versions

MOBILE API
RELEASE

VERSION
VERSION

Update
6
V44.1
Update
7

TIP: The Minimum App Version means that users running EMS Mobile
App below the minimum will not be able to use EMS. Increasing this value
essentially forces users on an older version to upgrade. Maximum App Version prevents users from using EMS Mobile App if they run a version above
the max.

EMS Software © 2018 / V44.1 / Page 53

CHAPTER 9: Change the Help Link Label and URL

CHAPTER 9: Change the Help
Link Label and URL
To change the label for the Help link label, locate the Everyday User Applications parameter, Label for the Help Link on the mobile app , and enter a
new value.
To change the label for the Help link URL, locate the parameter, URL for the

Help Link on the mobile app , and enter a new URL.

EMS Software © 2018 / V44.1 / Page 54

CHAPTER 9: Change the Help Link Label and URL

EMS Software © 2018 / V44.1 / Page 55

CHAPTER 10: Configure EMS Mobile QR Codes

CHAPTER 10: Configure EMS
Mobile QR Codes
In order to associate rooms with QR Codes, System Administrators must run
and print a Room Card - QR Code report (under Hoteling) in the EMS Desktop
Client. This automatically generates the codes and associates them with the
designated rooms.

EMS Software © 2018 / V44.1 / Page 56

CHAPTER 11: How Do I Know When To Upgrade the Mobile App and API?

CHAPTER 11: How Do I Know
When To Upgrade the Mobile App
and API?
DETERMINE EMS MOBILE API AND MOBILE APP VERSION
COMPATIBILITY
Use the matrix below to determine how you want to enforce user updates.

MOBILE API
RELEASE

VERSION
VERSION

Update
1
V44.1
Update

EMS Software © 2018 / V44.1 / Page 57

CHAPTER 11: How Do I Know When To Upgrade the Mobile App and API?

MOBILE API
RELEASE

VERSION
VERSION

Update
3
V44.1
Update
4
V44.1
Update
5
V44.1
Update
6
V44.1

EMS Software © 2018 / V44.1 / Page 58

CHAPTER 11: How Do I Know When To Upgrade the Mobile App and API?

MOBILE API
RELEASE

VERSION
VERSION

TIP: The Minimum App Version means that users running EMS Mobile
App below the minimum will not be able to use EMS. Increasing this value
essentially forces users on an older version to upgrade. Maximum App Version prevents users from using EMS Mobile App if they run a version above
the max.

EMS Software © 2018 / V44.1 / Page 59

CHAPTER 12: Set EMS Mobile Parameters

CHAPTER 12: Set EMS Mobile
Parameters
Configure your mobile application behavior using the parameters described
below.

CONFIGURED
AREA

(TBLREGISTRY NAME)

DefaultCancelReason

Applications ta-

applied
to bookings
that are

EMS Software © 2018 / V44.1 / Page 60

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

cancelled
by
everyday
users.
The ability for a
user to
choose
a
Cancel
Reason
does
not
need to
be
enabled
for a

EMS Software © 2018 / V44.1 / Page 61

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

MOBILE_HelpLinkLa-

Applications ta-

MOBILE_HelpLinkURL

Everyday User
Applications tab

EMS Software © 2018 / V44.1 / Page 62

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Mobile_Require2FA

Applications ta-

Mobile_AuthHead-

Applications ta-

EMS Software © 2018 / V44.1 / Page 63

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Applications ta-

go to
the
EMS Web App
and
scan
their 2fa
barcode

EMS Software © 2018 / V44.1 / Page 64

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

MOBILE_EverydayAppConfigJson

Authenti- Desktop Client

Applications ta-

authenticate
against
the api

portedAppVersion

EMS Software © 2018 / V44.1 / Page 65

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Applications ta-

should
allow to
connect

portedAppVersion

Applications ta-

should
allow to
connect

EMS Software © 2018 / V44.1 / Page 66

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

from
mobile
app

Applications ta-

EMS Software © 2018 / V44.1 / Page 67

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

ing
users
links to
the
EMS Web App

sionTokenSigningKey

Applications ta-

receive
once
they create a
valid

EMS Software © 2018 / V44.1 / Page 68

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Settings >
Parameters >
Everyday User
Applications tab

VEMS_User_Secur-

EMS Software © 2018 / V44.1 / Page 69

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Applications ta-

vationBook_StartTime

Settings >
Parameters >
Everyday User

EMS Software © 2018 / V44.1 / Page 70

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Applications tab

DropEventsInPast

Applications tab

VEMS_EmailAccount

Settings >
Parameters >

EMS Software © 2018 / V44.1 / Page 71

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Everyday User
Applications tab

istration >
Settings >
Parameters >
Everyday User
Applications tab

VEMS_EmailSender

tem Administration >
Settings >

EMS Software © 2018 / V44.1 / Page 72

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Parameters >
Everyday User
Applications tab

VEMS_EmailSender-

Settings >
Parameters >
Everyday User
Applications tab

VEMS_EmailServer

EMS Software © 2018 / V44.1 / Page 73

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Everyday User
Applications tab

Vems_Reservations_

AutoEmailFormat

Parameters >
Everyday User
Applications tab

VEMS_Reservations_

AutoSendSummary

EMS Software © 2018 / V44.1 / Page 74

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

istration > Set-

Everyday User
Applications tab

VEMS_Reservations_

Parameters >
Everyday User
Applications tab

VEMS_Reservations_

EMS Software © 2018 / V44.1 / Page 75

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

istration > Set-

tings >
Parameters >
Everyday User
Applications tab

LDAP_Authenticate

figuration.aspx

to
authenticate
with
LDAP.

EMS Software © 2018 / V44.1 / Page 76

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

inProximityDistance

Parameters >
Everyday User
Applications tab

imityUnitOfMeasurement prox-

Everyday User
Applications tab

EMS Software © 2018 / V44.1 / Page 77

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

MOBILE_MinutesToRe-

Applications ta-

Settings >
Parameters >
Everyday User

EMS Software © 2018 / V44.1 / Page 78

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

Applications tab

itOfMeasurement

Everyday User
Applications tab

EMS Software © 2018 / V44.1 / Page 79

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

PAM_WebServiceURL

Everyday User
Applications tab

URL for the EMS

Mobile App in the app

Applications ta-

EMS Software © 2018 / V44.1 / Page 80

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

App
popup
prompt
from
appearing.

URL for the EMS

Mobile App in the play

Applications ta-

App
popup
prompt

EMS Software © 2018 / V44.1 / Page 81

CHAPTER 12: Set EMS Mobile Parameters

(TBLREGISTRY NAME)

from
appearing.
iOS
Android

EMS Software © 2018 / V44.1 / Page 82

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Page Count                      : 87
Page Mode                       : UseNone
Page Layout                     : SinglePage
Language                        : en-us
Producer                        : madbuild
Create Date                     : 2018:03:07 11:12:56-07:00
Modify Date                     : 2018:03:07 11:12:56-07:00
Title                           : EMS Mobile App Configuration Guide
Author                          : EMS Software
Subject                         :

EXIF Metadata provided by EXIF.tools