Add New Document Set to Document Library Using HTTP Request REST ListItem method AddValidateUpdateItemUsingPath

[wskinnermctc]

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 TextEx2 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:

1. Background Information of Issue
2. Introduction of the method to add new document set using AddValidateUpdateItemUsingPath
3. Description of AddValidateUpdateItemUsingPath
   1. Body of HTTP Request Outline
   2. Body of HTTP Request Key Items
4. Example Flow to Add a New Document Set for Each Employee Listed in Excel Table
   1. General Info about document library used in example
   2. Basic Steps of the example Flow
   3. Detailed Steps of the example Flow
   4. Results of example Flow
5. 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:
  • Actions in PA are easier/simple to follow since it can use some of the standard folder actions.
  • Dealing with folder names that are duplicates is easier to manage or recognize errors.
  • Setting some metadata is easier
  • FaustoCapellan How to Create SharePoint Document Set 
  • Arjol Rrodhe LinkedIn - Create Document Set 
• 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
  • Allows for automatic attachment/folders templates of document set content type to be included
  • Relatively easy to get the new ItemID of the created document set from the http response that can be used in following steps to set additional metadata
  • Power Automate Forum - Flow to create document set when planner task added 
  • Power Automate Forum - Need Help Making Document Set 
  • Knowhere365.space - Microsoft Flow SharePoint DocumentSet Creation 
• Negatives of Method 2
  • More steps than Method 1 and using http request is a little more complicated
  • Formatting names might be more complicated since they have to pass in the url heading
  • Need to have secondary steps to set additional metadata since the action can only create a document set by name and not include any additional metadata fields.
  • The use of _vti_bin/listdata.svc and the "Slug" seems to be a 2010 SharePoint legacy function that is not really intended for this and my be deprecated or unstable long term.
  • Power Automate Forum - Trouble using the Slug header 
  • Colm Divilly Blog - Slug Header is only Suggestion and May Change Name Value 
  • Microsoft Learn - SharePoint Foundation 2010 REST Interface 
  • SharePoint Stack Exchange - Difference Between listdata.svc and client.svc 

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:

• SharePointCass.com - Programmatically Update SharePoint List Properties without affecting the versio... 
• Robert Schouten 2018 - Update File Metadata with REST api using ValidateUpdateListItem method 

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:

1. List Item Create 
• Sets the path to the new document set about to be created
2. 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
3. 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.

1. Folder Path/Decoded Url
2. Underlying Object Type
3. FieldName: "HTML_x0020_File_x0020_Type" / FieldValue: "SharePoint.DocumentSet"
4. FieldName: “ContentTypeId” / FieldValue: “{ContentTypeIdofDocumentSet}”
5. FieldName: “FileLeafRef” / FieldValue: “{YourNamefortheDocumentSet}”
6. bNewDocumentUpdate: false
7. 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.

• Microsoft Learn SharePoint Structures Common Fields Base Data Fields 
• Microsoft Learn SharePoint Structures Common List Item 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 VariablesFlowEx2 - Settings of Parent and Content Type NameFlowEx3 - Get Site AddressFlowEx4 - Get DecodedUrlFlowEx5 - Get Folder PropertiesFlowEx6 - Get List of Document LibraryFlowEx7 - Get ContentTypeId for Document SetsFlowEx8 - Excel Source of Employee ListFlowEx9 - Apply to Each Create New Document SetFlowEx10 - 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 - SettingsFlowResults2 - Get DecodedUrlFlowResults3 - 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 👋

[wskinnermctc · Accepted solution]

I made the post and consider it solved.

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.

New Document Set with Dynamic ContentNew Document Set with Text

[VNO]

What about action 'Create new document set' in SharePoint Connector ?

https://learn.microsoft.com/en-us/connectors/sharepointonline/#create-new-document-set 

 

https://learn.microsoft.com/en-us/connectors/sharepointonline/#create-new-document-set

[wskinnermctc]

Thanks for showing that. It is a new connector that was added sometime after January 20, 2023. I don't know when it was added since I can't see any kind of history like that, but I know it wasn't available in January from checking the learn site history.

It had to come out rather recently, and honestly I wasn't looking for it.

I'll make an instruction reference for the simple connector.

Looks like all my work is now obsolete ☹️

