Exercise 1: Implement a Custom Workflow Action in Visual Studio

Task 1 – Create a Custom Workflow Action in Visual Studio

In this task, you use Visual Studio 2010 to create a custom workflow action that creates a site when the workflow is approved.

The final step of the Non-Standard Business Purchase Request Approval workflow is to create a SharePoint site for the user to fill out a trip report to share with others in the company. SharePoint Designer doesn’t contain a workflow action to create a site; you’ll create a custom action to include in the workflow.

1. Launch Visual Studio 2010.
2. Create a new Empty SharePoint Project in C:\%Office365TrainingKit%\Labs\3.2\Source\Before\Visual Studio called SPDCustomWorkflowActions.
3. In the SharePoint Customization Wizard dialog, for What local site, enter the name of the SharePoint site you created for this lab, e.g., https://intranet.sharepoint.com/Lab03 and select Deploy as a sandboxed solution.
4. Click Finish to create the project.
5. Add a new class called CreateSiteAction to the project.
6. Change the CreateSiteAction’s class accessibility to public.

7. Under the existing using statements, insert the following code snippet to add the required using statements.

   (Code snippet 3.2.1)

   C#

   using System.Collections; using Microsoft.SharePoint; using Microsoft.SharePoint.UserCode;

8. Create a function called CreateSite using the code snippet below.

   (Code snippet 3.2.2)

   C#

   public Hashtable CreateSite(SPUserCodeWorkflowContext context, string siteName)
9. This function accepts an instance of SPUserCodeWorkflowContext for the current site and a string parameter for the name of the site to create.
10. The workflow uses a Hashtable property bag to return values from the workflows, e.g., whether or not the workflow succeeded (and the exception if there one was thrown).

11. Add the following code snippet to the body of the CreateSite function.

    (Code snippet 3.2.3)

    C#

    Hashtable results = new Hashtable(); try { using (SPSite site = new SPSite(context.CurrentWebUrl)) { using (SPWeb web = site.OpenWeb()) { web.Webs.Add( siteName, "Trip Report: " + siteName, string.Empty, 1033, "STS", false, false); } } results["success"] = true; results["exception"] = string.Empty; } catch (Exception e) { results = new Hashtable(); results["exception"] = e.ToString(); results["success"] = false; } return results;
12. The code gets the context to the current Site using the workflow context, and then opens the current Web and creates a site within it with the specified name.
13. The Hashtable property bag is populated with a success and exception key to indicate the workflow’s success or failure and record the exception details if there was an exception.
14. Add a new Empty Element item to the SharePoint project and call it CreateSiteActionDefinition. You will use this element to describe the custom workflow actions contained in this project.
15. In Solution Explorer, under CreateSiteActionDefinition, open the Elements.xml file.

16. Add a WorkflowActions element inside Elements:

    (Code snippet 3.2.4)

    XML

    <WorkflowActions> </WorkflowActions>

    In this section, you will define the custom actions that are packaged with this feature.

17. Add an Action element at Elements/WorkflowActions:
    1. The Name attribute specifies the name of the action as it will appear in SharePoint Designer.
    2. SandboxedFunction indicates that the workflow action is sandboxed.

    3. ClassName and FunctionName refer to the full namespace of the class that contains the function describing the action.

       (Code snippet 3.2.5)

    XML

    <Action Name="Create Site" SandboxedFunction="true" Assembly="$SharePoint.Project.AssemblyFullName$" ClassName="SPDCustomWorkflowActions.CreateSiteAction" FunctionName="CreateSite" AppliesTo="all" UsesCurrentItem="true" Category="Sandboxed Workflow Actions"> </Action>

18. Add a RuleDesigner element at Elements/WorkflowActions/Action. This describes the parameters that you have to provide when adding this action to the workflow design surface.

    (Code snippet 3.2.6)

    XML

    <RuleDesigner Sentence="Create Site with name %1 (exceptions logged to %2)"> <FieldBind Field="siteName" Text="Site Name" Id="1" DesignerType="TextBox" /> <FieldBind Field="exception" Text="Exception" Id="2" DesignerType="ParameterNames" /> </RuleDesigner>

    When you add the CreateSite action to the SharePoint Designer workflow design surface, you’re able to associate the siteName parameter with the Title of the item that was created in the Non-Standard Business Purchase Requests list.

19. Finally, add a set of Parameter elements at Elements/WorkflowActions/Action.

    (Code snippet 3.2.7)

    CAML

    <Parameters> <Parameter Name="__Context" Type="Microsoft.SharePoint.WorkflowActions.WorkflowContext, Microsoft.SharePoint.WorkflowActions" Direction="In" DesignerType="Hide" /> <Parameter Name="siteName" Type="System.String, mscorlib" Direction="In" DesignerType="TextBox" Description="Name of the site to create" /> <Parameter Name="exception" Type="System.String, mscorlib" Direction="Out" DesignerType="ParameterNames" Description="Exception encountered"/> </Parameters>
    1. The __Context parameter is the instance of the workflow context that it used as a parameter to the CreateSite function.
    2. The siteName parameter is also used by the CreateSite function and represents the name of the site to create.
    3. The exception parameter is returned by the workflow action and comes from the Hashtable property bag returned by the CreateSite function.
