TagDefinition

Supported Calls

delete(), describeSObjects(), query(), retrieve(), search(), undelete(), update()

Fields

Field	Field Type	Field Properties	Description
Name	string	Filter Nillable Update	Identifies the tag word or phrase.
Type	picklist	Filter Nillable Restricted picklist	Defines the visibility of a tag. Possible value are: Public: The tag can be viewed and manipulated between all users in an organization Personal: The tag can be viewed or manipulated only by a user with a matching OwnerId

Field

Field Type

Field Properties

Description

Name

string

Filter

Nillable

Update

Identifies the tag word or phrase.

Type

picklist

Filter

Nillable

Restricted picklist

Defines the visibility of a tag. Possible value are:

Public: The tag can be viewed and manipulated between all users in an organization
Personal: The tag can be viewed or manipulated only by a user with a matching OwnerId

Usage

When you create a tag for a record, an association is created with to a corresponding TagDefinition:

If the value in the tag's Name field is new, a new TagDefinition record is automatically created and becomes the parent of the tag.
If the value in the tag's Name field already exists in a TagDefinition, that TagDefinition automatically becomes the parent of the tag.

Each TagDefinition record has a one-to-many relationship with its child tag records.

The following standard objects represent tags for records:

Custom objects may also be tagged. Tags for custom objects are identified by a suffix of two underscores immediately followed by the word tag. For example, a custom object named Meeting has a corresponding tag named Meeting__tag in that organization’s WSDL. Meeting__tag is only valid for Meeting objects.

TagDefinition is useful for mass operations on any tag record. For instance, if you want to rename existing tags, you can search for the appropriate TagDefinition object, update it, and the child tag's Name values are also changed. The following Java example replaces all WC tags with the phrase West Coast:

public void tagDefinitionSample() {
    QueryResult qr = null;
    try {
        qr = binding.query("SELECT Id, Name FROM TagDefinition WHERE Name = 'WC'");
    } catch (RemoteException e) {
        System.out.println("An unexpected error has occurred." + e.getMessage());
    }
    TagDefinition d = (TagDefinition)qr.getRecords()[0];
    d.setName("West Coast");
    try {
        binding.update(new SObject[]{d});
    } catch (RemoteException e) {
        System.out.println("An unexpected error has occurred." + e.getMessage());
    }
}

When a tag is deleted, its parent TagDefinition will also be deleted if the name is not being used; otherwise, the parent remains. Deleting a TagDefinition sends it to the recycle bin, along with any associated tag entries.

For more information on tags, see “About Tagging” in the Salesforce.com online help.