Mr Sharepoint: Retrieving User Profile Properties in a SharePoint 2013 Workflow

Tuesday, May 19, 2015

Retrieving User Profile Properties in a SharePoint 2013 Workflow

Introduction

SharePoint 2010 Workflow includes an action called Lookup Manager of a User. This action was not included in SharePoint 2013 Workflow. The purpose of this blog post is to show how that action can be achieved in a SharePoint 2013 Workflow. To do so, we will make a call to the REST endpoint for the User Profile Service. Examples of such calls can be found in a link in the References section.

Workflow and App Permissions

I will not go into great detail about how workflow app permissions work. I have included some links in the References section that cover the subject better than I can. Access to the User Profile Service is not given to workflows by default, so we will need to elevate permissions.

The diagram shows the default permissions on UPS for the workflow app and the current user. Because both App and User share the None permission, the workflow will run with None permission on the UPS web service.

If the workflow app's permission is elevated to Full Control, it will look like the diagram. The highest permission shared by both the workflow app and the user is Read, so the workflow will run with Read permission on the UPS web service. This is ok, but it is not the best practice. It gives the workflow more permission than is required to perform the operation in our example workflow.

Update: Diagram is missing Edit in the App circle.

If the workflow app's permission is elevated to Read, it will look like the diagram. The highest permission shared by both the workflow app and the user is Read, so the workflow will run with Read permission on the UPS web service. This is the "sweet spot" because we are not giving the workflow app more permission than is required.

To elevate the workflow app's permissions for the User Profile Service, we must provide the appropriate Permissions Request XML. That XML follows the schema for the app manifest used by SharePoint apps. The References section contains a link that details the schema. The Permissions Request XML that we will use is:

<AppPermissionRequests><AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="Read" />
</AppPermissionRequests>

The feature that we would like to access is requested in the Scope. In our case, we would like tenant-level access to the social features. A link in the References section lists all of the possible Scopes.

Once we have our Scope, we need to assign the level of access that we require for it. This is done using Right. We are just getting the manager for a user, so we will only need Read access.

REST and Postman

Postman is an extension for the Chrome browser that lets you work with REST easily. I will not go into detail about the extension itself (more information can be found in the link in References.) The call that we will need to make to the User Profile Service using Postman is shown. An example of the output is also shown.

Create the Workflow

For this example, we will create a simple site workflow using SharePoint Designer 2013.

You'll need to create these variables for use later in the workflow:

requestHeader is a dictionary for storing the HTTP headers that are needed to pass to UPS.
responseContent is a dictionary that will store the body of the response that UPS will send back for our request.
responseCode is a string containing the HTTP response code for our request.
user is a string that will store the URL-encoded login name for the user whose manager we will retrieve.
manager is a string that will store the login name of the manager retrieved by our request.
errorMsg is a string that will contain any error message sent in the response if the responseCode returned is not OK.

Add a Build a Dictionary action. Set the output to the requestHeader dictionary variable. Click the ... to open the dialog for adding dictionary items. You will need to add an item as follows:

Name: Accept
Type: String
Value: application/json;odata=verbose

The Accept header will tell the REST web service to return the response in JSON format. This is required so that Workflow Manager can process the response and store it in a dictionary variable.

Add a Replace Substring in String action. Set the output to the user string variable. Set the strings, from left to right, as:

:
%3A
Lookup the user who iniated the workflow:
- Click the fx button to open the Lookup for String dialog.
- Set the Data Source to: Workflow Context
- Set the Field from source to: Initiator
- Set the Return field as to: Login Name

Update: Screenshot contains a typo. A semicolon was used instead of a colon for the first string.

Add a Replace Substring in String action. Set the output to the user string variable. Set the strings, from left to right, as:

#
%23
Lookup the workflow variable for our user string:
- Click the fx button to open the Lookup for String dialog.
- Set the Data Source to: Workflow Variables and Parameters
- Set the Field from source to: Variable:user
- Set the Return field as to: As String

Add a Call HTTP Web Service action. Right-click the action and choose Properties from the context pop-up. In the Call HTTP Web Service Properties dialog, set the following items:

