English

How To: 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, the initial release officially supports 10.7 and later version only.

Procedure

Installation
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.

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).

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 (the installation points to ArcGIS Online by default)
  • ArcGIS Portal Admin Credentials (needed to set the redirect URI for Portal sign-in)
  • ArcGIS JavaScript API (required for disconnected environments)
  • HTTP(s) ports
  • SSL certificate(s)
  • Survey123 website host URL (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\dist\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.com>: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.com>: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.com/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.com/survey123
  6. Repeat Step 2 to confirm that your additional redirectURI has been successfully added to the list.

Run post installation manually

  1. From a browser on your Survey123 website server, go to https://localhost:5443/api/setupPyxform. You should get a "success":true response. This process is run automatically when using the post installation wizard.
  2. Copy your certificate files (.pfx or .pem) into the cert folder for your installation, for example:
    C:\Program Files\ArcGIS\Survey123website\server\dist\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://localhost: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.
  3. An ArcGIS Enterprise administrator needs to manually add the Survey123 website host URL, for example:
    https://<survey123website.domain.com>:5443 - This is the redirectURI to your Portal.  See Steps 1 to 5 in the previous section.
  4. 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 your 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 your Survey123 website host URL. For example:
      https://<survey123website.domain.com>:5443
    3. Click Add domain. This allows your Survey123 web application domain to connect via (CORS) to the ArcGIS REST API.
  5. Open config.json in a text editor. It can be found in the root folder of the Survey123 website, for example:
    C:\Program Files\ArcGIS\Survey123website
    1. 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
      • arcgisJsApiUrl: ArcGIS JavaScript v4.x API URL, for example:
        https://portal_webadaptorhost.domain.com/portal_webadaptorname/jsapi/jsapi4/init.js
      • 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/dist/cert/cert.pem" is the default).
      • https.key: path to your Survey123 website HTTPS Base64 Ascii server certificate key (.pem) ("./server/dist/cert/key.pem" is the default).
      • https.pfx: path to your Survey123 website HTTPS Binary certificate file (.pfx), for example:
        "./server/dist/cert/your_certificate.pfx"
      • https.passphrase: encrypted password for your Survey123 website HTTPS Binary certificate. Please use the result from https://localhost:5443/api/encrypt?text=<your_pfx_password> as explained above to get the encrypted password.
    2. Save the config.json file.
    3. Restart the ArcGIS Survey123 website Windows service for the changes to take effect.

Related Information

Last Published: 8/20/2020

Article ID: 000023966

Software: ArcGIS Survey123 3.9, 3.8, 3.7, 3.6, 3.5, 3.4, 3.3, 3.2, 3.1, 3.0, 2.9.Classic, 2.8 Portal for ArcGIS 10.8.1, 10.8, 10.7.1, 10.7