Skip to main content

VertiGIS Studio Workflow TypeScript SDK Overview

The VertiGIS Studio Workflow for Web Applications SDK consists of a TypeScript project that eases development of custom Workflow activities and form elements. It produces a Workflow activity pack that can be consumed by web applications that use Workflow.

Overview​

The VertiGIS Studio Workflow SDK provides a development toolkit for building custom Workflow activities and form elements into a package that can be deployed to VertiGIS Studio Web called an activity pack. Once the activity pack has been developed, it can then be deployed to your SaaS or on-premises environment.

Requirements​

Getting Started​

  1. Run npx @vertigis/workflow-sdk@latest create <activity-pack-name> where <activity-pack-name> is the name of the directory that will be created in the current working directory
    • For example: npx @vertigis/workflow-sdk@latest create test-activity-pack
  2. Open the activity-pack-name directory in your favorite IDE. We recommend using Visual Studio Code for the best experience.
  3. Run npm run generate and follow the onscreen prompts to create a new activity or form element.
  4. Finally run npm start to start the development server.

Project Structure​

The created project contains a few important files and directories:

  1. The src/index.ts file which exports all of your custom activities and form elements.
  2. uuid.js which maintains a globally unique identifier that will be used when you create your custom activities and form elements. This enables you to load and use multiple activity packs in a given workflow. This identifier should not be modified.

Browser Support​

By default the Workflow SDK targets modern browsers. If you need to support Internet Explorer 11, you'll need to update a few configuration settings in your project.

Update TypeScript Configuration​

In the tsconfig.json of your project you'll need to change the target to es5:

tsconfig.json
{
    "extends": "@vertigis/workflow-sdk/config/tsconfig.json",
    "compilerOptions": {
        "target": "es5"
    },
    "include": ["src"]
}

Update browserslist​

In the package.json of your project, you'll need to update the browserslist to include ie 11:

package.json
"browserslist": [
    "last 2 chrome versions",
    "last 2 edge versions",
    "last 2 firefox versions",
    "last 2 safari versions",
    "ie 11"
]

Development Server​

To get started with the development server, run npm start in the terminal to start the development server. Before you can use the activity pack in your workflows, you will need to register the activity pack in your ArcGIS Portal.

  • The activity pack is available at https://localhost:5000/main.js by default.
    • You can change the port by setting the PORT environment variable when running npm start.
  • The HTTPS certificate of the development server is a self-signed certificate that web browsers will warn about. To work around this open https://localhost:5000/main.js in a web browser and allow the invalid certificate as an exception. For creating a locally-trusted HTTPS certificate see the Configuring a HTTPS Certificate section.
  • The development server supports CORS requests from any origin by default.
note

As localhost is only accessible to your host machine, activity packs hosted in this manner will not be accessible when running VertiGIS Studio Workflow Designer on a different machine.

Configuring a HTTPS Certificate​

You can create a locally-trusted development certificate that is trusted by your system using the mkcert utility. Once installed you can run:

$ mkcert -install
Created a new local CA at "/Users/ian/Library/Application Support/mkcert" 💥
The local CA is now installed in the system trust store! ⚡️
The local CA is now installed in the Firefox trust store (requires browser restart)! 🦊

$ mkcert localhost 127.0.0.1 ::1
Using the local CA at "/Users/ian/Library/Application Support/mkcert" ✨

Created a new certificate valid for the following names 📜
 - "localhost"
 - "127.0.0.1"
 - "::1"

The certificate is at "./localhost+2.pem" and the key at "./localhost+2-key.pem" ✅

Once you've created your locally-trusted development certificate you can provide the paths to the cert and key files:

$ npm start -- --cert "./localhost+2.pem" --key "./localhost+2-key.pem"
note

The extra -- used in the npm start script is necessary to forward the arguments to the development server process.

Deployment​

Deploying Workflow activities consists of two steps:

  1. Hosting the Workflow activity pack on a server accessible to the VertiGIS Studio Workflow Designer
  2. Making the Workflow activity pack known to VertiGIS Studio Workflow Designer and Workflow Applications by registering it as an ArcGIS item.

Creating a Production Build​

Run npm run build in the root of your project to create a production build of your activity pack. This creates an optimized production build that is output to the build folder of your project.

tip

Check out Implement Custom Activities for Web Applications to learn how to make activities for your activity pack.

Host the Activity Pack​

The build folder produced by running npm run build can be directly hosted with the web server technology that is most appropriate for your use case, such as IIS. Activity packs must be hosted by a web server that supports HTTPS and CORS.

