Tag Controller

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

GET/v5/tag

Returns a (paginated) list of tags for the current customer

Request Parameters

Field	Type	Required	Description
from	integer	✗	Start number for this query. Defaults to 0
size	integer	✗	number of tags to return. Maximum is 10,000 tags (ES max). Defaults to 100

Response

Field	Type	Description
count	integer	If you send operation count, you retrieve the number of items.
hits	object	The actual results of the request
└ total	integer	number of total hits for the request
└ max_score	integer	Maximum score of a search request. Will be 0 for term search or get operation
└ hits	array	Search hits
└ _id	string	ES Document Id = id of the tag.
└ _score	float	Score for this hit
└ _version	integer	Version of this document
└ text	string	The uni version of the tag
└ _source	object	The tag document – Properties will follow
└ matched_queries	array	List of matched queries
└ matched_queries	array	List of matched queries
└ languagesToSearchIn	array	ISO2 language codes of languages we searched in.
suggest	array
└ _id	string	ES Document Id = id of the tag.
└ _score	float	Score for this hit
└ _version	integer	Version of this document
└ text	string	The uni version of the tag
└ _source	object	The tag document – Properties will follow
└ matched_queries	array	List of matched queries
suggest	array	Response for suggestions
took	integer	Time in ms the search request took

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.

Invalid API documentation data

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.

Invalid API documentation data

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.

GET/v5/tag/suggestTag/:tagId

Request Parameters

Field	Type	Required	Description
tagId	integer	✓	tagId to search related tags for

Response

Field	Type	Description
count	integer	If you send operation count, you retrieve the number of items.
hits	object	The actual results of the request
└ total	integer	number of total hits for the request
└ max_score	integer	Maximum score of a search request. Will be 0 for term search or get operation
└ hits	array	Search hits
└ _id	string	ES Document Id = id of the tag.
└ _score	float	Score for this hit
└ _version	integer	Version of this document
└ text	string	The uni version of the tag
└ _source	object	The tag document – Properties will follow
└ matched_queries	array	List of matched queries
└ matched_queries	array	List of matched queries
└ languagesToSearchIn	array	ISO2 language codes of languages we searched in.
suggest	array
└ _id	string	ES Document Id = id of the tag.
└ _score	float	Score for this hit
└ _version	integer	Version of this document
└ text	string	The uni version of the tag
└ _source	object	The tag document – Properties will follow
└ matched_queries	array	List of matched queries
suggest	array	Response for suggestions
took	integer	Time in ms the search request took

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

POST/v6/tag

Creates a new tag for the client linked to this user.

Request Parameters

Field	Type	Required	Description
backgroundColor	hexColor	✗	backgroundColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
flag	integer	✗	TESTMODE only – send valid flag (e.g. 10 for IPTC)
fontColor	hexColor	✗	fontColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
name	string	✓	name of the tag
parentId	integer	✗	ParentId for tagsonomy. If not set, defaults to null. Can only be used, if customer.individualConfiguration.tags.tagsEnabled is true
restoreDeleted	boolean	✗	If true, and user has IAM permission tag.restoreDeleted, a deleted tag with the same name will be restored
restoreMerged	boolean	✗	If true, and user has IAM permission tag.restoreMerged, a merged tag with the same name will be restored
settings	object	✗	Optional settings for this tag
└ lock	boolean	✗	Set to true to lock this tag
└ deletionProtection	boolean	✗	Set to true to activate deletion protection for this tag
translations	array	✗	Array of translations (objects) – see below

Response

Field	Type	Description
backgroundColor	hexColor	backgroundColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
creatorId	integer	Id of the user who created this tag
customerId	integer	DO NOT USE
flag	integer	TESTMODE only – send valid flag (e.g. 10 for IPTC)
fontColor	hexColor	fontColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
id	integer	Id of the tag
lastEditorId	integer	Id of the user who last edited this tag
name	string	name of the tag
name_da	string	name of the tag in da
name_de	string	name of the tag in de
name_en	string	name of the tag in en
name_es	string	name of the tag in es
name_fr	string	name of the tag in fr
name_nl	string	name of the tag in nl
name_sv	string	name of the tag in sv
parentId	integer	ParentId for tagsonomy. If not set, defaults to null. Can only be used, if customer.individualConfiguration.tags.tagsEnabled is true
settings	object	Settings for this tag
└ lock	boolean	If true, this tag is locked for editing
└ lockUser	integer	Id of the user who locked this tag
└ deletionProtection	boolean	If true, this tag has deletion protection enabled
└ deletionProtector	integer	Id of the user who enabled deletion protection
userId	integer	DO NOT USE

Update tags

Updates an existing tag. Updating a tag will automatically set its flag to 0.

PUT/v5/tag/:tagId

Updates an existing tag. Updating a flag will automatially set its flag to 0.

Request Parameters

