Third Light Developer Exchange

mdyason

Member

Registered: 2015-01-20

Posts: 43

Set Metadata on a file

The API reference says the values field is "a hash mapping metadata fields to arrays of values that you would like the fields set to".  What does this look like?

Can anybody tell me please what is wrong with the following:

POST /api.json.tlx HTTP/1.1
Host: imstest.matrix-solutions.com
Content-Type: application/json

{"apiVersion": "1.0.1", 
"sessionId": "QfxxuQfEt8EktXdX8CF6Gq9Q9D2GlWeP", 
"action": "metadata.SetMetaData", "inParams": {"itemId": "28238339525", 
                                                "type": "FILE", 
                                                "values": {"caption":"NiceSunset", 
                                                            "siteCode":"1234", 
                                                            "wildlifeSpeciesName":"Bear"}}}

{"result":{"api":"OK","action":"MALFORMED_INPUT"},"outParams":"caption"}

the problem is not with "caption" specifically, because if I simply remove the caption parameter I then get
{"result":{"api":"OK","action":"MALFORMED_INPUT"},"outParams":"siteCode"}

Last edited by mdyason (2015-03-03 20:10:39)

dominic

Third Light Staff

Registered: 2013-06-06

Posts: 119

Re: Set Metadata on a file

Hi,

The metadata should be a hash of tag to an array of values - so, for example, it would be

"values": {"caption":["NiceSunset"]}

This is in order to maintain a consistent signature between fields like caption (single-values) and keywords (multi-valued).

Kind regards,

Dominic

mdyason

Member

Registered: 2015-01-20

Posts: 43

Re: Set Metadata on a file

Oh - thank you.  That makes sense!
2 more questions on this topic please.

I sent the following request:

POST /api.json.tlx HTTP/1.1
Host: imstest.matrix-solutions.com
Content-Type: application/json

{"apiVersion": "1.0.1", 
"sessionId": "hBSdbaaEl7flshqH-wGwTqA-VaddJ1,D", 
"action": "metadata.SetMetaData", "inParams": {"itemId": "28238339525", 
                                                                      "type": "FILE", 
                                                                      "values": {"caption":["Nice Sunset"], 
                                                                                       "siteCode":["1234"] 
                                                           }}}

the result was:
{"result":{"api":"OK","action":"OK"},"outParams":{"caption":[{"local":{"lastchanged":[1425416206],"uploaddate":[1425065930],"importdate":[1425065961]},"inherited":[],"overridden":[],"unused":[]}],"siteCode":["1234"]}}
However the metadata for the particular file did not get set.
Am I still doing this wrong?

Also if the metadata being referenced is a set of controlled keywords - as for Wildlife Species Code, how would I display the actual array?
For instance I tried:

POST /api.json.tlx HTTP/1.1
Host: imstest.matrix-solutions.com
Content-Type: application/json

{"apiVersion": "1.0.1", 
"sessionId": "hBSdbaaEl7flshqH-wGwTqA-VaddJ1,D", 
"action": "metadata.SetMetaData", "inParams": {"itemId": "28238339525", 
                                                "type": "FILE", 
                                                "values": {"caption":["Nice Sunset"], 
                                                            "siteCode":["1234"], 
                                                            "wildlifeSpeciesName":["Bear"]}}}

but the result was:
{"result":{"api":"OK","action":"FIELD_NOT_FOUND"},"outParams":"wildlifeSpeciesName"}

The metadata name shows in the application with spaces in it and I read somewhere to use camelcase.

Last edited by mdyason (2015-03-04 00:36:13)

dominic

Third Light Staff

Registered: 2013-06-06

Posts: 119

Re: Set Metadata on a file

When a metadata field is created, the default is for the key to be a camel-cased version of the initial display name - however this can be edited, and it would not automatically follow subsequent changes. Have a look at the field mappings on the edit metadata page inside IMS to see how the field is configured.

mdyason

Member

Registered: 2015-01-20

Posts: 43

Re: Set Metadata on a file

Ok - looked at Metadata Access mapping for a group as well as editing of metadata for the image as well as metadata editing for a folder.  They are all the same - the names are "Caption", "Wildlife Species Name" and "Site Code".  So if I turn these into camel case, I get "caption", "wildlifeSpeciesName" and "siteCode" as used above.  Still getting the same errors and metadata is not being set.  (Used as above with both the option to not include wildlifeSpeciesCode (the array) and to include it.
There are 2 questions in my previous post:
1.  What am I doing wrong in the first option?
2.  If the metadata being referenced is a set of controlled keywords - as for Wildlife Species Code, how would I create the actual array?

I also have a third (and forth) question.  I am really having trouble deciding exactly what the HTTP should look like for files.UpdateMetaData.  My first stab without a piece of metadata that is itself an array is as in the code box below.  It would be greatly appreciated if you would give actual pure http examples in your API reference.

{"apiVersion": "1.0.1", 
"sessionId": "nj7fwEnKW0RCFmUGV2sGozQqVMzUw-Wk", 
"action": "Files.UpdateMetaData", 
"inParams": {"assetId": "28238339525", 
               "metadataTags": {["caption"],["siteCode"]}
               "metadata": {"caption":["Nice Sunset"], 
                            "siteCode":["1234"]}
            }
}

3.  This is obviously wrong - what should it be? 
4.  If there is a piece of metadata that is itself an array (choice from a list) what would that look like (Like wildlifeSpeciesCode in my 2nd question above)

Last edited by mdyason (2015-03-10 20:42:50)

dominic

Third Light Staff

Registered: 2013-06-06

Posts: 119

Re: Set Metadata on a file

Hi,

The key thing to note is that you cannot infer the metadata tag name from the display name of the metadata: you need to refer to Configuration -> Metadata -> Customise Metadata and look at the 'Mappings' tab for the field in question. In the specific case, I believe that 'Wildlife Species Name' is actually 'speciesName'.

If you want to configure the available options for controlled keywords, you should use Metadata.AddToControlledVocab / Metadata.SetControlledVocab and related methods.

Dominic

dominic

Third Light Staff

Registered: 2013-06-06

Posts: 119

Re: Set Metadata on a file

Continuing to refer to Metadata.SetMetaData: the issue that I overlooked before is that the data should be supplied as an array of hashes as follows:

{"apiVersion": "1.0.1", 
"sessionId": "hBSdbaaEl7flshqH-wGwTqA-VaddJ1,D", 
"action": "metadata.SetMetaData", "inParams": {"itemId": "28238339525", 
                                                                      "type": "FILE", 
                                                                      "values": {"caption":[{"value":"Nice Sunset"}]}
}}

These hashes also support the keys 'inherit' and 'override', which are used to control the inheritance of metadata from folders.