How-To: Create Workflow Services and Activities with Vector in LASG

This is the sixth in the series of the Layered Architecture Solution Guidance 2013 walk-throughs where we will be exploring the Vector: Workflow Services and Activity Generator to create workflow services and workflow activity components. Creating workflow services is the fifth step in the LASG Code Generation process. Before beginning this guide, please make sure that you have completed the previous tutorial on Creating Business Components with Motion in LASG. Please make sure that your solution is fully compilable without any errors before starting.

This walk-through also uses the LeaveSample database that is part of the Layered Architecture Sample for .NET but you may use your own database to follow through. It is also important that you have followed the steps in the sample to create the Workflow Persistence Store database. Otherwise, follow the instructions here to locate the SQL scripts and then execute them on a newly created WorkflowInstanceStore database.

1. In Solution Explorer, expand the Tutorial solution, go to the Business folder.
2. Right-click on any one of the Tutorial.Workflows, Tutorial.Workflows.Activities or Tutorial.Workflows.Designers project and click Add Workflow Activities... on the context menu.
   
   
   
   
   Tip: Vector generates code to these 3 projects accordingly. The workflow service will be generated as an empty .xaml file to the Tutorial.Workflows project, activity classes will be generated to the Tutorial.Workflows.Activities project and their respective designer classes will be generated to the Tutorial.Workflow.Designers project. The classes in the Tutorial.Workflows.Designers project are only required for workflow design time purposes and do not need to be deployed onto your server.
   
   
3. This launches the Vector: Workflow Services and Activity Generator which contains 4 sections. Take note that Vector is designed to generate Windows Workflow Foundation (WF) services and activities, therefore, you are encouraged to read-up on WF and WorkflowServices to understand the terminologies used.
   
   
   
   
   
   Note: It is always difficult to classify Workflow Services in the Layered Architecture due to their technological nature of being both a business component and also a service. In LASG, Workflow Services are still classified under the business layer even-though they are considered peers to the WCF services.
4. By default, Vector will attempt to load the business project assembly from the centralized bin folder located under the solution (i.e. Tutorial\bin) and populate the details in the  1. Define Workflow Service  section. In this exercise, the Tutorial.Business.dll should be automatically loaded.
   
   Note: If the business project assembly is not loaded, please exit Vector and return to Visual Studio to make sure that there are business components in the Tutorial.Business project and the solution is compilable without errors. Also please ensure that all dependent assemblies are located in the centralized bin folder. You can also manually load the business project assembly by clicking the Load button and selecting the .dll file.
5. All business components that exists in the assembly will be listed in the Business components dropdown list. Verify that the LeaveComponent is selected.
6. Vector will suggest the Workflow service name for us. By default, it will replace the Component suffix from the business component with a WorkflowService suffix. Leave the default suggestions and let Vector create a LeaveWorkflowService component for us.
7. Vector will also suggest the service contract name for us. Verify that ILeaveWorkflowService is entered into the Service contract text box.
8. By default, the service namespace is http://tempuri.org/. You can change the value by typing into the Service namespace text box or click the   button to get Vector to suggest one for you. For this exercise, we will use the default value.
9. Since most of the values were automatically filled in for us, please ensure that the settings that you have are somewhat like the following:
   
   
   
   
   
10. Define an endpoint for the new service. This only needs to be done once when a workflow service is first created. At the  2. Define Endpoint Configurations  section, make sure basicHttpBinding is selected in the Binding dropdown list and leave the default values in the Endpoint name and Address. Click the    button to add it to the Service endpoints grid.
    
    
    
    
    
    Tip: You can create multiple endpoints for your services based on WCF's guidelines. You may be wondering why WCF is mentioned here. The reason is because WorkflowServices are actually a fusion of WF and WCF. Therefore, some of the WCF settings will apply to WorkflowServices as well. For this exercise, we will only use one endpoint.
    
    Note: The Address is only used in non-IIS/WAS hosts i.e. your own Console host. Since most enterprise WorkflowServices are usually (and recommended to be) hosted on IIS/WAS, this setting is seldom used and is just retained for backward LASG compatibility.
11. Creating the Apply workflow activity. At the  3. Define Workflow Activities  section, select Apply in the Business methods list box.
    
    Note: You can actually select more than one business method to be included in an activity but that is not recommended. It is always advisable to have one business method to be exposed as one activity whereby, you can later use the granular activities to compose more complex activities.
12. Make sure that CodeActivity is selected in the Base activity type dropdown list.
13. Leave the Activity name text box value as Apply. By default, Vector uses the name of the business method as the activity name.
14. Make sure None is selected in Emit tracking record dropdown list.
    
    
    
    
    
15. Select ReceiveAndSendReply at the Messaging wrapper activity type dropdown list. This will create a messaging wrapper activity that will wrap your activity between a pair of ReceiveActivity and SendReplyActivity.
    
    Tip: Selecting Receive will create an wrapper class that only contains a ReceiveActivity which will only allow asynchronous calls to your workflow activity.
