Summary

VertiGIS Studio Web has hundreds of commands and operations.  Many of them provide new or different functionality compared to workflow activities.  Workflows running in Web apps can use the Run Command and Run Operation activities to call on these commands and operations, expanding the tasks workflow is capable of doing.

There is a Commands and Operations Reference guide in the developer center, but it doesn't have many workflow-specific examples or screenshots, since it is not written exclusively for workflow authors.  This article will provide supplementary guidance for using Web commands and operations in workflows, including screenshots, examples, and strategies specifically for workflow authors.

Contents

• Concepts
  • Where to Find the Documentation
  • Chaining Operations Together
  • What to Expect from the Documentation
    • Argument Types
• Getting Values for Arguments
  • Getting Values from Workflow Activities
  • Getting "Extension" References from a Web App
    • LayerExtension or SublayerExtension
    • MapExtension
    • BasemapExtension
  • Getting Model references from a Web App
  • Getting "Features" or "Results"
    • Using results.from-graphics
    • Using Get Workflow Inputs to Get a Selection from the Web App
  • Getting Command-Specific Arguments
    • Example 1 (simple) - ZoomToScaleArgs
    • Example 2 (longer but simple) - DisplayNotificationArgs
    • Example 3 (complex) - DisplayUpdateFeatureArgs
    • Example 3b (more complex) - Using an Argument Definition within an Argument Definition
• Getting Assistance
• Additional Examples

Concepts

Where to Find the Documentation

Commands and operations are both listed on the same page at https://developers.vertigisstudio.com/docs/web/api-commands-operations. Commands are listed on the first half, and operations are listed after.  There are navigation links in the top-right corner of the page to skip between those 2 sections.  

Chaining Operations Together

The difference between commands and operations is that operations produce an output.  The outputs of operations can be used as inputs in other commands, operations, or workflow activities. 
In practice you will often need to string 2 or more operations and commands together to accomplish some tasks.  The out-of-the box commands that Web Designer presents are called "standard commands", and many of them actually use several commands and operations in sequence.

For example, the "standard" Identify command uses a chain of 2 operations (sketching.capture-geometry and tasks.identify) and 3 commands (results.display, charts.display, and kpi-cards.display).  Clicking the "Customize" button after setting the command in Web Designer reveals this:

When operations are listed in sequence like this in Web, the output of each operation is automatically passed along to any of the commands or operations listed afterwards.  In the example above, the outputs of tasks.identify are automatically passed along to the results.display, charts.display, and kpi.display commands. 

To reproduce the same functionality in Workflow, you would use 2 Run Operation activities and 3 Run Command activities like this:

Outputs are not passed along automatically in workflows like they are in Web.  To pass the outputs of tasks.identify along to the Run Command activities in the example above, you'd need to set the "Command Parameter" input on those activities.

What to Expect from the Documentation

For each command, the Commands and Operations Reference guide lists:

1. The command name.  Eg. map.apply-layer-preset
2. A description of what the command does.  Eg. "Applies a LayerPreset to the map(s). Web only."
   • Note: if a description says "Web only" like this example, that means the command can't be used in VertiGIS Studio Mobile.
3. The argument(s) the command accepts Eg. "ApplyLayerPresetArgs"
   • this refers to the type of object that the command needs to receive as an input
   • If many types are listed, only one needs to be used. You can pick which one to use from the list of options.
   • many arguments include a link to their definition

Additionally:

• Some commands have examples listed
  • Examples might demonstrate a whole command chain formatted for Web Designer (like the one for map.edit-note), or just the argument part (like the one for query-builder.display-query).  Generally if the example is a whole command chain formatted for Web Designer, you will see the command name repeated somewhere inside the example, like in the screenshot above.
• Operations will also list a "Result", which lets you know what type of object the operation will return

When translating this information to a Run Command activity, the name (1) should be used for the "Command Name" input, and an object matching the type listed as the argument (3) should be used for the "Command Parameter" input.

Argument Types

Arguments types can be many things, including:

• objects from the Esri JavaScript SDK
  • these usually have a reference starting with "@arcgis.core", eg. @arcgis.core.geometry.Extent
• objects from the Esri REST API
  • these usually have a reference starting with "@esri.rest-api", eg. @esri.rest-api.FeatureJson.FeatureJson
