Building Pluggable Workflow Services in SharePoint 2010

1. Building Pluggable Workflow Services in SharePoint 2010 Lyudmila Zharova SharePoint Developer at MRM Worlwide lzharova077@gmail.com Lyudmila.Zharova@MRMWorldwide.com Blog.sharepointsalvation.com 21/7/2010

2. About MRM • MRM is a marketing services agency dedicated to maximizing Customer Utility - ideas that drive our clients' business. • At MRM, the Technology group brings Customer Utility to life through campaigns and enduring platforms.  These platforms are manifested in Web Applications, Mobile Applications and Social Media Applications.   • The MRM technology group utilizes a broad array of technologies and technology platforms to deliver these applications.  Microsoft Office Sharepoint Server is an important element of our platform solution, and we use it extensively for clients such as the U.S. Army and internally as our enterprise document management and workflow utility: MRM works.

3. AGENDA • Pluggable Workflow Services - the new workflow feature in SharePoint 2010 • Workflow improvements in SP 2010 • Benefits of usage Pluggable Workflow Services • Architecture • Walkthrough of building Pluggable Workflow Services • Development Steps • Demo • Links

4. Pluggable Workflow Services - the new feature in SharePoint 2010 Workflow improvements in SP 2010 • .NET Famework 3.5 sp1 and Workflow Foundation 3.5 • Workflows can be associated with the sites • New options in “out of the box” workflows (In Approval and Collect feedback workflows, tasks can be assigned by stages, or to all members of a SharePoint group) • Two-ways Visio integration (.vwi)/code generation (.xoml) • Create new and customize OOB Workflows with SharePoint Designer 2010; Export as a Template (save in WSP in Site Assets Library) • Workflow forms generation in Visual Studio 2010 (new project item templates) • Workflow events • Visio visualization (unable Show workflow visualization on status page checkbox) • SP 2007 came with 23 out-of-the-box actions/SP2010 comes with 44 ones • Security: Impersonation step in SharePoint Designer • Asynchronous communication with the outside world

5. Pluggable Workflow Services - the new workflow feature in SharePoint 2010 Benefits of usage : • How SP 2007 workflow communicates with external systems - task items are used to send a message to the external system using a Web service - external system updates the task to return the result - limited number of event based activities • Pluggable workflow services were designed for sending and receiving messages out of a workflow instance • Pluggable workflow services provide a means for workflows to execute up to a specified point, and then wait for information from an external processes: - Line of business applicationslike SAP - .NET applications - Inter workflow communications Pluggable workflow services are valuable for any long-running system operation or long running process: - long-running calculation, decoding video, etc Example: If calculation or web service call takes more time to execute than needed, there's no need in keeping the workflow instance in memory. Hydrate the instance, and dehydrate it when the operation or process finish.

6. Architecture Custom workflows can send and receive messages from other workflows or .NET applications by using the SharePoint Workflow external data exchange service . • SPWorkflowExternalDataExchangeService - a new abstract class a that derived classes • can use to represent a workflow communication service. • All pluggable services must inherit from this class. CallExternalMethod activity - listens to any custom event implemented by a Local Service HandleExternalEvent activity - invoke a method on a Local Service Local Service • The client access the service through an interface that defines the method parameters

7. Pluggable Workflow Services - the new workflow feature in SharePoint 2010 Architecture: The following is the flow of data as a Pluggable Workflow Service starts: • The Workflow code starts and loads the Workflow engine. • The Workflow engine reads channel classes and assemblies from the configuration file • Channels are loaded from the Global Assembly Cache (GAC) and the Workflow runtime is started

8. Walkthrough of building Pluggable Workflow Services: Development Steps : • Workflow will call into a Local Service and will say "Hello Event Handler!" to an event receiver • Local Service then creates an announcement in an Announcements list • Event Receiver will respond "Hello Workflow!" to the new announcement by calling back into the hydrated Workflow How it can be accomplished? • HelloEventHandler method is called by the workflow via the CallExternalMethod activity • The event receiver then executes and invokes the HelloWorkflow event • Workflow is listening for only this event via the HandleExternalEvent activity

