[vrotsc,vrotsc-annotations] (#324) Add Workflow canvas Error Handling

docs/versions/latest/Components/Archetypes/typescript/Components/Workflows.md

@@ -6,17 +6,24 @@ How to use Aria Orchestrator Workflows and available decorators.
 
 ## Table of Contents
 
-1. [Workflow Decorator](#workflow-decorator)
-2. [Available Method Decorators](#available-method-decorators)
+1. [Argument Decorators](#argument-decorators)
+2. [Workflow Decorators](#workflow-decorators)
+3. [Available Method Decorators](#available-method-decorators)
    - [`@Item`](#item)
    - [`@WaitingTimerItem`](#waitingtimeritem)
    - [`@DecisionItem`](#decisionitem)
    - [`@RootItem`](#rootitem)
    - [`@DefaultErrorHandler`](#defaulterrorhandler)
    - [`@WorkflowEndItem`](#workflowenditem)
-3. [Example Workflow](#example-workflow)
+4. [Example Workflow](#example-workflow)
 
-### Workflow Decorator
+### Argument Decorators
+
+- `@In` - Used to bind an input to a function.
+- `@Out` - Used to bind an output to a function.
+- `@Err` - Used to bind an error to a function.
+
+### Workflow Decorators
 
 Not implemented yet.
 

docs/versions/latest/Release.md

@@ -24,6 +24,55 @@
 [//]: # (Optional But higlhy recommended Specify *NONE* if missing)
 [//]: # (#### Relevant Documentation:)
 
+### *Error handling for workflow canvas elements*
+
+There is a new decorator added `@Err` that can be used with arguments. This decorator will mean that the argument will be bound to the exeption if it occurs.
+Note, you add it as normal `@In` or `@Out` decorators, but the variable should not be used in the method.
+
+Furthermore, supported canvas items now have `exception` parameter that can be used to specify the method that will handle the exception.
+
+#### Supported Canvas Items
+
+- `@Item`
+- `@AsyncWorkflowItem`
+- `@ScheduledWorkflowItem`
+- `@WorkflowItem`
+- `@ActionItem`
+- `@DecisionItem`
+- `@WaitingTimerItem`
+
+#### Example
+
+```typescript
+import { Workflow, Out, In, Err, RootItem, Item } from "vrotsc-annotations";
+
+@Workflow({
+  name: "Example",
+  path: "VMware/PSCoE",
+  attributes: {
+    error: {
+      type: "string"
+    }
+  }
+})
+export class Example {
+  @Item({ 
+    target: "end",
+    exception: "exceptionHandle"
+  })
+  @RootItem()
+  public start(@Err error: string) {
+    if (true) {
+      throw new Error("Error");
+    }
+  }
+
+  @Item({ target: "end" })
+  public exceptionHandle(@In error: string) {
+    System.log(`Error: ${error}`);
+  }
+}
+```
 ### Support of Objects in the VROES.Shims.arrayFrom() Method
 
 Add support for objects in the `VROES.Shims.arrayFrom()` method so its behavior is similar to the standard `Array.from()` method.

typescript/vrotsc/e2e/cases/canvas-items/default-error-handler-custom-item.wf.ts

@@ -1,4 +1,4 @@
-import { Workflow, RootItem, In, Out, Item, DefaultErrorHandler, WorkflowEndItem } from "vrotsc-annotations";
+import { Workflow, RootItem, In, Out, Err, Item, DefaultErrorHandler, WorkflowEndItem } from "vrotsc-annotations";
 
 @Workflow({
 	name: "Default Error Handler Custom Item",
@@ -32,18 +32,16 @@ export class HandleDefaultError {
 	}
 
 	@DefaultErrorHandler({
-		exceptionVariable: "errorMessage",
 		target: "processError"
 	})
-	public defaultErrorHandler(@Out errorMessage: string) {
+	public defaultErrorHandler(@Out @Err errorMessage: string) {
 		// NOOP
 	}
 
 	@WorkflowEndItem({
 		endMode: 0,
-		exceptionVariable: "errorMessage",
 	})
-	public workflowEnd(@Out errorMessage: string) {
+	public workflowEnd(@Out @Err errorMessage: string) {
 		System.log(`Terminating workflow with error ${errorMessage}`);
 	}
 }

typescript/vrotsc/e2e/cases/canvas-items/default-error-handler-happy.wf.ts

@@ -1,4 +1,4 @@
-import { Workflow, RootItem, DefaultErrorHandler } from "vrotsc-annotations";
+import { Workflow, RootItem, DefaultErrorHandler, Err } from "vrotsc-annotations";
 
 @Workflow({
 	name: "Default Error Handler Happy",
@@ -18,10 +18,9 @@ export class HandleDefaultError {
 	}
 
 	@DefaultErrorHandler({
-		exceptionVariable: "errorMessage",
 		target: "end"
 	})
-	public defaultErrorHandler() {
+	public defaultErrorHandler(@Err errorMessage: string) {
 		// NOOP
 	}
 }

typescript/vrotsc/e2e/cases/canvas-items/end-item-exception.wf.ts

@@ -1,4 +1,4 @@
-import { Workflow, RootItem, DecisionItem, WorkflowEndItem } from "vrotsc-annotations";
+import { Workflow, RootItem, DecisionItem, WorkflowEndItem, Err } from "vrotsc-annotations";
 
 @Workflow({
 	name: "Workflow End Exception",
@@ -26,10 +26,9 @@ export class WorkflowEnd {
 
 	@WorkflowEndItem({
 		endMode: 1,
-		exceptionVariable: "errorMessage",
 		businessStatus: "Bad"
 	})
-	public workflowEnd() {
+	public workflowEnd(@Err errorMessage: string) {
 		// NOOP
 	}
 }

typescript/vrotsc/e2e/cases/canvas-items/workflow.wf.ts

@@ -1,4 +1,4 @@
-import { Workflow, Out, In, Item, RootItem, DecisionItem, DefaultErrorHandler, WaitingTimerItem, WorkflowEndItem, WorkflowItem } from "vrotsc-annotations";
+import { Workflow, Out, In, Err, Item, RootItem, DecisionItem, DefaultErrorHandler, WaitingTimerItem, WorkflowEndItem, WorkflowItem } from "vrotsc-annotations";
 
 @Workflow({
 	name: "Workflow Test",
@@ -82,18 +82,16 @@ export class HandleNetworkConfigurationBackup {
 
 	@WorkflowEndItem({
 		endMode: 0,
-		exceptionVariable: "errorMessage",
 		businessStatus: "Bad"
 	})
-	public workflowEnd() {
+	public workflowEnd(@Err errorMessage: string) {
 		// NOOP
 	}
 
 	@DefaultErrorHandler({
-		exceptionVariable: "errorMessage",
 		target: "workflowEnd"
 	})
-	public defaultErrorHandler() {
+	public defaultErrorHandler(@Err errorMessage: string) {
 		// NOOP
 	}
 }

typescript/vrotsc/e2e/expect/canvas-items/workflows/VMware/PSCoE/Default Error Handler Custom Item.xml

@@ -1,3 +1,3 @@
 <?xml version="1.0" encoding="utf-8" ?><workflow xmlns="http://vmware.com/vco/workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vmware.com/vco/workflow http://vmware.com/vco/workflow/Workflow-v4.xsd" root-name="item1" object-name="workflow:name=generic" id="c1d64164-67ce-3561-a9bb-9b5a18a3075c" version="1.0.0" api-version="6.0.0" restartMode="1" resumeFromFailedMode="0"><display-name><![CDATA[Default Error Handler Custom Item]]></display-name><description><![CDATA[Default error handler workflow with error handler redirecting to a workflow item]]></description><position x="50" y="100" /><attrib name="errorMessage" type="string" read-only="false" /><workflow-item name="item0" type="end" end-mode="0"><position x="300" y="66.66666666666667" /></workflow-item><workflow-item name="item1" out-name="item2" type="task"><script encoded="false"><![CDATA[System.log("Initiating workflow execution");
 ]]></script><display-name><![CDATA[initiateWorkflow]]></display-name><position x="100" y="66.66666666666667" /></workflow-item><workflow-item name="item2" out-name="item0" type="task"><script encoded="false"><![CDATA[]]></script><display-name><![CDATA[goToEnd]]></display-name><position x="200" y="66.66666666666667" /></workflow-item><workflow-item name="item3" out-name="item5" type="task"><script encoded="false"><![CDATA[System.log("Processing error using custom task with message '".concat(errorMessage, "'"));
-]]></script><display-name><![CDATA[processError]]></display-name><in-binding><bind name="errorMessage" type="string" export-name="errorMessage" /></in-binding><position x="200" y="133.33333333333334" /></workflow-item><error-handler name="item3" throw-bind-name="errorMessage" ><position x="100" y="133.33333333333334" /></error-handler><workflow-item name="item5" type="end" end-mode="0" throw-bind-name="errorMessage" ><out-binding><bind name="errorMessage" type="string" export-name="errorMessage" /></out-binding><position x="300" y="133.33333333333334" /></workflow-item><presentation></presentation></workflow>
+]]></script><display-name><![CDATA[processError]]></display-name><in-binding><bind name="errorMessage" type="string" export-name="errorMessage" /></in-binding><position x="200" y="133.33333333333334" /></workflow-item><error-handler name="item3"  throw-bind-name="errorMessage"><position x="100" y="133.33333333333334" /></error-handler><workflow-item name="item5" type="end" end-mode="0"  throw-bind-name="errorMessage"><out-binding><bind name="errorMessage" type="string" export-name="errorMessage" /></out-binding><position x="300" y="133.33333333333334" /></workflow-item><presentation></presentation></workflow>

typescript/vrotsc/e2e/expect/canvas-items/workflows/VMware/PSCoE/Default Error Handler Happy.xml

@@ -1 +1 @@
-<?xml version="1.0" encoding="utf-8" ?><workflow xmlns="http://vmware.com/vco/workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vmware.com/vco/workflow http://vmware.com/vco/workflow/Workflow-v4.xsd" root-name="item1" object-name="workflow:name=generic" id="e0145a6f-f13f-382f-aa56-674a70accad9" version="1.0.0" api-version="6.0.0" restartMode="1" resumeFromFailedMode="0"><display-name><![CDATA[Default Error Handler Happy]]></display-name><description><![CDATA[Default error handler workflow]]></description><position x="50" y="100" /><attrib name="errorMessage" type="string" read-only="false" /><workflow-item name="item0" type="end" end-mode="0"><position x="300" y="66.66666666666667" /></workflow-item><workflow-item name="item1" out-name="item2" type="task"><script encoded="false"><![CDATA[]]></script><display-name><![CDATA[initiateWorkflow]]></display-name><position x="100" y="66.66666666666667" /></workflow-item><error-handler name="item0" throw-bind-name="errorMessage" ><position x="100" y="133.33333333333334" /></error-handler><presentation></presentation></workflow>
+<?xml version="1.0" encoding="utf-8" ?><workflow xmlns="http://vmware.com/vco/workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vmware.com/vco/workflow http://vmware.com/vco/workflow/Workflow-v4.xsd" root-name="item1" object-name="workflow:name=generic" id="e0145a6f-f13f-382f-aa56-674a70accad9" version="1.0.0" api-version="6.0.0" restartMode="1" resumeFromFailedMode="0"><display-name><![CDATA[Default Error Handler Happy]]></display-name><description><![CDATA[Default error handler workflow]]></description><position x="50" y="100" /><attrib name="errorMessage" type="string" read-only="false" /><workflow-item name="item0" type="end" end-mode="0"><position x="300" y="66.66666666666667" /></workflow-item><workflow-item name="item1" out-name="item2" type="task"><script encoded="false"><![CDATA[]]></script><display-name><![CDATA[initiateWorkflow]]></display-name><position x="100" y="66.66666666666667" /></workflow-item><error-handler name="item0"  throw-bind-name="errorMessage"><position x="100" y="133.33333333333334" /></error-handler><presentation></presentation></workflow>

typescript/vrotsc/e2e/expect/canvas-items/workflows/VMware/PSCoE/Workflow End Exception.xml

@@ -1 +1 @@
-<?xml version="1.0" encoding="utf-8" ?><workflow xmlns="http://vmware.com/vco/workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vmware.com/vco/workflow http://vmware.com/vco/workflow/Workflow-v4.xsd" root-name="item1" object-name="workflow:name=generic" id="52bdb90f-2e9c-3ee7-a290-aae3156e1a25" version="1.0.0" api-version="6.0.0" restartMode="1" resumeFromFailedMode="0"><display-name><![CDATA[Workflow End Exception]]></display-name><description><![CDATA[Workflow with root and end item with end mode 1]]></description><position x="50" y="100" /><attrib name="errorMessage" type="string" read-only="false" /><attrib name="businessStatus" type="string" read-only="false" /><workflow-item name="item0" type="end" end-mode="0"><position x="200" y="50" /></workflow-item><workflow-item name="item1" out-name="item0" type="custom-condition" alt-out-name="item2"><script encoded="false"><![CDATA[return true;]]></script><display-name><![CDATA[initiateWorkflow]]></display-name><position x="100" y="100" /></workflow-item><workflow-item name="item2" type="end" end-mode="1" throw-bind-name="errorMessage" business-status="Bad" ><position x="200" y="150" /></workflow-item><presentation></presentation></workflow>
+<?xml version="1.0" encoding="utf-8" ?><workflow xmlns="http://vmware.com/vco/workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://vmware.com/vco/workflow http://vmware.com/vco/workflow/Workflow-v4.xsd" root-name="item1" object-name="workflow:name=generic" id="52bdb90f-2e9c-3ee7-a290-aae3156e1a25" version="1.0.0" api-version="6.0.0" restartMode="1" resumeFromFailedMode="0"><display-name><![CDATA[Workflow End Exception]]></display-name><description><![CDATA[Workflow with root and end item with end mode 1]]></description><position x="50" y="100" /><attrib name="errorMessage" type="string" read-only="false" /><attrib name="businessStatus" type="string" read-only="false" /><workflow-item name="item0" type="end" end-mode="0"><position x="200" y="50" /></workflow-item><workflow-item name="item1" out-name="item0" type="custom-condition" alt-out-name="item2"><script encoded="false"><![CDATA[return true;]]></script><display-name><![CDATA[initiateWorkflow]]></display-name><position x="100" y="100" /></workflow-item><workflow-item name="item2" type="end" end-mode="1"  throw-bind-name="errorMessage"business-status="Bad" ><position x="200" y="150" /></workflow-item><presentation></presentation></workflow>

typescript/vrotsc/e2e/expect/canvas-items/workflows/VMware/PSCoE/Workflow Test.xml

@@ -15,4 +15,4 @@ else {
 System.log("Counter: " + counter);
 System.log("Waiting Timer: " + waitingTimer);
 ]]></script><display-name><![CDATA[execute]]></display-name><in-binding><bind name="waitingTimer" type="Date" export-name="waitingTimer" /><bind name="counter" type="number" export-name="counter" /></in-binding><out-binding><bind name="waitingTimer" type="Date" export-name="waitingTimer" /><bind name="counter" type="number" export-name="counter" /></out-binding><position x="200" y="66.66666666666667" /></workflow-item><workflow-item name="item6" out-name="item5" type="task"><script encoded="false"><![CDATA[System.log("Starting workflow");
-]]></script><display-name><![CDATA[start]]></display-name><position x="100" y="66.66666666666667" /></workflow-item><workflow-item name="item7" out-name="item5" type="waiting-timer"><display-name><![CDATA[waitForEvent]]></display-name><in-binding><bind name="timer.date" type="Date" export-name="waitingTimer" /></in-binding><position x="400" y="16.66666666666667" /></workflow-item><workflow-item name="item8" type="end" end-mode="0" throw-bind-name="errorMessage" business-status="Bad" ><position x="200" y="133.33333333333334" /></workflow-item><error-handler name="item8" throw-bind-name="errorMessage" ><position x="100" y="133.33333333333334" /></error-handler><presentation></presentation></workflow>
+]]></script><display-name><![CDATA[start]]></display-name><position x="100" y="66.66666666666667" /></workflow-item><workflow-item name="item7" out-name="item5" type="waiting-timer"><display-name><![CDATA[waitForEvent]]></display-name><in-binding><bind name="timer.date" type="Date" export-name="waitingTimer" /></in-binding><position x="400" y="16.66666666666667" /></workflow-item><workflow-item name="item8" type="end" end-mode="0"  throw-bind-name="errorMessage"business-status="Bad" ><position x="200" y="133.33333333333334" /></workflow-item><error-handler name="item8"  throw-bind-name="errorMessage"><position x="100" y="133.33333333333334" /></error-handler><presentation></presentation></workflow>

typescript/vrotsc/src/compiler/decorators.ts

@@ -89,7 +89,8 @@ export interface WorkflowParameter {
 export enum WorkflowParameterType {
 	Default = 0,
 	Input = 1 << 0,
-	Output = 2 << 1,
+	Output = 1 << 2,
+	Err = 1 << 3
 }
 
 export enum WorkflowItemType {

typescript/vrotsc/src/compiler/transformer/fileTransformers/workflow/decorators.ts

@@ -104,6 +104,15 @@ function getItemStrategy(decoratorNode: ts.Decorator): CanvasItemDecoratorStrate
 	}
 }
 
+/**
+ * Registers all the argument decorators for the method
+ *
+ * Adds `input`, `output` and `canvasItemPolymorphicBag.exceptionBinding`
+ *
+ * @param methodNode The method node
+ * @param itemInfo The item info
+ * @returns void
+ */
 export function registerMethodArgumentDecorators(methodNode: ts.MethodDeclaration, itemInfo: WorkflowItemDescriptor) {
 	if (!methodNode.parameters.length) {
 		return;
@@ -118,17 +127,20 @@ export function registerMethodArgumentDecorators(methodNode: ts.MethodDeclaratio
 		// Adds state of what decorators are present
 		getDecoratorNames(decorators).forEach(decoratorName => {
 			switch (decoratorName || "In") {
-				case "In": {
+				case "In":
 					parameterType |= WorkflowParameterType.Input;
 					break;
-				}
-				case "Out": {
+
+				case "Out":
 					parameterType |= WorkflowParameterType.Output;
 					break;
-				}
-				default: {
+
+				case "Err":
+					parameterType |= WorkflowParameterType.Err;
+					break;
+
+				default:
 					throw new Error(`Decorator '${decoratorName}' is not supported'`);
-				}
 			}
 		});
 		if (parameterType === WorkflowParameterType.Default) {
@@ -140,6 +152,9 @@ export function registerMethodArgumentDecorators(methodNode: ts.MethodDeclaratio
 		if (parameterType & WorkflowParameterType.Output) {
 			itemInfo.output.push(name);
 		}
+		if (parameterType & WorkflowParameterType.Err) {
+			itemInfo.canvasItemPolymorphicBag.exceptionBinding = name;
+		}
 
 		addParamToWorkflowParams(itemInfo.parent, paramNode, parameterType);
 	});