• "extensions" that reference configuration from an individual VertiGIS Studio Web app
  • these usually have names ending in Extension, eg. LayerExtension
• other parts of an individual VertiGIS Studio Web app, eg. Model
• other objects from the VertiGIS Studio Web API, eg. Features
• types that exist exclusively for command and operation arguments
  • these often have names ending in "Args" or "Json", eg. ZoomToFeaturesArgs
  • clicking one of these leads to the "Argument Definition Reference" page in the developer center
• types that are produced exclusively by operations
  • these often have names ending in "Result", eg. CreateGraphicsResult
  • clicking one of these leads to the "Argument Definition Reference" page in the developer center
• basic types like string, number, or boolean, to denote something simple like an ID or a true/false value
• a list of exact string values that can be used
  • These will be separated by "|" characters, eg. "feet" | "kilometers" | "meters" | "miles" | "nautical-miles" | "yards"
• arrays of any of the above
  • these can be any of the above, suffixed with "[]"

Getting Values for Arguments

If you know which command you want to run in your workflow, your next step should be to figure out how you will get an acceptable value for the arguments.  You should consider:

• are any of the argument options simple types (eg. string, number, or boolean), that can just be written manually?
• are any of the argument options possible to get from a workflow activity?
• are any of the argument options possible to get from an operation?
  • will you be able to get acceptable values for that operation's arguments too?
• are any of  the argument options possible to get from Web Designer?
• do any of the options provide more control than the others?  Is that level of control necessary for the task at hand?

Getting Values from Workflow Activities

Some objects used for command arguments can be obtained from workflow activities.  In most cases, these are objects from the Esri JavaScript api.  Here are the most commonly used ones:

Getting "Extension" References from a Web App

Some command arguments will use extensions.  These can be obtained from Web Designer.

LayerExtension or SublayerExtension

1. Open the app in Web Designer
2. Select the Map component
3. In the Layer Extensions section, click the layer or sublayer of interest.  If it is inside a group, you will need to click the group first, then click the layer inside the group
4. In the top-right corner of the page, click the gear icon
5. Copy the "Model URI" value.  Use that string value for the argument or property where a LayerExtension or SublayerExtension is needed

Example for the map.remove-filter-effects command

MapExtension

1. Open the app in Web Designer
2. Select the Map component
3. In the top-right corner of the page, click the gear icon
4. Copy the "Model URI" value.  Use that string value for the argument or property where a MapExtension is needed

Example for the highlights.clear command

BasemapExtension

1. Open the app in Web Designer
2. Use File > Download App
3. Unzip the file and open the app.json file in a text editor like Notepad
4. Search the file (eg. using CTRL+F) for the name of your basemap
5. Copy the ID of the language string that the search finds
6. Run another search on the language string ID
7. Copy the "id" value from the basemap-extension config where the language string is found
8. Use a string comprised of "item://basemap-extension/" + your id, for the argument or property where a BasemapExtension is needed

Example for the basemap.set command

Getting "Model" References from a Web App

Some commands will list both "Model" and "string" as Argument options. These tend to be commands that target specific components inside an app's layout.

Eg.

Similar to "Extensions", this can be obtained from Web Designer:

1. Open the app in Web Designer
2. Select the component that you want the command to target
3. In the top-right corner of the page, click the gear icon
4. Copy the "Model URI" value.  Use that string value for the argument or property where a Model is needed.

This example runs ui.deactivate (aka "Hide") to hide an app's legend component:

Getting "Features" or "Results"

Some commands, like results.display-details or results.convert-to-xlsx will list "Features" or "Results" as an argument option.  You might expect that the Query Layer activity produces this type of object.  But Query Layer technically returns Esri Graphics and FeatureSets, which are different from VertiGIS Studio Features and Results.

The 2 most common ways to get "Features" or "Results" are either converting Esri Graphics using the results.from-graphics operation, or running the workflow as a feature action so that it passes along the user's existing selection from the results component.

Using results.from-graphics

1. Add an activity that returns Esri features (Graphics).  For this example we'll use Query Layer.
2. Configure Query Layer with the necessary inputs to find the features you need
3. Add a Run Operation activity.
   • set the Operation Name to: results.from-graphics
   • configure the Operation Parameter to use an object with a "graphics" property containing the "features" output from the Query Layer activity, like this: ={graphics:$query1.features}
