Workflow Designer
The Workflow Designer is a component in UBIK® which appears on many occasions, namely every time when there is a Workflow to be displayed or edited. It features a full re-hosted version of the designer for the Microsoft Workflow Foundation, extended with manipulation capabilities for UBIK® objects.
Workflow Designer used in the Workflow Editor control
Contents
Basics
Toolbox
The Toolbox features a broad range of activities that cane be used within your Workflows. There are generic activities as well as activities specific for the manipulation of UBIK® objects.
Standard activities
| Activity | Category | Purpose |
|---|---|---|
| AddToCollection<T> | Collection | Adds an Item to a Collection |
| ClearCollection<T> | Collection | Removes an Item from a Collection |
| ExistsInCollection<T> | Collection | Clears a Collection, removing all items stored in it |
| RemoveFromCollection<T> | Collection | Verifies if an Item exists in a Collection; if the item exists, its Result argument will yield True |
| DoWhile | ControlFlow | Executes its Body until the Condition evaluates to True; the Body will be executed at least once |
| ForEach<T> | ControlFlow | ForEach activity contains a list of Values and a Body; at runtime, the list is iterated and the body is executed for each value in the list |
| If | ControlFlow | The If activity selects a child activity for execution based on the value of a Boolean expression; if the Boolean expression Condition yields True (and “Then” activity is configured), the Then activity is scheduled; if the expressions yields False (and Else activity is set), the Else expression is scheduled |
| Parallel | ControlFlow | Parallel activity allows parallel execution of its children; it operates by scheduling each WorkflowElement in its Branches collection at the beginning of its execution; it completes when all of its Branches complete or when its CompletionCondition property evaluates to true |
| ParallelForEach<T> | ControlFlow | The ParallelForEach activity enumerates the elements of a collection(Values) and executes an Activity for each element of the collection, in a similar way than the ForEach activity does; the main difference is that the embedded statement is executed in a parallel fashion; just like the Parallel Activity, ParallelForEach has a CompletionCondition, so that the ParallelForEach activity could complete early if the evaluation of the CompletionCondition returns true; the CompletionCondition is evaluated after each iteration is completed |
| Pick | ControlFlow | The Pick Activity provides event-based control flow modeling in WF; the only valid children for a Pick activity are PickBranches; at the beginning of a Pick execution, all the Trigger activities from all its Branches are scheduled; when the first Trigger completes its corresponding Action activity is scheduled, and all other Trigger activities are canceled |
| PickBranch | ControlFlow | PickBranch represents a branch in a Pick; it consists of a Trigger and Action; PickBranch can only be added to a Pick activity |
| Sequence | ControlFlow | The Sequence activity allows for the execution of one or more Activities in order |
| Switch<T> | ControlFlow | Switch activity is similar to switch statement in C#; it contains an Expression and a set of Cases (each case has a key and an activity); after the expression is evaluated, the Switch activity looks for a Case with a key that matches the result of the expression and if found, it schedules the activity associated with that Case |
| While | ControlFlow | The While activity executes it's Body while a Boolean Condition is True |
| Rethrow | ErrorHandling | Throws a previously thrown exception from within a Catch activity |
| Throw | ErrorHandling | Throw activity throws an exception within a workflow; Throw activity has an Exception property that contains the exception that will be thrown at execution time |
| TryCatch | ErrorHandling | TryCatch activity is similar to the try...catch construct in C#: all activities in the Try block are executed and if an exception occurs, it will schedule the Catch block that best matches that exception (if no matching catch is found, the workflow is aborted); all Catch blocks are contained in a collection called Catches; TryCatch activity also has a Finally block that is executed after the Try (and any eventual Catch); a note on unhandled exceptions: TryCatch provides exception handling at the workflow level; when an unhandled exception is thrown, the workflow is aborted and therefore the Finally block won’t be executed; this behavior is consistent with C# |
| FlowChart | FlowChart | This is the root for a Flowchart; since Flowchart is an activity like any other, it can be composed inside any container activity; for example, we can add a Flowchart inside of a Sequence or a Flowchart inside another Flowchart; the green ball in the image at the right represents the start node of the Flowchart |
| FlowSwitch<T> | FlowChart | FlowSwitch activity selects a next node depending on the value of an expression; FlowSwitch can be seen as the equivalent of the procedural Switch activity in the Flowchart world |
| FlowDecision | FlowChart | FlowDecision models conditional forks within a Flowchart; tt can be seen as the equivalent of the procedural If activity in the Flowchart world; this activity contains a Boolean expression Condition; if the expression evaluates to “True”, the true path is executed (otherwise, the false path is scheduled) |
| Assign | Primitives | The Assign activity assigns the value of its Value argument to its To argument; the types of both arguments must be compatible; this compatibility is verified at runtime |
| Assign<T> | Primitives | The Assign<T> activity assigns the value of its Value argument to its To argument; the types of both arguments must be compatible; this compatibility is verified at design time |
| Delay | Primitives | Delay Activity, as its name suggests, will block the current workflow execution path for a Duration specified by user; after the duration expires, the workflow continues execution as expected; the duration of the delay is set using a TimeSpan |
| InvokeMethod | Primitives | InvokeMethod is the activity that allows you to call an existing CLR instance or static method; to invoke a method all you need to do is provide the owner of the method (TargetType for static methods, TargetObject for instance methods), the MethodName, and its Parameters |
| WriteLine | Primitives | Writes text to the configured output console |
| Persist | Runtime | Persists the workflow instance. Persistence will be done using the configuration of the WorkflowInstance that is being executed (this activity doesn’t have any arguments) |
| TerminateWorkflow | Runtime | Terminates the running workflow instance, raises the Completed event in the host, and reports error information; once the workflow is terminated, it cannot be resumed |
| CancellationScope | Transaction | The CancellationScope activity consists of two main parts, the Body and the CancelHandler; the body is the code path that normally executes; if the activity gets canceled, then the cancel handler is called |
| CompensableActivity | Transaction | CompensableActivity is used to define a potentially long running activity with accompanying Compensation and Confirmation logic; compensation allows the user to specify corrective action to be taken on an activity based upon activity which occurs after the successful completion of the Body of the activity |
| Compensate | Transaction | Compensate is used to explicitly invoke the compensation handler of a CompensableActivity |
| Confirm | Transaction | Confirm is used to explicitly invoke the confirmation handler of a CompensableActivity |
| TransactionScope | Transaction | The TransactionScopeActivity provides the mechanism for initializing a new transaction, making the transaction handle ambient (a workflow execution property) and calling complete on the transaction once the Body of the TransactionScope activity has completed |
UBIK® activities
| Activity | Category | Purpose (Short) |
|---|---|---|
| DebugMessage | UBIK Control Flow | Writes a debug Text |
| WriteLogEntry | UBIK Control Flow | Writes a log entry via the workflow logging mechanism |
| InvokeInterface | UBIK Control Flow | Invokes a UBIK® Interface component |
| InvokeWorkflow | UBIK Control Flow | Invokes a UBIK® Workflow object |
| SendEmail | UBIK Control Flow | Sends an Email To recipients via an SMTP Host |
| CreateCSVScope | UBIK Data Exchange | Creates a new csv document for flat data export |
| CreateCSVRow | UBIK Data Exchange | Creates a single row in a csv file |
| CreateCSVValue | UBIK Data Exchange | Creates a single value (column) in a csv row |
| CreateXMLScope | UBIK Data Exchange | Creates a new xml document for hierarchical data export |
| CreateXMLElement | UBIK Data Exchange | Creates a new xml element in an xml document |
| CreateXMLAttribute | UBIK Data Exchange | Creates a new xml attribute on an xml element |
| ReadCSVDocument | UBIK Data Exchange | Reads a csv file for flat data import |
| ReadXPathDocument | UBIK Data Exchange | Reads an xml file for hierarchical data import |
| GetXPathResult | UBIK Data Exchange | Evaluates an XPath-expression in a csv or xml document |
| CreateOLEOracleScope | UBIK Data Exchange | Creates a connection to an Oracle data source via OLE |
| CreateOLESQLScope | UBIK Data Exchange | Creates a connection to a SQL server data source via OLE |
| CreateOLEExcelScope | UBIK Data Exchange | Creates a connection to an Excel data source via OLE |
| CreateOLETableScope | UBIK Data Exchange | Creates a connection to a single table in an OLE data source |
| CreateOLERow | UBIK Data Exchange | Creates a new row (record) in an OLE table |
| EditOLERow | UBIK Data Exchange | Edits a single row of an OLE table |
| EditOLEValue | UBIK Data Exchange | Edits a single value of an OLE row (record) |
| AssignToNamedRelation | UBIK Object Primitives | Assigns a Child object via the named RelationName to a Parent object |
| AssignToSystemRelation | UBIK Object Primitives | Assigns a Child object via the given Relation to a Parent object |
| CreateInstance | UBIK Object Primitives | Creates a new instance of a given MetaClass |
| DeleteObject | UBIK Object Primitives | Deletes a UBIKObject (Deep delete by default, ShallowDelete optional) |
| GetObjectsByPropertyValue | UBIK Object Primitives | Queries instances of MetaClass where PropertyName has a certain value |
| GetObjectsByQuery | UBIK Object Primitives | Delivers the result of Query |
| GetObjectsByView | UBIK Object Primitives | Delivers the children the UBIKObject has in View |
| GetObjectByID | UBIK Object Primitives | Attempts to load an object via its GUID |
| GetCustomizedSystemObject | UBIK Object Primitives | Attempts to load an object that is configured as the customizing derivate of a systemobject |
| GetPropertyValue | UBIK Object Primitives | Gets the Value of the property named PropertyName from UBIKObject |
| RemoveFromNamedRelation | UBIK Object Primitives | Removes a Child object via the named RelationName from a Parent object |
| RemoveFromSystemRelation | UBIK Object Primitives | Removes a Child object via the given Relation from a Parent object |
| SaveObject | UBIK Object Primitives | Saves the UBIKObject (Deep save by default, ShallowSave optional) |
| SetPropertyValue | UBIK Object Primitives | Sets the Value to the property named PropertyName of the UBIKObject |
| AssignIconToBaseClass | UBIK UI Primitives | Assigns a selectable icon image to the UBIKObject |
| SelectSourceFile | UBIK UI Primitives | Brings up an open file dialog |
| SelectTargetFile | UBIK UI Primitives | Brings up a save file dialog |
| ShowUnsavedObjectsHierarchy | UBIK UI Primitives | Brings up the Unsaved Objects dialog |
| UserDecisionYesNo | UBIK UI Primitives | Brings up a Yes/No dialog with configurable Title and Text |
| UserInputText | UBIK UI Primitives | Brings up an input box with configurable Title and Text |
| EditClassDetail | UBIK Wizards | Brings up the Class Details control for UBIKObject in a Wizard |
| EditObject | UBIK Wizards | Brings up the Object Editor control for UBIKObject in a Wizard |
| EditRelation | UBIK Wizards | Brings up the Relation Editor control for UBIKObject and UBIKRelationship in a Wizard |
| EditRelationData | UBIK Wizards | Brings up the Object Editor control to edit RelationData between UBIKObject and Child in a Wizard |
| ReplicateInstance | UBIK Replication | Creates a replicate of the given source object based on the given ReplicationConfiguration. |
Design canvas
The design canvas is in the center of the control. This is the space where activities can be placed and arranged, typically with Drag&Drop from the Toolbox.
Property window
The property window consumes the right area of the control and is there to configure a single workflow activity. A typical configuration consists of supplying parameters with expressions or variables. All parameters are directed, which means they are either
- In
- Out
- Both
These directions are always from the perspective of the activity.
There is no design restriction that comes with that, it is more a supporting feature telling something about the argument: an inbound parameter will never write to a variable supplied and an outbound parameter will never read a value supplied to it.
Working with the designer
Toolbar
| Item | Purpose |
|---|---|
| Open file | Opens a dialog to load a previously saved UBIK® workflow file (.uwf) into the design canvas |
| Save to file | Saves the current design canvas into a file (.uwf) |
| Toggle breakpoint | Sets/Removes a breakpoint at the currently selected activity (async execution only) |
| Resume | Resumes execution if a breakpoint was hit (async execution only) |
| Delay between activities | Execution delay in Milliseconds between activities (async execution only) |
This control doesn't feature any context menu yet.
Designing workflows
Designing a workflow is fairly easy and typically involves placing, configuring and connecting various activities. All available activities are listed in the Toolbox on the left side. Use Drag&Drop to place an activity on the canvas in the middle. Select an activity on the canvas and use the context menu or the Del key to remove it again.
 | Unless the activity is of type FlowChart or Sequence, you will not be able to add more than one activity to the canvas |
