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:

<server.domain.com> specifies the server that the viewer template is deployed to.
<iis-virtual-directory> is the virtual directory in IIS that the viewer template is deployed to.
<page> is the name of the page to launch, for example, Index.html.
<url-parameters> are the parameters that allow you to control how the viewer launches—the extent that is initially shown, the language that is used, and so on.

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:

configBase: Specify the folder that contains the three different configuration files, and let the viewer detect the type of device and load the appropriate configuration file. The launch links in Manager use the configBase parameter.
viewerConfigUri: Specify which configuration file to load. This parameter overrides the configBase parameter.

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.

We recommend this method because it is both the easiest and the most robust in terms of upgrading the viewer.
Configure a short viewer URL in the ViewerSettings.json.js file.

This method may slightly improve performance but requires manually editing a viewer configuration file. Any changes will also survive after upgrading the viewer. This method overrides the previous method.
Configure a short viewer URL in the Index.html file.

This method offers the greatest performance but is also the most fragile. Any changes must be reapplied after upgrading the viewer. We do not recommend using this method. This method overrides the previous methods.

Configure the Global Unique ID

To configure the Global Unique ID by editing the viewer:

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.
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 ?.
Click Apply Changes.
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:

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

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": ""
        }
    ],
    ...
}

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:

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

In Geocortex Essentials Manager, click the Security & Data tab, expand the Security area in the side panel, and then click Providers.
Click the Edit icon beside the security provider whose issuer seed you want to get.
In the Advanced area, select the issuer seed and copy it.
Click OK to close the dialog box.
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:

URL: Give the viewer's URL to users, so they can type the URL into their browser's address bar.
Hyperlink: Put a hyperlink representing the viewer's URL on a website or other web-connected resource. Users click the hyperlink to launch the viewer.

URL-encode your URLs.
QR Code: Provide a QR (Quick Response) code in a web or print resource. To launch the viewer, users scan the QR code using a mobile device, such as a smartphone or tablet.

To display a QR code for a launch link in Manager, hover the mouse pointer over the QR code icon beside the launch link—the icon will expand into a scannable QR code.