How to apply XForm metadata transformations

Content Gateway supports "metadata transformation", which is a set of rules that adds custom metadata to every object in a domain or bucket.

The feature is documented here:

The feature is used in conjunction with the Management API and SCSP on the Content Gateway, and has been available since Gateway version 3.

Designing the metadata

Use XForm documents when you need to apply certain metadata to all objects in a domain or a bucket (depending on where you apply them).

The XForm document itself is a JSON document that defines the custom metadata. At its simplest, the document would look like this.

	"metadata": {
		"X-Color-Meta": "blue"
xform.json (END)

This form would apply the metadata X-Color-Meta : blue to every file uploaded to a bucket or domain.

A more practical use case would be to add a company identifier or tag for situations where multiple tenants share a cluster.

	"metadata": {
		"X-Company-Meta": "MetaCorp, Inc."
xform.json (END)

While assigning static metadata, you can make use of several variables:

Variable Name



Create/update time stamp where format is defined by Java SimpleDateFormat specification


Authenticated user ID


Domain name


Bucket name

Using these can result in very useful applications. For example:

	"metadata": {
		"X-Written-When-Meta": "${date:yyyyMMdd-HHmmss}",
		"X-Contains-Meta": "${domain}/${bucket}",
		"X-Copyright-Meta": "Copyright ${date:yyyy}, MetaCorp, Inc",
		"X-Author-Meta": "${user}"

This JSON causes any file uploaded to the domain to have the additional metadata highlighted below: 

Installing the XForm

To use the feature, upload your XForm document with the correct method and headers:

  1. Create the XForm file with the definitions for your custom metadata, described above.
  2. Important: Validate the syntax of the JSON you are applying. Use a JSON validator such as
  3. Save it as xform.json or similar.
  4. Verify that the user that will upload to the Gateway has the permissions on their policy to be able to PUT a policy or GET a policy.
  5. The XForm is an /etc document, which you upload via the management API using the /_admin/manage path:
    • If your Gateway IP is, the starting URL is
    • If your Gateway resolves from, the starting URL is
  6. To etc documents in a tenant, use this form (see Namespace Structure):
  7. The application of the XForm metadata doc is a HTTP PUT, shown here as cURL:

    curl -X PUT --data-binary @xformcorp.json -u tlokko -H "Content-Type: application/json"


curl -X PUTThe HTTP verb to PUT an object
--data-binary @xformcorp.jsonSpecifies reading the body of the xformcorp.json from a local file
-u tlokkoSpecifies the user that will PUT the file (must have that policy permission)
-H "Content-Type: application/json"

Required: This is a custom header for the file, and it is very important: If this content type isn't there, Gateway will fail to read the contents of the JSON correctly and writes to the Gateway may fail. Management API URI
...tenants/cloud/The base tenant domain we're applying it to end filename

Applies it only at the bucket level


Any domain-level XForm will supersede a bucket-level XForm.

© DataCore Software Corporation. · · All rights reserved.