-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add documentation for custom activities on VertiGIS Studio Desktop (#62)
Adding documentation, instructions and examples about implementing and integrating custom Workflow activities with VertiGIS Studio Desktop.
- Loading branch information
1 parent
74aa8d9
commit 3f02dfe
Showing
10 changed files
with
391 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| --- | ||
| title: Create an Activity | ||
| description: VertiGIS Studio Workflow - Create a workflow activity for desktop applications | ||
| --- | ||
|
|
||
| import useBaseUrl from "@docusaurus/useBaseUrl"; | ||
| import Tabs from "@theme/Tabs"; | ||
| import TabItem from "@theme/TabItem"; | ||
| import UseCaseContainer from "../../src/components/UseCaseContainer"; | ||
| import UseCaseCard from "../../src/components/UseCaseCard"; | ||
| import MobilePrereqs from "./snippets/prereqs-mobile.mdx"; | ||
| import DesktopPrereqs from "./snippets/prereqs-desktop.mdx"; | ||
| import WorkflowUrlSnippet from "../snippets/workflow-url.mdx"; | ||
|
|
||
| This article will walk you through creating a new workflow activity for VertiGIS Studio Desktop applications. | ||
|
|
||
| <img | ||
| src={useBaseUrl( | ||
| "img/desktop-pro-run-create-activity-workflow.png" | ||
| )} | ||
| /> | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| <DesktopPrereqs /> | ||
|
|
||
| ## Create the Activity | ||
|
|
||
| 1. If you haven't done yet, create a new Visual Studio project using the `ArcGIS Pro Module Add-In` project template. | ||
| 2. Create a new file `MyCustomActivity.cs` in the previously mentioned project. | ||
| 3. Add a new skeleton workflow activity that implements `IActivityHandler`. | ||
|
|
||
| ```cs title="MyCustomActivity.cs" | ||
| using System.Collections.Generic; | ||
| using System.Threading.Tasks; | ||
| using VertiGIS.Workflow.Runtime; | ||
|
|
||
| // highlight-next-line | ||
| [assembly:WorkflowActivities] | ||
| namespace Poc_ProCustomActivities | ||
| { | ||
| public class MyCustomActivity : IActivityHandler | ||
| { | ||
| // highlight-next-line | ||
| public static string Action => "uuid:cc39c481-4d05-4c39-8363-07b79dc03aa7::MyCustomActivity"; | ||
|
|
||
| public Task<IDictionary<string, object>> Execute(IDictionary<string, object> inputs, IActivityContext context) | ||
| { | ||
| IDictionary<string, object> outputs = new Dictionary<string, object>(); | ||
|
|
||
| outputs["test"] = "Hello World. This is a custom activity."; | ||
|
|
||
| return Task.FromResult(outputs); | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| :::important | ||
| It's important to conform to two necessary constraints to make the activity recognizable to VertiGIS Studio Desktop: | ||
|
|
||
| 1. Inside your assembly you need to add the `WorkflowActivities` attribute (make sure to add it only once across your whole project, e.g. in your module rather than inside your activity) | ||
| 2. Your custom activity needs to contain an action identifier that tells VertiGIS Studio Desktop what activity is represented by this implementation. This can be achieved by declaring a static string property named `Action` that returns the activities action id. As static members cannot be specified in interfaces, you have to ensure this property being present yourself. | ||
|
|
||
| Ignoring any of those rules will lead to the activity not being found by VertiGIS Studio Desktop and thus cause a runtime error. | ||
| ::: | ||
|
|
||
| ## Use the Activity in a Workflow | ||
|
|
||
| Workflows that run in your custom VertiGIS Studio Desktop application can now run this custom activity. | ||
|
|
||
| :::tip | ||
| [Registering stubs for .NET activities](sdk-net-register-activities.mdx) provides a user friendly interface for your custom activities in VertiGIS Studio Workflow Designer. | ||
|
|
||
| <img src={useBaseUrl("img/desktop-designer-run-activity.png")} /> | ||
| ::: | ||
|
|
||
| Without registering stubs you may still call your custom activity using the [`RunActivity`](https://docs.vertigisstudio.com/workflow/latest/help/Default.htm#wf5/help/activities/run-activity.htm%3FTocPath%3DActivities%7CActivity%2520Reference%7C_____167) by the name defined in `MyCustomActivity.cs` (for this example, `uuid:cc39c481-4d05-4c39-8363-07b79dc03aa7::MyCustomActivity`). | ||
|
|
||
| :::note | ||
|
|
||
| <p> | ||
| You can{" "} | ||
| <a | ||
| href={useBaseUrl("workflows/desktop-create-activity.json")} | ||
| download="custom-activity-workflow.json" | ||
| target="_blank" | ||
| > | ||
| download this demo workflow | ||
| </a>{" "} | ||
| that runs the custom activity and | ||
| <a | ||
| href="https://docs.vertigisstudio.com/workflow/latest/help/Default.htm#wf5/help/import-export-workflows.htm" | ||
| target="_blank" | ||
| > | ||
| {" "} | ||
| import it into the VertiGIS Studio Workflow Designer.{" "} | ||
| </a> | ||
| </p> | ||
| ::: | ||
|
|
||
| Next you need to run the workflow you just created in your VertiGIS Studio Desktop project. | ||
|
|
||
| <WorkflowUrlSnippet /> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| --- | ||
| title: Using the .NET Workflow SDK with VertiGIS Studio Desktop | ||
| sidebar_label: Overview | ||
| description: VertiGIS Studio Workflow - Overview of extending workflow for VertiGIS Studio Desktop | ||
| --- | ||
|
|
||
| import useBaseUrl from "@docusaurus/useBaseUrl"; | ||
| import UseCaseContainer from "../../src/components/UseCaseContainer"; | ||
| import UseCaseCard from "../../src/components/UseCaseCard"; | ||
|
|
||
| Custom activities are being added to VertiGIS Studio Desktop using the add-in mechanism of ArcGIS Pro. Providing some implementations for well-known elements, you easily can bring your custom logic to Workflow Desktop: | ||
|
|
||
| 1. [Create a new](https://developers.arcgis.com/documentation/arcgis-add-ins-and-automation/arcgis-pro/tutorials/build-your-first-add-in/) (or extend your existing) ArcGIS Pro add-in. | ||
| 1. Add a reference to Workflow Runtime [NuGet Package](https://www.nuget.org/packages/VertiGIS.Workflow.Runtime) to your project | ||
| 1. [Implement](sdk-desktop-create-activity.mdx) your activities | ||
|
|
||
| ## Next Steps | ||
|
|
||
| <UseCaseContainer> | ||
| <UseCaseCard | ||
| title="Implement a Custom Activity" | ||
| description="Implement a custom activity for VertiGIS Studio Desktop" | ||
| link={useBaseUrl("docs/workflow/sdk-desktop-create-activity")} | ||
| /> | ||
| </UseCaseContainer> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| --- | ||
| title: Wrapping activity inputs and outputs | ||
| sidebar_label: Input and output wrapping | ||
| description: VertiGIS Studio Workflow - Overview of extending workflow for VertiGIS Studio Desktop | ||
| --- | ||
|
|
||
| The implementation of the Workflow Runtime uses mechanisms to internally stay agnostic of used APIs. To achieve this, all [non-builtin types](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/built-in-types) in the output of an activity should get wrapped in a `WrapperBase`: | ||
|
|
||
| ```cs | ||
| public Task<IDictionary<string, object>> Execute(IDictionary<string, object> inputs, IActivityContext context) | ||
| { | ||
| // activity work, e.g. creating a feature | ||
| IDictionary<string, object> outputs = new Dictionary<string, object>(); | ||
|
|
||
| // highlight-start | ||
| outputs.Add("feature", new CustomActivityWrapper(createdFeature)); | ||
| // highlight-end | ||
| return Task.FromResult(outputs); | ||
| } | ||
| ``` | ||
|
|
||
| where an implementation of a WrapperBase at least offers a `Unwrap` method: | ||
|
|
||
| ```cs | ||
| private class CustomActivityWrapper : WrapperBase | ||
| { | ||
| //internals of the wrapper | ||
| public override object Unwrap() | ||
| { | ||
| return _actualObject; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Unwrapping inputs | ||
|
|
||
| Thus all inputs in an activity should get unwrapped before working with it. On Studio Desktop you may cast the input either to `WrapperBase` or `IServiceProvider` - both methods are equivalent: | ||
|
|
||
| ```cs | ||
| public Task<IDictionary<string, object>> Execute(IDictionary<string, object> inputs, IActivityContext context) | ||
| { | ||
| // Variant 1 IServiceProvider: | ||
| IServiceProvider provider = inputs["feature"] as IServiceProvider; | ||
| Row actualObject = (Row)provider.GetService(typeof(Row)); | ||
|
|
||
| // Variant 2 WrapperBase: | ||
| WrapperBase wrapper = inputs["feature"] as WrapperBase; | ||
| Row actualObject2 = (Row)wrapper.Unwrap(); | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| --- | ||
| title: Integrating the ArcGIS Pro SDK | ||
| description: VertiGIS Studio Workflow - Integrate the ArcGIS Pro SDK into custom activities for .NET applications | ||
| --- | ||
|
|
||
| [VertiGIS Studio Workflow](https://apps.vertigisstudio.com/workflow/designer/) was designed to be a flexible tool for implementing business logic for mapping applications, and tightly integrates with ArcGIS Pro SDK. You may want to use the ArcGIS Pro SDK in your own custom activities; this article will explain how to reference ArcGIS Pro SDK types in your custom activity or custom form elements for .NET applications. | ||
|
|
||
| ## VertiGIS Studio Desktop | ||
|
|
||
| When [creating a new ArcGIS Pro add-in project in Visual Studio](sdk-desktop-overview.mdx), your project already references the [ArcGIS Pro SDK](https://pro.arcgis.com/en/pro-app/latest/sdk/), so integrating the ArcGIS Pro API is as easy as adding a `using` statement to the top of your custom activity or form element. | ||
|
|
||
| For example: | ||
|
|
||
| ```c# | ||
| using Esri.ArcGISRuntime.Data; | ||
| ``` | ||
|
|
||
| ## VertiGIS Studio Workflow Server | ||
|
|
||
| It is **not possible** to reference the [ArcGIS Pro SDK](https://pro.arcgis.com/en/pro-app/latest/sdk/) in VertiGIS Studio Workflow Server, as the licensing does not allow for this usage. | ||
|
|
||
| :::tip | ||
| Consider using the [Geoprocessing activities](https://docs.vertigisstudio.com/workflow/latest/help/Default.htm#wf5/help/geometries.htm#Work_with_Geometries%3FTocPath%3DWork%2520with%2520Geometries%7C_____0) in a client workflow or the [`Run Python`](https://docs.vertigisstudio.com/workflow/latest/help/Default.htm#wf5/help/activities/run-python.htm%3FTocPath%3DActivities%7CActivity%2520Reference%7C_____174) activity on the server to have your workflow offload any operations that require server processing of ArcGIS types. | ||
| ::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| :::info Important | ||
| While extending VertiGIS Studio Workflow for Desktop can easily be achieved, you require an installed Workflow runtime module to make your custom activities work with VertiGIS Studio Desktop. | ||
| ::: | ||
|
|
||
| To ease using your custom activities when authoring of Workflows with Workflow Designer, you may create method stubs for your activities and publish them to make them, as described in [the corresponding chapter](/docs/workflow/sdk-net-register-activities.mdx). | ||
|
|
||
| :::note | ||
| A working knowledge of [C#](https://docs.microsoft.com/en-ca/dotnet/csharp/) and [.NET Standard](https://dotnet.microsoft.com/platform/dotnet-standard) is recommended before extending Workflow for VertiGIS Studio Desktop | ||
| ::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.