Commands and Operations

Commands and operations are runnable, independent units of work within Geocortex Web. Commands and operations act as global functions which can be executed from any component or service.

Commands and operations have one key difference. Commands execute behavior that can have effects on the application, while operations produce outputs which can be passed to commands. Commands and operations can be run sequentially in what's called a "command chain" to enable complex behavior.

Commands and Operations are grouped by namespace, for example:

tip

The full list of existing commands and operations available in Geocortex Web can be found in the API documentation.

Commands and operations are used to power much of Geocortex Web's built in behavior and interactions. They can be run through configuration, or through custom services or components.

One thing that makes commands and operations so powerful is that built in components have properties in the app config which take them as values. They power everything from basic components like the IWTM, to advanced functionality like the results list. This allows built-in component's internal behavior to be configured with different commands and operations.

{
"items": [
...
{
"id": "iwtm-config-1",
"items": [
{
"id": "return-to-initial-view",
"iconId": "zoom-initial",
"title": "Return to Initial View",
"action": "map.zoom-to-initial-viewpoint",
"$type": "menu-item"
},
],
"$type": "menu"
},
{
"id": "results-list-config",
"featureActions": {
"id": "results-context",
"items": [
{
"id": "zoom",
"iconId": "zoom-feature",
"title": "Zoom to Feature",
"action": "map.zoom-to-features",
"$type": "menu-item"
},
{
"id": "remove-feature",
"iconId": "trash",
"title": "Remove Feature",
"action": "results.remove",
"$type": "menu-item"
},
],
"$type": "menu"
},
"onFeatureClick": [
"results.display-details"
],
"$type": "results"
},
...
]
}

Workflow Command

Geocortex Workflow can allow for the creation of completely customized behavior without writing custom code. Geocortex Web has a special command, workflow.run, which allows you to run workflows anywhere you would run a command or operation. Using workflow, you can take custom behavior in Geocortex Web further without having to write custom code.

Check out this example of running a workflow from app config.

Configuring Commands and Operations

Commands and operations can be used through the app config to customize built in components.

{
"schemaVersion": "1.0",
"items": [
...
{
"id": "button-config",
"iconId": "zoom-in",
"title": "Zoom In",
"action": "map.zoom-in",
"$type": "menu-item"
}
...
]
}

App config properties like action can accept a singular command/operation or a command chain .

note

Command chains are arrays of commands and operations which are executed sequentially. The output of previous operations is passed along the chain to future operations and commands, allowing for complex input dependent behavior.

{
"id": "zoom",
"$type": "menu-item",
"title": "Zoom to Features",
"action": ["map.zoom-to-features", "highlights.pulse"]
}

Passing Explicit Arguments

Commands and operations can be configured with an arguments property that passes values to the function at execution time.

tip

You can find out what arguments a command or operation takes in the commands and operations API reference.

{
"$type": "menu",
"id": "iwtm",
"items": [
{
"title": "Hello",
"isEnabled": true,
"iconId": "info",
"action": {
"name": "ui.display-notification",
"arguments": {
"message": "World"
}
}
}
]
}

Passing Implicit Arguments

If you do not pass explicit arguments, then implicit arguments will be passed to the command or operation. Implicit arguments come from the context that a command or operation is running in, or from a previous operation in the command chain

For example, let's look at the configuration for the onFeatureClick property of a <results-list> component model.

{
"schemaVersion": "1.0",
"items": [
...
{
"id": "results-list",
"$type": "results",
"onFeatureClick": "results.display-details"
},
...
]
}

In this example, the context is an item in the results list, so results.display-details will receive an argument with a Features property, which is the shape of argument it needs.

Arguments are also passed implicitly if you create a command chain, which runs operations one after the other.

Command Chains

App config properties that accept a command or operation can take a single operation or they can take a command chain. Command chains are arrays of commands and operations which are executed sequentially. The output of previous operations is passed along the chain to future operations, allowing for complex chains of behavior.

