Well-defined tagging helps to quickly locate and aggregate mediacontainers. Tags are more flexible than folders but can be used as folders.
Tags can be added to mediacontainers manually. But tags can also be added automatically through object detection or by extracting IPTC keywords.
Tags can also be automatically translated (this is especially helpful for object detection, which returns tags exclusively in English).
For tag translations see TagLanguage Controller (TODO: Link)
Tag flags
Tags can have a flag, that tells you something about the state of the tag:
- flag 0 -> this tag is active and has been added or updated by a human
- flag 10 -> this tag is active but has been added by a machine (e.g. object detection, IPTC keywords, etc)
- flag 1 -> this tag is in trash
- flag 20 -> this tag has been permanently deleted. Even if object detection, etc tries to add it again, it will not succeed.
Make a suggested tag (flag 10) a real tag (flag 0)
AdmiralCloud collects tags from different sources (e.g. IPTC data, object detection, etc). All discovered tags are added to the customer’s tag catalog with flag 10 (suggested tags). If you want to “accept” the tag as real tag, the flag is set to 0. Mediacontainer-to-tag relations are not affected by this change.
Another way to make a suggested tag a real tag is by accepting a suggested tag for a mediacontainer as humanly assigned tag. This operation will update the tag to flag 0.
Reference
Find tags
Returns a (paginated) list of tags for the current customer
FindBatch tags
Returns the tags for the requested ids using ES _mget method. The result will have structure similar to tag.find and tag.search.
Search tags
Search for tags – similar to Mediacontainer search. You can either search with a searchTerm or create complete ES search queries. You can use a special field name “similarColor”.
If you use this call for the suggester, keep in mind, that you can not combine it with query or searchTerm and that only “flags” can be used as parameter.
Examples
// Find missing translations for English
// v5/tag/search
{
"query": {
"bool": {
"must_not": {
"exists": {
"field": "name_en"
}
},
"filter": [
{
"term": {
"customerId": 147
}
}
]
}
}
}
Suggest tags
Returns up to 10 tags related to the given one. The returned tags are often used together with the given one.
Create tags
Creates a new tag. If the tag exists an error message is returned. If you try to create a tag (with flag 0) that already exists (with flag 10), no new tag is created but the old one is updated (to flag 0).
Update tags
Updates an existing tag. Updating a tag will automatically set its flag to 0.
BatchUpdate tags
Batch updates tags
Returns a jobId which can be used to fetch the result after activity’s progress is 100%. Please see Activity Controller for details.
Destroy tags
Destroys an existing tag. If there are mediacontainers related to this tag (with flag 0), the response will contain those mediacontainers.
If the tag is a parent tag to any other tags, you have to provide a new parent tag (moveParentId) for those in order to destroy this tag.
Destroying a tag can mean
- mark as deleted (flag 1) but re-activate if a user or the transcoder is trying to create it again. MediaContainerToTag relations are updated to flag 1 (invisible) but not get lost – on reactivation those relations will be available again.
- mark as deleted (flag 20) but never show again. The tag can only be reactivated again by updating the flag back to 0. Otherwise you will receive an error message when trying to create it again. MediaContainerToTag relations are deleted – they cannot be re-activated or restored in any way.
- send forceDelete = true to finally destroy the tag and all relations, loosing the above information.
Export tags
Exports tags into an XLSX file. Maximum size for exports are 10,000 tags.
Import tags
In order to import tags a valid XLSX file is required. This file needs to be uploaded according to the steps laid out below
XLS File Structure
The XLS oder XLSX file must have the field names in the first row – one per column. At least “tag” is required, with tag being the uni name of the tag. If you want to update existing tags, make sure to also use “id”.
You can optionally add language codes like “de”, “en”, etc as well as “fontcolor” and “backgroundcolor”. The order of the fields is not relevant – the only requirement is that they are in the first row!
Now each following row holds the actual data. Again, “tag” is mandatory.
Fontcolor and backgroundcolor must be hex values (e.g. #ff9900), otherwise they will be ignored.
If a an id id is given and valid, the existing tag will be overwritten with the new data. If no id is given, a new tag is created.
Uploading the import file
Step 1: Create mediaContainer of type “importedTags” and with flag 50
Step 2: Create a media element for the new mediaContainer with type “document”, usage: “tagImport” and source “user”
Step 3: Upload a media file as usual and make sure to call s3/success at the end of this process. This will trigger the actual import – a job of type “importTags” is created and can be fetched via activities.find.
Additionally the s3/success call returns a jobId. With the batchResult call you can get the status of your tag import.
Importing tags without existing tag.ids will make the API create new entries in the tag table with flag: 11 and settings {“origin”: “tagImport”}.
Importing tags with existing tag.ids will make the API update the existing tags and leave the flag (flag: 0 stays flag: 0) untouched but settings {“origin”: “tagImport”} is set. Please be aware that a not
existing tag.id will cancel the import of the list from that tag.id. Further tags will not be imported.