1. REST API for Content Management 1.1
  2. Tasks
  3. Files

Assign a Metadata Collection to a File

post

/documents/api/1.1/files/{fileId}/metadata/{collectionName}

Associate an existing metadata collection with a specified file.

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

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

Request

Supported Media Types
  • application/json
  • application/xml
Path Parameters
collectionName
Type: string
Required: true
Name of the metadata collection to assign. For a user personal collection, it must start with Personal., such as Personal.MyCollection.
fileId
Type: string
Required: true

Globally unique identifier (GUID) for the file.

Response

Supported Media Types
  • application/json
  • application/xml
200 Response
The request was fulfilled.
Body
The response body includes information about the assign collection to a file operation.
Root Schema : FileCollectionResponse
The response body includes information about the assign collection to a file operation.
Example application/json

{
    "idList":"D3C1C1F319CFE6B102095C5DT0000000000100000001",
    "type":"file",
    "errorCode":"0"
}
400 Response
Request parameters are not formatted correctly.
403 Response
Forbidden if the user does not have read permission.
404 Response
File ID or collection name is not found.

Examples

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

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/metadata/CollectionA

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
  "errorCode": "0",
  "idList": "D3C1C1F319CFE6B102095C5DT0000000000100000001",
  "type": "file"
}

Example 2

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

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/metadata/Personal.CollectionA

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
  "errorCode": "0",
  "idList": "D3C1C1F319CFE6B102095C5DT0000000000100000001",
  "type": "file"
}

Example 3

The following example attempts to assign a nonexistent metadata collection to the specified file.

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/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.",    
    "type": "file"
    "idList": "D3C1C1F319CFE6B102095C5DT0000000000100000001",
    "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 file using invalid characters in the name.

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/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"
}