For example, here's configuration for the various behaviors of a <results-list> component.

{
"schemaVersion": "1.0",
"items": [
...
{
"id": "results-list",
"$type": "results",
"featureActions": [
"item://menu-item/zoom-to-features",
"item://menu-item/save-features-to-csv"
],
"onFeatureClick": "results.display-details"
},
{
"id": "zoom-to-features",
"$type": "menu-item",
"title": "Zoom to Features",
"action": ["map.zoom-to-features", "highlights.pulse"]
},
{
"id": "save-features-to-csv",
"$type": "menu-item",
"title": "Save Features to CSV",
"action": ["results.convert-to-csv", "system.download-file"]
},
...
]
}

Since these commands and operations are running from the context of a <results-list> component, the first command or operation will receive the relevant feature as its input. If the property is a command chain, the next step in line will receive one of two possible inputs.

  1. If the previous step was a command (which doesn't produce output), then the original input is passed on to the next step.
  2. If the previous step was an operation (which produces an output), then the output of that operation is passed onto the next step.

In this way, you can run multiple commands in a row that receive a feature as input, as seen in the action command chain of zoom-to-features in the example.

// Both of these commands will receive the Features argument passed into the
// command chain.
["map.zoom-to-features", "highlights.pulse"]

The action command chain of save-features-to-csv demonstrates how an operation can pass its output to the next command or operation in the list. In this case, it's passing the CSV content to system.download-file.

// `system.download-file` will receive the output of `results.convert-to-csv`.
["results.convert-to-csv", "system.download-file"]

Example: Configured Map and I Want to Menu

This example demonstrates two different types of argument passing behavior.

app/app.json
{
"schemaVersion": "1.0",
"items": [
{
"$type": "map-extension",
"id": "default",
"webMap": "https://www.arcgis.com/home/item.html?id=0ba877a4185448cb832af9a661031e31",
"onClick": [
"tasks.identify",
"highlights.add-focus",
"results.display"
]
},
{
"$type": "menu",
"id": "iwtm",
"items": [
{
"title": "Return to Default Map View",
"isEnabled": true,
"action": [
{
"name": "map.zoom-to-initial-viewpoint",
"arguments": ["item://map-extension/default"]
}
]
}
]
}
]
}

Let's first look at the command chain defined on the onClick property of a map. This chain consists of three operations and commands:

  • task.identify,
  • highlights.add-focus
  • results.display

tasks.identify does not have any named arguments defined, so it will take arguments passed into it from its current context. Since this chain is run on a map click, the context argument passed in has the shape:

{
"geometry": "Esri.Point(<map-click-location>)",
... <other props>
}

tasks.identify receives this argument, and since it is an operation, produces an output. Looking at the Commands and Operations Documentation, tasks.identify has output of type Features.

highlights.add-focus and results.display both take a Features type input, so the output of tasks.identify will work nicely. highlights.add-focus is immediately after tasks.identify, so it receives the output of identify. Since highlights.add-focus is a command, it does not produce any output. Therefore, results.display will receive the output of the last operation, tasks.identify. In this way, you can pass the output of an operation to multiple commands.

The second behavior in this application is a map.zoom-to-initial-viewpoint command on the I Want To Menu. This command takes Maps type argument. The argument property in the app config supplies an array of maps by referencing the default map with an Item URI. Item URIs are a way of referencing other items within the app config.

Next Steps

Geocortex Web has a large array of built-in command and operations that you can chain to power custom behavior. Custom commands and operations can also be implemented with the SDK.

Commands, Operations, and Events API

Check out the available commands and operations

Get Started

Run a Command or Operation with a Button

Learn how to configure a button to run a command or operation

Get Started

Build your own Commands and Operations

Use the SDK to implement custom commands and operations

Get Started

Learn about Events built into Geocortex Web

Learn about the global event infrastructure in Geocortex Web

Get Started
Edit this page