TRAINING GUIDE

Mobile for Administrators Part 1 – Intro and Configuration

Mobile for Administrators - Configuration This guide covers the Lucity 2.0 for Android and Lucity 2.0 for iOS (iPad, iPhone, iPod Touch). Lucity 2.0 can be used with Lucity 2016 and higher. If you are on Lucity 2015r2 or earlier, you will need to use the earlier version of the mobile applications. Much of this content is relevant for the earlier versions of the mobile applications, but there will be differences. See the ACT 2015 user guide for material applicable to that version.

The Lucity Android and Lucity iOS applications have been designed to work under the same framework as the Lucity Web application. Configuration for Lucity Web carries forward to these mobile devices automatically.

These mobile applications have 3 core components.

Dashboard

Views/Forms

GIS

The goal of this session is show how to get a tablet working out in the field for online and/or offline use and assumes that Lucity Web (dashboards, views, and forms) are already configured.

Contents Installation and Setup .................................................................................................... 2

Permissions .............................................................................................................. 2

Installing Mobile Server ................................................................................................ 2

System Settings for Lucity Mobile ................................................................................... 3

Downloading and Installing ........................................................................................... 4

Configuring the application for first time use ........................................................................ 4

For Android: ............................................................................................................. 4

For iOS: ................................................................................................................... 5

Additional Recommended Configuration ........................................................................... 6

Logging in ................................................................................................................... 8

Logging out .............................................................................................................. 8

Changing Password ........................................................................................................ 9

Troubleshooting login ................................................................................................... 11

Warning Prompts ...................................................................................................... 11

Local Tablet Log ...................................................................................................... 11

Server Log .............................................................................................................. 15

Managing Logged in Users .............................................................................................. 16

Final Configuration Consideration .................................................................................... 16

Installation and Setup

Permissions Access to the mobile apps is controlled through a permission in Lucity. In the permissions form in Lucity Security, these permissions are located under “Mobile”.

Users must have the Run permission to the mobile application they will be using. They must also have permission to any modules they need to access while in the field. For example, if users need to view Work Orders in the field, they must have Run permission to Work Orders. If they need to edit Work Orders in the field, they need those permissions as well. This is no different than the module level permissions configured for Lucity Web.

Installing Mobile Server Mobile Server is available on the Lucity installation media.

It should be installed to a web server (Windows Server 2008r2+). If the tablets will be using VPN or local Wi-Fi connections, this can be an internal web server. If not, this application must be placed in the DMZ so that it is available to the tablets.

Choosing to install with SSL (https) is recommended if you will be using Android and REQUIRED if you are using iOS regardless of whether you are using a secure VPN.

In addition to the Lucity Mobile product, if you want users to be able to upload and download documents, you will also need to install the Lucity Document Server. The Document Server does not typically get installed in the DMZ, it gets installed on an internal web server which can access the network locations which contain the files to be uploaded and downloaded. The Lucity Document Server is an application used for multiple applications within Lucity including Lucity Web, Lucity Citizen Portal, Lucity Mobile Server, Lucity Citizen Portal REST API, and the Lucity REST API.

If the Lucity Document Server is installed on different server than Lucity Mobile Server, ensure that firewall settings are configured to allow Lucity Mobile Server to make unsolicited requests to the Lucity Document Server on the port that is used for the Lucity Document Server (port 80).

The Lucity Android and iOS applications will not access the Lucity Document Server directly. All requests for documents (download and upload) are proxied through the Lucity Mobile Server.

Lastly you must configure your network to allow necessary access to your GIS Server. There are several ways this can be done and goes beyond the scope of this session. Regardless of whether you are hitting the primary ArcGIS instance or you are using an ArcGIS web adapter, the following requirements must be met:

The mobile devices must be able to connect to the ArcGIS web services. GIS web service access is not proxied through Lucity Mobile Server

The Lucity Mobile Server host must be able to connect to the ArcGIS web services. Lucity Mobile Server connects to these servers to get metadata about the layers (what layer is the sewer pipe layer, what layer is the water hydrant layer, etc). If Lucity Mobile Server cannot access to the web services, the maps will show up on the tablets but any attempts to do Show in Map, create work orders or inspections or other Lucity specific functions in the map will fail. This is discussed more in the GIS setup later in this session

System Settings for Lucity Mobile It is not required to configure anything in System Settings for mobile to work. However, there are several settings you can review and edit.

Log device latitude and longitude configures whether the mobile tablets will send tablet location information to Lucity Server for logging.

Maximum number of days to store the device location history allows you to configure how long you want that information stored.

Max Columns Returned allows you to increase how many columns a grid can display in mobile (more columns requires more memory in iOS and more vertical space in Android).

Maximum number of records to return per request for mobile allows you to limit the view page size for mobile users to a specific cap. Do not reduce this below 15.

Update the offline…cache nightly allows you to configure which types of offline caches you need the system to generate. If you are not using offline, set both of these to FALSE. Offline caches are

resource intensive on the server although they only happen at night (unless a cache is forced). It is a good idea to only enable the caches you need.

Downloading and Installing Lucity distributes all mobile applications via the standard app stores (Apple App store and Google Play store). Search Lucity and the app is generally easy to find in the search results.

We recommend configuring automatic updates for the Android application.

Configuring the application for first time use Once installed, tablet users (or whoever will be configuring the tablets) will need the following information:

The host name you want the tablets to use to connect to the server.

The name of the virtual directory used during the install. If the default was left, this is LucityMobileServer.

The port used for the installation. The default port is 443. If SSL was not chosen as an option during the Lucity Mobile Server installation, the default port is 80.

Whether or not SSL was used.

For Android:

Notes:_______________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

