Integrating the ArcGIS API for JavaScript

VertiGIS Studio 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.

Add ArcGIS API for JavaScript Typings

Type information for the ArcGIS API for JavaScript is provided by the @types/arcgis-js-api package. You need to install the version of this package that matches the version of the ArcGIS API for JavaScript present in the application where your activities and form elements will be used.

1. Open up a terminal shell in the SDK folder.
2. Run the npm install @types/arcgis-js-api command for the desired version of the ArcGIS API for JavaScript.

For applications like VertiGIS Studio Web that use the 4.x ArcGIS API for JavaScript use:

npm install @types/arcgis-js-api@4.17.0

For applications like Geocortex Viewer for HTML5 or Web AppBuilder for ArcGIS (2D) that use the 3.x ArcGIS API for JavaScript use:

npm install @types/arcgis-js-api@3.33.0

note

The exact minor and patch version numbers of the @types/arcgis-js-api package are often not critical. However, it is important to use the correct major version 3.x vs. 4.x.

Create an Activity

Follow the instructions in Create an Activity to create a custom workflow activity.

Use ArcGIS Types

To reference ArcGIS types you add import statements at the top of the file containing your custom activity.

For example, to use the esri/geometry/Extent type add the following import statement:

import * as Extent from "esri/geometry/Extent";

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.

import type { IActivityHandler } from "@vertigis/workflow/IActivityHandler";
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.
     * @required
     */
    extent: Extent;
}

/**
 * @category Custom Activities
 * @description An activity that expands the bounding extent of a polygon by a given factor.
 */
export class ExpandPolygon implements IActivityHandler {
    async execute(
        inputs: ExpandPolygonInputs
    ): Promise<ExpandPolygonOutputs> {
        return {
            extent: inputs.polygon.getExtent().expand(inputs.factor),
        };
    }
}

Build Activities to work with both 3.x and 4.x ArcGIS API for JavaScript Versions

VertiGIS Studio Workflow is designed to work with both the 3.x and 4.x versions of the ArcGIS API for JavaScript; however, many custom activity implementations only bother to support one or the other.

If you need to support both ArcGIS API versions, then you may need to account for differences between the APIs in your code. For more details on these differences, see the developer documentation for the 4.x ArcGIS API for JavaScript and the 3.x ArcGIS API for JavaScript respectively.

You can structure your activity to be compatible with differences between API versions by using the esri/kernel module to determine the API version that the activity is running in.

The following code provides a convenient utility function to distinguish between 3.x and 4.x versions:

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: 3.x and 4.x Compatible Custom Activity for Expanding a Polygon

This example builds on the ExpandPolygon activity to make it work with both the 3.x and 4.x versions of the ArcGIS API for JavaScript. 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 @types/arcgis-js-api package at time, you will have to cast to any for the other API version types when necessary to avoid 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 type { IActivityHandler } from "@vertigis/workflow/IActivityHandler";
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 expands the bounding extent of a polygon by a given factor.
 */
export class ExpandPolygon implements IActivityHandler {
    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),
        };
    }
}