This post will show how to create or add new instance of a Document Set (like adding a new folder) to a SharePoint Document Library using the power automate action 'Send HTTP Request to SharePoint' as a POST request with the URI using the ListItem update method AddValidateUpdateItemUsingPath
Below is code text that shows headers and body format of the http request that will add a new Document Set to a Document Library as a ListItem using AddValidateUpdateItemUsingPath:
POST https://{site_url}/_api/web/lists/GetbyId('{ListIDofDocumentLibrary}')/AddValidateUpdateItemUsingPath
Accept: "application/json;odata=none"
Content-Type: "application/json"
{
"listItemCreateInfo": {
"FolderPath": {
"DecodedUrl": "{YourSiteDecodedURL&PathofParentFolder}"
},
"UnderlyingObjectType": 1
},
"formValues": [
{
"FieldName": "HTML_x0020_File_x0020_Type",
"FieldValue": "Sharepoint.DocumentSet"
},
{
"FieldName": "ContentTypeId",
"FieldValue": "{TheContentIDofDocumentSetContentTypeforDocumentLibrary}"
},
{
"FieldName": "FileLeafRef",
"FieldValue": "{DesiredNameofNewDocumentSetfolder}"
}
],
"bNewDocumentUpdate": false,
"datesInUTC": true
}
Below are screenshot examples of 2 separate http requests which are the same. However, the examples show what a request would look like if filled manually with text while the other is filled with dynamic content.
Ex1 HTTP New Document Set Text
Ex2 HTTP New Document Set Dynamic Content
Below is a screenshot of the http response output once the Document Set is created. It will include the Id number of the newly created Document Set that can be used in following flow steps to get the item if needed.
HTTP Request - Response Outputs
Table of Contents for This Post:
- Background Information of Issue
- Introduction of the method to add new document set using AddValidateUpdateItemUsingPath
- Description of AddValidateUpdateItemUsingPath
- Body of HTTP Request Outline
- Body of HTTP Request Key Items
- Example Flow to Add a New Document Set for Each Employee Listed in Excel Table
- General Info about document library used in example
- Basic Steps of the example Flow
- Detailed Steps of the example Flow
- Results of example Flow
- Conclusion
Background: Creating Document Sets with Power Automate
I wanted to make personnel folders for each of our employees in a SharePoint document library. I decided to use Document Sets instead of generic folders because it could have additional custom metadata column/fields like Full Name and EmployeeID that would be put on any of the files added into the personnel folder (document set).
From what I have searched and attempted in PA; it seems like there were two $free methods for creating a document set.
Method 1: Convert General Folder into a Document Set
This method requires that a generic folder be made within the document library and then convert the folder to a content type of a document set by changing the property contentID of the folder.
- Positives of Method 1:
- Negatives of Method 1:
- Doesn't allow for any automatic attachment/folders templates of a document set content type to be included
- Multiple responses stating this method doesn't show the document set properly in other functions due to how it was created/converted
- Martin Pyman - See Responses to his Create Document Set
I don't use this Method 1 of converting a folder to a document set because it appears to have underlying issues and I do not want those causing problems later.
Method 2: Create Document Set Using Uri /_vti_bin/listdata.svc/ and a header "Slug"
This method uses a http REST request that has a uri and header that put's a lot of identification data together and creates a new document set. The uri will be /_vti_bin/listdata.svc/{DocumentLibraryName} and a header "Slug" with a value of Path/{DesiredNameofNewDocumentSetFolder}|{contenttypeID}. This method is consistent and probably the most commonly used from what I can tell.
- Positives of Method 2
- Negatives of Method 2
I have been making document sets using Method 2 and has been working for me. However, I do not like the method because I could not add metadata to the initial creation. Also, I don't know how long the method will be stable and the "Slug" is not very clear what is happening as an action and has the possibility of changing the name of the document set.
Introduction: Create Document Set as ListItem using AddValidateUpdateItemUsingPath
I'm sure I'm not the first to figure this out, but I never found an exact write up, so I'm making this post. Through trial and error I have made an HTTP Request POST to add a new Document Set to a SharePoint Document Library by treating it as a list item instead of a folder by using AddValidateUpdateItemUsingPath.
Usually when you try to create a document set as a folder Microsoft Working with Folders and Files Using REST SharePoint would block the action since it has to treat some of the properties of a document set as a list item instead of a folder. However, using the AddValidateUpdateItemUsingPath for a list item on the list of the document library is a way to work around.
- Positives of New Method 3:
- Allows for automatic attachments/folders templates of document set content type to be included.
- Can set metadata column/fields in the initial creation.
- Clear to see what data is sent and will error and not create item if any field is incorrect.
- Negatives of New Method 3:
- The body of the http request can be long due to setting each field name and field value.
- Requires column/fields to be written correctly and may require encoding (example _x0020_ in place of a space).
- Doesn't check or error notice duplicate names and the http request will timeout if name (FileLeafRef) is already used.
- Must get the newly created ItemID from the http response and convert it from text to integer for any following steps.
Description: HTTP request using AddValidateUpdateItemUsingPath
The use of AddValidateUpdateItemUsingPath within an HTTP POST request is primarily used as a way to update a list item without changing the version number. However, if the property ‘bNewDocumentUpdate’ is set to false, then it will create a new item.
We can use this to create a new list item in the document library list so long as some key properties are included within the post request. See the Microsoft Learn section Working with list items by using REST - Create List Item in a Folder
Here are some sites that discuss using AddValidateUpdateItemUsingPath:
Uri of HTTP Request:
The Uri within the http request requires getting the list title or listid and then the endpoint /AddValidateUpdateItemUsingPath. I do not use list titles since I prefer using the ListId to avoid any errors. The Id of a list for a document library is a GUID that can be found in the properties of the document library. Within my flow I get the listId of the list of the document library with a prior http request and put it in a variable. However, you should be able to use either Uri to achieve the same result.
URI: _api/web/lists/GetByTitle('{ListTitleOfDocumentLibrary}')/AddValidateUpdateItemUsingPath
URI: _api/web/lists/GetById('{ListId}')/AddValidateUpdateItemUsingPath
Body Outline of HTTP Request:
The HTTP POST request body to create a new instance of a document set (like adding a new folder) has a format and some key elements that must be included. Beyond the key elements the post request needs to be formatted correctly with JSON spacing between items and any column names for additional metadata must be named correctly to match the SharePoint field internal name.
The body is separated into 3 parts:
- List Item Create
- Sets the path to the new document set about to be created
- Form Values or metadata column/fields that are applied to the new document set
- This is where the data of the document set is added
- Additional Properties of the http POST request
- These two additional properties (bNewDocumentUpdate and datesInUTC) are used when creating a new item
{
"listItemCreateInfo": {
"FolderPath": {
"DecodedUrl": "{YourSiteDecodedURL&PathofParentFolder}"
},
"UnderlyingObjectType": 1
},
"formValues": [
{
"FieldName": "HTML_x0020_File_x0020_Type",
"FieldValue": "Sharepoint.DocumentSet"
},
{
"FieldName": "ContentTypeId",
"FieldValue": "{TheContentIDofDocumentSetContentTypeforDocumentLibrary}"
},
{
"FieldName": "FileLeafRef",
"FieldValue": "{DesiredNameofNewDocumentSetfolder}"
}
],
"bNewDocumentUpdate": false,
"datesInUTC": true
}
Body Key Items of HTTP Request:
There are some key items that have to be included within the request for it to function properly. I will list them below and then follow with a description for each.
- Folder Path/Decoded Url
- Underlying Object Type
- FieldName: "HTML_x0020_File_x0020_Type" / FieldValue: "SharePoint.DocumentSet"
- FieldName: “ContentTypeId” / FieldValue: “{ContentTypeIdofDocumentSet}”
- FieldName: “FileLeafRef” / FieldValue: “{YourNamefortheDocumentSet}”
- bNewDocumentUpdate: false
- datesInUTC: true/false
Folder Path/Decoded Url -
This is in the section listItemCreateInfo. This is the location where the new documentset will be added. It is basically the decodedUrl of the site and path of the parentfolder.
If you wanted a documentset added in the rootfolder of a documentlibrary named "MyDocLibrary" the decodedUrl should read "https://sunmc.sharepoint.com/sites/CORP/MyDocLibrary" and the new documentset will show in the main folder of MyDocLibrary after it is created.
If you wanted to put a documentset inside of a subfolder "MySubFolder" of the document library then the decoded Url should read "https://sunmc.sharepoint.com/sites/CORP/MyDocLibrary/MySubFolder" and the documentset will be added into MySubFolder.
Underlying Object Type -
This is an easy item that must always show a value of 1 (not "1" text, but just the integer number 1). This identifies the documentset as a File System Object Type of 1-Folder. The values of ObjectType are (0-File, 1-Folder, 2-Web). DocumentSets are considered 1-Folder types.
FieldName: "HTML_x0020_File_x0020_Type" and FieldValue: "SharePoint.DocumentSet" -
The FieldName "HTML_x0020_File_x0020_Type" and FieldValue "SharePoint.DocumentSet" showing this is a document set is crucial for this http to function properly. This FieldName and FieldValue should not change since it should be the same default for everyone. This must be included when adding a document set as a listitem.
This field contains the ProgId which is described as "Lookup field to the identifier of a client application that can be used to edit this document." It might be possible to use ProgID in place of this field but I have not tested it. I suspect it would be more difficult since ProgID is a lookup type field and this one is a text.
Surprisingly, the actual column name is "HTML_x0020_File_x0020_Type" which is a Generic List Data Fields .
FieldName: “ContentTypeId” and FieldValue: “{ContentTypeIdofDocumentSet}” -
The ContentTypeId of the documentset must be included in the request so sharepoint knows what contenttype to use. To get the contenttypeId of the documentset you must go to the document library settings and view the content types. You will see the documentset content type you added to your document library, and if you click on it you can see the very long contentypeid in the browser webaddress. To use the contenttypeId in this flow it is best to search for the id in a prior http request by searching contenttypes by name and getting the ContentTypeId to put in a variable that can be put in this POST request.
FieldName: “FileLeafRef” and FieldValue: “{YourNamefortheDocumentSet}” -
The FileLeafRef is basically the name of the documentset/folder you are creating. You can't use special characters that are Microsoft Folder and File Invalid Characters since the document set is a folder. This is going to be a required column since all folders need names. This is also different than a Title column. BE ADVISED! Duplicate FileLeafRef are not allowed in a document library. If you create a new documentset with the same name as another folder/docset this will error and not create the item. The http request will continue to attempt until eventually time out without a specific error response.
bNewDocumentUpdate: false -
The property "bNewDocumentUpdate" must be set to false. When this is set to false it will create a new list item. If you have it set to true then it is attempting to update a file as opposed to create a new file. It will error if you use true since the request is in the incorrect format.
datesInUTC: true or false -
The property datesInUTC can be set to true or false. Most likely you want this set to true. If this is set to false, then any dates you are posting into a sharepoint date/time column must be in a text format which is done by converting the date to "MM/dd/yyyy". If datesInUTC is set to true, then you can use the full date/time format that comes from power automate and it will go directly into a SharePoint date/time column. You may need to do some timezone adjustments depending on your data.
Body Form Values of HTTP Request:
The additional metadata fields of your document set such as employeeId’s, special dates, or any other custom columns you want to fill must be written in the correct format to be recognized. This requires using the internal column/field name or the EntityPropertyName of a column field. So if you have a custom column with spaces or special characters in the name, you need to find how sharepoint references the column. This can usually be done by going to the column in the list settings and viewing the name in the browser URL. However, this is also found by getting the Fields of the list using an http request that get’s details of each column/field.
Below are some references showing examples of columns or metadata fields.
Example Flow to Add a New Document Set for Each Employee Listed in Excel Table
Below I am going to show an example flow that I used to create a new document set/folder for employees listed in an excel list. This flow has initial settings/selections that will help get values to populate variables which will ultimately be used in the http post to create a new document set for each employee.
These are screenshots of the Document Library view and the Document Library Settings. You can see the full name of the Document Library, Column Names, and the Document Set ContentType that was added to the library in the Settings.
SharePoint Document Library
SharePoint Document Library Settings
Below is a screenshot of the fake employees Excel list I'm using to create document sets as personnel folders for each employee.
Example Excel Source Employee List
Below is an overall view of the steps used in my example power automate flow.
Example Flow All Steps Overview
Basic Steps of Example Flow:
The majority of the steps are to help get specific Ids and fill in variables; however, this is not required for the http post create a new document set. You could literally have 1 step which is the http request and somehow manually enter data in the http post request to create a new document set.
1. Initialize Variables - These are variables that will hold specific info to be used in the flow such as ListId or ContentTypeId - (None of the variables are set when initialized, they will all be set/filled later in the flow.)
2. Settings to Select Parent Folder and Name of Content Type
- Settings 1 - Select the folder that will be the parent folder of the new document set.
- Settings 2 - Select the Site Address where the document library is located so it can be used in other flow steps.
- Settings 3 - Type in the name of the document set ContentType so it can be searched in a step to get the full ContentTypeID.
3. Scope A - This gets the Site Address and DecodedUrl so it can be used in the flow and the DecodedURL can be used as part of the path to create the new document set.
4. Scope B - This uses the Set1 selected folder to get specific properties which can identify the document library and list of the document library.
5. Scope C - This will get the list of the document library and set the ListId that will be used in the Uri
6. Scope D - This will use the ContentTypeName from Set3 to find the ContentTypeID for the list
7. List Rows Present in Table - This is the source data list of employees that will be used to create document sets for each employee.
8. Apply to Each Excel Row - This is the section where the document set is created and then the response of the http request is parsed to get the new ItemId of the created document set.
Below are detailed screenshots of the example flow steps:
FlowEx1 - Initialize Variables
FlowEx2 - Settings of Parent and Content Type Name
FlowEx3 - Get Site Address
FlowEx4 - Get DecodedUrl
FlowEx5 - Get Folder Properties
FlowEx6 - Get List of Document Library
FlowEx7 - Get ContentTypeId for Document Sets
FlowEx8 - Excel Source of Employee List
FlowEx9 - Apply to Each Create New Document Set
FlowEx10 - Apply to Each Get ItemId of New Document Set
Results of Example Flow:
When the flow is run and the http post to create a new document set is completed, it will automatically have a response to the http request within the flow. This response contains the Id of the newly created document set. The Id is the unique interval item number that every item in a list has when it is added (this is not the uniqueId which is a full guid format).
The http response will have all of the fields that were originally included as well as the Id field. This must be parsed out of the JSON response so the Id can be used in following flow steps. The Id is in a text format when it is parsed out and must be converted to a number format to be used correctly.
Below are the results of running the flow and adding document sets to the Document Library:
Results Document Library New Document Sets
Below are some select outputs of the example flow to show items that were used in the http request like DecodedUrl, Parent Folder Path, and ContentTypeID:
FlowResults1 - Settings
FlowResults2 - Get DecodedUrl
FlowResults3 - Get ContentTypeID
Below is an output of the http request that created a new document set. All of the fields that were included in the request are returned with the response, and it now includes the additional "Id" field which contains the list item integer Id of the document set.
FlowResults - HTTP Response Outputs
Conclusion:
This method of creating a document set using an http request and AddValidateUpdateItemUsingPath is not a massive change or easy button over the method that uses a "Slug" header. However, there is benefit of being able to add metadata with the initial creation. Also, if someone is clever enough I'm sure they could make some form of batch requests and then prevent the apply to each needed in my example for each row in excel.
If you have any feedback or notice there could be a problem with creating document sets with this method please add a comment to let us know. The convert folder to document set method seemed viable until others left comments about potential issues. So please don't hesitate to add some input.
Thanks 👋
