Android Server-side Tasks

Main Steps

The main server-side steps to prepare for installation of the Geocortex Mobile App Framework are:

  1. Configure viewers to be available in the App.

    If your App supports multiple viewers, you must configure which viewers are available in the App. This step does not apply to single-viewer Apps.

  2. Configure offline maps and basemaps.

    If you are going to support offline use of the App, you must configure the maps and basemaps that you want to be available offline. If you are not going to support offline use of the App, you can skip this step.

  3. Create and deploy additional resources.

    You only need to do this if you have resources that you want to make available to end users, for example, locale files.

  4. Deploy the installation package to a server that end users have access to, and provide them with the package's location.

    If you are responsible for installing and configuring the App on end user devices, you can skip this step. You only need to do this step if the end users themselves are going to download and install the App from a server.

If you experience an error when you try to use the Geocortex Mobile App Framework to access a Viewer hosted behind a firewall, see Unable to Load a Viewer Hosted Behind a Firewall.

Configure Viewers to be Available in the App

Configuring the availability of viewers applies to multi-viewer Apps only. If the Geocortex Mobile App Framework was installed using a single-viewer installation package, you do not need to configure viewer availability.

When the App is first installed, it only contains a sample viewer. You must make your viewers available to end users so they can download the viewers to their device. The downloaded viewer includes everything the user needs to take the App offline, such as the offline maps and basemaps (TPK files) you have configured.

There are several ways to make viewers available to end users:

Add Viewers to the App's Available Viewers List

To add a viewer to the Available Viewers list:

  1. In Geocortex Essentials Manager, edit the site that contains the viewer.

  2. In the side panel, click Viewers, and then click the Edit icon beside the desired viewer.

  3. In the Viewer for HTML5 side panel, click Offline.

  4. Select the Add to List of Available Viewers checkbox.

    If the site is secured, the viewer will only appear in the Available Viewers list if the user has permission to access the viewer. For information on setting permissions on viewers, see Permissions.

  5. Click Apply Changes.

  6. Click Save Site.

    To download the viewer to the device, the end user taps the viewer in the Available Viewers list, and then taps Save. The viewer appears on the Saved Viewers page.

Download Viewers Automatically

To configure a viewer to download automatically:

  1. In Geocortex Essentials Manager, edit the site that contains the viewer.

  2. In the side panel, click Viewers, then click the Edit icon beside the desired viewer.

  3. In the Viewer for HTML5 side panel, click Offline.

  4. Select the Add to List of Available Viewers checkbox.

  5. Select the Automatically download checkbox.

    If the site is secured, the viewer will only appear in the Available Viewers list if the user has permission to access the viewer. For information on setting permissions on viewers, see Permissions.

  6. Click Apply Changes.

  7. Click Save Site.

  8. In the App, verify that the viewer appears on the Saved Viewers page.

    If the viewer does not appear on the Saved Viewers page, register the App with your Essentials instance .

    The viewer automatically downloads to the user's device when the user starts the App. The viewer appears on the Saved Viewers page.

Provide the Viewer's URL

If the App is not yet registered with an Essentials instance, using the Launch in Geocortex Mobile App Framework link will register it.

To provide users with the URL to add the viewer:

  1. In Geocortex Essentials Manager, edit the site that contains the viewer.

  2. In the side panel, click Viewers.

  3. Click Edit beside the viewer.

  4. Right-click the Launch in Geocortex Mobile App Framework link and copy the link's URL.

  5. Use one of the following methods to make the viewer available to end users:

    • Create a link or QR code that points to the URL. Publish the link or QR code to a website that end users have access to, or send the link or QR code in an email.

      To add the viewer, users either scan the QR code, or open the email on the device and tap the link. The viewer appears on the Saved Viewers page.

    • Send users the URL.

      To add the viewer, users type or paste the URL into the address bar of a web browser on the device. The viewer appears on the Saved Viewers page.

      Chrome for Android does not handle these URLs properly. Typing the URL into the address bar does not work in Chrome for Android.

Configure Offline Maps and Basemaps for Android

To allow end users to use the App offline, you must create the offline maps and basemaps that you want to be available offline. When you configure the offline map, you associate the offline basemap with the offline map. Usually, you configure the offline basemaps first, so they are available when you configure the offline map.

There are two types of offline basemap—pre-generated and custom. Typically, you create pre-generated offline basemaps for areas where you know that you have field workers working, and you use custom offline basemaps when you cannot predict what areas your users will need.

After you have configured an offline basemap, you must configure an offline map. As part of the configuration, you will specify the offline basemaps that the offline map uses.

You must also provide a way for end users to download and use the offline maps and basemaps. For example, you could add the Offline Maps tool to the viewer's toolbar, add an I Want To menu item, or add a hyperlink to the viewer.

