Last modified on 14 June 2016, at 15:24

Workflow Designer

Revision as of 15:24, 14 June 2016 by KNO (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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

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)

Context menu

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.

IC Hint square.pngUnless 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.

IC Hint square.pngSome 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.

IC Attention.pngEvery 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.

IC Attention.pngVariables 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#.

See also