Viewer URLs

URLs (Uniform Resource Locators) are also known as web addresses. For example, http://www.esri.com/ is a URL. A viewer URL is a URL that launches a viewer. In order for a user to launch a viewer, the user must know the viewer's URL, or have access to a hyperlink or QR code that links to the URL.

Geocortex Essentials Manager provides viewer launch links in several places: in the Site List, on the Viewers page, and also on the Viewer Info page for a specific viewer. These links are useful while you are developing and testing a site.

For legibility, URLs and URL parameters are shown unencoded. You should always URL encode your URLs.

Form of a Viewer's URL

The general form of a viewer's URL is:

http://<server.domain.com>/<iis-virtual-directory>/<page>?<url-parameters>

where:

The simplest URL to launch an HTML5 viewer is:

http://<server.mydomain.com>/<iis-virtual-directory>

This launches the default page, Index.html, for an unsecured site. The default page detects the type of device and launches the appropriate interface: Desktop, Tablet or Handheld.

To explicitly launch the Tablet interface for medium-format, touch-screen devices like tablets, use Tablet.html as the <page>. To explicitly launch the Handheld interface for small-format, touch-screen devices like smartphones, use Handheld.html as the <page>.

Determine the Launch URL for a Particular Viewer

To find the URL for a particular viewer, launch the viewer and copy the URL from the browser's address bar. To launch the viewer, click the viewer's Launch URL link in Manager.

Launch URL for an HTML5 viewer, shown on Manager's Viewers page

Note that the viewer URLs that Manager displays are not the full URL—it is just the link text. For example, the full URL for the link shown above is actually:

http://MyServer.com/Html5Viewer/Index.html?configBase=http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/virtualdirectory/Resources/Config/Default

URL Parameters

A URL parameter is a string attached to a URL that specifies initial values or actions. For example, you can use the extent URL parameter to make the map zoom to a particular extent when the viewer is launched. From the end user's point of view, the URL parameter's value is the default value. For example, to the end user, the extent at which the map loads is the default extent.

To specify a URL parameter, you add a question mark to the end of the URL, followed by parameter=value. The general form is:

http://server.domain.com/vwr/Index.html?parameter=value

A URL can have multiple parameters. Parameters are separated by the ampersand character (&). The general form is:

http://server.domain.com/vwr>/Index.html?parameter1=value1&parameter2=value2&...

URL Parameters to Load Configuration Files

For a viewer to launch, the viewer must load a configuration file. If you know what type of device the end user will be using, you can specify which configuration file to load. If the viewer will be launched on different types of devices, you can let the viewer detect the device type and load the appropriate configuration file.

The viewer launch URL has two parameters that you can use to tell the viewer how to locate the configuration file to load:

Example

In this example, the Handheld interface of the LA_County site's LA_County_HTML viewer launches in Canadian French with debugging turned on. The site is not secured.

http://server.domain.com/vwr/Handheld.html?configBase=http://server.domain.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default&locale=fr-CA&debug=true

URL Parameters Reference

For legibility, URLs and URL parameters are shown unencoded. You should always URL encode your URLs.

URL Parameters that can be used in HTML5 Viewer launch URLs

center

Specifies the coordinates at which to center the map when the map image loads. If you want to specify the coordinates using a different spatial reference than the map's, append the WKID that you want to use.

Syntax: ?center=x,y or ?center=x,y,wkid

Example 1: In this example, the map pans to center on the specified map coordinates when the viewer is launched.

http://MyServer.com/Html5Viewer/Index.html?center=-13176043.9862,4002474.5385

Example 2: In this example, the coordinates are given in the specified spatial reference (WKID 4326) instead of the map's spatial reference. When the viewer is launched, the map is reprojected to WKID 4326 and then pans to the specified coordinates.

http://MyServer.com/Html5Viewer/Index.html?center=-114.7993,30.9820,4326

Example 3: In this example, the center parameter is used with the scale parameter. The center parameter ensures that the map is centered over the desired features. The scale parameter ensures that the map is zoomed to a scale at which the features are visible.

http://MyServer.com/Html5Viewer/Index.html?center=255421.6566,b6250846.4361,3857&scale=9000

Module: Map Module

configBase

Specifies the URI of the folder where the configuration files are stored. The viewer detects the device type and loads the appropriate configuration file from the specified folder. Use a fully qualified URI.

