Microsoft Flow: Using the SharePoint REST API

May 4, 2018 by Jon Badgett | Posted in Programming | Tagged with SharePoint

This post will contain whatever handy information I come across for utilizing the SharePoint REST APIs with Microsoft Flow.

Why would you want to do this? Because there aren’t enough actions to accomplish all the things you’d want to do with SharePoint via Flow.

The first section of this guide comes from combining a few different blog posts, but I found Calling the SharePoint Online API from within Microsoft Flow by ROBRECHT-VAN-CAENEGEM to be the most useful. It’s got pictures!

How does this work?

Microsoft Flow can send generic HTTP requests, with custom headers, body, etc.
For Flow to authenticate to SharePoint during the REST calls, we’ll make use of the access tokens typically used for SharePoint Addins/Apps

Intial Setup

We’re going to need four pieces of data:

CLIENTID: Unique id assigned to your add-in registration
CLIENTSECRET: Secret value used by your add-in registration
REALM: This is the unique id assigned to your SharePoint Online tenant.
TENANT: The hostname of your tenant (e.g. example.sharepoint.com)

Obtain the CLIENTID and CLIENTSECRET values

On the SharePoint site that you need to communicate with, navigate to AppRegNew page
```
<your site's URL>/_layouts/15/appregnew.aspx
```
Fill in the information.
- Client Id: «Generate It!»
- Client Secret: «Generate It!»
- Title: «Project Name Flow»
- App Domain: localhost
- Redirect URI: https:/localhost
Store the Client Id and Secret. We’re going to need it for the next step.
Click the Create button.
Navigate to the AppInv page <your site's URL>/_layouts/15/appinv.aspx
Put the Client Id into the App Id text box and look it up.

Paste the following XML into the Permission Request XML box (modify as needed for what scope and right you need):

<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl" />
</AppPermissionRequests>

Click the Create button.

Obtain the REALM value

On the SharePoint site that you just finished app registration on, navigate to the AppPrincipals page
```
/_layouts/15/AppPrincipals.aspx
```
You should see your recently registered app principle along with an App Identifier. The last section of the App Identifier, after the @, is the REALM value.

Setup Authentication in Flow

In your created flow, directly after the trigger, do the following:

Create a new Parse JSON action, renamed to Authentication Values, filling in your own values and using the below schema.

Content:

{
    "realm": "{REALM}",
    "clientId": "{CLIENTID}",
    "clientSecret": "{CLIENTSECRET}",
    "principal": "00000003-0000-0ff1-ce00-000000000000",
    "tenant": "{TENANT}"
}

Schema:

{
    "type": "object",
    "properties": {
        "realm": { "type": "string" },
        "clientId": { "type": "string" },
        "clientSecret": { "type": "string" },
        "principal": { "type": "string" },
        "tenant": { "type": "string" }
    }
}

Create a new Initialize variable action, renamed to Initialize AccessTokenBody, with the following values: - Name: AccessTokenBody - Type: String - Value: concat('grant_type=client_credentials&client_id=', body('Authentication_Values')?['clientId'], '@', body('Authentication_Values')?['realm'], '&client_secret=', body('Authentication_Values')?['clientSecret'], '&resource=', body('Authentication_Values')?['principal'], '/', body('Authentication_Values')?['tenant'], '@', body('Authentication_Values')?['realm'])
Create a new HTTP - HTTP action.
Rename it Get Access Token
Fill in the values:
- Method: POST
- Uri: https://accounts.accesscontrol.windows.net/@{body('Authentication_Values')?['realm']}/tokens/oauth/2
- Headers:
```
{
    "Content-Type": "application/x-www-form-urlencoded"
}
```
- Body: the AccessTokenBody variable
Add a new Parse JSON action and rename it Parse Access Token.

Content should be set to the Body parameter from the previuos step. Schema should be set to the following:

{
    "type": "object",
    "properties": {
        "token_type": { "type": "string" },
        "access_token": { "type": "string" }
    }
}

With this setup, you should be able to test your FLOW and not have it error. You can also check and see the token_type and access_token being parsed. Note that the most tricky part of this is getting the Body variable of step 6 setup correctly. Note that my value depends upon you having renamed the steps as I instructed to work.

You’re now ready to start using SharePoint REST APIs in Flow!

Helpful Snippets

This section will be a hodge podge of useful snippets I plan to continue adding to.

General

Headers

It’s easiest to paste in the headers values of HTTP - HTTP actions if it’s in text mode. Here’s what’s needed (adjust the name of the action where mine says Parse Access Token to match the name of your action that parses the access tokens)

{
    "Authorization": "@{body('Parse Access Token')?['token_type']} @{body('Parse Access Token')?['access_token']}",
    "Accept": "application/json;odata=verbose",
    "Content-Type": "application/json;odata=verbose"
}

Groups and Permissions

Set the Owner of a SharePoint Group to another SharePoint Group

So, this apparently has been broken via typical REST API method calls for quite some time. There is a working alternative though - manually construct the call that the CSOM library would have made. The best resource I found for this is Jason Lee’s blog post: Custom Workflow Activity for Setting a SharePoint Group Owner, which is specifically talking about doing this within a SharePoint 2013 model workflow. We’ll modify it slightly.

Start with your standard HTTP - HTTP action.
Method = POST
Uri (adjust values for your environment) = https://{TENANT}/{SPSITE_URL}/_vti_bin/client.svc/ProcessQuery

Headers are slightly different than the Headers helpful snippet.

{
    "Authorization": "@{body('Parse Access Token')?['token_type']} @{body('Parse Access Token')?['access_token']}",
    "Accept": "application/json;odata=verbose",
    "Content-Type": "text/xml"
}

Body gets fun. You’ve got a few values to substitute.

<Request AddExpandoFieldTypeSuffix="true" SchemaVersion="15.0.0.0" LibraryVersion="15.0.0.0" ApplicationName="{YOUR_APP}" xmlns="http://schemas.microsoft.com/sharepoint/clientquery/2009">
    <Actions>
        <SetProperty Id="1" ObjectPathId="2" Name="Owner">
            <Parameter ObjectPathId="3" />
        </SetProperty>
        <Method Name="Update" Id="4" ObjectPathId="2" />
    </Actions>
    <ObjectPaths>
        <Identity Id="2" Name="740c6a0b-85e2-48a0-a494-e0f1759d4aa7:site:{SPSITE_ID}:g:{TARGET_GROUP_ID}" />
        <Identity Id="3" Name="740c6a0b-85e2-48a0-a494-e0f1759d4aa7:site:{SPSITE_ID}:g:{NEW_OWNER_GROUP_ID}" />
    </ObjectPaths>
</Request>

YOUR_APP = Identity your app. This isn’t really that important.
SPSITE_ID = this is the GUID of the site collection you’re working with. Don’t include the curly braces.
TARGET_GROUP_ID = this is the integer of the group that needs an ownership change
NEW_OWNER_GROUP_ID = this is the integer of the group that will be the owner

Schemas

These are some helpful schemas to paste in to get values back from REST calls.

Get Role Definition or Group Id

Example URLs:

https://{TENANT}/{SPSITE_URL}/_api/web/roledefinitions/getbyname('Contribute')/id
https://{TENANT}/{SPSITE_URL}/_api/web/sitegroups/getbyname('Some%20Group')/id

Schema:

{
    "type": "object",
    "properties": {
        "d": {
            "type": "object",
            "properties": {
                "Id": { "type": "number" }
            }
        }
    }
}

Get List or Library Id

Schema:

{
    "type": "object",
    "properties": {
        "d": {
            "type": "object",
            "properties": {
                "Id": { "type": "string" }
            }
        }
    }
}