URL Parameters for VertiGIS Studio Web Apps

Topic:

When launching a VertiGIS Studio Web app there are some out of the box URL parameters available that can be used to change the app's behaviour. There is the additional ability to use arbitrary URL parameters that can be consumed by a workflow on app initialization - separate from existing options for configuring a launch link workflow with parameters. Finally, there are two parameters available for changing how an app loads in the app designer interface. The following guide provides a walkthrough of configuring parameters for the listed situations with examples.

Guide:

The guide is separated into the following sub-sections:

App Parameters

Using a Workflow with the Parse URL Activity

Launch Link Workflows

App Designer Parameters

App Parameters:

At the most basic an app will have a unique launch link with the parameter that identifies the app itself:

• app=
  •  ex. app=af9b903746724d289b1a4fc087d6f80a where the expected value is the alphanumeric item ID for the app item in your ArcGIS Portal or ArcGIS Online.

The Social Sharing feature introduced in VertiGIS Studio Web 5.12 provided the "Get Sharing Link" command and the following URL parameters:

• scale-<Map Extension ID>=
  • ex. scale-default=5000 where the expected value is a numerical scale.
  • note: the scale parameter only works when it is accompanied by the center parameter
• center-<Map Extension ID>=
  • ex. center-default=-13733546.804885864,6177341.583529942 where the expected value is a coordinate pair for your map.
  • note: the center parameter only works when it is accompanied by the scale parameter
• basemap-<Map Extension ID>=
  • ex. basemap-default=69aea2b5-3ad2-4f11-9800-17fa628b6c66 where the expected value is the alphanumeric ID of a basemap extension object in the web app. 
    • 
• layers-<Map Extension ID>=
  • ex. layers-default=1,2 where a blank value loads the default webmap layer visibility, and including the zero based index value of a particular layer (counting up from the bottom of the layer list) toggles the visibility.

Put together into a single link they would look as follows below. Note in this example the map extension ID in the app is 3e85d9e8-4ec0-4732-a112-1973f1665fd0, and not default as it was in the examples provided from the bulleted list above.

https://apps.vertigisstudio.com/web/?app=9147d8afb59c4e8293791baec8f7a46c&scale-3e85d9e8-4ec0-4732-a112-1973f1665fd0=4514&center-3e85d9e8-4ec0-4732-a112-1973f1665fd0=-13733546.804885864%2C6177341.583529942&basemap-3e85d9e8-4ec0-4732-a112-1973f1665fd0=0f22908d-e70d-436f-8957-ede3b19e0d5a&layers-3e85d9e8-4ec0-4732-a112-1973f1665fd0=2

The link above will launch the VertiGIS Studio Sample App with a particular scale and center, the same basemap as normal, and with the Water Lines layer toggled off (it is on by default in the source webmap).

Note: To get the map extension ID, select the Map component in Web Designer and use the gear icon near the top-right of the page to view the component's Model URI. The ID is at the end of the Model URI.

Instead of relying on automatic detection of the browser locale for an internationalized app, you can add a parameter to the end of a launch URL to force a particular language:

• locale=
  • ex. locale=fr where the expected value is a 2 letter language code - fr for french in this case.

If you are debugging an app in the end-user app view then you can add the following parameter: 

• debug=true
  • Forces more detailed logging in the browser console.
  • Forces an app to get a fresh copy of a workflow on each run, removing any need to refresh the browser if changes are made to the workflow.
    • Note that if you are debugging workflows in the app designer (not end-user app view) then the above behaviour is true by default without the additional parameter being specified.

Using a Workflow with the Parse URL Activity:

Using the Get Browser Info and Parse URL activities in VertiGIS Studio Workflow it is possible to parse arbitrary URL parameters. In the example shown below there is a workflow that uses these activities to extract the 'title' and 'text' query parameters from an app's URL:

https://apps.vertigisstudio.com/web/?app=1c56e08072fe4d62ab075db9887bb409&title=Here%27s%20a%20Title&text=Hello%20World 

In the example the parsing is triggered by the button click of the workflow on the toolbar, but the workflow could equally as well be executed on app or map initialization depending on what actions the workflow subsequently performs - keeping the overall app initialization sequence in mind.

Launch Link Workflows:

This Knowledge Base Article provides an in-depth walkthrough of how to configure a launch link workflow and the associated parameters:

https://support.vertigis.com/hc/en-us/articles/15410305075730-Use-Launch-Link-Workflows-to-Modify-App-UI-at-Startup 

And the following is an example URL from the above walkthrough demonstrating how parameters are added for a launch link workflow:

https://apps.vertigisstudio.com/web/?app=d19d04834fa94971b999290a6bda1bdd&workflow=1e7e2be2-ac0f-4f4a-9826-d15b05057259&workflowParams={"parkUse":"camping"}

• workflowParams=
  • ex. workflowParams={"parkUse":"camping"} where the expected value is a JavaScript object with key value pairs that can be used in the launch link workflow.
  • values used in workflowParams can be retrieved later by the Get Workflow Inputs activity.

We also have some more general documentation on the topic:

• Launch Link Workflows
• Get an App Launch Link that Runs a Workflow 

App Designer Parameters:

VertiGIS Studio Web 5.28 added escape query string parameters to help with troubleshooting issues where the app errored on initialization, and prevented further configuration through the app designer interface.

• preview=false
  • Disables the preview of your web app in the app designer.
• pinpoint=false
  • Disables pinpoint search in the app designer.

Example usage: https://apps.vertigisstudio.com/web/designer/?preview=false#app=1c56e08072fe4d62ab075db9887bb409

Article last updated for VertiGIS Studio Web 5.28.1