Typically we want to start with a Sequence or a Flowchart, which are both able to host child (nested) activities
- The Sequence executes its nested activities sequentially, one after the other
- The FlowChart executes its nested activities in the order you link them with connecting lines
After placing a new activity, use the Property window to configure its arguments. Misconfiguration of an argument typically leads to a red exclamation mark on the activity, where the tooltip text displays the details of the error.
| Some activities expose special designers, that allow you to edit selected arguments directly in the canvas. However, this is just a different and limited view, the property window will always show all available arguments |
Arguments
Arguments are parameters that are either passed into the workflow on start up or returned by it when it exits.
They can be created in the arguments editor which is located at the bottom area of the design canvas. Once created, an argument can be referenced by its name in the activities.
 | Every argument you create has to be supplied to the workflow, missing arguments will lead to an exception! |
Variables
Variables are meant to pass values between activities and are therefore very important for the logic of a workflow. So if you want to i.e. pass a string from activity A to activity B, you need to
- create a variable of type String
- assign it to an out string parameter of activity A
- assign it to the in string parameter of activity B
Variables can be created in the variables editor which is located at the bottom area of the design canvas. Once created, a variable can be referenced by its name in the activities.
| Variables are only accessible in the defined scope, so please make sure to set the scope right |
Expressions
Most of the arguments and variables can be supplied with expressions instead of fixed values. Expressions will be evaluated at runtime and provide a powerful way to solve complex problems. Due to the underlying Microsoft Workflow Foundation, expressions are exclusively coded in VB.NET - unlike any other coding in UBIK® which is typically done in C#.
