Thursday, December 27, 2018

Manipulating SharePoint content using Flow

One of the great benefits of Flow is to help you manage content in SharePoint.  There are 10 triggers and over 40 Flow actions available out of the box that allow you to access and update your SharePoint content.

Retrieve contentCreate contentUpdate contentOther actions

  • Get attachments
  • Get entity values
  • Get file properties
  • Get files (properties only)
  • Get items
  • List folder
  • Extract Folder
  • Get all lists and libraries
  • Get attachment content
  • Get file content
  • Get file content using path
  • Get file metadata
  • Get folder metadata
  • Get folder metadata using path
  • Get item
  • Get list views
  • Get lists
  • List root folder

  • Copy file
  • Copy folder
  • Create file
  • Create item
  • Create sharing link for a file or folder
  • Move file
  • Move folder
  • Copy file (deprecated)

  • Add attachment
  • Delete attachment
  • Delete file
  • Delete item
  • Update file
  • Update file properties
  • Update item

  • Approve hub site join request
  • Cancel hub site join request
  • Join hub site
  • Resolve person
  • Send an HTTP request to SharePoint
  • Set content approval status
  • Set hub site join status to pending


In many cases, the actions available to retrieve content will suffice.  However, there are times, where you may need to go beyond these actions to access your data.  One such example is updating the name and URL of a link in a list or library item.

Send HTTP request to SharePoint Action

One of the actions mentioned above is the Send HTTP request to SharePoint action.  This action enables you to interact with most aspects of your SharePoint Online environment (assuming your Flow account has the right permissions).  The other actions are more specific in their functionality.

The Send HTTP request to SharePoint action leverages the SharePoint REST service to achieve this using an extensive set of Create, Read, Update, and Delete (CRUD) operations.

Example 1: Updating Links

Let's look at a simple example of how to use the Send HTTP request to SharePoint action.  Suppose you have a list, where you want to store my favourite links.  For each link, you want to capture the following information:


  • Title - description of my link
  • URL
  • Link name - a short name
Using the OOTB Create Item action, you not able to set the Link name property on the link




As a result, when you create the item, the link URL and name will be set to the URL.  Clearly, not what you were hoping to do.


Now, instead of using the Create Item action, if you use the Send HTTP request to SharePoint, you can see how you can provide the additional information to properly set the link name.


There are a number of parameters required for this action that are standard in making REST calls.

  • Site Address - the site collection you are working in (the Flow account needs access to it)
  • Method - what type of RESTful operation will you be performing?
    • GET - retrieve content
    • POST - create some content
    • PUT - update content
    • DELETE - delete content
    • PATCH - make partial updates to content (e.g. only a few fields)
  • Uri - the URL to the entity on which you will be performing the action
  • Headers - contain important information to help you resolve issues with the requests
    • Authorization - Carries credentials containing the authentication information of the client for the resource being requested.
    • WWW-Authenticate - This is sent by the server if it needs a form of authentication before it can respond with the actual resource being requested. Often sent along with a response code of 401, which means ‘unauthorized’.
    • Accept-Charset - This is a header which is set with the request and tells the server about which character sets are acceptable by the client.
    • Content-Type -  Indicates the media type (text/html or text/JSON) of the response sent to the client by the server, this will help the client in processing the response body correctly.
    • Cache-Control - This is the cache policy defined by the server for this response, a cached response can be stored by the client and re-used till the time defined by the Cache-Control header.
  • Body - contains the content to be used for the REST call.  Each metadata field is applied a single value or array of values
In the example above, the Body is divided into 3 different metadata fields:


'__metadata': { 'type': 'SP.Data.SP_x0020_HyperlinksListItem' }Defines the item as a list item in the SP Hyperlinks list.  (NOTE:  the space in SP Hyperlinks is replaced in SharePoint by _x0020_)
'Title': 'Title'Title of the list item
'Link':
     {'__metadata': {'type': 'SP.FieldUrlValue' },
     'Description': 'Link name',
     'Url': 'URL'
}}
Link field value.  As you can see, the Description and Url are provided separately and assigned values from the Flow trigger.

As you can see, the link name and URL are properly set in the second item.


Example 2:  Retrieving items

When working with the Send HTTP request to SharePoint to retrieve items, you use similar settings on the action.  Rather than using the POST method, you'll be using the GET method.  As well, since you are only retrieving information, no body is required to complete the action.  In the example below, the action will retrieve all the items in the SP Hyperlinks list.

Caveat

Whether you use the Get Items or Send HTTP request to SharePoint action to retrieve the items in a list, the items returned will be the same; however, there are slight differences in the JSON format returned, which you need to consider when iterating through the items to retrieve specific values.

Saturday, December 8, 2018

Strategy for enabling quick Flow Trigger or Action replacement

Every flow begins with a trigger.  In some cases, the business needs may change, which will require you to change the type of trigger being used.  If there are any references being made to dynamic content coming from the trigger, then you will notice as shown in Figure 1 that the Delete option for the trigger has disabled.  This is a mechanism used by Flow to ensure that you are not referencing dynamic content that is not available (NOTE:  it's possible to use expressions that refer to some dynamic data, which would not be checked by Flow, but would result in run-time errors.  Those examples are beyond the scope of this article).

Figure 1:  Trigger Delete option is disabled when dynamic content is reference in actions

The way to overcome this limitation is by storing the dynamic content you are referencing from the trigger in variables or other actions downstream.  Figure 2 shows an example, where the SharePoint list item ID is stored in a variable called Item ID.  Actions that need to refer to the trigger's Item ID can simply refer to the variable instead.

Figure 2:  Variable being used to store dynamic content from the trigger

Now, if you need to delete the trigger, simply delete its reference used in the Item ID variable.  All other actions downstream of the variable definition that refer to it will not be affected by this change.  As you see in Figure 3, the Delete option will now be enabled again on the trigger.  


Figure 3:  Removing reference to trigger dynamic content enables the deletion of the trigger


Once you delete the trigger, you will be able to select a new one a shown in Figure 4.

Figure 4:  Selection of a new trigger

In some cases, you may want to reference several dynamic content elements from the trigger.  Though it's possible to use one variable for each, it can get a bit more overwhelming to create so many variables.  Instead, you can use the Parse action that will store the output of the trigger.  To properly reference the fields within the Parse action, you need to define the schema.  One simple way to do this is to run the Flow without a schema (by setting the schema to {} ) and looking at the Body of the Parse function, as shown in Figure 5.

Figure 5:  Getting the schema of the trigger body

Save the body text and go back to editing the Flow.  Now, you can select the Use sample payload to generate schema for the Parse action to generate the schema.  Make sure that all fields are properly filled in the sample data; otherwise Parse will ignore them.

You can now reference the parameters from the Parse action schema in your downstream actions as depicted in Figure 6.  Keep in mind though that as you switch triggers, the type of data and variable names may change and you may need to modify the data to adjust it.  For example, a SharePoint list item identifier is stored in a field called ID.  If you work with a Dynamics 365 record, the identifier of the record is ItemInternalId.

Figure 6:  Referencing Parse parameters in downstream actions

You can even apply a similar approach to various actions throughout your Flow, where you may need to swap it out for another action.