Web Services support enabling categories for a record, disabling categories for a record, and reading categories (and category properties) for a record.

Before You Begin

You need to get the following information before working with categories using Web Services:

•Category unique key—This value is constructed like <projectUniqueCode + "_" + categoryTreePosition>

For example, if you are adding a parent category, Contracts, to a dispute record, then the category unique key would be "DISP_CONT"

(where the tree position for Contracts is "CONT"; and the unique code for the Dispute object is "DISP")

Another example would be if you are adding a child category, Confidentiality Breach, to a dispute record, then the category unique key would be "DISP_CONT_COBR"

(where the following apply:

▪the tree position for the child category, Confidentiality Breach, is "COBR"

▪the tree position for the parent category, Contracts, is "CONT"

▪the unique code for the Dispute object is "DISP")

•Category name

Enabling Categories

When creating or updating a record, you can enable categories for the record. You can enable multiple categories for a record with the exception of invoice line items, tasks, and expenses.

Important: A category must already exist in TeamConnect before you can enable the category for a record using Web Services. Web Services do not support creating a category for an object definition. Use the TeamConnect Designer UI area to create new categories.

When creating records that are system object or custom object types, the TeamConnect system automatically sets the default category to the corresponding object definition's root category (for example an account record's root category is Account). As a result, you are not required to set a category for records with the exception of invoice line items.

When creating an invoice line item record where the line item type is set to EXPENSE, you need to explicitly set one Expense Category. Otherwise, when creating an invoice line item record where the line item type is set to FEE, you need to explicitly set one Fee/Task Category.

Caution: If you set multiple categories for a line item, only the last set category will be saved.

Note: If a validation rule exists that requires new projects or matters to be saved with a category other than the root category, you may need to enable or add a category to the record when you create it using Web Services.

From the Category type class, use the setUniqueKey (String) method to identify which category you want to add to (enable for) a record. From an ObjectCreate class, you would use the getCategories() method to add an instance of the Category class for the type of record you are creating. For example:

Category cat = new Category();

cat.setUniqueKey("CONT_EXTE");

PersonCreate person = PersonCreate();

person.getCategories().add(cat);

Use the getCategories() method to:

•enable categories for a record during record creation or

•enable additional categories for a record during record update

Reading Primary Categories

If a record has multiple categories and you are only interested in getting the primary category, include primaryCategory in the properties parameters.

Disabling Categories

When updating a record, use the getCategoryDeleteUniqueKeys() method to disable a category for that record. For example:

PersonUpdate person = PersonUpdate();

person.getCategoryDeleteUniqueKeys().add("CONT_INTR");

\\where "CONT_INTR" is the unique key of the category to disable

Reading Categories

Reading categories for a record is different from reading other record properties in that in the properties (List of string property names) parameter, you include "categories". The returned record object will include a list of category objects for that record (including all of that record's custom fields).

Important: Reading categories is the exception to the general rule that when you specify a record's properties to read, for properties that are objects, you need to specify the non-object property of the parent object property to retrieve.

For example:

Person readPerson = (Person)contactRepository.readContact(uniqueKey, getPropertiesToRead());

}

private List<String> getPropertiesToRead() {

List<String> properties = new ArrayList<String>();

properties.add("firstName");

properties.add("lastName");

properties.add("address.type");

properties.add("categories");

return properties;

}