Prepare basemaps for offline use

[MarikaVertzonis]

Survey123 supports the use of offline basemaps. These basemaps must be of the Esri file type of tile package and web mercator projection. Tile packages can be created using ArcGIS Pro.

NOTE: Currently there are many manual steps required to use basemaps in your survey. It is expected that a more streamlined process will be added, but we wanted to make the functionality available as soon as possible. This topic will be updated as the user experience of including basemaps in your survey, evolves.

Create a map tile package

You can create a map tile package using ArcGIS Pro. Once created you can copy it directly to your device for use in Survey123 or share it in ArcGIS for others to use.

To create a map tile package:

1. Launch ArcGIS Pro.
2. Open an existing map or create a new map. Ensure your map has a suitable name and description. To edit these, right click the map in the table of contents, and choose properties.
3. In Toolbox, choose the Create Map Tile Package tool and enter the input map name and the output file name. Input map name and output file name are the minimum requirements for this tool. You can optionally enter other properties.
4. Run the Create Map Tile Package tool.

      A new .tpk will be created in your chosen output location. To use this file in Survey123 you can upload it to ArcGIS to share with others, or manually copy it to your device.

Copy your tile package directly to your device

If you do not have internet connectivity or are unable to connect to ArcGIS, you can copy your tile package directly to your device, or use it from an external storage card.

To copy your tile package directly to your device:

1. Connect to your device. If you are using an iOS device, you will need to use iTunes.
2. Copy you .tpk to your ~\ArcGIS\My Surveys\Maps folder. For example, on Windows this would be C:\Users\UserName\ArcGIS\My Surveys\Maps.
3. If you already had Survey123 open before copying, restart Survey123.

To use your tile package from an external storage card:

1. Copy your tile package to your storage card and place the card in your device.
2. Launch Survey123 on your device and on the My Surveys menu, choose Settings.
3. Nominate an additional Map Library Folder that represents your storage card. The default path of ~/ArcGIS/My Surveys/Maps will already be shown. You can add additional paths by

• Typing the additional path directly into the edit box (use a semi colon to separate paths).
• Use the folder browser to select an additional path. Any path selected will be appended to your Map Library Folder.

     When you next open a survey that has the map append property set to true, tile packages on your storage card will be appended to the list of available basemaps.

Currently no checking is performed to ensure that Map Library Folders are valid. the first path in the list will used when you choose to download tile packages from ArcGIS Online. The Map Library Folder path will not appear on iOS as external storage is not supported on this platform.

Share your tile package

You can share a map tile package in ArcGIS so that you can download it on different devices, or share with other people to use.

NOTE: The maximum file size that can be uploaded to ArcGIS Online is 1GB.

To share a tile package:

1. Sign in to  http://www.arcgis.com or your Portal for ArcGIS.
2. Browse to My Contents.
3. Select Create a new item.
4. Select From My Computer.
5. Browse to your tile package and choose to Upload. Be sure not to check the create tile service check-box when uploading your tile package.

     After your tile package has been uploaded to ArcGIS online, be sure to copy the URL of this package. An example tile package URL is http://www.arcgis.com/home/item.html?id=221a6aab56804a988a94ec9f82a063e7.

Associate a shared tile package to a survey

In order to be able make shared tile packages available to users of a survey, the survey itself needs to know where to download the survey from. This information is stored in the surveys .info file. Currently there is no user interface for this and you must enter text directly into this file. If you already have uploaded your survey to ArcGIS, you will already have a .info file that you can edit. If you have not already uploaded your survey to ArcGIS, you can create a new .info file with the following information.

To associate a shared tile package to your survey:

1. Browse to your survey folder on your computer.
2. Open the file MySurvey.info in a text editor. If you have not already uploaded this survey to ArcGIS, this file will not exist. You can create a new file called MySurvey.info, where MySurvey is the name of your survey.
3. Copy the follow code snippet into this file and save.
4. Upload your survey to ArcGIS.
   

   {
     "displayInfo": {
       "map": {
         "mapTypes": {
            "append": false,
            "includeLibrary": false,
            "mapSources": [
               {
                 "url": "http://www.arcgis.com/home/item.html?id=9a7e015149854c35b5eb94494f4aeb89",
                 "storeInMapLibrary": false
               },
               {
                 "url": "http://www.arcgis.com/home/item.html?id=4497b7bb42e543b691027840d1b9092a"
               }
           ]
         }
       }
     }
   }

