Categories have the following two purposes:

•They provide a simple way to organize and search for records.

•They organize custom fields by associating each custom field with a category. For custom fields to appear at all times, you can associate them with the root category. Users can display or hide custom fields by selecting or deselecting the associated categories.

In every object definition, the starting point for the category hierarchy is the root category. The hierarchy also includes a primary category, which the user sets manually. Upon record creation, the root category is set as the primary category.

Categories in the API

In the API, you represent categories with the following interfaces:

•CategoryService—The general category class that you use to obtain information about the categories for an object definitions or a tree position.

Note: Use the following code to access CategoryService: CategoryService categoryService = platform.getCategoryService();

•Category—The class that you use to obtain information about added categories and their hierarchical positions in a record, including any children and parent categories. A Category is an instance of a CategoryDefinition.

•CategoryDefinition—The class that you use to obtain information about categories that exist for an object and their associated custom fields.

•EnterpriseEntity—The class that includes methods that system objects and other interfaces extend. This class includes the getAllCategories(), getPrimaryCategory(), hasCategory(), and setPrimaryCategory() methods.

•Object model interfaces with categories—These class also have methods for getting and setting categories. For example, the Invoice class has the following methods: addCategory(), getCategories(), and removeCategory(). Other object model interfaces may have different category methods.

Note: In instances of an Involved object, categories are known as "involved roles."

Category Tree Positions

A full tree position uniquely identifies a category. The root category's full tree position is the same as the unique code of the object definition. The full tree position of non-root categories is a combination of the following with underscores as delimiters:

•The full tree position of the category's parent category

•The partial tree position of the category itself

For example, category B with partial tree position BBBB is under category A with partial tree position AAAA, which is under the root category of the Appointment object definition with the unique code APPT. As a result, the full tree position of category B is APPT_AAAA_BBBB, and the full tree position of category A is APPT_AAAA.