Address:
- Click the ... button to open the String Builder dialog.
- Add the Site URL:
  - Click the Add or Change Lookup button to open the Lookup for String dialog.
  - Set the Data Source to: Workflow Context
  - Set the Field from source to: Current Site URL
  - Set the Return field as to: As String
- Paste this text: /_api/SP.UserProfiles.PeopleManager/GetUserProfilePropertyFor(accountName=@v,propertyName='Manager')?@v='
- Add the user:
  - Click the Add or Change Lookup button to open the Lookup for String dialog.
  - Set the Data Source to: Workflow Variables and Parameters
  - Set the Field from source to: Variable: user
  - Set the Return field as to: As String
- Paste this text: '
RequestType: HTTP GET
RequestHeaders: requestHeader dictionary variable
ResponseContent: responseContent dictionary variable
ResponseStatusCode: responseCode string variable

Optional. Add an If condition to check the responseCode string variable for possible errors.

Optional. Add an Else branch to the If condition if you would like to check for errors.

Add Get an Item from a Dictionary action. Set the output to the manager string variable. Set the variables, from left to right, as:

item by name or path: d/GetUserProfilePropertyFor
Lookup the response content from the UPS call:
- Click the fx button to open the Lookup for String dialog.
- Set the Data Source to: Workflow Variables and Parameters
- Set the Field from source to: Variable:responseContent
- Set the Return field as to: As String

Add a Log to History List action. Set the message to the manager string variable.

Optional. Add a Get an Item from a Dictionary action if you would like to check for errors. Set the output to the errorMsg string variable. Set the variables, from left to right, as:

item by name or path: error/message/value
Lookup the response content from the UPS call:
- Click the fx button to open the Lookup for String dialog.
- Set the Data Source to: Workflow Variables and Parameters
- Set the Field from source to: Variable:responseContent
- Set the Return field as to: As String

Optional. Add a Log to History List action if you would like to check for errors. Set the message to the errorMsg string variable.

Add a Go to a stage action. Set the stage to End of Workflow.

Set the App Permissions

From the SharePoint site where the workflow was created, navigate to Site Settings > Site Actions > Manage site features > Workflows can use app permissions. This feature must be enabled to allow the workflow to use app permissions.

From the SharePoint site where the workflow was created, navigate to Site Settings > Site app permissions > Workflow. A portion of the App Identifier for the workflow app (between | and @) will need to be copied to the clipboard as highlighted:

i:0i.t|ms.sp.ext|1a26950e-0e38-4c13-ada3-00cbd8458c5e@d51a7eaf-77aa-48b2-a135-6c92fd7a5093

From the SharePoint site where the workflow was created, navigate to the following URL:

/_layouts/15/start.aspx#/_layouts/15/appinv.aspx

Fill in the form as:

App Id and Title:
- Paste the contents of the clipboard into the textbox, which should contain a GUID that is the workflow app's ID.
- Click the Lookup button. This should auto-populate the Title, App Domain, and Redirect URL textboxes.

App's Permission Request XML:

Copy the following content to the clipboard:

<AppPermissionRequests><AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="Read" />
</AppPermissionRequests>

Paste the contents of the clipboard into the textbox.

Click the Create button to set the app permissions for the workflow app.

The workflow app must now be trusted using the new app permissions. Since the scope was set to the tenant level for social, a tenant admin will need to trust this app. I haven't tested what the minimum requirements are for this example. Feel free to experiment and leave comments!

Test the Workflow

Peter Gibbons will be our guineau pig. As you can see from his user profile, his manager is Bill Lumbergh.

While logged in as the test user, the workflow is started.

The result in the workflow history shows the manager for the test user was retrieved successfully.

Conclusions

This blog post showed how to retrieve the manager for a user in a SharePoint 2013 workflow using the social features of SharePoint. The concepts provided here can be expanded upon to use other features of SharePoint that do not have native workflow actions. Explore the links in the References section for more information on how to access those features.

If you have any questions about this blog or would like to discuss workflow app permissions or the Call HTTP Web Service action in more detail, I can usually be found in the SharePoint Community chat room during the week. You can also reach me on Twitter.

References

by Paul Choquette via Everyone's Blog Posts - SharePoint Community

Mr Sharepoint