Walkthrough: Accessing a SharePoint Workflow from a LightSwitch Mobile App

Article
03/27/2017

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

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 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.
To define the email
1. For the To box, choose the Browse icon.
  
  The Select Users dialog box appears.
2. In the Or select from existing Users and Groups list, choose User who created current item.
  
  Note
  
  The developer account doesn’t support multiple users, so, in this case, the mail will be sent to your email address for the account. In a production environment, you would choose the manager of the employee who requested time off or a payroll group who has approval permissions.
3. Choose the Add button, and then choose the OK button.
4. In the Subject box, enter Time Off Request, and then choose the Add or Change Lookup button.
  
  The Lookup for String dialog box appears.
5. In the Field from source list, choose Title, and then choose the OK button.
6. Enter is requesting , and then choose the Add or Change Lookup button.
7. In the Field from source list, choose Absence Type, and then choose the OK button.
8. Enter from , and then choose the Add or Change Lookup button.
9. In the Field from source list, choose Start Date, and then choose the OK button.
10. Enter to , and then choose the Add or Change Lookup button.
11. In the Field from source list, choose End Date, and then choose the OK button.
12. Enter . Please use the Time Off Mobile app to approve or reject the request., and then choose the OK button.
  
  The completed email definition should look like the following illustration.
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.
To define the email
1. Choose the these users link.
  
  The Define E-mail Message dialog box appears.
2. For the To field, choose the Browse icon.
  
  The Select Users dialog box appears.
3. In the Or select from existing Users and Groups list, choose User who created current item.
4. Choose the Add button, and then choose the OK button.
5. In the Subject box, enter Time Off Approved.
6. In the body of the email message, enter Your request for [%Current Item:Absence Type%] from [%Current Item:Start Date%] to [%Current Item:End Date%] has been approved. [%Current Item:Comments%], and then choose the OK button.
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.
To define the email
1. Choose the these users link.
  
  The Define E-mail Message dialog box appears.
2. For the To field, choose the Browse icon.
  
  The Select Users dialog box appears.
3. In the Or select from existing Users and Groups list, choose User who created current item.
4. Choose the Add button, and then choose the OK button.
5. In the Subject box, enter Time Off Request Denied.
6. In the body of the email, enter Your request for [%Current Item:Absence Type%] from [%Current Item:Start Date%] to [%Current Item:End Date%] has been denied. [%Current Item:Comments%], and then choose the OK button.
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 Visual Basic or Visual C# node, choose 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, choose the Time Off node.
On the menu bar, choose Project, Enable SharePoint.
In the Enabling SharePoint wizard, enter https://Account.sharepoint.com/sites/Developer, where Account is the name of your Office 365 developer account, and then choose the Finish button.

A SharePoint project is added to the solution.

To attach to the SharePoint list

In Solution Explorer, open the shortcut menu for the Time_Off.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 Time_Off.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.lsml 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.

Walkthrough: Accessing a SharePoint Workflow from a LightSwitch Mobile App

Prerequisites

Create a SharePoint List and Workflow

To create the list

To create the workflow

To define the email

To define the email

To define the email

To publish the workflow

To create the client app

To enable SharePoint

To attach to the SharePoint list

To create the user interface

To write the approval code

Test the App

To add a vacation request

To review the request

Next Steps

See Also

Additional resources