Walkthrough: Accessing a SharePoint Workflow from a LightSwitch Mobile App

Article
06/08/2013

By using LightSwitch, you can create mobile apps that access and update SharePoint workflows, which help ensure that business processes are performed in a particular sequence. For example, you might use a workflow to route a document for approval or to process a payroll.

In this walkthrough, you’ll create a workflow for requesting and approving time off, hosting a list on SharePoint for Office 365. You’ll also build a client app in HTML so that managers can approve or deny those requests on mobile devices.

Prerequisites

This walkthrough requires Visual Studio 2012 Update 2.
You’ll also need the sample files in the download Acessing a SharePoint Workflow from a LightSwitch Mobile App.
To host the app, you must also have a SharePoint Developer site on Office 365, which you can get from the Developer Center for Apps for Office and SharePoint.

Create a SharePoint List and Workflow

As your first steps in creating your app, you'll create a SharePoint list for requesting time off and then design a workflow for approving the requests.

To create the list

In a web browser, open your SharePoint Developer site by entering the URL https://Account.sharepoint.com/sites/Developer, where Account is the name of your Office 365 developer account.
On the Office 365 menu bar, choose the Settings icon, and then choose the Site Settings menu item.
In the Web Designer Galleries list, choose List Templates.
On the Web Designer Gallery page, on the menu bar, choose Files, Upload Document.
In the Add a Template dialog box, choose the browse button, locate the TimeOffListTemplate.stp template file in the sample download, and then choose the OK button.
In the List Template Gallery dialog box, choose the Save button.
On the Office 365 menu bar, choose the Settings icon, choose Site Contents, choose the add an app link, and then choose Request Time Off.
In the Adding Custom List dialog box, name the list Request Time Off, and then choose the Create button.

The list is added to the Site Contents page.
On the Site Contents page, choose the Request Time Off list icon to open the list.

To create the workflow

On the menu bar, choose List, and then, on the ribbon, choose Workflow Settings, Create a Workflow in SharePoint Designer.

SharePoint Designer opens, and a Create List Workflow dialog box appears.
In the Create List Workflow dialog box, in the Name box, enter Time Off Workflow, and then choose the OK button.
On the ribbon, choose Action, and then choose Send an Email.

An Email these users action appears in the designer.
Choose the these users link.

The Define E-mail Message dialog box appears.
On the ribbon, choose Action, Wait for Event in List Item.

A Wait for this item event action appears in the designer.
Choose the this item event link.

The Choose List Item Event dialog box appears.
In the Event list, choose Event: When an item is changed.
In the List list, choose Current List, and then choose the OK button.
On the ribbon, choose Condition, If any value equals value.
Choose the first value link, and then choose the Define workflow lookup button.

The Define Workflow Lookup dialog box appears.
In the Field from source list, choose Approval Code, and then choose the OK button.
Choose the second value link, enter 1, and then choose the Start typing or use the Insert group on the Ribbon section.
On the ribbon, choose Action, Send an Email.

An Email these users action appears in the designer.
Choose the space below the current condition, as the following illustration shows.

A yellow line appears.
On the ribbon, choose Condition, If any value equals value.
Choose the first value link, and then choose the Define workflow lookup button.

The Define Workflow Lookup dialog box appears.
In the Field from source list, choose Approval Code, and then choose the OK button.
Choose the second value link, enter 0, and then choose the Start typing or use the Insert group on the Ribbon section.
On the ribbon, choose Action, Send an Email.
Choose the Transition to stage section, and then, on the ribbon, choose Action, Go to a stage.
Choose the a stage link, and then choose End of Workflow.

The completed workflow should look like the following illustration.

To publish the workflow

In SharePoint Designer, on the ribbon, choose Workflow Settings.
In the Start Options section, select the Start workflow automatically when an item is created check box.
On the ribbon, choose Publish.

The workflow is published and associated with the Request Time Off list.

To create the client app

As your next step, you'll create a mobile client app to approve or reject requests for time off. The app will use the SharePoint list as a data source, and you’ll write code to update a hidden Approval Code field in the list when a request is saved.

To enable SharePoint

