Workflow events

Workflow events are not associated with a scheduled item- activity, timer, child workflow or the Lamdba function. Examples of workflow events are signal event, cancel request event or workflow specific failure event.

To handle a workflow event you will-

• Define a method in your workflow with return type as either "void" or "WorkflowAction"
• Decorate the method with WorkflowEventAttribute

To handle a cancel request in workflow you can define a handler method like below:

public class OrderWorkflow : Workflow
{

    [WorkflowEvent(EventName.CancelRequest)]
    public WorkflowAction OnCancelRequest(WorkflowCancellationRequestedEvent @event)
    {
       return CancelWorkflow("Cancelling the workflow")
    }
}

You can declare the signature of workflow event handler in many ways to suit your requirement or style. Guflow gives you following options in declaring the workflow event handler method:

1. Return type can be void: If you do not want to return a workflow action then you can define the return type as void. In this case workflow event will be ignored.

 public class OrderWorkflow : Workflow
 {
    [WorkflowEvent(EventName.CancelRequestFailed)]
    public void OnCancellationFailure()
    {
      //Log and return nothing.
    }
 }

1. Method arguments are optional: If you're not interested in event details then do not pass any argument.
2. Method argument can be "workflow event type": Each of workflow event is associated with a event type. e.g. Signal event is represented by WorkflowSignaledEvent and Cancel request is represented by WorkflowCancellationRequestEvent. You can find more details about all supported workflow events and their type in following section. You can pass whole "workflow event type" object as method argument.

public class OrderWorkflow : Workflow
{
    [WorkflowEvent(EventName.WorkflowStarted)]
    public WorkflowAction OnStarted(WorkflowStartedEvent @event)
    {
       //You can add any conditional logic here.
       return StartWorkfow();
    }
}

3. Method arguments can be individual properties of "workflow event type": You can selectively choose the properties of associated "workflow event type" as method arguments. These arguments does not need to be of same type as source properties. Guflow can successfully populate arguments when argument name is same as one of the source property and it convertible from it.

public class OrderWorkflow : Workflow
{
    //In following example signalName and input is populated from WorkflowSignaledEvent's properties
    [WorkflowEvent(EventName.Signal)]
    public WorkflowAction InventoryUpdated(string signalName, string input)
    {
        return Ignore();
    }
}

4. Method arguments can custom type: If one of the property of "workflow event type" contains JSON format data then Guflow can directly deserialize in to a custom type argument:

public class OrderWorkflow : Workflow
{
    //In following example InventoryData argument will be deserialized from WorkflowSignaledEvent.Input property
    [WorkflowEvent(EventName.Signal)]
    public WorkflowAction InventoryUpdated(string signalName, InventoryData input)
    {
        return Ignore();
    }
}

Notes:

1. Only void and WorkflowAction are supported as return type for workflow event handler. In case of other return type a run time exception will be thrown.
2. While populating the method arguments, Guflow will look for same name property (case insensitive) in corresponding "workflow event type" object and covert/deserialize/copy over it to target argument. A runtime exception is thrown when source property can not be converted/deseralized/assigned to method argument. However if it can not find a corresponding property in "workflow event type" object then method argument is assigned default value.

In workflow you can handle following workflow events:

1. WorkflowStarted: This event is raised when workflow is started. Default behaviour for this event is to schedule all startup elements. However you can provide any custom action by providing the handler for this event. Corresponding "workflow event type" for this event is WorkflowStartedEvent.
2. Signal: This event is raised when workflow receive a signal. Corresponding "workflow event type" for this event is WorkflowSignaledEvent. You can handle signal events using either of three approaches
   1. By decorating the method with SignalAttribute and providing the signal name. This gets highest priority when deciding between multiple handler.

        [SignalEvent(Name="Inventory Updated")]
        public WorkflowAction OnInventoryUpdated(InventoryUpdateDetails details)
        {
          return ....your custom action...
        } 

   2. By decorating the method with SignalAttribute and naming the method with signal name.

        [SignalEvent]
        public WorkflowAction InventoryUpdated(InventoryUpdateDetails details)
        {
          return ....your custom action...
        } 

   3. By decorating the method with WorkflowEventAttribute. Guflow fallback to this approach when no matching method, decorated with SignalAttribute, is found.

       [WorkflowEvent(EventName.Signal)]
       public WorkflowAction InventoryUpdated(WorkflowSignaledEvent @event)
       {
         return ....your custom action...
       } 

   Note: You generally don't need to define event handlers for the signals if you're implementing human interaction unless you want to customize the default behaviour.
3. SignalFailed: This event is raised when current workflow is failed to send signal events to other workflows. Just like your workflow can receive signal from other program/workflows, it can also send send signals to other workflows for collaboration. Default behaviour on this event is to fail the workflow. Corresponding "workflow event type" for this event is WorkflowSignalFailedEvent.
4. CancelRequest: This event is raised when your workflow receives the cancellation request. Default behaviour for this event is to cancel the workflow immediately. However you can provide a handler and cancel the scheduled elements before cancelling the workflow. Corresponding "workflow event type" for this event is_ WorkflowCancellationRequestedEvent_.
5. CancelRequestFailed: This event is raised when Amazon SWF is failed to send cancellation request to other workflows. Just like your workflow can receive cancellation request from other workflow/program, it can also send cancellation request to other workflows. Default behaviour on this event is to fail the workflow. Corresponding "workflow event type" for this event is WorkflowCancellationRequestFailedEvent.
6. CompletionFailed: This event is raised there is failure in completing the workflow. A workflow is completed implicitly when there are no more children it schedule or you explicitly complete by "CompleteWorkflow" workflow action. Default behaviour for this event is to fail the workflow. Corresponding "workflow event type" for this event is WorkflowCompletionFailedEvent.
7. FailureFailed: This event is raised when Amazon SWF encounters error in terminating the workflow with a failure. You can fail a workflow by sending FailWorkflow action to Amazon SWF, however if Amazon SWF can't fail the workflow because of some error then "FailureFailed" event is raised. Default workflow action of this event is FailWorkflow. Corresponding "workflow event type" for this event is WorkflowFailureFailedEvent.
8. CancellationFailed: This event is raised when CancelWorkflow is failed. Default action for this event is FailWorkflow. Corresponding "workflow event type" for this event is WorkflowCancellationFailedEvent.
9. RecordMarkerFailed: This event is raised when amazon SWF failed to record a marker. You can record a marker by RecordMarker action. Default behaviour for this event is to fail the workflow. Corresponding "workflow event type" for this event is WorkflowRecordMarkerFailedEvent.