This URL parameter is useful if the viewer will be launched on different device types.

You can force the viewer to load a particular configuration file even though it uses configBase. This is useful when you are developing and testing your viewer.

Syntax: ?configBase=uri, where uri is the URI to the folder containing the configuration files

Example 1: This example launches the LA_County site's LA_County_HTML viewer and loads the appropriate configuration file for the device type. This is how you would use configBase in a production viewer.

http://MyServer.com/Html5Viewer/Index.html?configBase=http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default

Example 2: This example launches the LA_County site's LA_County_HTML viewer and loads the Handheld configuration file. This is how you can view the Handheld interface on your desktop computer when you are testing the viewer.

http://MyServer.com/Html5Viewer/Handheld.html?configBase=http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default

Module: None

debug

Logs additional types of event to the viewer's log file, and lists commands executed and events fired in the console. If you do not want additional logging turned on, omit the debug parameter from the URL.

Syntax: ?debug

Example: This example turns on additional logging for the viewer.

http://MyServer.com/Html5Viewer/Index.html?debug

Module: Log Module

extent

Zooms the map to the specified map coordinates. If you want to specify the coordinates using a different spatial reference than the map's, append the WKID that you want to use.

Syntax: ?extent=minX,minY,maxX,maxY  or  extent=minX,minY,maxX,maxY,wkid

Example 1: In this example, the map zooms to the specified map coordinates when the viewer is launched.

http://MyServer.com/Html5Viewer/Index.html?extent=1441172.484,550015.006,1456136.010,537754.744

Example 2: In this example, the coordinates are given in the specified spatial reference (WKID 4326) instead of the map's spatial reference. The map zooms to the specified latitude/longitude coordinates when the viewer is launched.

http://MyServer.com/Html5Viewer/Index.html?extent=35.2468,-80.8718,35.2139,-80.8210,4326

Module: Map Module

layerTheme

Specifies the layer theme to use when the viewer launches. You can specify the layer theme either by its ID or by its Display Name.

Syntax: ?layerTheme=MyLayerTheme, where MyLayerTheme is either the ID or the Display Name of the layer theme.

Example 1: In this example, the viewer launches using a layer theme with the ID, 0.

http://MyServer.com/Html5Viewer/Index.html?layerTheme=0

Example 2: In this example, the viewer launches using a layer theme with the Display Name, Imagery.

http://MyServer.com/Html5Viewer/Index.html?layerTheme=Imagery

Module: LayerThemes Module

locale

Specifies the language to use for the viewer. For this parameter to work, a language file for the specified language must exist and be configured in the viewer configuration. See Geocortex Viewer for HTML5 Translation for instructions.

By default, viewers display date/time and number data in the user's locale. The locale parameter overrides the end user’s locale preference. See Format Date/Time Fields information.

Syntax: ?locale=xx-YY, where xx-YY is the language tag of the language file

The language code for xx is from the ISO 639-1 standard. The country code for YY is from the ISO 3166-1 standard.

Example: In this example, the viewer launches in Canadian French, provided the fr-CA language file exists and is configured.

http://MyServer.com/Html5Viewer/Index.html?locale=fr-CA

Module: None—locale is an application-wide setting

project

Specifies a project to load when the viewer launches. The project parameter is used in the Project URL that the viewer displays to end users so they can share the project with other users.

Projects belong to the site of the viewer that created the project. A user cannot create a project in one viewer and then load the project in a viewer that belongs to a different site.

Syntax: ?project=id, where id is the ID of the project to load

You can find out a project's ID by viewing the project’s details on Manager's Data Store - Documents page. For information, see Geocortex Data Store.

Alternatively, you can get the project's ID from the Project URL that shows on the viewer's Share Project panel. See Sharing Projects for information.

Example: This example launches the LA_County_HTML viewer and loads the project with ID 45ca42175c554a1e82c9a63cb3d570b3:

http://host.domain.com/Html5Viewer/Index.html?viewer=LA_County.LA_County_HTML&project=45ca42175c554a1e82c9a63cb3d570b3

Module: Project Module

run or runWorkflow

Runs the specified workflow(s), mapping URL parameters to workflow input arguments. The run and runWorkflow URL parameters perform the same function.

If you specify more than one workflow to run, the workflows run concurrently. Each additional workflow must be separated by a comma (,).

