Content Gateway supports a feature called "Metadata transformation" it is to put simply a set of rules which will add custom metadata to every domain or bucket.
The feature is documented
here
https://connect.caringo.com/system/files/docs/s10/Gateway_Metadata_Transformation.html
and here
https://connect.caringo.com/system/files/docs/s10/Defined_ETC_Documents.html
The feature is used in conjunction with the management api + scsp on the content gateway and has been available since Gateway version 3.
Instructions
Using this method means that you can apply certain metadata to all objects in a domain or all objects in a bucket (depending on where the xform document is applied).
The xform document by itself is a json document which defines the custom metadata.
At its simplest the doc would look something 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 useful usecase may be to add a company id or tag for situations where multiple tenants share a cluster.
{
"metadata": {
"X-Company-Meta": "bluechip corp inc"
}
}
xform.json (END)
While assigning static metadata can be useful there are a few dynamic pieces of metadata you can assign also.
Variable Name | Description |
date:format | Create/update time stamp where format is defined by Java SimpleDateFormat specification |
user | Authenticated user ID |
domain | Domain name |
bucket | Bucket name |
As in the documented example below this can result in some very useful applications.
For example the json below
{ "comments": "Metadata transform document", "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}" }}Will result in the highlighted extra metadata on any file uploaded to the domain.
To use the feature first create the xform.json file with the definitions that your custom metadata will have as above and save it as xform.json or something similar.
The user you use to upload to the gateway must have the permissions on their policy to be able to PUT a policy or GET a policy.
the xform meta is an /etc document so we're going to upload it via the management api.
Anytime we're uploading to the managment api we use the /_admin/manage path
so for example if your gateway ip was 10.0.0.10 the url you'd start with would be
http://10.0.0.10/_admin/manage
And if cloud.example.com resolved to your gateway you would start with
http://cloud.example.com/_admin/manage/
So if we want to get to etc documents in a tenant it would be
http://cloud.example.com/_admin/manage/tenants/{tenantname}/etc/{insertyourjson}
This is described in this section of the docs
https://connect.caringo.com/system/files/docs/s10/Namespace_Structure.html
So as discussed earlier the application of the xform metadata doc is a http PUT . In the example below i use curl but anything that can do a http put should work.
curl -X PUT --data-binary @xformcorp.json -u tlokko -H "Content-Type: application/json" https://cloud.example.com/_admin/manage/tenants/cloud/domains/tlokko.cloud.example.com/etc/metaxform.json
So if we break the below down.
curl -X PUT
This is the http verb to put an object
--data-binary @xformcorp.json
This is reading the body of the xformcorp.json from a local file.
-u tlokko
this is the user i'm going to use to put the file.
-H "Content-Type: application/json"
This is a custom header for the file, very important. If the application/json content type isn't there gateway will fail to read the contents of the json correctly and writes to the gateway may fail.
https://cloud.example.com/_admin/manage/
management uri
https://cloud.example.com/_admin/manage/tenants/cloud/
base tenant
https://cloud.example.com/_admin/manage/tenants/cloud/domains/tlokko.cloud.example.com/
the domain we're applying it to
then the end filename.
if we wanted to be more selective and apply it at the bucket level we would go one level deeper
**important notes.
double and triple check the syntax of the json you are applying if you are applying a metadata transformation to a domain level object.
I recommend using a json validator when trying this stuff out https://jsonlint.com/ is a good one.
Be sure to add the "Content-Type: application/json" to the etc doc when uploading.
There is a precedence model in play here , any domain level xform.json will supersede a bucket level one.
Related articles