9. Walkthrough of building Pluggable Workflow Services: Step 1. Create a new Visual Studio 2010 project: • name - HelloPluggableWorkflowServices • choose sequential Workflow • type debug URL • chooseSite Workflow • Add the following references: • Microsoft.SharePoint • Microsoft.SharePoint.WorkflowActions

10. Walkthrough of building Pluggable Workflow Services:

11. Walkthrough of building Pluggable Workflow Services: Step 2. Create a Local Service • add class - HelloService.cs • add interface - IHelloService with [ExternalDataExchange] attribute The service interface lets the sending and receiving parties know what type of data to send to each other. This is done by declaring a method the sender calls and an event the receiver listens for. //to tap into the external data exchange services [ExternalDataExchange] public interface IHelloService { //the receiver listens for event EventHandler<HelloEventArgs> HelloWorkflow; //sender calls void HelloEventHandler(string message); }

12. Walkthrough of building Pluggable Workflow Services • extend the HelloService class with Microsoft.SharePoint.Workflow.SPWorkflowExternalDataExchangeService class and make it implement the IHelloServiceinterface • add HelloEventHandler method and HelloWorkflow event to HelloService class //At this stage the compiler cannot find the class for HelloWorldEventArgs. //This class we have yet to define. public event EventHandler<HelloEventArgs> HelloWorkflow;    public void HelloEventHandler(string message)   {         SPWeb web = this.CurrentWorkflow.ParentWeb;         SPList list = web.Lists["Announcements"];         SPListItem item = list.Items.Add();         item["Title"] = message;         item["Instance"] = WorkflowEnvironment.WorkflowInstanceId.ToString();         item.Update(); }

13. Walkthrough of building Pluggable Workflow Services: At this stage the compiler cannot find the class for HelloWorldEventArgs. This class we have yet to define. Within the method we're creating the new announcement and passing the workflow's instance ID into the "Instance" column within the announcement. This is how the event receiver will know which workflow to send a message to. • add CallEventHandler, CreateSubscription, and DeleteSubscription methods to the HelloService class The CallEventHandler method gets called each time an event is being requested in the Local Service. If the HelloWorkflow event is being requested, we create a new HelloEventArgs instance and pass in the workflow's instance ID to so the event knows which workflow it's invoking the event with. Next we pass in the message string from the event receiver and then invoke the event.

14. Walkthrough of building Pluggable Workflow Services public override void CallEventHandler( Type type, string eventName, object[] parameters, SPWorkflow workflow, string identity, System.Workflow.Runtime.IPendingWork handler, object item) { switch (eventName){ case "HelloWorkflow": var args = new HelloEventArgs(workflow.InstanceId); args.Answer = parameters[0].ToString(); this.HelloWorkflow(null, args); break; } } // creates a message event subscription to rout massages to the apropriate workflow instance public override void CreateSubscription(MessageEventSubscription subscription) { throw new NotImplementedException(); } public override void DeleteSubscription(Guid subscriptionId) { throw new NotImplementedException(); }

