1. REST API for Content Management 1.1
  2. Tasks
  3. Metadata Collection

Create Metadata Collection

post

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

Create a named collection to store field values as strings. To create a global collection, you must log in as an administrator. A global collection can be used by all tenant users.

Before you can assign field values, you must assign the collection to a folder or file.

New:

User personal collections can be created by prefixing the collection name with Personal.. A personal collection will be visible and accessible only to the user who created it; therefore, no naming conflict will exist if two different users define their own personal collections using the same name.

Note:

Global collection names must be unique in the instance where the collection is defined, and you cannot change the collection name after it is created. For these reasons, consider implementing naming conventions if you plan to make extensive use of metadata collections.

Request

Supported Media Types
  • application/json
  • application/xml
Path Parameters
collectionName
Type: string
Required: true
Maximum Length: 240

Global collection names must be unique in the instance where the collection is defined and used. User personal collection names must start with Personal., such as Personal.MyCollection, to be user scoped.

Note:

You cannot change the name of a collection after you create it.

The following restrictions apply to collection and field names:

  • Collection and field names can't start or end with a space.
  • The combined length of the collection and field name can't exceed 240 characters.
  • Collection and file names aren't case-sensitive; that is, Field Name and field name are considered identical.

Don't use the following characters in collection or field names:

 / \ < > [ ] { } = $ %
 ' * " ? : # & ^ . , |

The following strings are also not allowed in collection or field names:

  • NUL
  • NULL
  • xSystem
  • xUser
  • xAF
  • dMetadataUnitID
  • dParentMetadataUnitID
  • dMetadataInheritLevel
  • dAssignedMetaCollection
  • dMetaCollection
  • dMetaCollections
  • dMetadataCollectionID
  • dMetadataID

Body Parameter
The request body defines details of the create metadata collection request.
Root Schema : CollectionCreateBody

Description of fields available to create a metadata collection.

Example application/json

{
    "fields":"FieldA,FieldB"
}

Response

Supported Media Types
  • application/json
  • application/xml
201 Response

The request was fulfilled.

Body

The response includes details on the created collection.

Root Schema : CollectionCreateResponse

The response includes details on the created collection.

Nested Schema : User
User information
400 Response

Request parameters are not formatted correctly.

A collection with that name already exists.

Examples

The following example creates a collection called CollectionA with two fields, A1 and A2. 

POST .../metadata/CollectionA

Request Header

None.

Request Body

{
    "fields": "A1,A2"
}

HTTP Status Code

HTTP_STATUS = 201

JSON Response

{
    "errorCode": "0"
}

Example 2

The following example creates a personal collection called Personal.CollectionA with two fields, A1 and A2. 

POST .../metadata/Personal.CollectionA

Request Header

None.

Request Body

{
    "fields": "A1,A2"
}

HTTP Status Code

HTTP_STATUS = 201

JSON Response

{
    "errorCode": "0"
}

Example 3

The following example attempts to create a collection using an already existing name.

POST .../metadata/CollectionA

Request Header

None.

Request Body

{
    "fields": "field1,field2"
}

HTTP Status Code

HTTP_STATUS = 409

JSON Response

{
    "errorCode": "-17",
    "errorKey": "!csUnableToCreateMetaColDef!csMetaDefinitionExists,CollectionA",
    "errorMessage": "Unable to create metadata collection definition. Metadata field definition 'CollectionA' is already defined.",
    "title": "Unable to create metadata collection definition. Metadata field definition 'CollectionA' is already defined.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 4

The following example attempts to create a collection using an invalid character in the name.

POST .../metadata/CollectionA,B

Request Header

None.

Request Body

{
    "fields": "field1,field2"
}

HTTP Status Code

HTTP_STATUS = 400

JSON Response

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