Workflows specified with the run or runWorkflow parameters will conflict if they target the same container in the viewer. A similar problem occurs if multiple workflows attempt to set the map extent or a layer's visibility.

If the workflow has arguments, you specify the arguments the same way you would specify additional URL parameters (name=value, with & separators). You must use the argument name as the parameter name. If an argument is optional, you can include it in the URL, or omit it.

Syntax: These two forms run workflows that do not have arguments:

&run=workflowId1,workflowId2,...  or 
&runWorkflow=workflowId1,workflowId2,
...

These two forms run the specified workflow with the specified arguments (arg1, arg2, ...).

&run=workflowId&arg1=value1&arg2=value2&...  or 
&runWorkflow=workflowId&arg1=value1&arg2=value2&
...

Example 1: In this example, the URL that you make available to end users launches the viewer and runs the workflow with ID "StartupWorkflow". StartupWorkflow does not have any arguments.

http://MyServer.com/Html5Viewer/Index.html&runWorkflow=StartupWorkflow

Example 2: This example runs the FindParcel workflow. The FindParcel workflow finds the specified parcel, and then optionally runs a report using the parcel's information. The workflow's two arguments are:

  • pid: (required) The ID of the parcel to find.

  • reportToRun: (optional) The ID of a report that reports parcel information.

http://MyServer.com/Html5Viewer/Index.html&run=FindParcel&pid=02503116&reportToRun=MailingLabels

Example 3: This example runs the same FindParcel workflow as the previous example, except the optional reportToRun argument is omitted. In this case, the workflow finds the specified parcel, but does not run a report.

http://MyServer.com/Html5Viewer/Index.html&run=FindParcel&pid=02503116

Module: Workflow Module

scale

Specifies the initial scale. The scale parameter takes the scale's denominator as its value. If the map does not have the specified scale, the nearest available scale is used.

Syntax: ?scale=value, where the scale is 1:value

Example 1: In this example, when the viewer launches, the map zooms to the scale nearest to 1:2654.7813.

http://MyServer.com/Html5Viewer/Index.html?scale=2654.7813

Example 2: In this example, the scale parameter is used with the center parameter. This ensures that the map is zoomed and panned to show the desired view.

http://MyServer.com/Html5Viewer/Index.html?center=255421.6566,6250846.4361,3857&scale=9000

Module: Map Module

viewer

Specifies the ID of the viewer to launch. The value to use for the viewer parameter generally matches the Global Unique ID of the viewer. However, there are alternative ways to set up the value to use for the viewer parameter. For more information, see Short Viewer URLs.

As the name suggests, the Global Unique ID must be unique for each viewer across all sites and instances of Essentials.

The Global Unique ID must not contain special characters such as <, >, %, &, :, *, \, / and ?.

If you do not set the Global Unique ID, all viewers use the default Global Unique ID, which consists of the Site ID and the Viewer ID separated by a period character. For example, http://MyServer.com/Html5Viewer/index.html?viewer=MySiteID.MyViewerID.

Syntax: ?viewer=MyViewer

Example: In this example, the viewer whose Global Unique ID is MyViewer is launched by the following URL:

http://MyServer.com/Html5Viewer/Index.html?viewer=MyViewer

The Global Unique ID is set by editing the viewer, on the Viewer Info page.

Module: None

viewerConfigUri

The viewerConfigUri property has been deprecated.

Specifies the URI of the configuration file to load. We recommend using a fully qualified URI. The configuration file must be on the same domain as the viewer. This parameter overrides the configBase parameter.

This URL parameter is useful if you know the type of device that the end user will be using. If you do not know the device type, use the configBase URL parameter instead.

Syntax: ?viewerConfigUri=uri, where uri is the URI to the configuration file

Example: This example launches the LA_County site's LA_County_HTML viewer using the Handheld interface:

http://MyServer.com/Html5Viewer/Index.html?viewerConfigUri=http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/Handheld.json.js

Because you are specifying which configuration file to load, you could use the corresponding HTML page—Tablet.html for Tablet.json.js, or Handheld.html for Handheld.json.js—instead of Index.html. This is optional.

Module: None

Short Viewer URLs

You can set up a short launch URL for a particular viewer that has the form:

http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer

There are a few different ways to set up the value for the viewer parameter:

Configure the Global Unique ID

