Install and configure the ArcGIS Survey123 website

Summary

Organizations are sometimes required to work in completely disconnected environments where they have no external access to the internet. Other organizations  may be connected, but are required to host the ArcGIS Survey123 website and/or Survey123 REST API on their own infrastructure.

The Survey123 REST API is used to take your survey configurations and convert them into the forms for use in the Survey123 apps (field app / web form), such as connected created .xlsx files, or website created configurations. The website, on the other hand, provides the functionality to both create and manage the surveys, and view and analyze the collected data. Both components are separate, but they work together to provide the functionality that is seen in the ArcGIS Survey123 website (https://survey123.arcgis.com).

What is included

A local install of the Survey123 REST API and website, which enables creating and publishing surveys from Survey123 Connect, or the website on your own infrastructure. This provides most of the full functionality of the ArcGIS Survey123 website, with the notable exception that the reporting API cannot yet be hosted locally.

What is required

It is necessary to download the installer file from the My Esri website. The installation steps below are for Windows installs only. Also required are ArcGIS Enterprise portal administrator credentials, as well as administrator access for the web server. The Survey123 website installer can be deployed on the same machine as the Portal instance, or on a standalone web server. While the installed Survey123 website has been tested successfully with ArcGIS Enterprise portal versions 10.5.1 and later, each release officially supports ArcGIS Enterprise versions that are in the 'General Availability' phase of the Product Life Cycle at the time of release.

Internally used ports (26080, 26443, 28080, 28443)

Ports 26080, 26443, 28080, and 28443 are used by the installed Survey123 website for internal services. You do not have to open these ports for access by other machines. However, you should be aware that the installed Survey123 website is using them in case you run other applications that require the same ports. Unlike some ArcGIS Enterprise components, the installed Survey123 website cannot automatically increment to a different port if the ports above are not open.

Procedure

Installation

Download the ArcGIS Survey123 website via My Esri.

Windows:
Unzip the downloaded file to the desired machine, then run the Setup.exe. Accept the Master Agreement, choose the install location, and click Install. The process can take up to approximately 30 minutes. When this is done click Finish to exit the installation.

Linux:

Caution:
The archive files contained here must be extracted on a Unix machine. If done from a Windows machine, they lose the permissions necessary to run the setup properly and some filename casing may be changed.

1. Extract the contents of the .tar.gz file on the machine on which you want to install the Survey123 website using the command gunzip [filename].tar.gz followed by tar xf [filename].tar in Terminal.
2. Once extracted, run ./Setup in Terminal, accept the Master Agreement, choose the install location, and click Install. The process can take approximately 5-10 minutes. When this is done click Finish to exit the installation.

Post Installation
The steps for configuring the installed Survey123 website vary depending on the ArcGIS Enterprise environment. Please refer to the relevant section below.

Note:
A security warning may be encountered by your browser. Accept this and continue to the website, this is addressed by configuring a certificate during post installation. 

Note:
Make a backup of the config.json file (default location is C:\Program Files\ArcGIS\Survey123website) before running the post installation. If the installation is incorrectly configured, this file can be used to restore and start again (or make manual edits to the existing config.json).

Check if your Portal is limiting the domains that can connect via Cross-Origin Resource Sharing (CORS) to the ArcGIS REST API:

1. Log in to ArcGIS Enterprise as an administrator, go to Organization > Settings > Security > Allow origins group. By default, all domains are allowed, that is, there are no URLs in the list here. If you are already limiting the domains, add your Survey123 host URL to the list.
2. Click Add and add the Survey123 website host URL. For example:
   • https://<survey123website.domain>:5443
3. Click Add domain. This allows the Survey123 web application domain to connect via (CORS) to the ArcGIS REST API.

ArcGIS Enterprise with built-in authentication
Run the post installation by opening https://localhost:5443/share/post-install.html on the install machine. 

The post installation is presented as a survey-like wizard to edit the config.json file. This configures the following:

• Default ArcGIS Portal URL (https://domain.com/portalwebadaptor) to configure Survey123 website with ArcGIS Enterprise.The installation points to ArcGIS Online (arcgis.com) by default.
• ArcGIS Portal Admin Credentials (needed to set the redirect URI for Portal sign-in)
• ArcGIS JavaScript API (only required for versions before 3.19 in disconnected environments). By default it will use the Javascript API installed with Portal.
• HTTP(s) ports to be used (by default it will use 5080 and 5443)
• SSL certificate(s) (Require either .pem or .pfx certificate format used by Portal web adaptor)
• Survey123 website host URL Usually it will be https://localhost:5443 or https://FULLYQUALIFIEDDOMAINNAME:5443 (this is the http or https URL for the machine hosting your Survey123 website – remember to include the port number). This is added as a redirectURI to your Portal to allow sign-in.
• Settings for disconnected environments. Selecting Yes to the question "Are you installing the Survey123 website in a disconnected environment with no internet access?" sets Survey123 Organization properties that prevent Survey123 Connect from making internet calls (for things like tutorial videos, Twitter and Geonet).

Confirming the settings and clicking Submit updates the config.json file, it also

• Imports the certificate file(s) to the ~ArcGIS\Survey123website\server\cert\ folder
• Appends the Survey123 website host URL as a redirectURI to the survey123hub AppID
• Updates Survey123 Organization Properties (basemapsGroupQuery, showCommunityContent and showTutorialContent)

Open the config.json file in a text editor to view the updated settings.

ArcGIS Enterprise with Windows authentication (IWA)

• If the Survey123 website is not installed on the same host URL as ArcGIS Enterprise, please refer to the Run post installation manually section below.
• If the Survey123 website is installed on the same host URL as ArcGIS Enterprise, to allow the ArcGIS Enterprise (IWA) sign-in credentials to be used from the browser, go to the following URL for post installation:

https://<survey123website.domain >:5443/share/post-install.html

This allows the ArcGIS Enterprise (IWA) sign-in credentials to be used from the browser.

The post installation sets up everything listed above, but requires an ArcGIS Enterprise administrator to manually add the Survey123 website host URL, https://<survey123website.domain >:5443, as a redirectURI to Portal to allow sign-in:

1. Log in to the portal admin REST interface, for example:
   • https://portal_webadaptorhost.domain /portal_webadaptorname/portaladmin
2. Go to Security > OAuth > Get App Info, and enter the App ID survey123hub, and click Get App Info.
3. Copy the contents of the response.
4. Go back to OAuth and this time, go to Update App Info.
5. Paste the copied response into the input box, making sure to add the URL that you will use to access your Survey123 website to the list of redirectURIs, and click Update App. This may well include the reverse proxy access point if you intend setting one up, for example:
   • https://survey123website.domain /survey123
6. Repeat Step 2 to confirm that your additional redirectURI has been successfully added to the list.

Run post installation manually

1. Copy your certificate files (.pfx or .pem) into the cert folder for your installation, for example:
   • ~\ArcGIS\Survey123website\server\cert\
   • If using a .pfx file you will need to encrypt the password by making a request to your installed Survey123 REST API. The response can then be copied into your config.json file (see below).
     • This is done by appending your .pfx password to the API URL using the encrypt?text= parameter, for example:
     • https://<survey123website.domain>:5443/api/encrypt?text=<your_pfx_password>
   • The response will be in the format: {"result":"a6c2812bed063dd9be"}, just copy the result, that is, a6c2812bed063dd9be, for later use in the config.json file.
2. An ArcGIS Enterprise administrator needs to manually add the Survey123 website host URL, for example:
   • https://<survey123website.domain >:5443 - This is the redirectURI to your Portal.  See Steps 1 to 5 in the previous section.
3. Open config.json in a text editor. It can be found in the root folder of the Survey123 website, for example: ~\ArcGIS\Survey123website
   • Update the following parameters according to your requirements:
     • portalUrl: ArcGIS Enterprise URL, for example: https://portal_webadaptorhost.domain.com/portal_webadaptorname
     • arcgisJsAPi3Url: ArcGIS JavaScript v3.x API URL, for example: https://portal_webadaptorhost.domain.com/portal_webadaptorname/jsapi/jsapi/init.js (*Only required for versions before 3.19)
     • arcgisJsApiUrl: ArcGIS JavaScript v4.x API URL, for example: https://portal_webadaptorhost.domain.com/portal_webadaptorname/jsapi/jsapi4/init.js (*Only required for versions before 3.19)
     • httpPort: Survey123 website HTTP port (default is 5080)
     • https.port: Survey123 website HTTPS port (default is 5443)
     • https.cert: path to your Survey123 website HTTPS Base64 Ascii server certificate (.pem) ("./server/cert/cert.pem" is the default).
     • https.key: path to your Survey123 website HTTPS Base64 Ascii server certificate key (.pem) ("./server/cert/key.pem" is the default).
     • https.pfx: path to your Survey123 website HTTPS Binary certificate file (.pfx), for example: "./server/cert/your_certificate.pfx"
     • https.passphrase: encrypted password for your Survey123 website HTTPS Binary certificate. Please use the result from https://<survey123website.domain>:5443/api/encrypt?text=<your_pfx_password> as explained above to get the encrypted password.
4. Save the config.json file.
5. Restart the ArcGIS Survey123 website Windows service and the survey123 service on Linux  for the changes to take effect.

Add Survey123 website in Enterprise Portal App Launcher

1. Copy the Survey123 website Url.
2. Navigate to Portal Home > Content.
3. Choose to Add/Create Item and choose Application.
4. For Application type choose Web Application.
5. Paste the Url from Step 1.
6. Fill in the app details. See: Manage apps in the app launcher
7. Once the Survey123 website is added to Portal Content, navigate to the item details page for it.
8. Copy the Url, for example: https://DOMAIN.COM/PORTALWEBADAPTOR/home/item.html?id=123456789abcdefghi
9. Navigate to Portal Home > Settings > Security > App.
10. Choose to add application and paste the Url from step 8.
11. Edit the necessary details and proceed to add Survey123 website as registered/approved apps.
12. Once these process completed, Survey123 website should shows up in Portal App Launcher.