20. When you added the Empty Element item to the project, a feature called Feature1 was created automatically.
21. Open Feature1.

22. Make sure the Scope of Feature1 is set to Site to ensure that the feature is deployed at the site collection level.

23. Save your changes.

Task 2 – Deploy Custom Workflow Action to SharePoint

In this task you will deploy the custom workflow action to SharePoint.

1. From the Solution Explorer window, right-click the SPDCustomWorkflowActions project and select Package to package the solution WSP.
2. Launch Internet Explorer and navigate to your top-level SharePoint site collection; e.g.: https://intranet.contoso.com.
3. Click SiteActions >> Site Settings.
4. Under Galleries, click on the Solutions link to view the site collection’s SolutionGallery.
5. Click on the Solutions tab in the ribbon to view the Upload Solution button.
6. Click the Upload Solution button.
7. Browse to C:\%Office365TrainingKit%\Labs\3.2\Source\Before\Visual Studio\SPDCustomWorkflowAction\bin\Debug\SPDCustomWorkflowActions.wsp and click Open and OK.
8. In the Solution Gallery – Activate Solution dialog, click the Activate button on the Ribbon to activate the solution.
9. Click the Activate button on the ribbon to activate the solution.

Task 3 – Incorporate Custom Workflow Action into SharePoint Designer Workflow

1. Browse to your SharePoint site; e.g.: https://intranet.contoso.com/Lab03.
2. Click Site Actions >> Edit in SharePoint Designer to edit the site in SharePoint Designer 2010.

3. Click the Workflows link in the left navigation.

4. In the right-pane, open and edit the Non-Standard BusinessPurchase Approval workflow.

5. Click the Edit workflow link to edit the workflow.

6. In the “Yes” branch of the If condition, move the mouse under the Email:Current Item:Created By link until you see an orange bar.

7. Click the orange bar.

8. Click the Actions item on the Workflow tab in the ribbon, and insert a Create Action activity from the Sandboxed Workflow Actions category.

9. The CreateSite action is added to the logic of the “Yes” branch of the If condition.

10. Click the Site Name link and associate it with the Current Item’s Title property in the list.

11. Save the workflow.

12. The revised workflow should now look like this:

13. Click Publish on the Workflow tab in the ribbon to publish the workflow to your SharePoint site.

    SharePoint Designer will validate the workflow and publish it to the Lab03 site in SharePoint.

14. Browse to your SharePoint Online site; e.g.: https://contoso.sharepoint.com/Lab03.
15. From the Quick Launch, browse to the Non-Standard Business Purchase Request list.

16. In the ribbon, open the List tab and click Workflow Settings.

17. Select Purchase Request from the drop down list.

18. You can see that a new version of the Non-Standard Business Purchase Approval workflow has been associated with the list.

Task 4 – Test Custom Workflow Action

1. Browse to your SharePoint site; e.g.: https://intranet.contoso.com/Lab03.
2. Open the Non-Standard Business Purchase Requests list from the Quick Launch.
3. Click the Add new item link to create a new item in the list.
4. Create a new item in the list, for example:
   • Title: SharePoint Conference
   • Requested By: << Enter your account here >>
   • Description: SharePoint Conference 2010 in Anaheim, CA

   • Price: 4999

5. Select the newly created item in the list and click Workflows in the ribbon.

6. The workflows screen displays all the workflows that you can start on this list item.

7. Click the Non-Standard BusinessPurchase Approval workflow to start an instance of the workflow on the list item.

8. The workflow initiation form appears and prompts the user to enter the business rationale for their request. Enter “I’d like to learn all about SharePoint Online”.

9. Click Start to start the workflow.

10. Open the workflows of the list item to see the status of the workflow. You can now see an instance of the Non-Standard BusinessPurchase Approval workflow under the RunningWorkflows section.

11. Click on the workflow instance.
12. To approve the workflow, you would typically have to log out and log back in with a user who is a member of the Approvers group. In this case, you are already logged in as an administrator so you can approve the workflow.

13. On the same screen, in the Tasks section, click the title of the approval task.

14. The Workflow Task dialog contains information about the task that was assigned to the Approvers group.

15. Click Approve to approve the request.

16. Go back to the Non-Standard Business Purchase Requests list and open the workflows page for the request list item.

    You can see the instance of the Non-Standard Business Purchase Approval workflows in the Completed Workflows section.

17. Click on the workflow instance.

18. The workflow visualization is updated to show the path that the user took through the workflow. The checkmark on each step indicates that the step was completed successfully.

    Notice that the custom action that you added in the previous exercise is now visible in the workflow visualization.

19. From Site Actions, select View All Site Content.
20. The site that was created by the custom workflow action appears in the Sites and Workspaces section.

21. Open the site.

    A trip report site was created by the custom workflow action for the user to fill out a trip report.