If your site is secured and you do not allow anonymous access, users will have to sign in to use offline maps. You can allow anonymous users to see offline maps by changing the Data Store policy.

See also...

About Offline Maps and Basemaps

Offline Requirements

Add a Pre-generated Offline Basemap using an Existing TPK

To configure an existing TPK file:

  1. In Geocortex Essentials Manager, edit the site you want to configure.

  2. Click Offline in the side panel.

  3. Click the Offline Basemaps tab.

  4. Click Add Offline Basemap.

  5. Select Use an existing TPK, and then click Next.

  6. Select one of the following:

    • Use the URL of an existing TPK file available online:

      In the TPK URL box, type the URL of the TPK file.

      End users download the TPK directly from the specified server. The TPK is not copied to the Essentials server.

    • Use a TPK file already on the server:

      From the TPK File drop-down list, select the TPK file on the server.

      To appear in the TPK File drop-down list, the TPK file must be in the Essentials TPKs folder. In the default Essentials installation, the TPKs folder is here:

      C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Sites\TPKs

  7. Click Next.

  8. In the Display Name box, type a display name for the offline basemap, and click Finish.

  9. Click Save Site.

    You can now add your pre-generated offline basemap to an offline map. When the end user downloads the offline map, the basemap downloads with it. Alternatively, the user can manually copy the TPK file to the device before downloading the offline map. In this case, the App detects that the TPK file is already on the device and does not download the basemap.

Add a Pre-generated Offline Basemap that Generates the TPK File

To use an ArcGIS tiled map service to generate the TPK file, the map service must support the ExportTiles operation.

To specify a map service to generate the TPK file:

  1. In Geocortex Essentials Manager, edit the site you want to configure.

  2. Click Offline in the side panel.

  3. Click the Offline Basemaps tab.

  4. Click  Add Offline Basemap.

  5. Select Use a map service supporting the ExportTiles operation to generate a TPK file, and click Next.

  6. In the Map Service URL box, type the URL of the TPK file, and then click Next.

  7. Click Extent, and pan and zoom the map to the extent you want to be available offline.

  8. Click Max Resolution, and zoom the map to the maximum level of detail you want to be available offline.

  9. Click Next.

  10. In the Display Name box, type a display name for the offline basemap, and then click Finish.

    The TPK file representing the basemap will start being generated. When it is completed, its Status changes to Ready. You do not need to wait for the TPK file to complete before moving to the next step.

    The TPK file is written to the Essentials TPKs folder. In the default Essentials installation, the TPKs folder is here:

    C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Sites\TPKs

  11. Click Save Site.

    You can now add your pre-generated offline basemap to an offline map. When the end user downloads the offline map, the basemap downloads with it. Alternatively, the user can manually copy the TPK file to the device before downloading the offline map. In this case, the App detects that the TPK file is already on the device and does not download the basemap.

Manually Copy an Existing TPK File to the Device

Normally, the TPK files of any pre-generated offline basemaps are automatically downloaded to the device when the user syncs an offline map that includes them. If a TPK file is very large and you do not want to download it this way, you can manually copy the TPK file to the device instead. For example, you could copy the TPK file to a thumb drive, and give the thumb drive to the end user to copy the file to their tablet.

When the end user downloads the offline map, the App detects that the TPK file is already on the device so it does not download the basemap.

To manually copy an existing TPK file to the device:

  1. Copy the TPK file to the following folder on the device:

    Android\data\Geocortex.App\files

Configure a Custom Offline Basemap

Custom offline basemaps are based on basemaps that are configured on the Basemaps page in the site. To create a custom offline basemap from a particular basemap, choose one of the following that applies to you:

You may want to use a map service that does not support the ExportTiles operation for online use, and a different service that does support ExportTiles for offline. For example, you could use one of the ArcGIS Online services that supports ExportTiles, like the World Topographic, Imagery, or Street Map services, to create the TPKs.

If you delete an offline map that contains a custom offline basemap, the custom offline basemap is also deleted.

To specify an ArcGIS tiled map service to use for a custom offline basemap:

  1. In Geocortex Essentials Manager, edit the site that you want to configure, and then click Basemaps in the side panel.

  2. In the list of basemaps, click the basemap that you want to edit, or hover the pointer over the basemap.

    The management tools appear.

  3. Click the Edit tool.

  4. Set the Export Tiles Override setting to the URL of an ArcGIS tiled map service that supports the ExportTiles operation. For example:

    http://MyServer.com/arcgis/rest/services/MyMapService/MapServer

  5. Click OK.

  6. Click Apply Changes.

  7. Click Save Site.

    You can now add your custom offline basemap to an offline map.

Create an Offline Map

There are two ways to create an offline map:

There are several steps to create an offline map, specifically: specify the extent and layers that will be available offline; add at least one offline basemap; and share the offline map with specific users or groups of users.