In Visual Studio, on the menu bar, choose File, New Project.
In the list of templates, expand the LightSwitch node, and then choose either LightSwitch HTML Application (Visual Basic) or LightSwitch HTML Application (Visual C#).
In the Name text box, enter Time Off, and then choose the OK button.
In Solution Explorer, open the shortcut menu for the Properties node, and then choose Open.
On the SharePoint tab, choose the Enable SharePoint button.
In the Add SharePoint dialog box, enter https://Account.sharepoint.com/sites/Developer, where Account is the name of your Office 365 developer account, and then choose the Validate button.

If prompted, enter the user name and password for your Office 365 developer account.
In the Connection successful dialog box, choose the OK button.
In the Add SharePoint dialog box, choose the OK button.

A SharePoint project is added to the solution.

Note

The SharePoint project doesn't appear in Solution Explorer unless you switch to File View.

To attach to the SharePoint list

In Solution Explorer, open the shortcut menu for the Server node, and then choose Add Data Source.
In the Attach Data Source Wizard, choose the SharePoint icon, and then choose the Next button.
In the Specify the SharePoint site address box, enter https://Account.sharepoint.com/sites/Developer, where Account is the name of your Office 365 developer account, and then choose the Next button.
Expand the Lists node, and then select the RequestTimeOff check box.
In the Specify the name of the data source box, enter TimeOffList, and then choose the Finish button.

The RequestTimeOff entity appears in the Entity Designer.

To create the user interface

In Solution Explorer, open the shortcut menu for the HTML Client node, and then choose Add Screen.

The Add New Screen dialog box opens.
In the Screen Data list, choose TimeOffList.RequestTimeOffs, and then choose the OK button.
In the Screen Designer, choose the Screen | Browse Request Time Offs node.
In the Properties window, set the Display Name property to Time Off Mobile.
In the Screen Designer, choose the List | Request Time Offs node.
In the Properties window, choose the Item Tap: None link.

The Edit Item Tap dialog box appears.
In the showTab list, choose editSelected, and then choose the OK button.

The Add New Screen dialog box appears.
In the Name box, enter ApproveTimeOff, and then choose the OK button.
In the Screen Designer, choose the Title field, and then change the control type to Text.
In the Properties window, set the Display Name property to Employee.
In the Screen Designer, choose the Start Date, End Date, and Absence Type fields, and change their control types to Text.
Delete the Rows Layout | Right node.

To write the approval code

In Solution Explorer, open the shortcut menu for the RequestTimeOffs node, and then choose Open.
On the menu bar, open the Write Code list, and then choose the RequestTimeOffs_Updating method.

In the Code Editor, add the following Imports or using statements:

Imports Microsoft.SharePoint.Client

using Microsoft.SharePoint.Client;

Add the following code to the Updating method:
```
If entity.Status = "Approved" Then
                entity.ApprovalCode = 1
            ElseIf entity.Status = "Rejected" Then
                entity.ApprovalCode = 0
            End If
```
```
{
if (entity.Status == "Approved") {
entity.ApprovalCode = 1;
} else if (entity.Status == "Rejected") {
entity.ApprovalCode = 0;
}
}
```
This code gets the value of the Status field and updates the ApprovalCode field accordingly. The Status field is accessible to users on the SharePoint list, so employees can approve their own requests. By using the hidden ApprovalCode, you ensure that only requests that managers approve trigger the next step in the workflow.

Test the App

Now you’re ready to see the workflow and app in action. You’ll need to add your developer account to your email client if you haven't already. The email account ID is the same as your user ID: YourName@Account.onmicrosoft.com.

To add a vacation request

On your SharePoint developer site, choose the Site Contents link, and then choose Request Time Off.
Choose the New Item link, fill out the form, and then choose the Save button.

The workflow starts by executing the first step and sending an email. If you refresh your browser, you can verify that the Time Off Workflow field is set to Stage 1.
In your email client, locate the Time Off Requested email from Developer, and verify that it contains the information that you entered in the form.

Note

The email may take some time to arrive.

To review the request

In Visual Studio, on the menu bar, choose Debug, Start Debugging to run the app.

If prompted, enter the user ID and password for your developer account.
When the Do you trust Time Off? page appears in your browser, choose the Trust it button.
On the Time Off Mobile screen, choose the entry for the name that you entered in the Request Time Off form.
On the Approve Time Off screen, choose the Status list, and then choose either Approved or Rejected.
In the Comments box, enter a comment, and then choose the Save button.

The changes are saved to the SharePoint list, the next step in the workflow is triggered, and the code in the Updating method is run.
In your email client, locate the Time Off Approved or Time Off Request Denied email from Developer, and verify that it contains the comment that you entered.
On your SharePoint developer site, refresh the page, and then verify that the status is updated and contains the comment that you entered.
To view the workflow status, choose the Stage 1 link for the request, and then verify that the Internal Status value is Completed.

Next Steps

Now that you’ve verified that everything works, you can publish the LightSwitch app and access it from your mobile device. You’ve learned how to create a simple workflow and access it from LightSwitch, but you can do much more. For example, you might add logic to the app to verify that the dates are valid workdays, or you could add a step to the workflow to move approved requests to another list and start another workflow for payroll processing.