Modifying object metadata

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.
ParameterRequiredDescription
directoryYesFolder name.
fileYesName of the file, including file extension.
domainSpecifies the Active Directory domain that contains the user account specified by the owner query parameter.
holdNoPlaces an object on hold or specifies that it's not on hold. Either true or false.
indexNoSpecifies whether the object should be indexed for search. Either true or false.
label-holdNoSpecifies 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

x-hcp-labelretentionhold [{"id":"UniqueLabelHold-1","hold":true}, {"id":"UniqueLabelHold-2","hold":true}]
ownerNo

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.

retentionNoSpecifies 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.

shredNoSpecifies 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.

Return codes

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

CodeMeaningDescription
200OKHCP successfully updated the metadata.
400Bad 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.

403Forbidden

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.
404Not FoundHCP 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