4. Use that Run Operation activity's output (ie. =$runOperation1.result) in the Run Command activity where a Features or Results-type argument is needed.

Using Get Workflow Inputs to Get a Selection from the Web App

This option is only available if you want to have users run the workflow through a result action.  Ie. the end-user will use tools like Identify or Search to make a selection, then they will use a menu in the results list or a button in the results details to run the workflow on that selection.

1. Open your app in Web Designer
2. Select the Map component
3. In the Layer Extensions section, click the layer or sublayer of interest.  If it is inside a group, you will need to click the group first, then click the layer inside the group.
4. In the Result Actions section, click the "+Add Menu Item" button, and select your workflow
5. In Workflow Designer, add a Get Workflow Inputs activity
6. In the Run Command activity where you need the "Features" or "Results" argument, use the "context" value from the Get Workflow Inputs activity. Eg. =$getWorkflowInputs1.inputs.context

Note: $getWorkflowInputs1.inputs.context will contain the selected feature or features from the results component where the workflow is being run.  The Use a Workflow's Inputs in the Workflow documentation has more information on the topic of using the "context" property this way.

Configuration example:

This is how the end-user will run the workflow:

Getting Command-Specific Arguments

Some argument types are exclusive to commands and operations.  These often have names ending in "Args" or "Json".  They are defined in the Argument Definition Reference page.

Eg.

For this type of argument you will need to click the link to open the argument definition, then use that as a guide to build an object in workflow.  This is the rough format to use for the "Command Parameter" input in your workflow:

={
  propertyName1: <insert value here>,
  propertyName2: <insert value here>,
  propertyName3: <insert value here>
}

The argument definition will list the names of the properties you can include, and the types that can be used for their values.  Just like the Arguments sections in the Commands and Operations Reference, some properties may list more than one type.  In those cases you can choose which one to use.

If a property says "required", then it is necessary to include it.  If it does not say "required", it can usually be omitted.  It's important to read through each property description carefully though, because exceptions to this rule may be noted.  Eg.

Example 1 (simple) - ZoomToScaleArgs

This is an example for how to write a ZoomToScaleArgs object in workflow.  ZoomToScaleArgs is the argument type used by the map.go-to-scale command, which lets you zoom to a specified scale without playing a zoom animation along the way.  Here is the definition:

There are only 2 properties.  Reviewing those properties:

• maps seems okay to omit in most cases. It does not say "required", and from the description it seems like it is only relevant if our Web app has more than one map.
• scale is required.  Its type is just "number", so we don't have to use a workflow activity, operation, or extension from Web Designer to get a value for it.

We can write the "Command Parameter" input as:

={
  scale: 1000
}

Example 2 (longer but still simple) - DisplayNotificationArgs

This is an example for how to write a DisplayNotificationArgs object in workflow.  DisplayNotificationArgs is the argument type used by the ui.display-notification command, which lets you display a small message on the map.  Unlike an Alert, it does not temporarily block the user from using the map. 

For this example, let's say we have a workflow that is going to run a "sketching.capture-geometry" operation to have the user draw a polygon on the map.  We've decided to run a ui.display-notification command right before this operation, to inform the user that they will need to draw on the map in order to proceed.  ui.display-notification is a good fit for this scenario because the notification is eye-catching, but the user does not need to close it to start drawing like they would with an Alert.

Here is the definition:

The definition has a lot of properties, but most of their types are simple: strings and booleans.  We can write these without having to retrieve values from another workflow activity, operation, or extension from Web Designer.  Reviewing the properties:

• autoClose, notificationGroup, title, and type should not be used because they say "Mobile Only".  It seems that the available properties are significantly different between Web and Mobile.
• message is the most important property to include.  It is the only one that says "required".
• We can omit category.  It says the default is "info", and that is already a good option for a message about drawing on the map.  We wouldn't want to make the message to look like an error.
• disableTimeouts and id seem to help configure different options for closing the message.  We could either:
  • have timeouts enabled and let the message auto-close on its own after a couple seconds
  • have timeouts disabled, set an id, and use ui.hide-notification later in the workflow to close the notification
  • have timeouts disabled and make the user close the notification themselves instead of closing it automatically for them
• We can omit onClose.  It's not well-defined and doesn't sound like something we need.
• We should use position to make sure the notification is shown at the top of the map.  "bottom", "left", "right", and "top" are shown as the only valid options for this property.