The following lists the optional properties you can define when managing tile packages in your surveys:

• append—When you set the append property to equal true, the user will see the list of default online basemaps with your tile package appended at the bottom. When set to false, users will only be able to see the tile packages defined in your MySurvey.info file. The default value is true.
• includeLibrary—When you set the includeLibrary property to equal true, all tile packages stored on the device will appear in the list of basemaps of the current survey. When set to false, only the basemaps (online or tile packages) defined in the MySurvey.info file will be listed. The default value is true.
• storeInMapLibrary - Only relevant to tile package map sources. Specifies if the tile package will be stored in the map library or is private to the survey. If includeLibrary is set to false, then tile packages are automatically stored privately and this property will be ignored. The default value is true.

Download a shared tile package in Survey123

You can download tile packages for later offline use. Tile packages need to be associated to a survey for you to be able to find them and download.

To download a shared tile package:

1. Launch Survey123 and sign in with your ArcGIS named user account.
2. Select the survey that you associated a tile package too.
3. Select the menu and choose Download Maps.
4. Choose the tile package from the list to download.

     Once successfully downloaded, you will see the tile package in the list of maps on the location page of your survey.

Use a tile package in Survey123

You can use either manually copied tile packages or downloaded shared tile packages in your survey.

To use a tile package:

1. Launch Survey123 and sign in with your ArcGIS named user account.
2. Select the survey that you associated a tile package to.
3. Choose Collect.
4. Select the location question and display the full screen map.
5. Select the menu and choose the tile package.

[CharlesBailey3]

Marika can you give an example of a .info file with a url for online (esri basemap) and offline tpk that works? I finally got it to work with side-loading but need a shared tpk service. Copying that code snippet to the bottom of the file doesn't cut it, right?

[AurelieShapiro]

Hello,

I have created a basemap tpk that works fine in collector - i transfer it to my android device no problem and we use it for our data collection:

http://panda.maps.arcgis.com/home/item.html?id=333e260d0a0e46798ae6bd2e50fd4ea2

I have followed all the steps defined here:

I copied it into the maps folder in Sruvey123 on my device.
I also changed the code snippet in the info file on my computer as follows (i change the first link but it isn't clear what the second link does in the instructions):

   {

     "displayInfo": {

       "map": {

         "mapTypes": {

            "append": true,

            "includeLibrary": true,

            "mapSources": [

               {

                 "url": "http://panda.maps.arcgis.com/home/item.html?id=333e260d0a0e46798ae6bd2e50fd4ea2",

                 "storeInMapLibrary": true

               },

               {

                 "url": "http://www.arcgis.com/home/item.html?id=4497b7bb42e543b691027840d1b9092a"

               }

           ]

         }

       }

     }

   }

however, as soon as i do anything in survey123, the .info file reverts back as it was before. The basemap can not be found in the survey123 connect app nor in survey123 the device, and it seems I cannot take my survey offline, which means I wasted an entire 2 days creating it, as we will have to go back to collector. Can anyone please explain more clearly how to take a survey and basemap offline?

[MarikaVertzonis]

Be sure that Survey123 or Connect is not open whilst you edit the .info file in a text editor. If Survey123 is open it will indeed try and re-write the file.

I know that manually editing the .info file is a clunky but we are working on removing this need in (near) future, thank you for persisting with it.

[AurelieShapiro]

Thank you - would seem simple enough  solution but it does not work. It's not that the process is clunky, it's that it's not  clearly described with all the required steps (for example, closing Survey123 connect) for the audience whom you are trying to encourage to use the app. I saw my base map listed in my device, and in the updated info file, but when I click it, nothing happens. I see it in my map library but it has never been listed in the basemaps. I have tried to repeat the process and re-upload my survey but now I cannot see the appended map related to the survey or any options to download it.

Can you please specify ALL the tasks required - in sequential order with every step, including restarting the phone or app? - more clearly for those who might not be programmers or advanced developers?

For example, once the map is set to append in the info file - what are the exact steps in the app? delete the survey and re-download it? Re-start the phone? Are we meant to see the map listed in the map settings for survey123 connect and enter it there? (it is not there, even when the info file was correct).

Why are there two URLs in the code snippet - are two required?

Many thanks for your help.

[MarikaVertzonis]

Based on your statement of 'I have created a basemap tpk that works fine in collector - i transfer it to my android device no problem' you actually don't even need to go to the map library menu (in Settings) on your device. As long as you have

         "mapTypes": {

            "append": true,

            "includeLibrary": true,

in your .info file, they should appear in the list of basemaps.

In response to your specific questions:

- in the app, you do not need to delete the app, updating it is enough (restart the phone is not a requirement)

- the map will not be listed in map settings in connect

- two URL's in the code snippet - no they are not both required - and as above you don't need them at all if you have 'transferred your map to your device'. the URL's in the code snippet are for TPK's that you want to retrieve from ArcGIS Online.

[AurelieShapiro]

Thank you for your quick reply!

The tpk is on my phone. I see it listed in the map library in the survey123 app.

this is my new info file:

"mapTypes": {

                "append": true,

                "includeLibrary": true,

                "mapSources": [

                    {

                        "storeInMapLibrary": true,

                        "url": "http://panda.maps.arcgis.com/home/item.html?id=4b9145c747114b039124a4a33df685dd"

The map is not listed in the basemaps when I go to choose location. There are only the default ones...which cannot be taken offline, am I correct?

[MarikaVertzonis]

Since you have manually copied the TPK to your phone, you don't actually need the the mapSources section in the .info file. And considering the size of your TPK - making it available to download is probably not a good idea.

As a quick test, i did download your TPK via arcgis online and copied it to my desktop Survey123 maps folder. The screenshot below shows the name in the list (my surveys .info file just has includeLibrary set to true), and in the background you can see your tpk is visible.

One thing that would be important to do in Survey123 Connect is to set your default extent for your survey. Whilst you are doing this in Survey123 Connect you will be looking at one of the default online Esri basemaps, but that same extent will apply in the app when you choose your offline basemap.

The next thing to troubleshoot is your phone. What device are you using? I will try and copy the TPK to a similar device. Are you copying it to the /ArcGIS/My Surveys/Maps folder or some other folder?

[AurelieShapiro]

Thank you - can you please send the screenshot?

I am creating a new basemap and trying with that.

I am using a blackberry PRIV with Android 6.0.1, but my colleagues in Zambia, who are trying to get this to work are using Samsung J1.

[vipulsoni]

Hi,

I created TPK  from ArcGIS Desktop and copied it to my Android Mobile , but the Map Scales are very limited. The Tiles are of vector maps of floor plans and we would like to zoom to a room / space but the zoom above a certain level is not available. Is there any limitation to this. The setting on tile creation was level of detail 20 (in AGS Desktop Tool). but it was not sufficient at all. I was not able to zoom on the data to reach to high scale levels.

Please help.

[zkovacs]

This is a known limitation. Follow this blog article to create a tile package with more levels. (You don't need to upload it to AGOL, so you can skip that part.) Create a tiling scheme with more levels you need right now, so you can re-use it later.

I hope this helps.

[JamesWilson2]

If I have a survey on multiple devices across the state, and want each device to use it's own .tpk for that location, is it possible to load these into the device?

My devices are already running collector with .tpk's of their local area, I would like to associate these with Survey123. Is it possible for Survey123 to look in the collector tpk location?

All of my devices are iOS, and running Survey123 1.7.20.

[JamesWilson2]

I am running Survey123 1.7.20, and I do not have that 'Download Maps' option. Any ideas what I am doing wrong?

[MarikaVertzonis]

Yes you can have a different .tpk on each device. Using iOS adds some extra hoops to jump through. iOS does not allow apps sharing files so you can not just point Survey123 to your Collector generated .tpk.

You would need to:

 - connect your device to a computer and use an app such as iTunes or iExplorer to navigate the app files on your device.

 - copy your .tpk to the ~\ArcGIS\My Surveys\Maps folder

[JamesWilson2]

works perfectly! thanks for that pity iTunes makes it so hard to access subdirectories, and that it can't share with Collector.Some minor issues with zoom within the app, tiles load better if I use the + and - buttons rather than pinch-to-zoom

Seems a waste of space to double up, especially when my .tpk's start getting over the 10gb mark!

[IlyaPodosinnikov]

Good Afternoon!

Can anyone help me with the problem related to connection between Survey123 and Portal for ArcGIS?

The problem is: I have .tpk file which is hosted on our company`s server (with the use of Portal for ArcGIS). We need to upload it online while using Survey123. This tpk is already associated with the survey (code snippet is already in survey`s .info file). When I open map in the current survey I see the required .tpk in the list of Maps (link to the Portal is correct), but .tpk is not displayed (only the gray background)

What is the problem?

Esri layers or Google Maps (from the example above) are displayed well, the  only problem is with my .tpk layer. I have already checked extent of the map and some related features.

Hope to see any feedback. 

[MarikaVertzonis]

You describe that the required .tpk is in the list of Maps - that already eliminates a lots of issues. You also describe that you have checked the extent of the map - this is the critical step to review. When you choose a different basemap, does the extent default to your expected area?

[JohnWarden1]

Is it possible to have multiple tile packages associated with a survey by modifying the .info file?  

I would like users to have an option to download a low-res (17 layer) tile package, or a high-res (18 layer) package when out in the field.  Some users have size constraints, while others do not.  

[MarikaVertzonis]

Yes you can multiple tile packages list - the examples above show this. Just be sure to uniquely name the different basemaps, for example

   {
     "displayInfo": {
       "map": {
         "mapTypes": {
            "append": false,
            "includeLibrary": false,
            "mapSources": [
               {

                 "name": "Low res basemap (good for in field downloads)",
                 "url": "http://www.arcgis.com/home/item.html?id=9a7e015149854c35b5eb94494f4aeb89"
               },
               {

                 "name": "High res basemap (warning large file!)",
                 "url": "http://www.arcgis.com/home/item.html?id=4497b7bb42e543b691027840d1b9092a"
               }
           ]
         }
       }
     }
   }

[CraigCarsley]

I'm not sure this is the best place to add this comment, but I do hope it might be helpful to someone.

We had a user modifying .INFO files of multiple surveys to use an offline basemap. He accidentally copied ALL of the content from the .INFO file of one survey into the .INFO file of another survey.  

The result was that the survey was pointing to the wrong feature service.  Every survey that was filled out still submitted successfully, but not of the attribute data was preserved because the surveys were sent to the feature service of another survey (different schema).

All in all, the survey data was irrevocably lost.  It was an unusual mistake, but it's worth remembering for the sake of caution.

[MichaelWallace3]

I have managed to piece together a .info file that looks for a local tpk and defaults to showing that tpk.

My issue now is deploying this solution. Survey123 Connect in my experience always overwrites this file. Even if I close survey123 connect I would have to reopen it to publish the survey and upon reopening the .info file is overwritten. I will investigate the "downloading map option" but I wanted to know if there were plans to update this portion of survey123. Also It would be nice when setting the default map, zoom level and center point that the extent for the Feature Layer also be set based on the the extent that you zoom too in Survey123 connect. I consider that the extent being set to the whole world as an annoyance/bug that could be easily fixed.

Sincerely,

Michael Wallace

[MarikaVertzonis]

...upon reopening the .info file is overwritten.

This line in your comment above strikes me. This is not - should not - be the case. I have tried my own offline sample again (which i haven't used for a few releases) and it still contains the expected modifications.

Do check that when you finish editing your .info file that you close the file in whatever text editor you are using, before you open Connect. Although a number of improvements have been identified for the offline map workflow - they have not been scheduled for release.

Regarding the extent of the feature service - this can be changed in ArcGIS Online. This is in fact the first I've heard of this (and we have no internal bugs or issues along these lines) so this makes me think its a niche request. Happy to be proved wrong with examples.

[BillSimper]

So I've created tilepacks, uploaded to AGOL, associated them with my Survey, and successfully downloaded them to my device. They show up in my Map Library with the correct file sizes. I know they're legit tilepacks-- I've used them in Survey123 data forms before.

However, they are not available in the 'Map Types' list in the location control in my form. They have been associated with the survey in question, and the values of 'append', 'storeInMapLibrary', and 'includeLibrary' are all set to 'true'.

I've used this feature successfully before, so I'm wondering if something broke during a software update. I'm currently using version 2.6.9 on iPads.

[Sierra]

Hi! we've implemented a custom offline map (tile) following the steps defined here and everything works just fine on end-user devices: they are able to mark and submit locations as needed. We have a problem seeing locations in the surver123.arcgis.com under Data tab though: when we click on a record to bring up the right-side panel to go over that record, the location field comes up blank, not showing any map at all. When they hit the Print button to printout the report, the location field also prints out blank. All other fields work fine, including images. We didn't have that problem in previous versions of the survey where we didn't use an offline tile package map. I only guess that the .tpk had to be somehow associated with the structure under the "Data" tab on the website, but have no clue what to do to make that custom map (or any map) appear in the report. Any help would be greatly appreciated!!! Thank you!