Create Documents by Parent Folder ID

POST /ws/rest/service/v1/dm/document/create/<parent_node_id>

Available: Version 23.12 and later

Purpose

Add documents (files) to a particular folder using the folder node ID. It also supports adding revisions to an existing document.

Note:

  • Starting with version 26.4, file validations are performed based on the data section name attribute rather than the uploaded file name.
  • The number of uploaded files must be equal to or less than the number of files specified in the data list.
  • When the number of uploaded files is less than the number of files specified in the data list, a dummy file will be displayed in the UI for each missing file. Each dummy file will be named according to the corresponding entry from the list, similar to how a metadata file is created during import.

Request Format

Send an API request in the following format:

https://<host>:<port>/ws/rest/service/v1/dm/document/create/<parent_node_id>

data: [ {"Name":"<value>",

"docTitle":"<value>",

"revNo":"<value>",

"issueDate":"<value>"

}]

Path Parameter

Specify the following path parameter:

Request Parameter Required? Data Type Description
parent_folder_id Yes Integer The ID of the parent folder's node where the documents will be created.

Note:

Although you can specify a path in the request payload, the call ignores it. The document is only created in the node ID provided in the URL.

Use the Get Folders or Documents Metadata by Path REST Service to get the node_id value for the folder.

Request Parameters

This a multi-part request, and all parameters must be listed before all file parts. Provide the parameters in the following order:

Request Parameter Required? Data Type Description
projectnumber No String

The project associated with the document. Not required for company level.

If the project number is not specified, the document is created in the Company Workspace. If the parent folder Id is not in the Company Workspace, the document will not be visible even in Company Workspace.
dorevise No String Indicates whether to revise the file using the same file name. Valid values include: "yes", and "no" (default).
data Yes JSON String List of field and values for the Document Attribute Form.
Name Yes String Name of the document to be created.
isCustomEnable No String

Indicates whether to provide additional information. Valid values include: "yes" and "no" (default).

If the value is yes, the following additional requirements must be met:

  • The file extension specified in the "Name" attribute must match the actual file.
  • The "Name" attribute cannot include the following special characters: / : * ? " < > |

Additionally, if the value is yes, the following additional actions occur:

  • Numeric, String, Date, and Date and time custom fields are populated.
  • The file name that is displayed in the UI is derived from the "Name" value.
  • If "dorevise" is yes, the REST call revises the document with same name, displays the file ID in the response, and does not update any custom fields.
  • If the document is uploaded from the root folder, the file ID is displayed in the response.

Response Format

A JSON object is returned in the following format.

{

"data": [],

"message": [],

"status": <REST status code value>

}

Sample Request

To create a document "ProjectDetails.doc" in the"/Project Documents/Service docs" folder with node ID 6561, send the API request in the following format:

http://<host>:<port>/ws/rest/service/v1/dm/document/create/6561

[ {"fileName":"ProjectDetails.doc",

"docTitle":"project details",

"revNo":"1",

"issueDate":"06/01/2016",

<any additional document attribute form properties, excluding creation date and owner> }

]

Note:

  • Except for the creation date and owner, you can add any additional Document Attribute Form properties as key value pairs in the preceding JSON.
  • This call only updates the elements visible in the Upload window, such as Document Title, Revision No, and Issue Date. The system cannot update custom data elements that are not listed in the Upload window.

Sample Multipart Form Request

Note:

The form data body boundary in the example below is "—file upload—", but can be anything (or left unset).

-----file upload---

Content-Disposition: form-data; name="shortname"

unifier

-----file upload---

Content-Disposition: form-data; name="authcode"

MTIzMTIz

-----file upload---

Content-Disposition: form-data; name="dorevise" yes

-----file upload---

Content-Disposition: form-data; name="data"

[

{"Name":"ProjectDetails.doc","Owner":"Company Administrator","Creation Date":"01/01/2016","% Complete":"100","Description":"Fold 1" }

]

-----file upload---

Content-Disposition: form-data; name="0"; filename="b.txt" Content-Type: text/plain

test document contents

-----file upload-----

Sample Success Request

Send a request in the following format to upload the document, export (3).doc, from local storage:

http://<host>:<port>/ws/rest/service/v1/dm/document/create/713

projectnumber:AP

dorevise:yes

data:[{"Name":"export (3).doc"}]

isCustomEnable: yes

Note:

parent_node_id is provided as part of the path parameter in above REST call.

Sample Success Response

A successful message is displays in the following format when a ProjectDetails.doc document is successfully created in the Service docs folder:

{

"data": [{

"Path":"/test",

"from_object_id":"713 ",

"parentId":"713",

"Name": "export (3).doc"

}],

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

"status": 200

}

Sample Failed Request

An invalid parent_node_id is sent in the following request:

http://<host>:<port>/ws/rest/service/v1/dm/document/create/71345

projectnumber:AP

data:[{"Name":"trial10.doc"}]

Note:

The parent_node_id is provided as part of the path parameter in the above REST call.

Sample Failed Response

A failed response displays in the following format with status code 1045 for the above request when an invalid parent_node_id is specified:

{

"data": [ {

"Name": "ProjectDetails.doc"

}],

"message": [ { "message": "parent_node_id parameter is invalid", "status": 1046 }],

"status": 1045

}

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
parent_node_id parent_node_id is blank. 500 Server error. Contact System Administrator.
parent_node_id parent_node_id is invalid. 1046 parent_node_id parameter is invalid.
projectnumber project number is invalid. 602 Project/Shell number is not correct.
Name Name is blank. 1054 Input required: Name
Name Name is not specified in the data JSON object. 1054 Input required: Name
Name Name is invalid (against the rules of naming). 1048 Invalid file name.
Name Existing name is specified (upper or lower case). 1047 File already exists in the path.
Name The file extension specified does not match the file provided.   Extension given in Name attribute must be same as uploaded file extension.
dorevise Random values are specified.    
% Complete Characters are given 200 In UI, characters are not reflected instead "0" is kept.
Description Description exceeds 4000 characters. 500 Server error. Contact System Administrator.