Technology•Apr 14, 2016
SharePoint 2013 Online: Accessing User Profile Properties in a Designer Workflow
Although the ability to access user profile fields in a SharePoint Designer Workflow was an out-of-the-box feature in the 2010 version, it is not nearly as simple in 2013. The process isn’t actually that complicated, but the development process can be painful unless you know exactly what to do. This post will detail the necessary steps to retrieve user profile properties in a SPD workflow as well as highlight a few common issues you may encounter during development.
Granting the App Permissions
First, you’ll need to ensure your workflow has the appropriate permissions in order to access the User Profile Service.
1. Navigate to the Site Settings menu and click on Site app permissions under Users and Permissions.
2. Copy the portion of the Workflow App Identifier between | and @.
a. Example: i:0i.t|ms.sp.ext|3a71d4ce-8404-5b90-cba2-b1947066c17d@382a50da-3b5d-75d2-ab43-82686fd5e224
3. Using a tenant admin account (see step #5a for explanation), append /_layouts/15/appinv.aspx to the URL of the site where your workflow lives. In the textbox below App Id, enter your copied value, and click “Lookup”. This will populate the Title, App Domain, and Redirect URL fields.
Here’s the critical part: in the Permission Request XML field, enter the following XML and then click Create:
<AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="Read">
a. The workflow must have tenant-level permissions in order to access the User Profile Service. Note that the above example assumes the workflow only needs to read user profile data—depending on your task, you may need to change Read to Write, Manage, or FullControl.
b. Note that other permissions may need to be included based on the other requirements of your workflow. For other permissions, enter additional <AppPermissionRequest> nodes as part of the XML. For more information about app permissions, see this MSDN article.
5. The following screen will verify that you want to trust the Workflow app. Make sure the listed permissions includes “Allow application access to user profiles: Read”, and then click Trust It.
a. Because of the tenant-scoped permission, a tenant admin account is required in order to trust the app. Otherwise, you will see a screen such as the following:
Now that the workflow has been granted the appropriate permissions, we can call the User Profile REST API from the workflow in order to retrieve the appropriate user profile properties.
An Aside on Permissions
There are many articles and blog posts out there that discuss the concept of workflows (and other apps) that can run using elevated permissions. While there are many great use cases for this functionality, retrieving data from the User Profile Service is not one of them, at least for SharePoint Online (on-premise may be different).
As far as my research can tell, a workflow/app that accesses the User Profile Service must run under the context of a user whose SharePoint account is synced to Active Directory. A workflow running with elevated permissions that attempts to retrieve user profile information will error out since it’s running as itself and has no corresponding AD account.
Back to the Workflow
Let’s assume we have already set up a workflow variable UserName that stores the target user’s login name in the format i:email@example.com (which would probably be retrieved from the workflow/list context, or perhaps a separate web service call).
1. Generate the REST URL that will return the relevant user profile property. For this example, we’ll be retrieving the user’s department by setting the URL as follows
a. Vardhaman Deshpande has a fantastic blog post that details how to get user profile properties using the REST API—I encourage you to check it out.
2. Note in the above screenshot that I have replaced the single quotes around the user name with %27. Otherwise, the REST call may result in an error. Similarly, we need to encode the | and # in the portion of the URL that now contains the user’s login name, using %7C and %23. Add the following steps to your workflow:
a. This is (potentially) a big “gotcha”: for most other simple REST calls from a SharePoint Designer 2013 workflow, the only required headers are Accept and Content-Type. For non-SharePoint REST calls, however, one known issue is that you must explicitly add an Authorization header with an empty string value in order to avoid an Unauthorized response. This shouldn’t be an issue for the User Profile API, but it caused some issues for me. If you’re getting a response of Unauthorized, then make sure you have the Authorization header in this dictionary.
4. Now we can make the API call by adding a Call HTTP Web Service
6. Next, open the step properties (move your cursor to the right side of the step, click the arrow that appears, and then select Properties), set RequestHeaders to the corresponding request headers variable, and set ResponseContent to a new dictionary variable.
a. You may also optionally set variables for the request content, response headers, and response status code. It is generally a good idea to check the response code of the web service call in order to account for possible errors.
7. Add a Get an Item from a Dictionary Enter d/GetUserProfilePropertyFor for the item name (this will be different if you’re calling other endpoints of the User Profile REST API), ResponseContent as the dictionary, and a new string variable called Department for the item.
That’s it! We have now retrieved a user profile property within a SharePoint 2013 Designer Workflow. If you are still encountering issues, I would encourage you to log the HTTP response code to the Workflow History list as a quick way of determining the root cause of the error.