Field	Type	Required	Description
backgroundColor	hexColor	✗	backgroundColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
flag	integer	✗	flag for this tag. Only allowed value is 0.
fontColor	hexColor	✗	fontColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
name	string	✗	name of the tag
parentId	integer	✗	ParentId for tagsonomy. If not set, defaults to null. Can only be used, if customer.individualConfiguration.tags.tagsEnabled is true
settings	object	✗	Optional settings for this tag
└ lock	boolean	✗	Set to true to lock this tag
└ deletionProtection	boolean	✗	Set to true to activate deletion protection for this tag
tagId	integer	✓	Id of the tag

Response

Field	Type	Description
backgroundColor	hexColor	backgroundColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
creatorId	integer	Id of the user who created this tag
customerId	integer	DO NOT USE
flag	integer	flag for this tag. Only allowed value is 0.
fontColor	hexColor	fontColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
id	integer	Id of the tag
lastEditorId	integer	Id of the user who last edited this tag
name	string	name of the tag
name_da	string	name of the tag in da
name_de	string	name of the tag in de
name_en	string	name of the tag in en
name_es	string	name of the tag in es
name_fr	string	name of the tag in fr
name_nl	string	name of the tag in nl
name_sv	string	name of the tag in sv
parentId	integer	ParentId for tagsonomy. If not set, defaults to null. Can only be used, if customer.individualConfiguration.tags.tagsEnabled is true
settings	object	Settings for this tag
└ lock	boolean	If true, this tag is locked for editing
└ lockUser	integer	Id of the user who locked this tag
└ deletionProtection	boolean	If true, this tag has deletion protection enabled
└ deletionProtector	integer	Id of the user who enabled deletion protection
userId	integer	DO NOT USE

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.

PUT/v5/tag/batchUpdate

Request Parameters

Field	Type	Required	Description
backgroundColor	hexColor	✗	backgroundColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
delete	boolean	✗	if set to true, the tags will be marked as deleted or removed from the tagCollectionId
fontColor	hexColor	✗	fontColor of the tag. Send as 6-digits hex value with a trailing dash (e.g. #ccff99)
forceOperation	boolean	✗	if set to true and combined with property delete, tags will be destroyed even if they have relations
ids	array	✓	ids of the tags for batch update.
merge	boolean	✗	if set to true, this batchJob is considered a merge job
parentId	integer	✗	Parent tag id for the given tags
settings	object	✗	Optional settings for this tag
└ lock	boolean	✗	Set to true to lock this tag
└ deletionProtection	boolean	✗	Set to true to activate deletion protection for this tag
tagCollectionId	integer	✗	tagCollectionId to add/remove tags to/from this tagCollectionId
targetTagId	integer	✗	required for merge jobs – this will be the target of the merge

Response

Field	Type	Description
jobId	string	JobId for this batch job

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.

DELETE/v5/tag/:tagId

Destroys an existing tag. If there are mediacontainers related to this tag (with flag 0), the response will contain those mediacontainers.

Request Parameters

Field	Type	Required	Description
flag	integer	✗	Only allowed value is 20. If not send, defaults to 1. See tag flag section for details on this property.
forceDelete	boolean	✗	if set to true, relations are ignored
forceDeleteTag	boolean	✗	if set to true, the tag and all relations will be permanently destroyed (not flagged) without further question
moveParentId	integer	✗	Required if you want to destroy a tag which is a parent. This is the new parentId for all tags with the tag to destroy as parent tag.
tagId	integer	✓	Id of the tag to destroy

Response

Field	Type	Description
id	integer	Id of the tag

Export tags

Exports tags into an XLSX file. Maximum size for exports are 10,000 tags.

GET/v5/tag/exportTags

Request Parameters

Field	Type	Required	Description
colors	boolean	✗	If true, colors are also exported
createdAfter	integer	✗	if set, only tags created after the given timestamp are exported
flag	integer	✗
ids	base64	✓	tag ids as base64 encoded array
languages	string	✗	comma-separated list of languages to export – defaults to customer's metadata languages
missingLanguage	string	✗	if set, only tags missing this language are exported

Response

Field	Type	Description
count	integer	If you send operation count, you retrieve the number of items.
hits	object	The actual results of the request
└ total	integer	number of total hits for the request
└ max_score	integer	Maximum score of a search request. Will be 0 for term search or get operation
└ hits	array	Search hits
└ _id	string	ES Document Id = id of the tag.
└ _score	float	Score for this hit
└ _version	integer	Version of this document
└ text	string	The uni version of the tag
└ _source	object	The tag document – Properties will follow
└ matched_queries	array	List of matched queries
└ matched_queries	array	List of matched queries
└ languagesToSearchIn	array	ISO2 language codes of languages we searched in.
suggest	array
└ _id	string	ES Document Id = id of the tag.
└ _score	float	Score for this hit
└ _version	integer	Version of this document
└ text	string	The uni version of the tag
└ _source	object	The tag document – Properties will follow
└ matched_queries	array	List of matched queries
suggest	array	Response for suggestions
took	integer	Time in ms the search request took

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.

Marks in database of imported tags

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.

API

Tag flags

Reference

Find tags

FindBatch tags

Search tags

Suggest tags

Create tags

Update tags

BatchUpdate tags

Destroy tags

Export tags

Import tags

Related Articles