REST API for Documents

Edit Metadata Collection

put

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

Add or remove fields in a specified metadata collection.

Enable or disable a metadata collection.

Request

Supported Media Types

application/json
application/xml

Path Parameters

collectionName: string

Collection name. For a user personal collection, it must start with Personal., such as Personal.MyCollection.

The request body defines the details of edit fields or the enable/disable status in a metadata collection request.

Root Schema : CollectionEditBody

Type: object

Description of fields available to edit fields in a metadata collection request. There are no required attributes.

Show Source

addFields(optional): string
Add 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.
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
addFieldsArray(optional): array addFieldsArray

Can be used instead of addFields parameter if more granular control over added fields is desired. If both addFields and addFieldsArray are supplied, then the former will be ignored.
removeFields(optional): string

Specify the names of one or more fields to delete, separated by commas.
settings(optional): string
Enable or disable a metadata collection.
Possible values are:
- enable
- disable

{
    "description":"<p>Description of fields available to edit fields in a metadata collection request. There are no required attributes.</p>",
    "properties":{
        "addFields":{
            "type":"string",
            "description":"<p>Add 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. </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 file 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>"
        },
        "addFieldsArray":{
            "type":"array",
            "description":"Can be used instead of <code>addFields</code> parameter if more granular control over added fields is desired. If both <code>addFields</code> and <code>addFieldsArray</code> are supplied, then the former will be ignored.",
            "items":{
                "type":"object",
                "properties":{
                    "fieldName":{
                        "type":"string",
                        "description":"Field names as described for <code>addFields</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>."
                    }
                }
            }
        },
        "removeFields":{
            "type":"string",
            "description":"Specify the names of one or more fields to delete, separated by commas."
        },
        "settings":{
            "type":"string",
            "description":"<p>Enable or disable a metadata collection.</p><p>Possible values are:<ul><li>enable</li><li>disable</li></ul></p>"
        }
    }
}

Nested Schema : addFieldsArray

Type: array

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

Show Source

Array of: object items

{
    "type":"array",
    "description":"Can be used instead of <code>addFields</code> parameter if more granular control over added fields is desired. If both <code>addFields</code> and <code>addFieldsArray</code> are supplied, then the former will be ignored.",
    "items":{
        "type":"object",
        "properties":{
            "fieldName":{
                "type":"string",
                "description":"Field names as described for <code>addFields</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 addFields 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>addFields</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)

{
    "addFields":"FieldX,FieldY,FieldZ",
    "removeFields":"FieldA,FieldB",
    "settings":"enable"
}

Response

Supported Media Types

application/json
application/xml

200 Response

The request was fulfilled.

Root Schema : CollectionEditResponse

Type: object

The response body includes information about edit fields in a metadata collection operation.

Show Source

errorCode(optional): number

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

{
    "description":"The response body includes information about edit fields in a metadata collection operation.",
    "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 does not exist.

Examples

The following example adds two fields, B3 and B4, and removes field B2 from the CollectionB metadata collection. Also, it disables CollectionB.

PUT .../metadata/CollectionB

Request Header

None.

Request Body

{
    "addFields": "B3,B4",
    "removeFields": "B2"
    "settings" : "disable"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0"
}

Example 2

The following example adds two fields, FieldE and FieldF (with type, description and with or without default value), and removes field FieldA from the Personal.CollectionA metadata collection. Also, it disables Personal.CollectionA.

PUT .../metadata/Personal.CollectionA

Request Header

None.

Request Body

{
    "addFieldsArray":[
        {"fieldName":"FieldE", "fieldType":"text", "fieldDescription":"Field E"},
        {"fieldName":"FieldF", "fieldType":"number", "fieldDescription":"Field F", "defaultValue":345}
    ],
    "removeFields": "FieldA",
    "settings" : "disable"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0"
}

Example 3

The following example attempts to edit the definition of a collection that does not exist.

PUT .../metadata/Personal.CollectionAB

Request Header

None.

Request Body

{
    "addFields": "A3,A4",
    "removeFields": "A2"
    "settings" : "disable"
}

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "errorCode": "-16",
    "errorKey": "!csUnableToEditMetaColDef!csMetaCollectionDoesntExist,Personal.CollectionAB",
    "errorMessage": "Unable to edit metadata collection definition. Metadata Collection 'Personal.CollectionAB' is not defined.",
    "title": "Unable to edit metadata collection definition. Metadata Collection 'Personal.CollectionAB' is not defined.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 4

The following example attempts to edit the definition of a collection using invalid characters in the name.

PUT .../metadata/Personal.CollectionA,B

Request Header

None.

Request Body

{
    "addFields": "A3,A4",
    "removeFields": "A2"
    "settings" : "disable"
}

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