REST API for Documents

Create Metadata Collection

post

/documents/api/1.2/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: string
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

The request body defines details of the create metadata collection request.

Root Schema : CollectionCreateBody

Type: object

Description of fields available to create a metadata collection.

Show Source

fields: string
Maximum Length: 240
One or more field names separated by commas. You can add and remove fields after the collection is created. Field names must be unique within the collection. All fields will be of type text.
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 field 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
fieldsArray(optional): array fieldsArray

Can be used instead of fields parameter if more granular control over created fields is desired. If both fields and fieldsArray are supplied, then the former will be ignored.

{
    "description":"<p>Description of fields available to create a metadata collection.</p>",
    "required":[
        "fields"
    ],
    "properties":{
        "fields":{
            "type":"string",
            "description":"<p>One or more field names separated by commas. You can add and remove fields after the collection is created. Field names must be unique within the collection. All fields will be of type <code>text</code>.</p><p>The following restrictions apply to collection and field names:<ul><li>Collection and field names can&#39;t start or end with a space.</li><li>The combined length of the collection and field name can&#39;t exceed 240 characters.</li><li>Collection and field names aren&#39;t case-sensitive; that is, <code>Field Name</code> and <code>field name</code> are considered identical.</li></ul></p><p>Don&#39;t use the following characters in collection or field names:</p><p><table> <tr><td>&nbsp;&#47;</td><td>&nbsp;&#92;</td><td>&nbsp;&#60;</td><td>&nbsp;&#62;</td><td>&nbsp;&#91;</td><td>&nbsp;&#93;</td><td>&nbsp;&#123;</td><td>&nbsp;&#125;</td><td>&nbsp;&#61;</td><td>&nbsp;$</td><td>&nbsp;%</td></tr><tr><td>&nbsp;&#39;</td><td>&nbsp;&#42;</td><td>&nbsp;&#34;</td><td>&nbsp;&#63;</td><td>&nbsp;&#58;</td><td>&nbsp;&#35;</td><td>&nbsp;&#38;</td><td>&nbsp;&#94;</td><td>&nbsp;&#46;</td><td>&nbsp;&#44;</td><td>&nbsp;&#124;</td></tr></table></p><p>The following strings are also not allowed in collection or field names:</p></p><ul><li>NUL</li><li>NULL</li><li>xSystem</li><li>xUser</li><li>xAF</li><li>dMetadataUnitID</li><li>dParentMetadataUnitID</li><li>dMetadataInheritLevel</li><li>dAssignedMetaCollection</li><li>dMetaCollection</li><li>dMetaCollections</li><li>dMetadataCollectionID</li><li>dMetadataID</li></ul></p>",
            "maxLength":240
        },
        "fieldsArray":{
            "type":"array",
            "description":"Can be used instead of <code>fields</code> parameter if more granular control over created fields is desired. If both <code>fields</code> and <code>fieldsArray</code> are supplied, then the former will be ignored.",
            "items":{
                "type":"object",
                "properties":{
                    "fieldName":{
                        "type":"string",
                        "description":"Field names as described for <code>fields</code> input parameter."
                    },
                    "fieldType":{
                        "type":"string",
                        "description":"<p>Type of the field.</p> <p>Possible values are:<ul><li>text (default)</li><li>number</li><li>date</li><li>boolean</li></ul></p>"
                    },
                    "fieldDescription":{
                        "type":"string",
                        "description":"Description of the field."
                    },
                    "defaultValue":{
                        "type":"string",
                        "description":"Default value of the field. If the <code>fieldType</code> is <code>date</code>, the value should be in the <code>yyyy-mm-ddThh:mm:ss</code> form. For <code>boolean</code> types, valid values should be (1) for <code>true</code> and (0) for <code>false</code>."
                    }
                }
            }
        }
    }
}

Nested Schema : fieldsArray

Type: array

Can be used instead of fields parameter if more granular control over created fields is desired. If both fields and fieldsArray are supplied, then the former will be ignored.

Show Source

Array of: object items

{
    "type":"array",
    "description":"Can be used instead of <code>fields</code> parameter if more granular control over created fields is desired. If both <code>fields</code> and <code>fieldsArray</code> are supplied, then the former will be ignored.",
    "items":{
        "type":"object",
        "properties":{
            "fieldName":{
                "type":"string",
                "description":"Field names as described for <code>fields</code> input parameter."
            },
            "fieldType":{
                "type":"string",
                "description":"<p>Type of the field.</p> <p>Possible values are:<ul><li>text (default)</li><li>number</li><li>date</li><li>boolean</li></ul></p>"
            },
            "fieldDescription":{
                "type":"string",
                "description":"Description of the field."
            },
            "defaultValue":{
                "type":"string",
                "description":"Default value of the field. If the <code>fieldType</code> is <code>date</code>, the value should be in the <code>yyyy-mm-ddThh:mm:ss</code> form. For <code>boolean</code> types, valid values should be (1) for <code>true</code> and (0) for <code>false</code>."
            }
        }
    }
}

Nested Schema : items

Type: object

Show Source

defaultValue(optional): string

Default value of the field. If the fieldType is date, the value should be in the yyyy-mm-ddThh:mm:ss form. For boolean types, valid values should be (1) for true and (0) for false.
fieldDescription(optional): string

Description of the field.
fieldName(optional): string

Field names as described for fields input parameter.
fieldType(optional): string
Type of the field.

Possible values are:
- text (default)
- number
- date
- boolean

{
    "type":"object",
    "properties":{
        "fieldName":{
            "type":"string",
            "description":"Field names as described for <code>fields</code> input parameter."
        },
        "fieldType":{
            "type":"string",
            "description":"<p>Type of the field.</p> <p>Possible values are:<ul><li>text (default)</li><li>number</li><li>date</li><li>boolean</li></ul></p>"
        },
        "fieldDescription":{
            "type":"string",
            "description":"Description of the field."
        },
        "defaultValue":{
            "type":"string",
            "description":"Default value of the field. If the <code>fieldType</code> is <code>date</code>, the value should be in the <code>yyyy-mm-ddThh:mm:ss</code> form. For <code>boolean</code> types, valid values should be (1) for <code>true</code> and (0) for <code>false</code>."
        }
    }
}

Example Request (application/json)

{
    "fields":"FieldA,FieldB"
}

Response

Supported Media Types

application/json
application/xml

201 Response

The request was fulfilled.

Root Schema : CollectionCreateResponse

Type: object

Description of fields available in the create metadata collection response.

Show Source

errorCode(optional): number

An error code of zero (0) indicates no errors.

{
    "description":"<p>Description of fields available in the create metadata collection response.</p>",
    "properties":{
        "errorCode":{
            "type":"number",
            "description":"An error code of zero (0) indicates no errors."
        }
    }
}

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 = 200

JSON Response

{
    "errorCode": "0"
}

Example 2

The following example creates a personal collection called Personal.CollectionA with multiple fields of different types with descriptions and default values.

POST .../metadata/Personal.CollectionA

Request Header

None.

Request Body

{
    "fieldsArray":[
        {"fieldName":"FieldA", "fieldType":"text", "fieldDescription":"Field A", "defaultValue":"Hello world"},
        {"fieldName":"FieldB", "fieldType":"number", "fieldDescription":"Field B", "defaultValue":123},
        {"fieldName":"FieldC", "fieldType":"date", "fieldDescription":"Field C", "defaultValue":"2020-02-20T11:12:13"},
        {"fieldName":"FieldD", "fieldType":"boolean", "fieldDescription":"Field D", "defaultValue":1}
    ]
}

HTTP Status

HTTP_STATUS = 200

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

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"
}