Creating a Document or Folder by Using the Project Document Management Creation API

This topic explains how you can create a document or folder by using the Project Document Management Creation API.

Prerequisites

To create an application and request access to use the SAP Ariba APIs relevant to this feature, you must have access to the SAP Ariba Developer Portal. For details refer to Steps to Start Using the SAP Ariba APIs in Help for the SAP Ariba Developer Portal.
All queries made to this API must be authenticated using OAuth authentication. For details refer to SAP Ariba Developer Portal Authentication in Help for the SAP Ariba Developer Portal.
If you are using SAP Ariba Contracts integrated with Icertis Contracts Intelligence for SAP Ariba Solutions, you cannot process the Main Agreement or Contract Addendum documents in SAP Ariba as these documents are processed in ICI. If you must process the Main Agreement or Contract Addendum document in SAP Ariba, you must disable the integration by setting the Application.ACM.IcertisIntegration parameter to false. For more information about the parameter, see Enable SAP Ariba Contracts integration and contract data sharing with Icertis. However, note that disabling the integration might adversely impact some of the business process flows and should be done only after careful considerations and consultations.
You must obtain the parent folder ID in which the document or folder needs to be created.

Context

The POST /projectDocuments/{parentId} endpoint of the Project Document Management Creation API enables you to create folders or project documents of type Standard Document, Main Agreement, and Contract Addendum.

Procedure

Obtain the ID of the parent folder in which the document or folder needs to be created. You can view the parent folder ID in the user interface.
You can create a folder or a project document.
- To create a Standard Document, use the POST /projectDocuments/{parentId} endpoint.
  
  Example:
```
POST {{runtime_URL}}/projectDocuments/CW12345?user=myUser&passwordAdapter=PasswordAdapter1&realm=mySite
```
  Where:
  - realm is your site name
  - user is the User ID of the user for whom the Project Document Management Creation API will perform the action
  - passwordAdapter is the password adapter used to authenticate the user. For example: PasswordAdapter1
  At a minimum, the request body must contain the file element. You can upload the Standard Document file in the file element. File extension of the uploaded file must be the same as the extension specified in the title.
  Optionally, using the properties element in the request body, you can update attributes for the Standard Document you have uploaded (header fields in the Overview tab):
  - Name: Specify the file name of the Standard Document that you want to create. The name specified for the Standard Document must have the same extension as the uploaded file. For example, if the name specified is Standard_Document.docx then the uploaded file must be of type .docx.
    
    If this value is not specified, then uploaded file name will be set as the document title. However, if this value is specified, then it is prioritized over the uploaded file name.
    
    The name specified for the Standard Document is unique at the parent level.
  - description: Specifies the description of the Standard Document.
  - owner: Specifies the owner of the Standard Document. An owner can be an individual user, a global group or a project group. If the owner information is invalid, an appropriate error message will be returned.
    
    Default value: current session user
    
    owner element contains the following fields:
    - name: Specify the name of the user or the group
    - uniqueName: Specify the unique name of the user or the group
    - passwordAdapter: Specify the password adapter used to authenticate the user. This field is required only for user.
    - type: Specify the owner type. Valid values: User, ProjectGroup, Group
  - Specify the documentType element. Valid value: Document
  - useAs: Valid values are:
    - ContractContent: If you specify this value, then only files of type xlsx are allowed. The Excel file will contain contract terms or pricing terms. However, if the Parameter Application.ACM.EnableExcelXLSXContractContent is disabled, then files of type xlsx are not allowed.
      
      Note
      
      To download pricing terms in an xls file, contact SAP Ariba Support to enable the feature SC-20703: Enable Old 2003 Excel Format for Source To Contract Pricing Term Excel file and the parameter Application.ACM.EnableExcelXLSXContractContent for your site.
    - ContractAttachment
    - None
  - accessControl: Specifies the access control applicable on the document. You can specify multiple values, delimited by commas. For example: [ “Legal Information”, “Private to Team Members” ]
  - createAnnouncement: Specifies whether to announce the creation of the new Standard Document. Set the value to true to announce the creation of the Standard Document.
    
    Default value: false
  - publishRequired: If the value is set to either true or false, values specified as part of the current version will be updated. If the key-value pair is not specified, then the current version will not be updated.
    
    Default value: false
    
    Use the following data model for the properties field:
    { "name": "Standard_Document.docx", "description": "Standard Document", "owner": { "name": "Standard_Document.docx", "description": "Standard Document", "owner": { "name": "test", "uniqueName": "molson", "passwordAdapter": "PasswordAdapter1", "type": "User" }, "documentType": "Document", "useAs": "None", "accessControl": [ "Legal Information" ], "createAnnouncement": false, "publishRequired": false, }
  The Project Document Management Creation API returns details of the Standard Document created.
  
  For example:
```
{
    "id": "Doc4583517",
    "name": "Standard_Document.docx",
    "size": 13718,
    "version": "1",
    "parentFolderId": "CW6127",
    "projectId": "CW6127",
    "owner": "molson",
    "lastModifiedDate": "2022-06-13T09:03:07.510+0000",
    "creationDate": "2022-06-13T09:03:07.510+0000",
    "documentType": "Document",
    "active": true,
    "status": "Draft",
    "otherVersion": []
}						
		
```
- To create a Main Agreement, use the POST /projectDocuments/{parentId} endpoint.
  
  Example:
```
POST {{runtime_URL}}/projectDocuments/CW12345?user=myUser&passwordAdapter=PasswordAdapter1&realm=mySite
```
  Where:
  - realm is your site name
  - user is the User ID of the user for whom the Project Document Management Creation API will perform the action
  - passwordAdapter is the Password adapter used to authenticate the user. For example: PasswordAdapter1
  At a minimum, the request body must contain the following elements:
  - file: Select the Main Agreement file. You can upload the Main Agreement file in the file element. File extension of the uploaded file must be the same as the extension specified in the title.
  - In the properties element, specify the documentType field. Valid value: MainAgreement
  Optionally, using the properties element in the request body, you can update attributes for the Main Agreement you have uploaded (header fields in the Overview tab):
  - Name: Specify the file name of the Main Agreement that you want to create. The name specified for the Main Agreement must have the same extension as the uploaded file. For example, if the file name is Main_Agreement.docx then the uploaded file must be of type .docx.
    
    If this value is not specified, then uploaded file name will be set as the document title. However, if this value is specified, then it is prioritized over the uploaded file name.
    
    The name specified for the Main Agreement is unique at the parent level.
  - description: Specifies the description of the Main Agreement.
  - owner: Specifies the owner of the Main Agreement. An owner can be an individual user, a global group or a project group. If the owner information is invalid, an appropriate error message will be returned.
    
    Default value: current session user
    
    owner element contains the following fields:
    - name: Specify the name of the user or the group
    - uniqueName: Specify the unique name of the user or the group
    - passwordAdapter: Specify the password adapter used to authenticate the user. This field is required only for user.
    - type: Specify the owner type. Valid values: User, ProjectGroup, Group
  - useAs: Valid values are:
    - ContractContent: If you specify this value, then only files of type xlsx are allowed. The Excel file will contain contract terms or pricing terms. However, if the Parameter Application.ACM.EnableExcelXLSXContractContent is disabled, then files of type xlsx are not allowed.
      
      Note
      
      To download pricing terms in an xls file, contact SAP Ariba Support to enable the feature SC-20703: Enable Old 2003 Excel Format for Source To Contract Pricing Term Excel file and the parameter Application.ACM.EnableExcelXLSXContractContent for your site.
    - ContractAttachment
    - None
  - accessControl: Specifies the access control applicable on the document. You can specify multiple values, delimited by commas. For example: [ “Legal Information”, “Private to Team Members” ]
  - createAnnouncement: Specifies whether to announce the creation of the new Main Agreement. Set the value to true to announce the creation of the Main Agreement.
    
    Default value: false
  - publishRequired: If the value is set to either true or false, values specified as part of the current version will be updated. If the key-value pair is not specified, then the current version will not be updated. Default value: false
  - autoFinalizeOnPublish: If the value is set to true, then the Main Agreement is automatically finalized when the Contract Workspace (Procurement) containing the Main Agreement is published. If the value is set to false, then the Main Agreement is not automatically finalized when the Contract Workspace (Procurement) containing the Main Agreement is published.
    
    Default value - false
    
    Use the following data model for the properties field:
    { "name": "Main_Agreement.docx", "description": "Main Agreement", "owner": { "name": "test", "uniqueName": "molson", "passwordAdapter": "PasswordAdapter1", "type": "User" }, "documentType": "MainAgreement", "useAs": "None", "accessControl": [ "Legal Information" ], "createAnnouncement": false, "publishRequired": false, "autoFinalizeOnPublish": false }
  The Project Document Management Creation API returns details of the created Main Agreement.
  
  For example:
```
{
    "id": "Doc30964352",
    "name": "Main_Agreement.docx",
    "size": 13712,
    "version": "1",
    "parentFolderId": "CW42675",
    "projectId": "CW42675",
    "owner": "molson",
    "lastModifiedDate": "2022-06-21T10:44:38.081+0000",
    "creationDate": "2022-06-21T10:44:38.081+0000",
    "documentType": "Main Agreement",
    "active": true,
    "status": "Draft",
    "otherVersion": []
}						
		
```
- To create a Contract Addendum, use the POST /projectDocuments/{parentId} endpoint.
  
  Example:
```
POST {{runtime_URL}}/projectDocuments/CW12345?user=myUser&passwordAdapter=PasswordAdapter1&realm=mySite
```
  Where:
  - realm is your site name
  - user is the User ID of the user for whom the Project Document Management Creation API will perform the action
  - passwordAdapter is the Password adapter used to authenticate the user. For example: PasswordAdapter1
  At a minimum, the request body must contain the following elements:
  - file: Select the Contract Addendum file. You can upload the Contract Addendum file in the file element. File extension of the uploaded file must be the same as the extension specified in the title.
  - In the properties element, specify the documentType field. Valid value: ContractAddendum
  Optionally, using the properties element in the request body, you can update attributes for the Contract Addendum you have uploaded (header fields in the Overview tab):
  - Name: Specify the file name of the Contract Addendum that you want to create. The name specified for the Contract Addendum must have the same extension as the uploaded file. For example, if the file name is Contract_Addendum.docx then the uploaded file must be of type .docx.
    
    If this value is not specified, then uploaded file name will be set as the document title. However, if this value is specified, then it is prioritized over the uploaded file name.
    
    The name specified for the Contract Addendum is unique at the parent level.
  - description: Specifies the description of the Contract Addendum.
  - owner: Specifies the owner of the Contract Addendum. An owner can be an individual user, a global or a project group. If the owner information is invalid, an appropriate error message will be returned.
    
    Default value: current session user
    
    owner element contains the following fields:
    - name: Specify the name of the user or the group
    - uniqueName: Specify the unique name of the user or the group
    - passwordAdapter: Specify the password adapter used to authenticate the user. This field is required only for user.
    - type: Specify the owner type. Valid values: User, ProjectGroup, Group
  - useAs: Valid values are:
    - ContractContent: If you specify this value, then only files of type xlsx are allowed. The Excel file will contain contract terms or pricing terms. However, if the Parameter Application.ACM.EnableExcelXLSXContractContent is disabled, then files of type xlsx are not allowed.
      
      Note
      
      To download pricing terms in an xls file, contact SAP Ariba Support to enable the feature SC-20703: Enable Old 2003 Excel Format for Source To Contract Pricing Term Excel file and the parameter Application.ACM.EnableExcelXLSXContractContent for your site.
    - ContractAttachment
    - None
  - accessControl: Specifies the access control applicable on the document. You can specify multiple values, delimited by commas. For example: [ “Legal Information”, “Private to Team Members” ]
  - createAnnouncement: Specifies whether to announce the creation of the new Contract Addendum. Set the value to true to announce the creation of the Contract Addendum.
    
    Default value: false
  - publishRequired: If the value is set to either true or false, values specified as part of the current version will be updated. If the key-value pair is not specified, then the current version will not be updated. Default value: false
  - autoFinalizeOnPublish: If the value is set to true, then the Contract Addendum is automatically finalized when the Contract Workspace (Procurement) containing the Contract Addendum is published. If the value is set to false, then the Contract Addendum is not automatically finalized when the Contract Workspace (Procurement) containing the Contract Addendum is published.
    
    Default value - false
    
    Use the following data model for the properties field:
    { "name": "Contract_Addendum.docx", "description": "Contract Addendum", "owner": { "name": "test", "uniqueName": "molson", "passwordAdapter": "PasswordAdapter1", "type": "User" }, "documentType": "ContractAddendum", "useAs": "None", "accessControl": [ "Legal Information" ], "createAnnouncement": false, "publishRequired": false, "autoFinalizeOnPublish": false }
  The Project Document Management Creation API returns details of the created Contract Addendum.
  
  For example:
```
{
    "id": "Doc30968627",
    "name": "Contract_Addendum.docx",
    "size": 13685,
    "version": "1",
    "parentFolderId": "CW42675",
    "projectId": "CW42675",
    "owner": "molson",
    "lastModifiedDate": "2022-06-21T10:51:27.613+0000",
    "creationDate": "2022-06-21T10:51:27.613+0000",
    "documentType": "Contract Addendum",
    "active": true,
    "status": "Draft",
    "otherVersion": []
}						
		
```
- To create a folder, use the POST /projectDocuments/{parentId} endpoint.
  
  Example:
```
POST {{runtime_URL}}/projectDocuments/CW12345?user=myUser&passwordAdapter=PasswordAdapter1&realm=mySite
```
  Where:
  - realm is your site name
  - user is the User ID of the user for whom the Project Document Management Creation API will perform the action
  - passwordAdapter is the Password adapter used to authenticate the user. For example: PasswordAdapter1
  At a minimum, the request body must contain the following elements:
  - Name: Specify the name of the folder that you want to create.
    
    The name of the folder must be unique at the parent level. For example, Folder1.
  - In the properties element, specify the documentType field. Valid value: Folder
  Optionally, you can update attributes of the folder using the properties element in the request body:
  - description: Specify a description of the folder.
  - owner: Specify the owner of the folder. An owner can be an individual user, a global group or a project group. If the owner information is invalid, an appropriate error message will be returned.
    
    Default value: current session user
    
    owner element contains the following fields:
    - name: Specify the name of the user or the group
    - uniqueName: Specify the unique name of the user or the group
    - passwordAdapter: Specify the password adapter used to authenticate the user. This field is required only for user.
    - type: Specify the owner type. Valid values: User, ProjectGroup, Group
  - accessControl: Specifies the access control applicable on the document. You can specify multiple values, delimited by commas. For example: [ “Legal Information”, “Private to Team Members” ]
  Use the following data model for the properties field:
```
{
  "name": "Folder1",
  "description": "Folder",
  "owner": {
    "name": "test",
    "uniqueName": "molson",
    "passwordAdapter": "PasswordAdapter1",
    "type": "User"
  },
  "documentType": "Folder",
  "accessControl": [
    "Legal Information"
  ],
}			
		
```
  The Project Document Management Creation API returns details of the created folder.
  
  For example:
```
{
    "id": "WS4584427",
    "name": "Folder1",
    "version": "1",
    "parentFolderId": "CW6127",
    "projectId": "CW6127",
    "owner": "molson",
    "lastModifiedDate": "2022-06-13T12:10:38.782+0000",
    "creationDate": "2022-06-13T12:10:38.782+0000",
    "documentType": "Folder",
    "active": true,
    "childrenDocument": []
}						
		
```
To troubleshoot your queries to the Project Document Management Creation API, refer to Error Messages Returned by the Project Document Management API.