We can write our "Command Parameter" input as:

={
  disableTimeouts: true,
  id: "myWorkflowNotification",
  message: "draw a polygon on the map to proceed",
  position: "top"
}

Example 3 (complex) - DisplayUpdateFeatureArgs

This is an example for how to write a DisplayUpdateFeatureArgs object in workflow. DisplayUpdateFeatureArgs is used by the edit.display-update-feature command, which lets you open Web's feature-editing tools for a specific feature.  This command is useful for cases where you want a workflow to handle getting a feature, but want Web to handle generating a form for editing the feature.  The edit.display-update-feature command accepts two possible argument types, as seen here:

Compared to the Features option, DisplayUpdateFeatureArgs offers a higher level of control over which parts of the feature the user will be allowed to edit.

For this example, let's say we are creating a workflow that allows users to search for a building by address, and then immediately start editing its attributes but not its geometry.  The application is for city clerks that should be allowed to update things like address or zoning information, but not the shapes of the buildings.  We have already built the search part using a Display Form and Query Layer activity, and we are ready to set up the edit.display-update-feature command.

Here is the DisplayUpdateFeatureArgs definition (split across 3 screenshots):

This is a long definition. But most of the properties are optional.  Since our main goal is to only edit the attributes, we can review the properties and conclude that only 3 are necessary to achieve that goal:

• features will let us specify which feature to edit
  • This needs a Features, Target, or FeatureProperties[] object.
    • Per the Getting "Features" or "Results" section earlier, we can get Features using the results.from-graphics operation
• editGeometry will let us disable geometry editing
• editAttributes will let us enable attribute editing.  
  • This probably defaults to true, but since the description doesn't specify the default behaviour we'll include it just to be safe.

We'll add a Run Operation activity before the Run Command activity (and configure it using the steps described at Using results.from-graphics) to get the value for the features property.  Then we can write the "Command Parameter" input for edit.display-update-feature as:

={
  features: $runOperation1.result,
  editGeometry: false,
  editAttributes: true
}

Example 3b (more complex) - Using an Argument Definition within an Argument Definition

Lets say that we changed our mind a bit while working on Example 3 above.  We still don't want to let the user perform any major shape-changing edits to the feature geometry, but we do want to let them move the feature's location.

One of the properties in DisplayUpdateFeatureArgs is editGeometryOptions, and we notice it has a link that leads to another definition in the "Argument Definition Reference" page.  EditGeometryOptions has more fine-grained properties for restricting geometry editing.  Here is that definition:

We can write an EditGeometryOptions object for this property using the same strategies we use for arguments. Reviewing the properties, these ones seem the most relevant for our goals:

• enableDelete will let us specify whether the user can delete the geometry.  It says it defaults to false though, which is the value we would have wanted, so we don't have to include the property.
• enableMoving will let us specify whether the user can move the geometry.  It says it defaults to true though, which is the value we would have wanted, so we don't have to include the property.
• enableRotation defaults to true.  We'll want to set it to false so the user can't rotate the geometry.
• enableScaling defaults to true. We'll want to set it to false so the user can't scale the geometry.
• enableVertexEditing defaults to true. We'll want to set it to false so the user can't edit the vertices and change the geometry's shape.

Our EditGeometryOptions object should be written as:

{
  enableRotation: false,
  enableScaling: false,
  enableVertexEditing: false
}

Therefore the whole Command Parameter in the Run Command activity, with the EditGeometryOptions object included, should be written as:

={
  features: $runOperation1.result,
  editGeometry: true,
  editGeometryOptions: {
    enableRotation: false,
    enableScaling: false,
    enableVertexEditing: false
    },
  editAttributes: true
}

Getting Assistance

Don't hesitate to contact support if you get stuck when configuring commands or operations. We can help if:

• Any of the commands, operations, or argument properties don't seem to work as they're described in the documentation
• The documentation is missing information or unclear about what types of objects or values to use for arguments or their properties
• The Run Command or Run Argument activities that you've configured in your workflow aren't working the way you expect, and you're not sure why

For direct VertiGIS customers, follow How to submit a VertiGIS Studio Support Request to open a support ticket. If your organization has purchased VertiGIS Studio through a partner or reseller, please contact your vendor through their support channels.

Additional Examples

Attached below are many of the the examples described in this article, plus two additional examples for creating xlsx files and drawing markup.