16. Verify that the value ApplyReceiveSend is entered into the Messaging wrapper activity name text box.
17. The Apply activity is the first activity in our workflow (as in a User applies for a leave). To allow our activity to start the workflow, we will need to check the Can create instance check box.
18. Check the Persist before send check box.
    
    
    
    
    Tip: Persist before send will ensure that all our values in our workflow will be saved before returning the result to the caller.
19. Click the  button to add the Apply activity to the Activities grid.
    
    Tip: To remove an activity from the grid, right-click on the row to invoke a context menu and click Delete.
20. Create an Approve activity. Select Approve in the Business methods list box. Make sure ReceiveAndSendReply is selected in the Messaging wrapper activity type dropdown list and click the  button to add it to the Activities grid.
    
    Tip: Notice the Can create instance check box has been automatically unchecked? This is to prevent us from accidentally creating multiple activities that could start the workflow.
21. Create a Cancel activity. Select Cancel in the Business methods list box. Make sure ReceiveAndSendReply is selected in the Messaging wrapper activity type dropdown list and click the  button to add it to the Activities grid.
22. You should now have 3 activities in the Activities grid.
    
    
    
    
    
23. Click on the Add to Code Generation button to queue the definitions.
24. By now, you should be familiar with the tool-bar in the  4. Generate Workflow Activities  section, so we will skip repeating the explanations.
25. At the Generate group box at the bottom of the section, check on the Workflow xaml check box to instruct Vector to create a blank xaml file for us.
    
    Warning! You only need to do this for the first time you are creating the workflow service. If you already have a workflow service xaml with the same name, you will be prompted whether to overwrite it. Take extra caution on this!
26. Make sure the Base wrapper activity check box is checked. This will instruct Vector to create the base class that provides basic functionality to the wrapper activity classes. Your code will fail to compile if you do not check this.
    
    Warning! You only need to do this once when you create your first workflow activity. You can safely omit this on subsequent workflow activity creation.
27. Check the Service configuration check box to let Vector register the endpoints in the Host project config file. 
28. If you have created the WorkflowInstanceStore database before beginning this guide, you can check the Persistence store check box and click on the Connect button to connect to your SQL Server. 
29. At the Connect... dialog, Enter the Server name and provide the relevant authentication details to your SQL Server. Click the Connect button to connect.
30. Back at the  4. Generate Workflow Activities  section, the WorkflowInstanceStore database should be available for selection in the dropdown list. Select WorkflowInstanceStore.
    
    
    
    
    
31. Click the Generate button to generate the workflow service and activity classes.
32. At the Code Generation Completed dialog, click OK.
33. Vector will generate code to all 3 of the workflow projects - Tutorial.Workflows, Tutorial.Workflows.Activities and Tutorial.Workflows.Designers.
    
    
    
    
    

Post Code-Generation Steps

After generating the code, you can begin designing the workflow using the Visual Studio workflow designer.

1. Open the LeaveWorkflowService.xaml in Visual Studio and design the workflow accordingly.
2. Drag a Flowchart activity from the Visual Studio Toolbox pane into the workflow designer surface.
3. Drag the ApplyReceiveSend activity that we just code generated into the flowchart.
   
   Tip: If you are curious and look at the code of the ApplyReceiveSend activity, you will notice that it is just a design time activity that instructs the designer to wrap a ReceiveActivity and SendReplyActivity around the Apply activity. You can also achieve the same result by dragging the activities manually and hooking them up, but Vector just made it simpler for you.
4. Connect the Start to the ApplyReceiveSend activity.
   
   
   
   
   
5. One important step that needs to be done with the activities generated by Vector is to set the CorrelationID.
6. Expand the ApplyReceiveSend activity by double-clicking on it in the Workflow Designer.
   
   
   
   
   
7. Click on the Apply Receive activity.
8. At the properties pane in Visual Studio, locate the CorrelatesOn property. Click on the ellipses [...] button.
   
   
   
   
   
9. At the CorrelatesOn Definition dialog, define a key by selecting the CorrelationID from the Leave entity. The XPath will be automatically created for you. Click OK and you are done.
   
   
   
   
   

You can continue to complete your workflow following the ASPNET-WCF-DAAB sample found in the Layered Architecture Sample for .NET. If you do not complete the workflow with the Approve and Cancel activities, you will still be able to proceed with the next tutorial.

Summary

In this tutorial, we have gone through how to use the Vector: Workflow Services and Activities Generator to create a workflow service and activities. Vector attempts to make the development workflows faster and easier by providing a means to quickly expose your business methods as activities. You are welcomed to change the generated code but take note that any changes made in your code will not be reflected in the definitions stored in Vector. Therefore, practice caution when you are regenerating code on existing code file.

Coming up next - How-To: Create User Interface Process Components with Impulse in LASG.