Create Documents by Path

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

Available: Version 23.12 and later

Purpose

Add documents (files) with metadata for a particular folder. 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.

Prerequisites

Ensure the following:

  • Configure the Document Manager in the shell where the document is to be created in a folder.
  • You must have Create permission to use this REST service of Document Manager.
  • Create the folder before you create or upload the document.

Request Format

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

This is a multi-part request, and all parameters must be listed before all file parts.

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

"Name":"<value>",

"docTitle":"<value>",

"revNo":"<value>",

"issueDate":"<value>"

}]

Request Parameters

As stated above, this a multi-part request, and all parameters must be listed before all the file parts. Provide the parameters in the order listed below, and then upload the file contents by specifying the file name (with extension) in the key value and selecting the file under the value.

Request Parameter Required? Data Type Description
projectnumber No String The project associated with the document. Not required for company level.
Path Yes String Full path where the document will be created. The folder path must exist for the document to be created.
Name Yes String Name of the document to be created.
dorevise No String Indicates whether to revise the file using the same file name. Valid values include: "yes", and "no" (default).
% Complete No Integer The amount of work completed on that type of file/document.
Description No String A description of the folder to be updated.
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.

    Note:

    Creation Date, Owner, Upload By, Pub No., and Size are loaded by default with appropriate values. Owner and Upload By is specifies the shell-level administrator.

Sample Request

Send an API request in the following format to create a document "ProjectDetails.doc" under "/Project Documents/Service docs" folder:

data [{"path":"/Service docs",

"fileName":"ProjectDetails.doc",

"docTitle":"project details",

"revNo":"1",

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

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

}]

Note:

  • Except for 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="projectnumber"

Shell-001

-----file upload---

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

[

{"Path":"/Service docs","Name":"ProjectDetails.doc","docTitle":"project details","revNo":"1","issueDate":"06/01/2016", additional document attribute form properties, excluding creation date and owner }

]

-----file upload---

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

test document contents

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

Sample Success Request

To upload a document, export(2).doc, from the local storage to the test folder, specify a request in the following format:

projectnumber:AP

data:[{"Path":"/test","Name":"export (2).doc"}]

isCustomEnable: yes

Sample Success Response

A successful message displays in the following format, with status code 200, when the ProjectDetails.doc document is created in the Service docs folder:

{

"data":[{

"Path":"/Service docs",

"from_object_id":"713",

"file_id":"629",

"parentId":"713",

"Name":"export (2).doc",

"node_id":"1000"

}],

"message":[{"message":"OK",

"status":200

}],

"status":200

Sample Failed Request

The following request contains a file name with invalid characters.

projectnumber:AP

data:[{"Path":"/test","Name":"<>*||.doc"}]

Sample Failed Response

A failed response displays in the following format, with status code 1045, when a parent path is not specified in the request:

{

"data": [{

"Path":"/test",

"from_object_id":"713",

"Name":"<>*||.doc"

}],

"message": [ { "message":"Invalid file name.", "status":1048 } ],

"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
projectnumber project number is invalid. 602 Project/Shell Number is not correct.
projectnumber project number is blank and path is invalid. 1039 Invalid folder name.
Path Path is invalid. 500 Server Error, contact system administrator.
Path Path is blank. 1039 Parent path or node id is invalid or does not exist.
Name File name is blank. 1054 Input required: Name
Name Invalid Name is given (against the rules of naming). 1048 Invalid file name.
Name Name is not specified in the data object. 1054 Input required: Name
Name An existing name is specified (upper and 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 When random values are specified, it assumes the default value as "no".    
% Complete When random values are specified, it assumes the default value as "0".    
Description Description exceeds 4000 characters. 500 Server error.