Attribute TagSet & EnumSet

TagSet and EnumSet are two different attributes types which are very similar.

  • Their usage in the UI is the same
  • The declaration of the Allowed Tags is the main difference:
    • EnumSet: the allowed values are declared in the datamodel
    • TagSet: the allowed values are dynamic data declared on each iTop instance

If you need to code a behavior in PHP based on a particular tag present or not on an object, then use an EnumSet, so that code can be tested regardless of the data created on the iTop

Display of such field

What does it look like within the details of an objet
You're not sure about the exact meaning of a tag, just move your mouse over it

Display Tooltip

TagSet specific: If you click on a Tag value, it will give you all the objects that do have this particular tag.

Search on such field

Searching for FAQs having either End-User or Agent Tag or End-User and Agent Tag

FAQs having End-User OR Agent tags FAQs having End-User AND Agent tags

Searching for Communications displayed on the User Portal (User Portal is the label of an allowed value of the portals EnumSet)

đźš§ Add screenshot

OQL syntax

A search on field of those types: TagSet & EnumSet use a specific OQL syntax

Assuming you have 2 domains with code agent and enduser, and some FAQs with those tags:
You can search for FAQs having either one or the other of those 2 tags:

  SELECT FAQ WHERE domains MATCHES 'agent enduser'

You can search for FAQs having both tags:

  SELECT FAQ WHERE domains MATCHES 'agent' AND domains MATCHES 'enduser'

You can search for FAQs having no tags:

  SELECT FAQ WHERE domains = ''

Searching for Person which can put clothes of size S OR M

  SELECT Person WHERE cloth_size= '__S __M'
There is a MySQL (and MariaDB) limitation to the length of the string which can be searched with MATCHES, it must be >= 3 characters

Edit such field

Add a Tag

If you have a small number of possible tags, they are listed in the drop-down

If you enter some text, the list of selectable values is filtered to those containing your text

If you have a single value listed, pressing the key enter does add it to your tags

There is a maximum number of tags which can be set on an object.
This maximum is defined in the datamodel field declaration

When you reached the maximum number of tags allowed, then the list of possible values is not displayed so you can no more add a value. If after you've reached the limit, you remove a tag, then the list of possible values is displayed again.

Remove a Tag

If you have at least one selected tag and put the cursor in that field: pressing the key back will remove the last tag.

If you click on the x on a selected tag, it will remove that tag.

Bulk edition of TagSet/EnumSet field

If you have bulk write right then you can add or remove Tags massively. It supports those use cases:

  • Add a Tag to a set of objects and leave the other tags unchanged on all modified objects. Adding a tag to an object which has it already, has no effect.
  • Remove a Tag from a set of objects and leave the other tags unchanged on all modified objects. Removing a tag from an object which doesn't have it, has no effect.

Modify a list of objects on which you want to bulk add or remove tags This is how the tags are displayed in the bulk modify edit screen:

  • The tags which are present on all objects-to-modify are displayed with a white background
  • The tags which are present on at leat one objects-to-modify are displayed with a grey background
    • If you click on a grey tag it becomes white and will be added to all objects-to-modify
    • If you leave unchanged a grey tag, it will remain on those objects who had it before and won't be added on others.
  • Tags present on none of the objects-to-modify but needing to be added, must be selected as in single object edition.
  • You can remove a tag exactly as described in the single object edition.

Export / Import

When you export objects with a TagSet attribute, the tags are exported with their label, separated by a pipe |. The same format is supported for importing data.

  • You can export the labels, or the codes checking the flag Export Code instead of Label
  • You can only import using labels of the Tags, the codes within the console are not yet supported.
Limitation: Tags with a label with less than 3 characters cannot be CSV imported in an object field

Workaround on the above limitation for EnumSet only: if you must have shorter labels such as shoe-size or clothing size, define longer labels in a language you don't use, and import CSV the EnumSet fields with a user in that language

Manage TagSet allowed values

The allowed values of an EnumSet are declared in PHP or XML, so in the datamodel
The information below is just for TagSet

Add an allowed Tag

Managing the proposed values for a particular TagSet attribute, is done in iTop as you managed a Typology. See the new menu under “Data administration”:

It's possible to change who can see this menu (as for any menu) and who can modify those classes, by fine-tuning the profiles using the parent class TagSetFieldData or the children classes (TagSetFieldDataFor_Class__AttCode) if we want.

A tag within a TagSet is made of a code and a label
The code must be 3 caracters min.
If not, iTop prefix automatically the provided code with underscore character(s) to reach 3

Example, if you define codes like this:

 XS, S, M, L, XL, XXL 

iTop will change them into:

 _XS, __S, __M, __L, _XL, XXL

For the labels they won't be transformed, but if they are shorter than 3 letters, then you won't be able to CSV import object with this tag value in the object field. See export_import

Search allowed values

  1. Select the Class/Attribute for which you want to manage the values
  2. Check existing values
  3. Create missing ones

  • code can only use numbers and letters, no other character.
  • Tags are ordered by code using alphabetic order [1..9][A..Z][a..z].
Some values cannot be used as tag code: ABOUT, ARE, FOR, FROM, HOW,…
Check the full list
As Tag ordering is based on their code, better align code and label to make it more obvious for users
You can put emoji within a tag label, using a simple copy-paste

Modify an allowed Tag

  • If no object is using that tag value, then it can be freely modified.
  • If at least one object is using that tag, then the code cannot be changed, but label and description can.

Delete an allowed Tag

  • If no object is using that tag value, then it can freely be deleted
  • If at least one object is using that tag, then it cannot be deleted.

Remove first that tag from all objects using it:

  1. Click on the Tag
  2. Open the tab “Tag usage”
  3. Click on the modifiy action on the listed object
  4. Remove the Tag in the bulk edition form and submit
  5. Now you can delete the Tag, retrieved on the breadcrum

Configure a TagSet Attribute

As part of the definition of a tag, you must define

  • The maximum number of tags <max_items> allowed on a given object. This does not limit the number of available tags, which has no limit.
  • You should limit the size of a tag code for performance <tag_code_max_len>
It is highly recommended to set max_items x tag_code_max_len < 255
Do not reduce <max_items> or <tag_code_max_len> on an existing TagSet with real data being above the new limits or you may lose data.
Defining an AttributeTagSet with id domains on class FAQ, create automatically a class TagSetFieldDataFor_FAQ__domains

Q&A

Query results are incoherent with the content, what can I do ?

Try to rebuild the corresponding MySQL table full text index by launching as a MySQL user the optimize table statement (see corresponding documentation).

Limitations

TagSet / EnumSet cannot be updated by DataSynchro
  • “Allowed values” cannot be localized with a TagSet, but it can of course with a EnumSet
  • There is no warning when a user has reached the maximum numbers of Tags allowed on an object, it just stops proposing new values
  • Extension Data Localizer was not yet tested with TagSet đźš§
  • Reducing the size of <max_items> or <tag_code_max_len> on an existing TagSet with real data being above the new limits, will lead to unpredictable results depending on your database.
  • TagSet / EnumSet cannot be copied with Object Copier
No Tag attribute should be added to Contact or Person class, as it breaks the login phase
latest/feature/tag.txt · Last modified: 2025/08/28 19:11 by 127.0.0.1
Back to top
Contact us