Modifying object metadata

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

You use the HTTP POST method to change the metadata for existing objects in a namespace. The request changes only the metadata that it explicitly specifies. All other metadata remains unchanged.

You can modify metadata only for the current version of an object. You cannot modify metadata for an old version.

If the request to change metadata specifies a symbolic link, HCP changes the metadata on the object that’s the target of the link.

Access permission

To modify object metadata, you need write permission.

To specify a hold parameter, you also need privileged permission for the namespace.

To specify an owner parameter, you need change owner permission for the namespace.

Request header

POST /rest/directory/file HTTP/1.1

These considerations apply to requests to change object metadata:

  • You cannot change the hold and retention settings in the same request.
  • You cannot change the shred setting from true to false.
Parameter Required Description
directory Yes Folder name.
file Yes Name of the file, including file extension.
Content-Type No

Specifies the media type of the resource. This header sends a string along with the file to specify its format.

domain   Specifies the Active Directory domain that contains the user account specified by the owner query parameter.
hold No Places an object on hold or specifies that it's not on hold. Either true or false.
index No Specifies whether the object should be indexed for search. Either true or false.
label_hold No Specifies whether to place an object on labeled hold and if true, specifies a JSON format array containing pairs of one or more unique labeled hold IDs and an associated hold value.
id
Unique identifier string for the labeled hold. The maximum ID size is 64 characters.
hold
Specifies whether the object is on labeled hold using this id. Either true or false.

Example

label_hold=[{"id":"MY-HOLD-ID1","hold":true}, {"id":"MY-HOLD-ID2","hold":true}]
owner No

Specifies the user that owns the object.

One of:

  • The name of a user account that’s defined in HCP
  • The name of an AD user account that HCP recognizes. This can be either the user principal name or the Security Accounts Manager (SAM) account name for the AD user account.

    If you specify an AD user account, you also need to specify the domain parameter.

  • An empty string

    Specifying an empty string causes the object to have no owner.

retention No Specifies the retention setting for the object.
0 (zero) or Deletion Allowed
Allows the object to be deleted at any time. You can assign this value to an object only when you add it to the namespace or when its retention setting is -2.
The value -0 is equivalent to 0 (zero).
-1 or Deletion Prohibited
Prevents the object from being deleted and its retention setting from being changed. You can assign this value to an object that is not in a retention class at any time.
If an object is assigned to a retention class and that class is then deleted, the retention setting for that object changes to -1.
-2 or Initial Unspecified
Specifies that the object does not yet have a retention setting. You can assign this value to an object when you add the object to the namespace. You can also directly change the retention setting for an object from 0 to ‑2.
You can change ‑2 to any other retention setting.
datetime
Prevents the object from being deleted until the specified date and time. You can assign this value to an object that is not in a retention class if the specified date and time is later than the current retention setting for the object. You cannot assign it to an object for which the current retention setting is -1.
offset
Specifies a period for which to retain the object. You can assign this value to an object that is not in a retention class at any time, except when its current retention setting is -1.
HCP calculates the retention setting date and time from the offset and one of these:
  • The time the object was added to the namespace
  • The current retention setting
  • The current time
C+retention_class_name
Assigns the object to a retention class.
You can assign this value to an object if any one of these is true:
  • The original retention period for the object has expired.
  • The original retention period for the object has not expired, and the retention class results in a retention period that is longer than the current retention period.
  • The retention setting for the object is 0 or -2.
  • The retention setting for the object is -1, and the class has a retention setting of -1.
  • The object is in a retention class, and the duration of the new class is not shorter than the duration of the original class.
  • The retention class you assign must already be defined for the namespace.
shred No Specifies whether to shred the object after it is deleted. Either true or false.

Response headers

This operation does not return any request-specific response headers.

Status codes

The table below describes the HTTP status codes that have specific meaning for this request.

Code Meaning Description
200 OK HCP successfully updated the metadata.
400 Bad Request

One of:

  • The URL in the request is not well-formed.
  • The request is trying to change the retention setting from a retention class to an explicit setting, such as a datetime value.
  • The request is trying to change the retention setting and the retention hold setting at the same time.
  • The request is trying to change the retention setting for an object on hold.
  • The request is trying to change the shred setting from true to false.
  • The request is trying to change the owner of an object and specifies an invalid username or domain.
  • The request is trying to change the owner of an object to an AD user, but Active Directory authentication is not supported.
  • The request contains an unsupported query parameter or an invalid value for a query parameter.

If more information about the error is available, the response headers include the HCP product-specific X‑HCP-ErrorMessage header.

403 Forbidden

One of:

  • The Authorization header or hcp-ns-auth cookie specifies invalid credentials.
  • The namespace requires client authentication, and the request does not have an Authorization header or hcp-ns-auth cookie.
  • The user does not have write permission.
  • For a request to hold or release an object, the user does not have privileged permission.
  • For a request to change the owner of an object, the user does not have change owner permission.
  • The access method (HTTP or HTTPS) is disabled.
404 Not Found HCP could not find the specified object, or the URL path contains a symbolic link to a directory anywhere other than in the last component.

Example: Changing multiple metadata values for an existing object

Here is a sample HTTP POST request that makes the following changes to the metadata for the Q1_2020.ppt file:

  • Increases retention by one year from the current value
  • Turns on shredding on delete
  • Turns off indexing

Request with curl command line

curl -k -i -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -d "retention=R+1y" -d "shred=true" -d "index=false"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2020.ppt"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
theHeader = ["Transfer-Encoding: chunked"]
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d", theHeader])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/Q1_2020.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.POST, 1)
theFields = "retention=R+1y&shred=true&index=false"
theHeader = ["Transfer-Encoding: chunked"]
curl.setopt(pycurl.POSTFIELDS, theFields)

curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

POST /rest/quarterly_rpts/Q1_2020.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 37
Content-Type: application/x-www-form-urlencoded

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
Content-Length: 0