Panel to create a new offline map

Configure an Offline Map using Geocortex Essentials Manager

To configure an offline map in Geocortex Essentials Manager:

  1. In Geocortex Essentials Manager, edit the site that you want to configure, and then click Offline in the side panel.

  2. Click the Offline Maps tab.

  3. Click New.

  4. In the Name box, type a name for the offline map.

    After typing a name for the offline map, you can click Finish at any time to accept the default settings for a new offline map. By default, the offline map's area of interest is set to the initial extent, all feature layers and attachments are included for offline use, no offline basemaps are included, and the offline map is not shared.

  5. Click Area of Interest.

  6. Select one of the selection tools, and then select the area of the map that you want to be available offline.

  7. Click OK.

  8. Click Layers.

  9. Select the feature layers that you want to be available offline.

    If you want to restrict the number of features of a layer, click to set a definition expression for the layer. This is equivalent to a WHERE clause in SQL. For example, TYPE = 'Residential'.

  10. If you want feature attachments to be included offline, select the Include Attachments checkbox.

  11. Click OK.

  12. Click Basemaps.

    The Select Basemaps panel opens.

    Example of the panel that allows you to select basemaps for an offline map

    The Select Basemaps panel lists the basemaps that are configured on Manager's Basemaps page.

    In the Select Basemaps panel:

    • The Pre-generated option only appears if there is at least one offline basemap. The drop-down list lists the offline basemaps that have been added to the site. For example, in the screen capture above, the Imagery basemap's drop-down list shows that the site has an offline basemap called GreaterVictoria.

    • The Custom option only appears if the basemap contains at least one map service that supports the ExportTiles operation, or you have configured the basemap's Export Tiles Override setting.

  13. For each basemap, select one of the following:

    • None: If you do not want to use this basemap offline.

    • Pre-generated: If you want to use a pre-generated offline basemap from the Offline Basemaps page in Manager:

      1. From the drop-down list, select the pre-generated offline basemap you want to use offline.

    • Custom: If you want to use a custom offline basemap from the Basemaps page in Manager:

      1. Click Edit.

      2. Use the slider to select the level of detail that you want to be available offline.

      3. Click Done.

      4. In the Days Between Refresh box, type the period of days to wait until the TPK file should regenerate when the user synchronizes the offline map.

      If you create a custom offline basemap from a basemap that contains multiple tiled map services, the TPK is created from the topmost map service in the basemap—the other map services are omitted from the TPK. If you want to create the custom offline basemap from one of the other map services, set the basemap's Export Tiles Override setting to the map service that you want to use in the TPK.

  14. Click OK.

  15. Click Sharing.

  16. To share the offline map with others:

    1. If you want to share the offline map with a particular user, select Individuals from the drop-down list.

      If you want to share the offline map with a group of users, select Groups from the drop-down list.

    2. In the Search box, type the name of the user or group that you want to share with.

    3. Click Add.

      The user or group is added to the list of users and groups that have access to the offline map. By default, they have View access.

    4. Select a sharing option:

      • None: If you do not want to share the offline map with this user or group.

      • View: If you want this user or group to be able to view the offline map, but not edit it.

      • Edit: If you want this user or group to be able to view and edit the offline map.

    Repeat this step to share the offline map with as many users and groups as you want. Click OK when you are finished.

  17. Click OK.

  18. Click Finish.

Create an Offline Map in the App

To create an offline map in the App:

  1. Start the App and sign in.
  2. Open the viewer that you want to add the offline map to.

  3. If necessary, tap to open the toolbar.

  4. Tap Offline Maps .

  5. In the Offline Maps panel, tap the Panel Actions Menu button .

  6. Tap Manage .

  7. Tap New.

  8. In the Name box, type a name for the offline map.

    After typing a name for the offline map, you can tap Finish at any time to accept the default settings for a new offline map. By default, the offline map's area of interest is set to the initial extent, all feature layers and attachments are included for offline use, no offline basemaps are included, and the offline map is not shared.

  9. Tap Area of Interest.

  10. Select one of the selection tools, and then select the area of the map that you want to be available offline.

  11. Tap OK.

  12. Tap Layers.

  13. Select the feature layers that you want to be available offline.

    If you want to restrict the number of features of a layer, tap to set a definition expression for the layer. This is equivalent to a WHERE clause in SQL. For example, TYPE = 'Residential'.

  14. If you want feature attachments to be included offline, select the Include Attachments checkbox.

  15. Tap OK.

  16. Tap Basemaps.

  17. For each basemap that can be used offline, do one of the following:

    • None: Select None if you do not want to use this basemap offline.

    • Pre-generated:

      1. Select Pre-generated.

      2. Select the desired pre-generated offline basemap from the drop-down list.

    • Custom: 

      1. Select Custom.

      2. Tap Edit.

      3. Use the slider to select the level of detail that you want to be available offline.

      4. Tap Done.

      5. In the Days Between Refresh box, type the period of days to wait until the TPK file should regenerate after synchronizing the offline map.

  18. Tap OK.

  19. Tap Sharing.

  20. To share the offline map with others:

    1. If you want to share the offline map with a particular user, select Individuals from the drop-down list.

      If you want to share the offline map with a group of users, select Groups from the drop-down list.

    2. In the Search box, type the name of the user or group that you want to share with.

    3. Tap Add.

      The user or group is added to the list of users and groups that have access to the offline map. By default, they have View access.

    4. Select a sharing option:

      • None: If you do not want to share the offline map with this user or group.

      • View: If you want this user or group to be able to view the offline map, but not edit it.

      • Edit: If you want this user or group to be able to view and edit the offline map.

    Repeat this step to share the offline map with as many users and groups as you want. Tap OK when you are finished.

  21. Tap OK.

  22. Tap Finish.

Allow Anonymous Users to View Offline Maps

If your site is secured, by default end users who are not signed in cannot see offline maps in the App. You can allow anonymous users to view offline maps by changing the Data Store policy. Anonymous users cannot edit offline maps.

Allowing end users to view offline maps also allows them to view other Data Store documents, such as HTML5 Viewer projects. For more information, see Geocortex Data Store.

To allow anonymous users to view offline maps:

  1. In Geocortex Essentials Manager, click the Security & Data tab, expand the Data Store area in the side panel, and then click Policies.

  2. Select Allow Public Read Access.

  3. Click Apply Details.

Use an Offline Map in the App

To use an offline map, the user selects the map in the Offline Maps panel.

The Offline Maps tool (left) opens the Offline Maps panel in the App

To use an offline map in the App:

  1. In the App, open a viewer for a site that contains offline maps.

  2. If necessary, tap to open the toolbar.

  3. Tap the Offline Maps tool .

    The Offline Maps panel opens.

  4. Tap the offline map you want to use.

    Offline maps that have not yet been downloaded are marked with a download icon .

  5. If prompted to confirm you want to download the offline map, tap OK.

    The offline map starts to download. After the offline map has finished downloading, it becomes active. If you want to return to only using online data, tap Go Online.

  6. While your offline map is active, you can browse and edit features on the map even without network connectivity.

  7. When you regain network connectivity, tap the offline map's Sync button .

    The synchronization process starts. When finished, your edits are synchronized with the server and your offline map is also updated.

    To synchronize all the changes to any offline map, in the notification at the top of the screen, click Sync Now. This notification only appears when you have unsynchronized changes and network connectivity.

    If one or more of your offline maps have not been synchronized for a week, the App displays a notification to allow you to synchronize all your offline maps, regardless of whether you have made any changes.

    These notifications only appear within the viewer. They do not appear within the viewer selection screen in multi-viewer Apps.

    If network connectivity is interrupted during synchronization of an offline map, you can resume synchronization when you regain network connectivity. To resume synchronization, select the offline map and tap . To delete the partially transferred data instead, tap Delete Data when the App informs you that synchronization failed.

Create and Deploy Additional Resources

Resources are additional assets used by a viewer to support your business goals. For example, the locale files that are used to translate the App are resources.

Resource URIs point to resource files. To make a resource available to end users, provide them with a link or QR code to the file. When a user taps the link or scans the QR code, the resource file is loaded onto the device. You can also remove resources that have been previously added to a device.

You do not need to use resource URIs to add tile package (TPK) files. Instead, configure your offline basemaps in Geocortex Essentials Manager.

To allow end users to add a specific resource:

  1. Put the resource file on a server that end users have access to.

  2. Provide end users with a link or QR code that points to the following URL:

    gcx://resource?action=download&url=[resource URL]

    Be sure to replace [resource URL] with the fully qualified URL of the resource file.

To allow end users to remove a specific resource:

  1. Provide end users with a link or QR code that points to the following URL:

    gcx://resource?action=remove&name=[file name]

    Be sure to replace [file name] with the name of the file that you want users to be able to remove.

See also...

Translate the App on Android

Download Additional Resources

Deploy the Installation Package

The Geocortex Mobile App Framework must be installed on each end user's device. One way to make the installation package available to users is to deploy it to a file share or web server that users have access to. They can then download the package from the server and install the App on their device.

You can skip this step if you are responsible for installing the App on behalf of the end user, for example, if your organization provides devices to mobile workers. You only need to do this step if the end users themselves are going to download and install the App from a server.

To deploy the installation package:

  1. Put the APK file on a file share or web server that your end users have access to.

    For information on the web server's requirements, see Deployment Server Requirements.

  2. Provide end users with the location of the installation package so they can download it to their device.

What's next?

Install on an Android Device