15. Walkthrough of building Pluggable Workflow Services: Step 4. Create HellodEventArgsclass [Serializable]     public class HellodEventArgs : ExternalDataEventArgs { //store the workflow instance ID public HelloWorldEventArgs(Guid id) : base(id) { }     //the message the event receiver will pass to the workflow //This message will get logged into the workflow's History List public string Answer;   } • id (GUID) - will store the workflow instance ID. • Answer (string) - the message the event receiver will pass to the workflow.

16. Walkthrough of building Pluggable Workflow Services: Step 5. Configure the CallExternalMethod activity • within Workflow1, add the CallExternalMethod activity • specify the IHelloService interface next to the InterfaceType property • change the MethodName property to be HelloEventHandler • change the message property to be "Hello Event Handler!" Tip: MethodInvoking property is not specified in our project. It's an event handler that is invoked just before the method is called. Step 6. Configure the HandleExternalEventactivity • add the HandleExternalMethod activity below the CallExternalEvent activity • specify the IHelloService interface next to the InterfaceType property • change the EventName property to be HelloWorkflow (The event receiver must invoke this event to communicate with the workflow. The workflow will listen only for this event.) • bind the "e" property by choosing Field in the Bind to New Member tab (e parameter is the HelloEventArgs class that is passed when the event is raised. It contains the data returned by the local service.) • open the code view of the workflow and remove "=new..." to make it looks like: public HelloEventArgs handleExternalEventActivity1_e1;

17. Walkthrough of building Pluggable Workflow Services: Step 6. Configure a Log to History List activity • add a LogToHistoryList activity below the HandleExternalEvent activity • right click the LogToHistoryList activity and choose Generate Handlers • add the code inside the MethodInvoking method  to write the event receiver's message to the history: • logToHistoryListActivity1.HistoryDescription = handleArgs.Answer; Step 7. Add an "Instance" column onto an Announcements list Step 8. Add a new Event Receiver to the project • Add -> New Item select the Event Receiver item • name - AnnouncementsReciever • choose List Events, Announcements, and An item was added • add the logic to ItemAdded method of the receiver

18. Walkthrough of building Pluggable Workflow Services: if (properties.ListTitle == "Announcements") { Guid instance = new Guid(properties.ListItem["Instance"].ToString()); string answer = "Hello Workflow!"; SPWorkflowExternalDataExchangeService.RaiseEvent( properties.Web, instance, typeof(IHelloWorldService), "HelloWorkflow", new object[] { answer }); } We pass an instance (workflow's instance ID set to a Guid) as a parameter into the RaiseEvent method. This way the RaiseEvent method knows which workflow to send the message to. Other parameters are the SharePoint site where the workflow is running, the event to invoke ("HelloWorkflow" event), the message to the workflow, "Hello Workflow!". The last parameter is an object array, so you can load that up with any serializeable object you think the workflow needs to do its business.

19. Walkthrough of building Pluggable Workflow Services: Step 9. Register the HelloWorldService with the SharePoint workflow runtime • in the wb.config file find the <WorkflowServices> element add the WorkflowService in the WorkflowServices element (all on one line): <WorkflowService Assembly="HelloPluggableWorkflowServices, Version=1.0.0.0, Culture=neutral, PublicKeyToken= 4dda0331da5ab1e1" Class=" HelloPluggableWorkflowServices.HelloService"> </WorkflowService> Step 9. Test the workflow • Build and Deploy the project • Navigate to your SharePoint site, and under View Site Content, click Site Workflows • Start your pluggable workflow (should be named PluggableWorkflowServices - Workflow1) • Navigate to the Announcements list and you should see a new announcement titled "Hello Event Handler!“ • Go back to Site Workflow and click the "Completed" status of the PluggableWorkflowServices - Workflow1 workflow. You should see the event receiver's response of "Hello Workflow!"

20. Links MSDN http://msdn.microsoft.com/en-us/magazine/ee335710.aspx Blog posts: http://philwicklund.com/Lists/Posts/Post.aspx?List=7379e84f%2Dd131%2D4c1b%2D903e%2D4b12849edf5b&ID=149 &Source=http%3A%2F%2Fphilwicklund%2Ecom%2Fdefault%2Easpx&Web=8de7cf99%2D762e%2D4745%2Db902%2D B821d850c07f http://sergeluca.spaces.live.com/Blog/cns!E8A06D5F2F585013!7584.entry http://sandhoo.wordpress.com/2010/05/26/sharepoint-2010-pluggable-workflow-services-with-correlation-and- external-callbacks/

21. Thank you! Please Don’t Forget to Complete Your Evaluation FormYour input is important!Plus, this is how you’ll get the chance to enter the raffle draws throughout the event