For iOS:

Name is a user friendly name for the dataset you are logging into. We commonly call this the client. If you have a training/test and a production environment, your tablet can point to both environments. You can use the Name to help distinguish between these environments.

The Host is the name of the server where the Lucity Mobile Server product is installed. This may be a server name, it may be an IP address, or it may be an alias. For example, your server might be called JARVIS but your alias might be “mobile.cityOfLucityKS.gov”, or if you do not have an alias or public DNS, your server name may be the externally routable IP address of the server.

For Android the hostname also needs to include a port (for non-default ports only). If the port is 80 or 443 this is not necessary. If you installed Lucity Mobile Server to port 8081 on a server called CityOfLucityServer, the host would be “CityOfLucityServer:8081”.

The Scheme identifies whether http or https are being used. These are the only 2 schemes supported. iOS is defaulted to 443 so there is no scheme field to set.

For iOS, there is a separate port field. The default value, 443, is for https installations on the default SSL port.

The REST application path is the name of the virtual directory used when installing the software. By default this is LucityMobileServer.

Once the host, scheme, application path, and possibly port are set, click the save in Android or

the in iOS.

Additional Recommended Configuration There are several other configuration items that should be reviewed and set:

DEVICE IDENTIFIER (ANDROID ONLY): The device identifier is used to identify the device in server logs and in activations if licensing is a per device license. By default this is populated with the first user that logged in combined with the model of the device. This can be edited as needed. If device licensing is in use, you may want to delete the activation that is tied to the old name (if it exists). It is against the Lucity license agreement to use this bypass Lucity licensing. The device identifier for Apple devices cannot be changed.

DEFAULT CATEGORY: This is the category that will be used as the default category for requests and work orders generated from an address or XY in the map from the tablet. This is stored per tablet per login.

This means you can have your graffiti crew and your sidewalk crew share a tablet. But it also means this must be set for each user. Once set, it will remember it for the next login.

ENABLE LOCATION TRACKING: Lucity allows you to configure your tablets to send their location periodically to the Lucity Server. You can enable or disable this feature on a per user basis. Users can also enable and disable this but only if you have granted the Configure Location Tracking permission for the user.

Notes:_______________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

Logging in Once a user logs in they are kept logged in until they explicitly log out again or until their token expires.

Logging out To log out of the device, select “Log Out” from the menu. Logging out will prevent unauthorized users from getting access to modify the data in the Lucity Mobile application. If the Android or iOS application is in an offline state, it is not possible to logout. It is particularly important for devices which are using the application offline to use additional layers of security for device access such as a device passcode or other protection.

Changing Password Users can change their password directly from the mobile applications but only if they are able to successfully login with their current password. To change a password, select “Change Password” from the dashboard menu in iOS or Android.

Android

iOS

Users can also view the password requirements.

Android

iOS

Notes:_______________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

Troubleshooting login Typically the initial hurdle in a tablet implementation is getting the devices logged in. It can be challenging to know what to put in the setup when configuring it, users may not have the password right, or may have the username wrong. You also may have problems with the network or firewall or VPN (if applicable) not being configured properly.

There are 3 sources to use when troubleshooting the devices.

Warning Prompts If there is a problem with the username and password, the user will be notified that the credentials are incorrect: “Invalid username or password”. They will also get a message if their password is about to expire.

Local Tablet Log There is a local log on the tablet which will log errors. If logon fails, you can refer to this log for more details on the failure. The log is accessed from the client setup screen (it is no longer accessible from the login screen).

The log shows the most recent entries at the top of the list

Select an entry summary to view the extended details in the log.

Frequently a failure will be logged in more than one log entry depending on the cause of the failure. Sometimes the log is helpful, other times you may need to resort to additional troubleshooting measures.

If you are working with support or want an email of the log, you can email one entry or an entire log. In Android, to email log entries select the entry, then click “Email a Copy”. It will ask you whether you want to email just one entry or all entries.

In iOS to send one log entry, click the menu and select Email.

To email an entire log in iOS, navigate back to “Log Messages” and Click Email All at the bottom of the screen

If error logging is not providing enough information, logging can be increased. This is controlled by a setting. The full logging setting is time forward.

In Android, after logging in, tap the menu and select “View Settings”.

On this screen, tap the checkbox next to Enable Full Logging and Save.

In iOS, after logging in, tap the menu and select “Settings”.

On this screen, tap the toggle next to Enable Full Logging and then tap Done.

Server Log In addition to the tablet log, it may be helpful to view server logs. Server logs may provide more information about why a tablet will not activate. The two recommended server logs to review are the rolling log located in the installation directory of Lucity Mobile Server (under a folder called Logs) and the Application Event Viewer logs on the web server.

Server logs are where you would find out of licenses are not available, a user is not configured properly, or if something else was misconfigured on the server.

Notes:_______________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

Managing Logged in Users When a user logs into the tablet, they will be able to continue using the app until their login token expires. By default this is 10 hours. After the 10 hours (or right before the 10 hour window) they will be prompted to login again to continue using the application.

If you think a device has been compromised and need to revoke access to the currently logged in user immediately, you can do that through the Security Tokens interface in Lucity Web. If the user’s password has been compromised you also should change their password.

To revoke a token, select the user in the Security Tokens of the admin portal

And click the Delete Selected Alias button

Final Configuration Consideration If tablets are in your office for configuration, and if users will be going offline with maps, it is recommended that you load offline basemap tile packages to the device. Lucity does not currently support downloading tiled base map packages (tpk) over WIFI or over 3G. They must be present and available on the device to be used.

Offline Basemap Configuration and installation will be covered with Offline content in this session.

Notes:_______________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________

______________________________________________________________________________