Update Folder Metadata by Path
POST /ws/rest/service/v1/dm/folder/update
Purpose
This service allows you to modify the metadata for documents under a folder using the folder path value.
Prerequisites
To use this REST service:
- Configure the Document Manager (DM) in the shell where folder is to be created.
- To include categories and phases in the request, ensure the categories are configured in the Project Phase.
- Go to the Company Workspace tab, and switch to Admin mode.
- In the left Navigator, select Data Structure Setup, select Data Definitions, and then select Basic.
- Open Project Phase.
Multiple categories and phases can be included in the request.
- As an integration user, you must also have update access on DM functionality.
Request Format
Send an API request in the following format:
(Form Data (content type : application/x-www-form-urlencoded))projectnumber: <value>
data:[
{
"Path": "<value>",
"Description": "<value>",
"Name": "<value>",
"Categories": "<value>",
"Phases": "<value>"
}
]
Note:
parent_node_id can be provided as a part of path parameter in request.Supported Request Parameters
The following parameters can be included in the request:
| Request Parameter | Required? | Data Type | Description |
|---|---|---|---|
| projectnumber | Yes | String |
The project number or shell that is to be included in the folder. However, if you are creating a folder at the company level, the project number is not mandatory. By default, when the project number is not provided, the folder is then created in the specified path within the Company Level Shell. |
| Data JSON Map: The following parameters can be included. Optional fields are based on the Attribute form design. | |||
| Path | Yes | String |
Path in the Document Manager where you want to update a folder. Specify the full path of the document to update. For example, "/Project Documents/Service docs/Folder1/pipeline estimate.doc" |
| Name | No | String |
The new name of the renamed folder. A maximum length of 250 characters is supported. Names that will not be supported are those that contain non-printable ascii, names with trailing spaces, and the special names "." and "..". |
| Description | No | String | A short description of the folder's purpose. |
| Categories | No | String | The folder category associated with the folder being updated. |
| Phases | No | String | The phase associated with the folder being updated. For example, Preplanning. |
Sample Request
To update a document "dm1.PNG" under "/test" folder, the data must be:
URL: http://<host>:<port>/ws/rest/service/v1/dm/document/update
data:[
{
"Path":"/test/dm1.PNG",
"Name":"dm1.PNG",
"Owner":"Company Administrator",
"Creation Date":"01/01/2016",
"% Complete":"100",
"Description":"dm1.PNG df"
}
]
Tip:
Use the GET call to get the structure of the JSON data.
Response Format
A JSON object is returned in the following format.
{
"data": [],
"message": [],
"status": <REST status code value>,
"rest_audit_id": <value>
}
Note:
The read-only fields will not be updated with values from input.Sample Success Response
This is an example of a successful response:
{
"data":[
{
"Path":"/test/dm1.PNG",
"Creation Date":"01/01/2016",
"Owner":"Company Administrator",
"Description":"dm1.PNG df",
"% Complete":"100",
"Name":"dm1.PNG"
}
],
"message":[
{
"message":"OK"
}
],
"status":200
}
Sample Failed Response
This is an example of a failed response with a status code 505 for an invalid folder name.
{
"data":[
{
"Path":"/test/dm2.PNG",
"Creation Date":"01/01/2016",
"Owner":"Company Administrator",
"Description":"dm1.PNG df",
"% Complete":"100",
"Name":"d1.PNG"
}
],
"message":[
{
"message":"Invalid folder name."
}
],
"status":505
}
Supported Validation Messages and Status Codes
The following validation messages and status codes display in the response when incorrect values are provided in the request.
| Field Name | Use-case Scenario | Status code | Error Message |
|---|---|---|---|
| projectnumber | The project number is invalid. | 602 | Server Error, Contact System Administrator. |
| projectnumber | The project number is blank and Path is not valid. | 505 | Invalid folder name. |
| projectnumber | The project number is blank and Path is valid at the company level. | 200 | Ok |
| Path | The Path is blank | 500 | Server Error, contact system administrator. |
| Path | An invalid Path is specified. | 505 | Invalid folder name. |
| Name | The Name is blank. | 505 | Input Required: Name |
| Name | Name is not specified in the data JSON object. | 505 | Server Error, contact system administrator. |
| Name | Renamed a folder in a blank shell. | 505 | Invalid folder name. |
| Name | Renamed a root folder. | 505 | Root folder cannot be renamed. |
| Name | An existing folder is duplicated (case-insensitive) | 505 | Folder with given name already exists |
| Categories | An invalid Category is specified. | 505 | Invalid Categories, Please provide correct Category values |
| Phases | An invalid Phase is specified. | 505 | Invalid Phases, Please provide correct Phase values |