SaaS CMS has officially launched! Learn more now.

Class InstanceHandler

Implementation of IInstanceHandler. This is the main component for handling of workflow instances

Inheritance
System.Object
InstanceHandler
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: EPiServer.WorkflowFoundation
Assembly: EPiServer.WorkflowFoundation.dll
Version: 7.19.2
Syntax
public class InstanceHandler : IInstanceHandler, ICommunicationServiceCallback

Constructors

InstanceHandler(IStorageProvider, IBroadcastHandler, WorkflowRuntime)

Do not create an instance of this object, use InstanceHandler to get the singelton instance instead.

Declaration
[Obsolete("Use the constructor which takes a LocalizationService instead", false)]
public InstanceHandler(IStorageProvider storageProvider, IBroadcastHandler broadcastHandler, WorkflowRuntime runtime)
Parameters
Type Name Description
IStorageProvider storageProvider

A handle to the storage provider

IBroadcastHandler broadcastHandler

The broadcast handler.

System.Workflow.Runtime.WorkflowRuntime runtime

A handle to runtime

InstanceHandler(IStorageProvider, IBroadcastHandler, WorkflowRuntime, LocalizationService)

Do not create an instance of this object, use InstanceHandler to get the singelton instance instead.

Declaration
public InstanceHandler(IStorageProvider storageProvider, IBroadcastHandler broadcastHandler, WorkflowRuntime runtime, LocalizationService localizationService)
Parameters
Type Name Description
IStorageProvider storageProvider

A handle to the storage provider

IBroadcastHandler broadcastHandler

The broadcast handler.

System.Workflow.Runtime.WorkflowRuntime runtime

A handle to runtime

LocalizationService localizationService

The resource locator used for translation.

Properties

BroadcastHandler

Handle to broadcast sender

Declaration
protected IBroadcastHandler BroadcastHandler { get; }
Property Value
Type Description
IBroadcastHandler
Remarks

To change type override EPiServer.WorkflowFoundation.AspNetWorkflowManager.BroadcastHandler

LocalizationService

The localizationService used for translations.

Declaration
protected LocalizationService LocalizationService { get; }
Property Value
Type Description
LocalizationService
Remarks

Will use the static instance Current if not set.

Runtime

The workflow runtime

Declaration
protected WorkflowRuntime Runtime { get; }
Property Value
Type Description
System.Workflow.Runtime.WorkflowRuntime

StorageProvider

Handle to storage provider

Declaration
protected IStorageProvider StorageProvider { get; }
Property Value
Type Description
IStorageProvider
Remarks

To change type override StorageProvider

WorkflowInstances

Local (within this class) access to the _workflowInstances variable should always goes through this accessor. (This is to assure it is loaded when using LazyLoading)

Declaration
protected virtual Dictionary<Guid, WorkflowDefinitionInstance> WorkflowInstances { get; }
Property Value
Type Description
System.Collections.Generic.Dictionary<System.Guid, WorkflowDefinitionInstance>

Methods

AddHistoryItem(String, String, String, Guid)

Adds a history item to a workflow instance

Declaration
public virtual void AddHistoryItem(string subject, string description, string user, Guid instanceId)
Parameters
Type Name Description
System.String subject

The subject of the item to log

System.String description

The description of the item to log

System.String user

The user related to this item (if any)

System.Guid instanceId

The instance id.

AddUserData(String, Object, Boolean, Guid)

Adds an serialized object to the UserData member of an instance

Declaration
public virtual void AddUserData(string key, object value, bool logAction, Guid instanceId)
Parameters
Type Name Description
System.String key

The key.

System.Object value

The value.

System.Boolean logAction

if set to true [log action].

System.Guid instanceId

The instance id.

Remarks

The passed object must be serializable and if a custom type is used then schema of type must be registered with object store

AssociateWithPage(PageReference, Boolean, Guid)

Associates an instance with a page.

Declaration
public virtual void AssociateWithPage(PageReference pageLink, bool logAction, Guid instanceId)
Parameters
Type Name Description
PageReference pageLink

The page link.

System.Boolean logAction

if set to true [log action].

System.Guid instanceId

The instance id.

ContainsInstance(Guid)

Indicates wetter there exists an instance with this id

Declaration
public virtual bool ContainsInstance(Guid workflowInstanceId)
Parameters
Type Name Description
System.Guid workflowInstanceId

instance id

Returns
Type Description
System.Boolean

wetter instance exist

CreateTaskForInstance(Guid, String, String, String, PageReference, Boolean, Boolean, Boolean)

Creates a task and associates it with the instance

Declaration
public virtual Task CreateTaskForInstance(Guid workflowInstanceId, string assignedTo, string subject, string description, PageReference pageLink, bool notifyByEmail, bool logAction, bool activityRelated)
Parameters
Type Name Description
System.Guid workflowInstanceId

The workflow instance id.

System.String assignedTo

The person/group this task is assigned to

System.String subject

The subject of the task

System.String description

The description of the task

PageReference pageLink

The page if the task should be associated with a page

System.Boolean notifyByEmail

if set to true a notification is sent to assignedTo

System.Boolean logAction

if set to true an entry is added to history items for the workflow instance

System.Boolean activityRelated

if set to true event related activities are looked for ActivityPlugIn and if found control specified is loaded for task. if set to false standard task view is shown

Returns
Type Description
Task

the created task

Exceptions
Type Condition
WorkflowInstanceException

If instance not found

CreateTaskForInstance(Guid, String, String, String, DateTime, PageReference, Boolean, Boolean, Boolean, String, Dictionary<String, Object>)

Creates a task related to instance.

Declaration
public virtual Task CreateTaskForInstance(Guid workflowInstanceId, string assignedTo, string subject, string description, DateTime dueDate, PageReference pageLink, bool notifyByEmail, bool logAction, bool activityRelated, string eventActivityName, Dictionary<string, object> stateBag)
Parameters
Type Name Description
System.Guid workflowInstanceId

The workflow instance id.

System.String assignedTo

The assigned to.

System.String subject

The subject.

System.String description

The description.

System.DateTime dueDate

The due date.

PageReference pageLink

The page link.

System.Boolean notifyByEmail

if set to true [notify by email].

System.Boolean logAction

if set to true [log action].

System.Boolean activityRelated

if set to true [activity related].

System.String eventActivityName

Name of the event activity.

System.Collections.Generic.Dictionary<System.String, System.Object> stateBag

The state bag.

Returns
Type Description
Task

The created task

DeleteTask(Int32, Boolean, Guid)

Deletes a task.

Declaration
public virtual void DeleteTask(int taskId, bool logAction, Guid instanceId)
Parameters
Type Name Description
System.Int32 taskId

The task id.

System.Boolean logAction

if set to true [log action].

System.Guid instanceId

The instance id.

DeleteTasksForInstance(Boolean, Guid)

Deletes all tasks associated with an instance

Declaration
public virtual void DeleteTasksForInstance(bool logAction, Guid workflowInstanceId)
Parameters
Type Name Description
System.Boolean logAction

if set to true [log action].

System.Guid workflowInstanceId

The workflow instance id.

GetInstance(Guid)

Gets instance

Declaration
public virtual WorkflowDefinitionInstance GetInstance(Guid workflowInstanceId)
Parameters
Type Name Description
System.Guid workflowInstanceId

instance id

Returns
Type Description
WorkflowDefinitionInstance

instance

Exceptions
Type Condition
WorkflowInstanceException

If instance not found

GetInstance(Guid, AccessLevel)

Gets the instance.

Declaration
public virtual WorkflowDefinitionInstance GetInstance(Guid workflowInstanceId, AccessLevel accessLevel)
Parameters
Type Name Description
System.Guid workflowInstanceId

The workflow instance id.

AccessLevel accessLevel

The access level.

Returns
Type Description
WorkflowDefinitionInstance

instance

Exceptions
Type Condition
WorkflowInstanceException

If instance not found

GetInstances()

Gets all running Workflow instances

Declaration
public virtual IList<WorkflowDefinitionInstance> GetInstances()
Returns
Type Description
System.Collections.Generic.IList<WorkflowDefinitionInstance>

Instances

GetInstances(PageReference)

Returns information about all instantiated Workflows attached to a specific page that are not completed

Declaration
public virtual IList<WorkflowDefinitionInstance> GetInstances(PageReference pageLink)
Parameters
Type Name Description
PageReference pageLink

pageLink

Returns
Type Description
System.Collections.Generic.IList<WorkflowDefinitionInstance>

information about all Workflow instances

Remarks

It will return instances that are associated with any version of the page

GetInstances(PageReference, AccessLevel)

Returns information about all instantiated Workflows attached to a specific page that are not completed

Declaration
public virtual IList<WorkflowDefinitionInstance> GetInstances(PageReference pageLink, AccessLevel accessLevel)
Parameters
Type Name Description
PageReference pageLink

pageLink

AccessLevel accessLevel

The access level.

Returns
Type Description
System.Collections.Generic.IList<WorkflowDefinitionInstance>

information about all Workflow instances

Remarks

It will return instances that are associated with any version of the page

GetInstances(AccessLevel)

Gets all running Workflow instances that caller has given access to

Declaration
public virtual IList<WorkflowDefinitionInstance> GetInstances(AccessLevel accessLevel)
Parameters
Type Name Description
AccessLevel accessLevel

The acess level to match for

Returns
Type Description
System.Collections.Generic.IList<WorkflowDefinitionInstance>

Instances

GetInstances(Guid)

Returns information about all instantiated Workflows from a specified definition that are not completed

Declaration
public virtual IList<WorkflowDefinitionInstance> GetInstances(Guid workflowDefinitionId)
Parameters
Type Name Description
System.Guid workflowDefinitionId

The definitionId

Returns
Type Description
System.Collections.Generic.IList<WorkflowDefinitionInstance>

information about all Workflow instances

GetInstances(Guid, AccessLevel)

Returns information about all instantiated Workflows from a specified definition that are not completed

Declaration
public virtual IList<WorkflowDefinitionInstance> GetInstances(Guid workflowDefinitionId, AccessLevel accessLevel)
Parameters
Type Name Description
System.Guid workflowDefinitionId

The workflow definition id.

AccessLevel accessLevel

The access level.

Returns
Type Description
System.Collections.Generic.IList<WorkflowDefinitionInstance>

information about all Workflow instances

GetInstances(Type)

Returns information about all instantiated Workflows of a certain type that are not completed

Declaration
public virtual IList<WorkflowDefinitionInstance> GetInstances(Type workflowType)
Parameters
Type Name Description
System.Type workflowType

the type to match against

Returns
Type Description
System.Collections.Generic.IList<WorkflowDefinitionInstance>

information about all Workflow instances

GetInstances(Type, AccessLevel)

Returns information about all instantiated Workflows of a certain type that are not completed

Declaration
public virtual IList<WorkflowDefinitionInstance> GetInstances(Type workflowType, AccessLevel accessLevel)
Parameters
Type Name Description
System.Type workflowType

Type of the workflow.

AccessLevel accessLevel

The access level.

Returns
Type Description
System.Collections.Generic.IList<WorkflowDefinitionInstance>

information about all Workflow instances

GetQueueInfo(Guid)

Gets the Workflow queue for a specific Workflow instance, could be used i.e. to determine which event a specific Workflow waits for

Declaration
public virtual ReadOnlyCollection<WorkflowQueueInfo> GetQueueInfo(Guid workflowInstanceId)
Parameters
Type Name Description
System.Guid workflowInstanceId

the workflow instance

Returns
Type Description
System.Collections.ObjectModel.ReadOnlyCollection<System.Workflow.Runtime.WorkflowQueueInfo>

Gets all items in queue

Exceptions
Type Condition
WorkflowInstanceException

If instance not found

GetSystemInstance(Guid)

Gets the wrapped system instance

Declaration
public virtual WorkflowInstance GetSystemInstance(Guid workflowInstanceId)
Parameters
Type Name Description
System.Guid workflowInstanceId

The workflow instance id.

Returns
Type Description
System.Workflow.Runtime.WorkflowInstance

system instance

GetTasks(Guid)

Gets all tasks related to the workflow instance

Declaration
public virtual IList<Task> GetTasks(Guid workflowInstanceId)
Parameters
Type Name Description
System.Guid workflowInstanceId

The workflow instance id.

Returns
Type Description
System.Collections.Generic.IList<Task>

A list of all task associated with this instance

GetWaitingEvents(Guid)

Gets the Acivitys for the Workflow that are registered to listen for events

Declaration
public virtual IList<Activity> GetWaitingEvents(Guid workflowInstanceId)
Parameters
Type Name Description
System.Guid workflowInstanceId

The workflow instance id.

Returns
Type Description
System.Collections.Generic.IList<System.Workflow.ComponentModel.Activity>

waiting activities

Exceptions
Type Condition
WorkflowInstanceException

If instance not found

LoadInstances()

Loads persisted info about Workflow instances

Declaration
protected virtual Dictionary<Guid, WorkflowDefinitionInstance> LoadInstances()
Returns
Type Description
System.Collections.Generic.Dictionary<System.Guid, WorkflowDefinitionInstance>

instances

SaveInstance(WorkflowDefinitionInstance)

Saves the instance

Declaration
public virtual void SaveInstance(WorkflowDefinitionInstance instance)
Parameters
Type Name Description
WorkflowDefinitionInstance instance

The updated instance

Exceptions
Type Condition
AccessDeniedException

If current user has not rights to save instance

WorkflowInstanceException

If instance not found

WorkflowDefinitionException

If definition not found

SaveInstance(WorkflowDefinitionInstance, AccessLevel)

Saves the instance

Declaration
public virtual void SaveInstance(WorkflowDefinitionInstance instance, AccessLevel access)
Parameters
Type Name Description
WorkflowDefinitionInstance instance

The updated instance

AccessLevel access

The access.

Exceptions
Type Condition
AccessDeniedException

If current user has not rights to save instance

WorkflowInstanceException

If instance not found

WorkflowDefinitionException

If definition not found

StartInstance(Guid)

Starts a Workflow of specified definition

Declaration
public virtual WorkflowDefinitionInstance StartInstance(Guid definitionId)
Parameters
Type Name Description
System.Guid definitionId

The definition id.

Returns
Type Description
WorkflowDefinitionInstance

The created instance

Remarks

null is returned if some event handler to InstanceStarting cancels the action

Exceptions
Type Condition
System.Workflow.ComponentModel.Compiler.WorkflowValidationFailedException

The workflow engine fails to validate the workflow definition

AccessDeniedException

Access denied

WorkflowInstanceException

Action was cancelled

WorkflowException

Unexpected failure

StartInstance(Guid, IDictionary<String, Object>)

Starts a Workflow of specified definition

Declaration
public virtual WorkflowDefinitionInstance StartInstance(Guid definitionId, IDictionary<string, object> args)
Parameters
Type Name Description
System.Guid definitionId

The definition id.

System.Collections.Generic.IDictionary<System.String, System.Object> args

optional params passed to Workflow

Returns
Type Description
WorkflowDefinitionInstance

The created instance

Remarks

null is returned if some event handler to InstanceStarting cancels the action

Exceptions
Type Condition
System.Workflow.ComponentModel.Compiler.WorkflowValidationFailedException

The workflow engine fails to validate the workflow definition

AccessDeniedException

If current user has not rights to start instance

WorkflowInstanceException

Unexpected failure

StartInstance(Guid, IDictionary<String, Object>, PageReference)

Starts an instance of a Workflow definition

Declaration
public virtual WorkflowDefinitionInstance StartInstance(Guid definitionId, IDictionary<string, object> args, PageReference pageLink)
Parameters
Type Name Description
System.Guid definitionId

The definition id to start an instance of

System.Collections.Generic.IDictionary<System.String, System.Object> args

passed to Workflow instance as start arguments

PageReference pageLink

page that this instance relates to. PageReference.EmptyReference if not page related

Returns
Type Description
WorkflowDefinitionInstance

The created instance

Remarks

null is returned if some event handler to InstanceStarting cancels the action

Exceptions
Type Condition
System.Workflow.ComponentModel.Compiler.WorkflowValidationFailedException

The workflow engine fails to validate the workflow definition

AccessDeniedException

If current user has not rights to start instance

WorkflowInstanceException

Unexpected failure

StartInstance(Guid, IDictionary<String, Object>, PageReference, AccessLevel)

Starts a Workflow of specified definition

Declaration
public virtual WorkflowDefinitionInstance StartInstance(Guid definitionId, IDictionary<string, object> args, PageReference pageLink, AccessLevel access)
Parameters
Type Name Description
System.Guid definitionId

The definition id.

System.Collections.Generic.IDictionary<System.String, System.Object> args

optional start params passed to Workflow

PageReference pageLink

If given, associates Workflow with the given page

AccessLevel access

The required access level for start instance

Returns
Type Description
WorkflowDefinitionInstance

The created instance

Remarks

null is returned if some event handler to InstanceStarting cancels the action

Exceptions
Type Condition
System.Workflow.ComponentModel.Compiler.WorkflowValidationFailedException

The workflow engine fails to validate the workflow definition

AccessDeniedException

Access denied

WorkflowInstanceException

Action was cancelled

WorkflowException

Unexpected failure

StartInstance(Guid, IDictionary<String, Object>, Guid)

Starts a Workflow of specified definition with a specified instance id

Declaration
public virtual WorkflowDefinitionInstance StartInstance(Guid definitionId, IDictionary<string, object> args, Guid instanceId)
Parameters
Type Name Description
System.Guid definitionId

The definition id.

System.Collections.Generic.IDictionary<System.String, System.Object> args

optional start params passed to Workflow

System.Guid instanceId

The id of the instance to be created

Returns
Type Description
WorkflowDefinitionInstance

The created instance

Remarks

null is returned if some event handler to InstanceStarting cancels the action

Exceptions
Type Condition
System.Workflow.ComponentModel.Compiler.WorkflowValidationFailedException

The workflow engine fails to validate the workflow definition

AccessDeniedException

Access denied

WorkflowInstanceException

Action was cancelled

WorkflowException

Unexpected failure

StartInstance(Guid, IDictionary<String, Object>, Guid, PageReference, AccessLevel)

Starts a Workflow of specified definition

Declaration
protected virtual WorkflowDefinitionInstance StartInstance(Guid definitionId, IDictionary<string, object> args, Guid instanceId, PageReference pageLink, AccessLevel access)
Parameters
Type Name Description
System.Guid definitionId

definition id

System.Collections.Generic.IDictionary<System.String, System.Object> args

start parameters

System.Guid instanceId

instance id

PageReference pageLink

related page

AccessLevel access

access level

Returns
Type Description
WorkflowDefinitionInstance

instance

Remarks

null is returned if some event handler to InstanceStarting cancels the action

Exceptions
Type Condition
System.Workflow.ComponentModel.Compiler.WorkflowValidationFailedException

The workflow engine fails to validate the workflow definition

AccessDeniedException

Access denied

WorkflowInstanceException

Action was cancelled

WorkflowException

Unexpected failure

StartInstance(Guid, IDictionary<String, Object>, Guid, AccessLevel)

Starts a Workflow of specified definition with a specified instance id

Declaration
public virtual WorkflowDefinitionInstance StartInstance(Guid definitionId, IDictionary<string, object> args, Guid instanceId, AccessLevel access)
Parameters
Type Name Description
System.Guid definitionId

The definition id.

System.Collections.Generic.IDictionary<System.String, System.Object> args

optional start params passed to Workflow

System.Guid instanceId

The id of the instance to be created

AccessLevel access

The access.

Returns
Type Description
WorkflowDefinitionInstance

The created instance

Remarks

null is returned if some event handler to InstanceStarting cancels the action

Exceptions
Type Condition
System.Workflow.ComponentModel.Compiler.WorkflowValidationFailedException

The workflow engine fails to validate the workflow definition

AccessDeniedException

Access denied

WorkflowInstanceException

Action was cancelled

WorkflowException

Unexpected failure

TerminateInstance(Guid, String)

Terminates a given Workflow instance

Declaration
public virtual void TerminateInstance(Guid workflowInstanceId, string reason)
Parameters
Type Name Description
System.Guid workflowInstanceId

the instance to abort

System.String reason

A description why the instances was terminated

Exceptions
Type Condition
AccessDeniedException

If current user has not rights to terminate instance

WorkflowInstanceException

If instance not found

System.InvalidOperationException

If instance not found in persistance store

TerminateInstance(Guid, String, AccessLevel)

Terminates a given Workflow instance

Declaration
public virtual void TerminateInstance(Guid workflowInstanceId, string reason, AccessLevel access)
Parameters
Type Name Description
System.Guid workflowInstanceId

The workflow instance id.

System.String reason

A description why the instances was terminated

AccessLevel access

The required access level for terminate instance

Exceptions
Type Condition
AccessDeniedException

If current user has not rights to terminate instance

WorkflowInstanceException

If instance not found in runtime

System.InvalidOperationException

If instance not found in persistance store

TryGetInstance(Guid, AccessLevel, out WorkflowDefinitionInstance)

Tries to get the instance with specified id

Declaration
public virtual bool TryGetInstance(Guid workflowInstanceId, AccessLevel accessLevel, out WorkflowDefinitionInstance workflowInstance)
Parameters
Type Name Description
System.Guid workflowInstanceId

The id of the instance to get

AccessLevel accessLevel

The access level to match

WorkflowDefinitionInstance workflowInstance

The workflow instance with the given id. Null if instance does not exist

Returns
Type Description
System.Boolean

true if instance exist else false

TryGetInstance(Guid, out WorkflowDefinitionInstance)

Tries to get the instance with specified id

Declaration
public virtual bool TryGetInstance(Guid workflowInstanceId, out WorkflowDefinitionInstance workflowInstance)
Parameters
Type Name Description
System.Guid workflowInstanceId

The id of the instance to get

WorkflowDefinitionInstance workflowInstance

The workflow instance with the given id. Null if instance does not exist

Returns
Type Description
System.Boolean

true if instance exist else false

UpdateTask(Int32, TaskStatus, String, String, String, Boolean, Boolean, Guid)

Updates a task

Declaration
public virtual void UpdateTask(int taskId, TaskStatus status, string assignTo, string taskSubject, string taskDescription, bool notifyByEmail, bool logAction, Guid instanceId)
Parameters
Type Name Description
System.Int32 taskId

The task id.

TaskStatus status

The status.

System.String assignTo

The assign to.

System.String taskSubject

The task subject.

System.String taskDescription

The task description.

System.Boolean notifyByEmail

if set to true [notify by email].

System.Boolean logAction

if set to true [log action].

System.Guid instanceId

The instance id.

ValidateStartParams(WorkflowDefinition, IDictionary<String, Object>)

Before an instance of definition is started, assure predefined arguments on definition is added and then the args collection is iterated to see that each passed args is present in definition and that type is correct. If not param is removed from args to avoid exceptions when starting workflow.

Declaration
protected static void ValidateStartParams(WorkflowDefinition definition, IDictionary<string, object> args)
Parameters
Type Name Description
WorkflowDefinition definition

The definition that an instance is about to start from

System.Collections.Generic.IDictionary<System.String, System.Object> args

The parameters to validate

Events

InstanceDeleted

Occurs when an instances was deleted, for example when it is completed or terminated.

Declaration
public event EventHandler<WorkflowDeletedEventArgs> InstanceDeleted
Event Type
Type Description
System.EventHandler<WorkflowDeletedEventArgs>

InstanceStarting

Occurs when a workflow instance is about to be created, It gives possibilities to pass in start arguments to instance

Declaration
public event EventHandler<StartInstanceEventArgs> InstanceStarting
Event Type
Type Description
System.EventHandler<StartInstanceEventArgs>
Examples

Shows how event can be used to pass start parameters to workflow instance

InstanceStartingCancelled

Occurs when starting of an instance was cancelled.

Declaration
public event EventHandler<StartInstanceCancelledEventArgs> InstanceStartingCancelled
Event Type
Type Description
System.EventHandler<StartInstanceCancelledEventArgs>

Implements

Extension Methods