To configure the Global Unique ID by editing the viewer:

  1. In Geocortex Essentials Manager, edit the viewer that you want to configure—edit the site that the viewer belongs to, click Viewers in the side panel, and then click the Edit icon beside the viewer.

  2. On the Viewer Info page, type any value without special characters for Global Unique ID. For example, MyViewer.

    As the name suggests, the Global Unique ID must be unique for each viewer across all sites and instances of Essentials.

    The Global Unique ID must not contain special characters such as <, >, %, &, :, *, \, / and ?.

  3. Click Apply Changes.

  4. Click Save Site.

    The Launch in Browser link now contains the short launch URL in the form of:

    http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer

    where the viewer parameter is the same value as the Global Unique ID of the viewer.

    If you do not set the Global Unique ID, all viewers use the default Global Unique ID, which consists of the Site ID and the Viewer ID separated by a period character. For example, http://MyServer.com/Html5Viewer/index.html?viewer=MySiteID.MyViewerID.

Configure a Short Viewer URL in the ViewerSettings.json.js File

To configure a short viewer URL in the ViewerSettings.json.js file:

  1. In the root folder where the HTML5 Viewer is installed, open the ViewerSettings.json.js file in a text editor. The default location is:

    C:\inetpub\wwwroot\Html5Viewer\ViewerSettings.json.js

    You may need to run your text editor as an Administrator to modify this file.

  2. For each viewer, do one of the following:

    • To configure a short launch link for any interface, in the viewerSettings array, add a new object with the following properties.

      The viewerConfigUri property has been deprecated.

      {
          "viewerSettings": [
              {
                  "id": "MyViewer",
                  "url": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/",
                  "securityUrl": ""
              }
          ],
          ...
      }
      

      Set id to any value without special characters you want to use for the viewer parameter.

      Set url to the folder containing the viewer configuration files.

      If the site is secured, set the optional securityUrl property to the Essentials sign-in URL. For example:

      http://MyServer.com/Geocortex/Essentials/REST/security/signin?token_type=fragment&app=

    • To configure a short launch link for a specific interface such as the Handheld interface, in the viewerSettings array, add a new object with the following properties:

      {
          "viewerSettings": [
              {
                  "id": "MyViewer",
                  "viewerConfigUri": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/Handheld.json.js",
                  "securityUrl": ""
              }
          ],
          ...
      }
      

      Set id to any value without special characters you want to use for the viewer parameter.

      Set viewerConfigUri to the location of a specific viewer configuration file.

      If the site is secured, set the optional securityUrl property to the Essentials sign-in URL. For example:

      http://MyServer.com/Geocortex/Essentials/REST/security/signin?token_type=fragment&app=

  3. If you want the viewer to use a custom splash screen image, add the splashScreenUrl property to the viewerSettings object. Set splashScreenUrl to the image's fully qualified URL.

    When you configure the short URL in the ViewerSettings.json.js file, you must configure the custom splash screen image in the ViewerSettings.json.js file instead of in Manager.

    {
        "viewerSettings": [
            {
                "id": "MyViewer",
                "url": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/",
                "splashScreenUrl": "http://host.domain.com/resources/images/splash-image.png"
                "securityUrl": ""
            }
        ],
        ...
    }
    
  4. Save the file.

    You can use the following URL to launch the viewer: 

    http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer

Configure a Short Viewer URL in the Index.html File

To configure a short viewer URL in the Index.html file:

  1. In the root folder where the HTML5 Viewer is installed, open the Index.html file in a text editor. The default location is:

    C:\inetpub\wwwroot\Html5Viewer\Index.html

    You may need to run your text editor as an Administrator to modify this file.

  2. For each viewer, do one of the following:

    • Within the ViewerInitializationOptions object passed into the ViewerLoader's loadAndInitialize() method, add a new property to the aliases property:

      new geocortex.essentialsHtmlViewer.ViewerLoader().loadAndInitialize({
          aliases: {
              default: "Resources/Config/Default/" + shellName + ".json.js",
              MyViewer: "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/virtualdirectory/Resources/Config/Default/" + shellName + ".json.js"
          }
      });
      

      Set the name of the new property to the ID you want to use for the viewer parameter.

      Set the value of the new property to the location of the viewer configuration file. The shellName variable allows the viewer to load different configuration files for each type of interface: Desktop, Tablet or Handheld.

      Viewers defined using this method override viewers defined using the following alternative method.

    • Within the viewerConfig variable, add a new property to the configurations property:

      var viewerConfig = {
          "configurations": {
              "default": "Resources/Config/Default/" + shellName + ".json.js",
              "MyViewer": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/virtualdirectory/Resources/Config/Default/" + shellName + ".json.js"
          },
          "viewerConfigUri": null
      };
      

      Set the name of the new property to the ID you want to use for the viewer parameter.

      Set the value of the new property to the location of the viewer configuration file. The shellName variable allows the viewer to load different configuration files for each type of interface: Desktop, Tablet or Handheld.

    The configuration files must be on the same domain as the viewer.

  3. Save the file.

    You can use the following URL to launch the viewer: 

    http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer

URLs for Secured Sites

You do not need a different URL to access a secured site—you can use a regular viewer URL, as described above in Form of a Viewer's URL. However, you can improve a viewer's launch performance by using a URL that links directly to the sign-in page. A direct link skips the steps required for the viewer to determine whether the site is secured.

When you link directly to the sign-in page, you pass the viewer's URL as a parameter. This ensures that the user's browser can be correctly directed to the viewer after the user has authenticated.

The general form for a URL that links directly to the sign-in page is:

http://server.domain.com/(Undefined variable: GE.Geocortex)/Essentials/REST/security/signIn?[url-parameters]

For legibility, URLs and URL parameters are shown unencoded. You should always URL encode your URLs.

URL Parameters for Sign-in Page URLs

The table below lists the parameters that you can use in sign-in page URLs.

URL Parameters for Sign-in Page URLs

app

The URL of the web application (viewer) to launch after the user has authenticated.

The app parameter is required. The URL specified in the parameter should be URL encoded. The URL can have URL parameters.

Syntax: app=url

idp

The security provider to use for authentication.

Some security providers are identified using a predefined value. Other security providers are identified by the security provider's unique issuer seed. For information, see Find the Value for the idp URL Parameter below.

The idp parameter is optional. If you omit the idp parameter, the user's browser redirects to a page that lists the security providers for that site, and the user selects the security provider to sign in with.

Syntax: idp=security-provider-identification

token_type

Required in viewer URLs that link directly to the sign-in page.

Syntax: token_type=fragment

Find the Value for the idp URL Parameter

The idp URL parameter identifies the security provider to use for authentication. The table below lists the values for different security providers. For Geocortex Identity Server and ArcGIS Online security providers, you need the security provider's issuer seed. Instructions for getting the issuer seed are given below the table.

Values to Use for the idp URL Parameter

Security Provider

Value

Example

Windows Integrated

AD AUTHORITY

idp=AD AUTHORITY

Anonymous Access

urn:gcx:guest

idp=urn:gcx:guest

Geocortex Identity Server

urn:gcx:idp:[issuer-seed]

idp=urn:gcx:idp:2895BE5E-FA19-4731-82F1-33F5FE30F786

ArcGIS Online

urn:gcx:ags:[issuer-seed]

idp=urn:gcx:ags:b2e2357d-84e8-4406-94aa-e34b798d1a98

Determine a Security Provider's Issuer Seed

To get the issuer seed for a security provider:

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

  2. Click the Edit icon  beside the security provider whose issuer seed you want to get.

  3. In the Advanced area, select the issuer seed and copy it.

  4. Click OK to close the dialog box.

  5. Paste the issuer seed in the URL's idp parameter.

Example 1 - URL for an HTML5 Viewer and Windows-Secured Site

Suppose you have a site that is secured using the Windows Integrated security provider. The URL below performs the authentication using Windows Authentication, and then launches the HTML5 viewer called MyViewer.

http://server.domain.com/Geocortex/Essentials/REST/security/signIn?token_type=fragment&idp=AD+AUTHORITY&app=http://server.domain.com/viewers/Index.html?Viewer=MyViewer

Example 2 - URL for an HTML5 Viewer and Site that is Secured Using ArcGIS Online

Suppose you have a site that is secured using ArcGIS Online. The URL below performs the authentication using ArcGIS Online, and then launches the HTML5 viewer called mobile in the Handheld interface.

http://server.domain.com/Geocortex/Essentials/REST/security/signIn?token_type=fragment&idp=urn:gcx:ags:9b567ddc-27ab-4321-b968-570df7b53bfe&app=http://server.domain.com/gvh/Handheld.html?Viewer=mobile

Publish Viewer URLs

As the application administrator, you must provide users with a way to launch the viewer. There are different ways to do this: