Class InstanceHandler

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

Inheritance

System.Object

InstanceHandler

Implements

IInstanceHandler

ICommunicationServiceCallback

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: 8.11.0

Syntax

public class InstanceHandler : IInstanceHandler, ICommunicationServiceCallback

Constructors

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

IInstanceHandler

ICommunicationServiceCallback