Server Requirements​

  • The server must have a valid HTTPS certificate.
  • The server must support Cross-Origin Resource Sharing (CORS) and allow CORS requests from the https://apps.vertigisstudio.com origin or the origin of your VertiGIS Studio Workflow if running on-premises.
note

If you sign in to VertiGIS Studio Workflow Designer using Portal for ArcGIS your server will need to allow CORS requests from your custom origin. For example, https://acme.apps.vertigisstudio.com.

Hosting Workflow activity packs in this manner allows VertiGIS Studio Workflow Designer to read the list of custom activities and their associated metadata.

Register the Activity Pack​

To make an activity pack available to workflow authors in VertiGIS Studio Workflow Designer you must create a special item in ArcGIS Online or Portal for ArcGIS that references it.

  1. Sign in to ArcGIS Online or Portal for ArcGIS.
  2. Go to My Content.
  3. Select Add Item > An application.
    • Type: Web Mapping
    • Purpose: Ready To Use
    • API: JavaScript
    • URL: The URL to your activity pack manifest
      • Use https://localhost:5000/activitypack.json for the development server, or the URL to your production server hosting the activity pack such as https://myserver.com/custom-activity-pack/activitypack.json.
    • Title: Your desired title
    • Tags: Must include geocortex-workflow-activity-pack
Important

The activity pack will not be registered unless it includes the geocortex-workflow-activity-pack tag.

Sharing the Activity Pack​

As a workflow author, you will see custom activities in VertiGIS Studio Workflow Designer from the activity packs you have registered. You will also see activity packs that have been shared with you via groups you are a member of.

To share an activity pack with other workflow authors in your organization share the ArcGIS item that represents the activity pack with a group that contains the target users.

note

You do not need to share the activity pack Portal item with the end users of your applications that run workflows containing custom activities. It only affects the visibility of the activity pack in the VertiGIS Studio Workflow Designer.

Upgrading to v4​

There is a breaking change in v4 of the SDK that requires manual changes in order to continue to work. We moved the contents of the runtime folder in the @vertigis/workflow package to the parent folder. Any new activities or form elements that you create will use the new path, but existing code needs to be updated manually.

  1. Upgrade the packages.
    1. Open a command prompt and go to the root directory of your activity pack.
    2. Run npm install -D @vertigis/workflow@5.33.0 @vertigis/workflow-sdk@4.0.0.
  2. Update existing code.
    1. Find and replace all instances of @vertigis/workflow/runtime with @vertigis/workflow in your existing code.
    2. Save all changes.

Upgrading to v3​

There is a breaking change in v3 of the SDK that requires manual changes in order to continue to work. We renamed the @geocortex/workflow package to @vertigis/workflow. Any new activities or form elements that you create will use the new @vertigis/workflow package name, but existing code needs to be updated manually.

  1. Upgrade the packages.
    1. Open a command prompt and go to the root directory of your activity pack.
    2. Run npm uninstall @geocortex/workflow.
    3. Run npm install -D @vertigis/workflow@5.31.0 @vertigis/workflow-sdk@3.0.0.
  2. Update existing code.
    1. Find and replace all instances of @geocortex/workflow with @vertigis/workflow in your existing code.
    2. Save all changes.

Migrating from the Legacy SDK​

If you're migrating from our previous activity-sdk.zip there are a few steps you will want to follow to migrate your source code over to the new SDK:

  1. Follow the instructions above to create a new project and register the activity pack.

    • Note the updated instructions to register the activity pack. The URL should end in /activitypack.json.

  2. Copy the UUID value from .build/uuid.txt in your existing project and overwrite the value in uuid.js of your new project.

  3. Copy your activity and form element modules into the src/activities directory.

  4. Add each activity and form element to the index.ts exports. For example if you copied over an activity called src/activities/Sum.ts, you would add the following to src/index.ts:

    • export * from "./activities/Sum";

  5. Check your main.ts and init.ts logic in your existing project to see if any of it is still relevant. You no longer need to call mapDependencies() to use third party libraries as the new SDK will handle this for you.

  6. Test your activity pack to ensure it still behaves as expected.

Next Steps​

Implement a Custom Activity

Implement a custom activity for web applications

Get Started

Implement a Custom Form Element

Implement a custom form element for web applications

Get Started

Reference a Third Party Library

Reference a third party library in web applications

Get Started

Integrate the ArcGIS API for JavaScript into custom activities

Integrate the ArcGIS API for JavaScript into custom code

Get Started