Tags

Tags are a way of categorizing or grouping various objects (for search and organization) in the Tidal Automation (TA) eco-system. Tagging objects allows the ability to search for objects using those specific tags. The potential uses of these are to setup visualization representations of categories of objects using tags.

Tagging is supported for the “Job definition” object in the TA system.

Typical Operations:

  • Enabling a tag will make it active.

  • Copying a parent tag will copy its child hierarchy.

  • Deleting a parent tag is possible only if none of its child tags are referenced (mapped) in other objects.

  • Disabling a parent tag, disables its entire child hierarchy.

  • Disabling a tag does not remove its previous tag mappings to the job definitions.

  • Assigning a disabled tag to one or more job definitions, displays an error message.

    All API calls related to assignment or removal of tags are checked for the user security rights prior to performing those operations.

Tag Examples

From the browser, issue and click Manual Commands (Post). Test the REST API examples from the Client Manager API post screen that appears. Likewise, error messages and exceptions are displayed for invalid parameters and unsuccessful execution of a request.

Create a Tag

The tag object provides a method called create. This REST API call allows a user to create a tag.

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Tag.create xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tes:Tag>
<tes:name>Completed_JR</tes:name>
<tes:ownerid>2</tes:ownerid>
<tes:active>Y</tes:active>
<tes:pub>Y</tes:pub>
<tes:type>1</tes:type>
<tes:clientcontext>client-context-1</tes:clientcontext>
</tes:Tag>
</tes:Tag.create>
</entry>

These fields are required to create a tag:

  • Name, Owner ID, Type, Public and Active are the required fields.

  • Parent ID, if provided has to be a valid, existing tag ID that is not deleted.

Currently only 1 (Navigation) and 2 (Filter) are the available options for the Tag type. Additional types will be added in future releases.

Update a Tag

The tag object provides a method called update. A valid tag id should be provided to update a tag. This REST API call allows a user to update a tag.

<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Tag.update xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tes:id>414</tes:id>
<tes:name>Completed_JR</tes:name>
<tes:active>Y</tes:active>
<tes:description>test</tes:description>
<tes:ownerid>2</tes:ownerid>
<tes:pub>Y</tes:pub>
<tes:type>1</tes:type>
<tes:parentid>415</tes:parentid>
<tes:clientcontext>client-context-1</tes:clientcontext>
</tes:Tag.update>
</entry>

Note: The ID is the required field, and the conditions for parent id and the tag type are as same as the conditions applicable for the fields required to create a tag.

Note: The Parent ID, if provided has to be a valid, existing tag ID that is not deleted. If the Parent ID field is provided, a circular reference check will be performed to ensure that the parent does not point to its child tag.

Assign a Tag to a Job

The tag object provides a method called assigntagstojob. This REST API call allows a user to assign one or more tags to one or more job definition objects.

<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Tag.assigntagstojob xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tags>Tag</tags>
<dataAlias>job alias 1, job alias 2</dataAlias>
<tableId>13</tableId>
</tes:Tag.assigntagstojob>
</entry>

These fields are required to assign a tag to a job:

  • Tag names should be provided as comma-separated string, and should reference a valid existing tag that is not deleted or disabled.

  • Job Alias should be provided as comma-separated string, and should reference a valid existing job that is not deleted.

  • Table Id will be 13 (for job definition).

This API call is additive in nature, which means that each tag name provided will be an additional mapping to the job alias.

Remove a Tag from a Job

The tag object provides a method called removetagsfromjob. This REST API call allows a user to remove one or more tags from one or more job definition object.

<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Tag.removetagsfromjob xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tags>Tag 1, Tag 2</tags>
<dataAlias>job alias 1, job alias 2</dataAlias>
<tableId>13</tableId>
</tes:Tag.removetagsfromjob>
</entry>

These fields are required to remove a tag from a job:

  • Tag names should be provided as comma-separated string and should reference a valid existing tag that is not deleted or disabled.

  • Job Alias should be provided as comma-separated string and should reference a valid existing job that is not deleted.

  • Table Id will be 13 (for job definition).

This API call is subtractive in nature, which means that each tag name provided will be removed from the tag mapping to the job alias.

Replace a Tag Mapping from a Job

The tag object provides a method called replacetagsforjob. This REST API call allows a user to delete all the existing tag mappings for a job and replace it with new mappings.

<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Tag.replacetagsforjob xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<tags>Tag 1, Tag 2</tags>
<dataAlias>job alias 1, job alias 2</dataAlias>
<tableId>13</tableId>
</tes:Tag.replacetagsforjob>
</entry>

These fields are required to replace a tag mapping from a job:

  • Tag names should be provided as comma-separated string, and should reference a valid existing tag that is not deleted or disabled.

  • Job Alias should be provided as comma-separated string, and should reference a valid existing job that is not deleted.

  • Table Id will be 13 (for job definition).

    This API call provides the ability to remove and replace all the existing tag mappings for one or more job aliases.

Get Child Tags

The tag object provides a method called getChildTags. This REST API call allows a user to retrieve the child tag ids in the child hierarchy for the specified tag.

<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Tag.getChildTags xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<id>1</id>
</tes:Tag.getChildTags>
</entry>

Note: The Tag ID field is required. If provided has to be a valid, existing tag ID that is not deleted.

Remove Tag Mappings for a Job

The tag object provides a method called Tag.removetagmappingsforjob. This REST API call allows a user to remove all tag mappings from one or many job definitions irrespective of the tag type.

<?xml version="1.0" encoding="UTF-8" ?>
<entry xmlns="http://purl.org/atom/ns#">
<tes:Tag.removetagmappingsforjob xmlns:tes="http://www.tidalsoftware.com/client/tesservlet">
<dataAlias>jobalias1, jobalias2</dataAlias>
<tableId>13</tableId>
</tes:Tag.removetagmappingsforjob>
</entry>

These fields are required to remove a tag mappings for a job:

  • Job Alias should be provided as comma-separated string and should reference a valid existing job that is not deleted.

  • Table Id will be 13 (for job definition).