REST API for Documents

Edit Fields in a Metadata Collection

put

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

Edit field definitions or status in 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 the enable/disable status for fields in a metadata collection request.

Root Schema : CollectionFieldEditBody

Type: object

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

Show Source

fields(optional): string

Field names, separated by commas.
fieldsArray(optional): array fieldsArray

Can be used instead of fields and settings parameters if field definitions need to change in addition to or instead of enabling or disabling the fields.
settings(optional): string
Enable or disable metadata fields specified in fields.
Possible values are:
- enable
- disable

{
    "description":"The request body defines details of the enable/disable fields in a metadata collection request.",
    "properties":{
        "fields":{
            "type":"string",
            "description":"Field names, separated by commas."
        },
        "settings":{
            "type":"string",
            "description":"<p>Enable or disable metadata fields specified in fields.</p><p>Possible values are:<ul><li>enable</li><li>disable</li></ul></p>"
        },
        "fieldsArray":{
            "type":"array",
            "description":"Can be used instead of <code>fields</code> and <code>settings</code> parameters if field definitions need to change in addition to or instead of enabling or disabling the fields.",
            "items":{
                "type":"object",
                "properties":{
                    "fieldName":{
                        "type":"string",
                        "description":"Field names as described for <code>fields</code> input parameter."
                    },
                    "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>."
                    },
                    "isEnabled":{
                        "type":"boolean",
                        "description":"Enable (1) or disable (0) metadata field. Overrides <code>settings</code> value for this field."
                    }
                }
            }
        }
    }
}

Nested Schema : fieldsArray

Type: array

Can be used instead of fields and settings parameters if field definitions need to change in addition to or instead of enabling or disabling the fields.

Show Source

Array of: object items

{
    "type":"array",
    "description":"Can be used instead of <code>fields</code> and <code>settings</code> parameters if field definitions need to change in addition to or instead of enabling or disabling the fields.",
    "items":{
        "type":"object",
        "properties":{
            "fieldName":{
                "type":"string",
                "description":"Field names as described for <code>fields</code> input parameter."
            },
            "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>."
            },
            "isEnabled":{
                "type":"boolean",
                "description":"Enable (1) or disable (0) metadata field. Overrides <code>settings</code> value for this field."
            }
        }
    }
}

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.
isEnabled(optional): boolean

Enable (1) or disable (0) metadata field. Overrides settings value for this field.

{
    "type":"object",
    "properties":{
        "fieldName":{
            "type":"string",
            "description":"Field names as described for <code>fields</code> input parameter."
        },
        "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>."
        },
        "isEnabled":{
            "type":"boolean",
            "description":"Enable (1) or disable (0) metadata field. Overrides <code>settings</code> value for this field."
        }
    }
}

Example Request (application/json)

{
    "settings":"disable"
}

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 disables fields B1 and B2 in the CollectionB metadata collection.

PUT .../metadata/CollectionB/field

Request Header

None.

Request Body

{
    "fields": "B1,B2",
    "settings" : "disable"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0"
}

Example 2

The following example modifies the description of FieldB while enabling it and modifies the description of FieldC while disabling it in the Personal.CollectionA metadata collection.

PUT .../metadata/Personal.CollectionA/field

Request Header

None.

Request Body

{
    "fieldsArray":[
        {"fieldName":"FieldB", "fieldDescription":"Enabled Field B", "isEnabled":"1"},
        {"fieldName":"FieldC", "fieldDescription":"Disabled Field C", "isEnabled":"0"}
    ]
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0"
}

Example 3

The following example attempts to disable fields in a metadata collection using an invalid character in the name.

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

Request Header

None.

Request Body

{
    "fields": "A1,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"
}