But at least we have an easy connector now 😀

[monav]

Your hard work is greatly appreciated.  I don't think it is obsolete because the connector only lets you create an out of the box document set.  I was able to use your helpful information to create my custom document sets.  Thank you SO MUCH for sharing!!!

[Pearple]

Thank you for this post. It helped me creating docsets with a dynamic url. Hope you can help with the following. How can I extract the ID of the docset so that I can use it in other actions?

Thank you in advance for your time!

[wskinnermctc]

Hi @Pearple 

The steps to get the ID are in the original example photos above. If you look at the actions that follow "Send an HTTP request to SharePoint POST Add New DocumentSet" you can see they are about getting the ID of the new document set and putting it into the variable.

It is basically using Parse JSON on the HTTP Request that was used to create the new Document Set

Get DocSet ID after Creation

The final HTTP request in the example is just to show using the ID of the document set in a new HTTP request. But you could use the variable anywhere.

Here are the details of the steps below:

Parse JSON of the HTTP Create New DocumentSet

The Schema used in the Parse JSON is below:

{
    "type": "object",
    "properties": {
        "d": {
            "type": "object",
            "properties": {
                "AddValidateUpdateItemUsingPath": {
                    "type": "object",
                    "properties": {
                        "__metadata": {
                            "type": "object",
                            "properties": {
                                "type": {
                                    "type": "string"
                                }
                            }
                        },
                        "results": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "ErrorCode": {
                                        "type": "integer"
                                    },
                                    "ErrorMessage": {},
                                    "FieldName": {
                                        "type": "string"
                                    },
                                    "FieldValue": {
                                        "type": "string"
                                    },
                                    "HasException": {
                                        "type": "boolean"
                                    },
                                    "ItemId": {
                                        "type": "integer"
                                    }
                                },
                                "required": [
                                    "ErrorCode",
                                    "ErrorMessage",
                                    "FieldName",
                                    "FieldValue",
                                    "HasException",
                                    "ItemId"
                                ]
                            }
                        }
                    }
                }
            }
        }
    }
}

These are the steps below that use that Parse JSON to finally get the ID into a variable.

Put ID from Parse JSON into Variable

Let me know if this works for you,

[Pearple]

Thank you for your quick response! I'm having trouble with converting the FieldValue Id to integer.

The body of the Select action to get the Id is: 

It looks like FieldValue is replaced by "76"?

[wskinnermctc]

It is difficult to tell which Select action you are referring since I have 2 select actions in the example I made for you. But I think you have something backwards or selected out of order.

You want to Select the results from the Parse JSON and

Map the FieldName to FieldValue

Also, it seems like we are in different languages, so there might be some confusion with how my instructions or pictures are being translated. 

[Pearple]

Thank you, but I can't get it to work.

I'm referring to action 'Select the Fieldvalue to get the Id value of the new Document Set'. 

Output of  filter array

output of action 'Select the Fieldvalue to get the Id value of the new Document Set'. 

The value of Fieldvalue is blanc, while "Fieldvalue" is replaced bij the value.

I can't figure out what is going wrong.

[wskinnermctc]

Good Morning @Pearple , I think I can see the issue you are having.

You need to change the Select action so that the Map field is a single box. The Map field can be changed from the Key Value Mode which has two boxes. You want the Map to be in Text Mode which is a single box.

Select - Key Value ModeSelect - Text Mode

You can change the mode by clicking the icon next to the Map field.

Select - Switch to Text Mode

When the Select action Map field is in Text Mode there will be a single box where you can enter the expression item()?['FieldValue'] so that there is just a single value instead of a split column.

Select - Enter Expression for Map

Do this and the output will only have "87" in the result instead of "87":""

Let me know if this works for you,

Do Not click Accept as Solution. Accepteer niet als oplossing. (Please do not click Accept as Solution button for any of my responses to you @Pearple . I made the original post as a reference for creating an HTTP request. I also made a Solution for the original post. If you mark one of my replies to you as a solution it will move that response up to the top of the original post. I do not want that to happen.) 

[monav]

@Pearple I'm not sure if this will be helpful to you, but this is a screenshot of how I got the ID after the http action that creates a document set (thanks to this very helpful post by @wskinnermctc).