Create Folders by Path

POST /ws/rest/service/v1/dm/folder/create

Purpose

This service allows you to create folders under a parent folder. You can also use this service to create folders under different parent folders.

projectnumber (String) Optional. Not required for company level.
data (JSON String) Required: List of field and values for the Folder Attribute Form.
- Path: Specify the full parent path where folder has to created.
- Name: Name of the folder to create: "Folder1"
- Path and Name are required fields, other fields are optional/required based on the attribute form design.

Prerequisites

To use this REST service:

Configure the Document Manager 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.
1. Go to the Company Workspace tab and switch to Admin mode.
2. In the left Navigator, select Data Structure Setup, select Data Definitions, and then select Basic.
3. Open Project Phase.
As an integration user, you must also have create access on DM functionality.

Request Format

Send an API request in the following format:

(Form Data (content type : application/x-www-form-urlencoded))

data:[

{

"Path": "<value>",

"Name": "<value>",

"Owner": "<value>",

"Creation Date": "<value>",

"% Complete": "<value>",

"node_id": "<value>"

}

]

Note: Creation Date, % Complete, and Owner are optional fields and are loaded by default with appropriate values. The Owner is the shell-level administrator.

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 creating a folder at the company level, the projectnumber is not mandatory. By default, when the projectnumber 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 create a folder.
Name	Yes	String	Name of the folder to be created. A maximum length of 250 characters is supported. Names that will not be supported are those that contain non-printable ascii, / or \, 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 to be created.
Phases	No	String	The phase associated with the folder to be created. For example, Preplanning.

Sample Request

To create a folder "REST Folder" under "/Project Documents/Folder112" then data should as below

projectnumber:TestProj-C

data:[

{

"Path":"/Folder112",

"Name":"REST Folder",

"Owner":"Company Administrator",

"Creation Date":"01/01/2016",

"% Complete":"100",

"Comments":"Fold 1"

}

]

Response Format

A JSON object is returned in the following format:

{

"data": [],

"message": [],

"status": <REST status code value>

}

where:

"data": [] contains list of fields defined in the Folder Attribute Form.

Sample Success Response

In addition to the data, a successful response displays:

a response "status" code of 200
a _record_status key with a "SUCCESS" value or an error message

{

"data":

[

{

"Path":"/Folder112/Folder112",

"Creation Date":"01/01/2016",

"Owner":"Company Administrator",

"Comments":"Fold 1",

"% Complete":"100",

"Name":"REST Folder",

"node_id":"2003150"

}

],

"message":[{"message":"OK"}],

"status":200

}

Sample Failed Response

The following is an example of the failed response:

{

"data":

[

{

"Path":"/Folder112/Folder112",

"Creation Date":"01/01/2016",

"Owner":"Company Administrator",

"Comments":"Fold 1",

"% Complete":"100",

"Name":"REST Folder"

}

],

"message":[{"message":"Folder with given name already exists"}],

"status":1043

}

Supported Validation Messages and Status Codes

The following error 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	An invalid projectnumber is specified in the request.	602	Project/Shell Number is not correct.
projectnumber	The projectnumber is blank and the path is not valid.	1043	Parent path or node id is invalid or does not exist.
Path	The Path is not specified.	500	Server Error, contact system administrator.
Path	An invalid path is specified.	1043	Parent path or node id is invalid or does not exist.
Name	Name is blank.	1043	Input Name Required-Empty Name Given.
Name	Name is not specified in the data JSON object.	1043	Server Error, contact system administrator.
Name	An invalid Name is specified including special characters.	1043	Folder Name cannot have special characters '/','\\',':','*','?','\"','<','>','\|'
Name	An existing Name is specified (case-insensitive).	1043	Folder with given name already exists.
Description	The Description exceeds 2000 characters.	1043	Valid Input required for fields : 'Description'.
Categories	An invalid Category is specified	1043	Invalid Categories, Please provide correct Category values.
Phases	An invalid Phase is specified.	1043	Invalid Phases, Please provide correct Phase values.

Purpose

Prerequisites

Request Format

Supported Request Parameters

Sample Request

Response Format

Sample Success Response

Sample Failed Response

Supported Validation Messages and Status Codes

Related Topics