Integrating the ArcGIS API for JavaScript

Geocortex Workflow was designed to be a flexible tool for implementing business logic for mapping applications, and tightly integrates with ArcGIS API for JavaScript. You may want to use the ArcGIS API in your own custom activities; this article will explain how to reference ArcGIS API types in your custom activity or custom form element for web applications.

Prerequisites

Follow the instructions in the Web Applications SDK page to set up your development environment.

note

A working knowledge of TypeScript is recommended before extending Workflow for web-based hosts.

Follow the instructions in Implement a Custom Activity to create a custom workflow activity. You can then import ArcGIS API types with a require call.

Example: Custom Activity for Expanding a Polygon

This is a custom activity which imports types from the ArcGIS API for JavaScript to expand a polygon by a given factor and returns the new extent bounds.

note

The activity-sdk uses the ArcGIS API for JavaScript 3.x by default. See Using Alternate ArcGIS API Versions for details.

// Import the desired type
import * as Extent from "esri/geometry/Extent";
import * as Polygon from "esri/geometry/Polygon";
export interface ExpandPolygonInputs {
// @description The polygon to Expand.
// @required
polygon: Polygon;
// @description The factor to expand the polygon extent by.
// @required
factor: number;
}
export interface ExpandPolygonOutputs {
// @description The extent bounds for the expanded polygon.
extent: Extent;
}
// @category Custom Activities
// @description An activity that calculates the extent a polygon would cover if it was expanded by a given factor.
export class ExpandPolygon {
static action = "your:unique:namespace::ExpandPolygon";
static suite = "your:unique:namespace";
async execute(inputs: ExpandPolygonInputs): Promise<ExpandPolygonOutputs> {
return {
extent: inputs.polygon.getExtent().expand(inputs.factor),
};
}
}

Using Alternate ArcGIS API for JavaScript Versions

Geocortex Workflow is designed to be able to be used with the 4.x or 3.x ArcGIS API for JavaScript. Each workflow host uses a specific version:

If you decide to use the API, you should ensure you are using the right version for your application.

Change the API Version used by the Activity SDK

The ArcGIS API version for the activity SDK can be changed by updating the @types/arcgis-js-api version in the package.json file and then running npm install again.

For example, a package.json file in an activity SDK that uses the 4.x ArcGIS API might look like this;

{
...
"devDependencies": {
"@types/arcgis-js-api": "4.14.0",
...
},
...
}

Build Activities to work with both ArcGIS API Versions

If you need to support both ArcGIS API versions, then you may need to account for differences between the APIs. For more details, see the developer documentation for the 4.x JavaScript API and the 3.x JavaScript API respectively. You can structure your activity to be compatible with differences between versions by using the esri/kernel module to determine the API version that the activity is running in.

import * as kernel from "esri/kernel";
enum ArcGisApiVersion {
Unknown,
v3,
v4,
}
const getArcGISApiVersion = (): ArcGisApiVersion => {
const prefix = kernel.version.substr(0, 2);
if (prefix === "4.") {
return ArcGisApiVersion.v4;
} else if (prefix === "3.") {
return ArcGisApiVersion.v3;
} else {
return ArcGisApiVersion.Unknown;
}
};

Example: ExpandPolygon Custom Activity that is 4.x and 3.x ArcGIS API Compatible

This example builds on the ExpandPolygon activity to make it work with both the 3.x and 4.x versions of the ArcGIS API. The execute method of the activity checks the ArcGIS API version and executes the appropriate code for the given API.

note

Since the SDK can only reference one version of the ArcGIS JavaScript API at time, you will have to cast to any for the other API version types when necessary to override TypeScript errors.

In this example, the way the Extent of a polygon is retrieved is the difference between the APIs. In 4.x, extent is a property, while in 3.x extent is retrieved using the getExtent() method. The APIs converge after this, with both supporting the expand(factor) method.

// Import the desired type
import * as Extent from "esri/geometry/Extent";
import * as Polygon from "esri/geometry/Polygon";
import * as kernel from "esri/kernel";
enum ArcGisApiVersion {
Unknown,
v3,
v4,
}
const getArcGISApiVersion = (): ArcGisApiVersion => {
const prefix = kernel.version.substr(0, 2);
if (prefix === "4.") {
return ArcGisApiVersion.v4;
} else if (prefix === "3.") {
return ArcGisApiVersion.v3;
} else {
return ArcGisApiVersion.Unknown;
}
};
export interface ExpandPolygonInputs {
// @description The polygon to Expand.
// @required
polygon: Polygon;
// @description The factor to expand the polygon extent by.
// @required
factor: number;
}
export interface ExpandPolygonOutputs {
// @description The extent bounds for the expanded polygon.
extent: Extent;
}
// @category Custom Activities
// @description An activity that calculates the extent a polygon would cover if it was expanded by a given factor.
export class ExpandPolygon {
static action = "your:unique:namespace::ExpandPolygon";
static suite = "your:unique:namespace";
async execute(inputs: ExpandPolygonInputs): Promise<ExpandPolygonOutputs> {
const apiVersion = getArcGISApiVersion();
let extent;
if (apiVersion == ArcGisApiVersion.v4) {
extent = (inputs.polygon as any).extent;
} else if (apiVersion == ArcGisApiVersion.v3) {
extent = inputs.polygon.getExtent();
} else {
throw new Error(
`ArcGIS JS API Version version '${apiVersion}' not recognized.`
);
}
return {
extent: extent.expand(inputs.factor),
};
}
}
Edit this page