Jump to

• Request
• Response
• Examples

Assign a Metadata Collection to a Folder

post

/documents/api/1.2/folders/{folderId}/metadata/{collectionName}

Associate an existing metadata collection with a specified folder.

Note: To assign a global collection to a folder, you must be the owner or have the manager role for the folder. If it is a personal collection, you can assign only if you are the folder's owner.

You must assign a collection to a particular folder before you can assign values to the fields for the particular folder. You can assign a collection to one or more folders, and any folder can have one or more collections assigned to it.

Metadata Inheritance:

Metadata fields assigned to a folder are available to all folders and files in the hierarchy beneath that folder. Similarly, the values you assign to those fields are inherited by all folders and files nested beneath that folder unless explicitly defined for a nested folder or file. Metadata values specified for a folder or file replace the inherited value for that folder and, by the same rules of inheritance, any folders or files in the hierarchy nested beneath that folder.

Request

Supported Media Types

• application/json
• application/xml

Path Parameters

• collectionName: string
  Name of the metadata collection to assign.
• folderId: string

  Globally unique identifier (GUID) for the folder. If the referenced folder is the user's home folder, the value for folderId is self.

Back to Top

Response

Supported Media Types

• application/json
• application/xml

200 Response

The request was fulfilled.

Body ()

Root Schema : FolderCollectionResponse

Type: object

The response body includes information about the assign collection to a folder operation.

Show Source

• errorCode(optional): string
  An error code of zero (0) indicates no errors.
• idList(optional): string
  Globally unique identifier (GUID) of the original folder.
• type(optional): string
  Item type folder.

{
    "description":"The response body includes information about the assign collection to a folder operation.",
    "properties":{
        "idList":{
            "type":"string",
            "description":"Globally unique identifier (GUID) of the original folder."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>folder</code>."
        },
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        }
    }
}

Example Response (application/json)

{
    "idList":"F94131468853B4845E0508854EE870070A1AA68C3354",
    "type":"folder",
    "errorCode":"0"
}

400 Response

Request parameters are not formatted correctly.

404 Response

Folder ID or collection name is not found.

Back to Top

Examples

The following example assigns the CollectionA metadata collection to the specified folder.

POST .../folders/F94131468853B4845E0508854EE870070A1AA68C3354/metadata/CollectionA

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
  "errorCode": "0",
  "idList": "F94131468853B4845E0508854EE870070A1AA68C3354",
  "type": "folder"
}

Example 2

The following example assigns the Personal.CollectionA metadata collection to the specified folder.

POST .../folders/F94131468853B4845E0508854EE870070A1AA68C3354/metadata/Personal.CollectionA

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
  "errorCode": "0",
  "idList": "F94131468853B4845E0508854EE870070A1AA68C3354",
  "type": "folder"
}

Example 3

The following example assigns a nonexistent metadata collection to the specified folder.

POST .../folders/F94131468853B4845E0508854EE870070A1AA68C3354/metadata/Personal.CollectionAB

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "errorCode": "-16",
    "errorKey": "!csUnableToSetMetadata!csMetaCollectionDoesntExist,Personal.CollectionAB",
    "errorMessage": "Unable to set metadata. Metadata Collection 'Personal.CollectionAB' is not defined.",
    "errorType": "folder",
    "idList": "F94131468853B4845E0508854EE870070A1AA68C3354",
    "title": "Unable to set metadata. Metadata Collection 'Personal.CollectionAB' is not defined.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 4

The following example attempts to assign a metadata collection to the specified folder using invalid characters in the name.

POST .../folders/F94131468853B4845E0508854EE870070A1AA68C3354/metadata/Personal.CollectionA,B

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "errorCode": "-96",
    "errorKey": "!csCollectionNameInvalidCharacters,Personal.CollectionA\\,B",
    "errorMessage": "Invalid characters in the collection name 'Personal.CollectionA,B'.",
    "title": "Invalid characters in the collection name 'Personal.CollectionA,B'.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Back to Top