API Package Classes

The API includes the following packages:

com.mitratech.teamconnect.enterprise.api—Includes any general classes, mainly Platform.
com.mitratech.teamconnect.enterprise.api.callable—Includes the four different types of callable methods that you use with UtilityService.runAsSystemUser().
com.mitratech.teamconnect.enterprise.api.custom—Includes the classes you extend when you are creating custom screens, automated qualifiers, and automated actions.
com.mitratech.teamconnect.enterprise.api.model—Includes the classes for all API objects that are not part of the other model packages.
com.mitratech.teamconnect.enterprise.api.model.custom—Includes the API model classes for all design entities.
com.mitratech.teamconnect.enterprise.api.model.enums—Includes the API model classes for all enumerations.
com.mitratech.teamconnect.enterprise.api.model.exceptions—Includes the API model classes for all exceptions.
com.mitratech.teamconnect.enterprise.api.model.parameters—Includes the API model classes for all parameters.
com.mitratech.teamconnect.enterprise.api.model.search—Includes the API model classes for searching.
com.mitratech.teamconnect.enterprise.api.service—Includes all the service classes.

To see the specific contents of these packages, refer to the API Reference in the following location on your installation media:

~\utilities\javadocs\api\index.html

Model Classes

Use the API model classes to describe properties of TeamConnect objects and to implement actions.

Note: To use model classes, you may need to access a service class if you do not already have access to an instance of the object.

The following diagram illustrates the structure of most API model classes.

Screen Shot 2017-09-21 at 4.42.41 PM.png

All model classes correspond to an object in the database. The TeamConnect API includes the following main model classes:

EnterpriseEntity—The base class for all model classes that correspond to records of system and custom objects. The classes for these objects include methods for record features associated with the objects, such as security, custom fields, and categories. Those model classes extend EnterpriseEntity.
Entity—The base class that provides functionality for sub-objects and other properties of EnterpriseEntity records, such as assignees, phone numbers, and invoice adjustments. EnterpriseEntity extends Entity, which means that Entity also provides a base class for system and custom objects.

For example, the Project model class extends EnterpriseEntity, which extends Entity. The ProjectAssignee model class, which provides functionality for a project, extends Entity. The following diagram illustrates the API model structure with these classes.

Enumerations

Enumerations, or enums, manage options in drop-down lists in TeamConnect. Unlike lookup tables, you cannot add options to these drop-down lists.

All enums are model API classes that include a list of the enum constants. The purpose of these enums is to specify the selected option for a drop-down field, so that you can use the field in API code. Enum classes always include the following two methods:

valueOf()—Returns the enum constant for a given field name.
value()—Returns the list of enum constants.

For example, accounts in TeamConnect have the drop-down list field of Overdraft Type. The AccountOverdraftType class includes three enum constants for the three options in this drop-down list. You use this class for the Overdraft Type account field.

Service Classes

You access a service class for a particular object when you are using any of the ResourceService methods (create(), update(), read(), etc.). For example, if you need to use the update() method to update the name of an account, you need to access AccountService.

Note: If you are adding the custom code to a screen or rule, the API already has access to the object with that screen or rule. As a result, you do not need to access the service class for that object.

When you use the API, you must reference the service classes so that you can call or invoke methods that the service classes use. Accessing the service classes requires two parts:

A main utility class specific to the module, which you can use to retrieve service implementations. Platform is the main utility class for the TeamConnect enterprise module. If you look at the Platform class in the javadocs, you see a method that you can use to call each service class for ResourceService and TransationalService. For example, to access the account service using the Platform class, you use the following method:

platform.getAccountService()
A service class. Service classes provide access to API model classes. To access the account model classes using the main utility class method, you enter the following information:
- The name of the service class
- A variable name for the method
- An equal sign
- The Platform method for the service class

For example, to access AccountService, enter the following code:

AccountService accountService = Platform.getAccountService();

Note: Before you can make a change to an object, you must access the service class for the object. If you are using objects from more than one service class in your code, you must access the service classes for both objects.

After you call the service class(es), you can use the API model classes to describe properties of TeamConnect objects and implement actions.

Resource Services

Resource services provide classes for creating, reading, updating, deleting, searching for, and manipulating model objects. Each service class corresponds to a TeamConnect entity or object type (for example, contacts, projects, accounts, invoices, etc.).

While each service class has it's own set of methods that are specific to that object, ResourceService provides a few common functions that all service classes extend, as shown in the following table.

ResourceService Method Actions

Action	Methods to Use
Creating a record	Use the `create()` method to create a record. Note: When writing code to create a record for a rule, condition, or wizard, you do not need to use the create() method because the changes automatically commit to the database. Use the `batchCreate()` method to create multiple records.
Updating a record	Use the `update()` method to update a record. Note: When writing code to update a new record for a rule, condition, or wizard, you do not need to use the update() method because the changes automatically commit to the database. Use the `batchCreate()` method to update multiple records.
Reading a record	Use the `read()` method to read a record using it's primary key. Use the `readLastSaved()` method to read the last saved version of a record. You can use this version to determine if a record property has any updates.
Deleting a record	Note: When you want to delete a record that is a dependency for another record, consider the best way to delete that record. Use the `delete()` methods to delete a record: One `delete()` method deletes an object for which you have a reference. The other `delete()` method deletes an object for which you have no reference and the primary key is known. Use `batchDelete()`to delete multiple records. `batchDelete()` uses the `ddelete()` method multiple times.
Creating a copy of a record	Use the `copyEntity()` method to create a copy of a record.
Searching for a record	Use the `search()` methods to search for a record: One `search()` method uses the search criteria to search. One `search()` method uses the search criteria and parameters to search. One `search()` method uses an existing search view to search. All `search()` methods use the search model classes.
Determining if security settings changed	Use the `isSecurityChange()` method to determine if security settings for an entity changed.
Retrieves a record URL	Use the `getRecordURL()` method to return the URL to a record on your instance.

For examples of some of these functions, see the code examples for each service class:

In the cases of the record that triggers the qualifier or action and the record with the custom block, you do not need to call the service class to access to the record.

The following table shows whether you use ResourceService classes in qualifiers, actions, and screens.

Services in Qualifiers, Actions, and Screens

Method	Qualifiers and Actions	Custom Screens
`read()` (for the initial record)	No	No
`create()`	No	Yes
`update()`	No	Yes
`new<object>()` (for the new object method in the Service class)	Yes	Yes

Qualifiers and Actions

When you create an automated qualifier or action, the code calls the CustomCondition.condition(M)orCustomAction.action(M)methods. Your code must override these methods, which allows access to the record that triggered the qualifier or action. Because you have access to the record, you do not need to call the service class to read the record.

Rules, wizards, and conditions save all changes automatically. As a result, you do not need to use the create() or update() service methods. To delete an object or create an object using the new<Object>() method in a service class, you must still call the service class for the object.

Custom Screens

When you create a custom block for a record, you use the CustomBlock.getRecord() method to access the record. Because you have access to the record, you do not need to call the service class for the record.

Unlike with automated qualifiers and actions, custom screens do not save automatically. As a result, if you want to create a new record or update the record with the screen, you must use the create() or update() methods. Because create() and update() are ResourceService methods, you must call the service class of the record as part of the code.

For example, if the custom screen is on the contact object definition, but you are not creating a new record or updating an existing contact, you do not need to call ContactService. However, if you want to update a field in the contact record when another field changes, your custom screen code must include the call to ContactService so that you can use the update() method.

When you want to delete a record that is a dependency for another record, you must first delete the record that has the dependency, then you can delete the dependency record. For example, if you want to delete a contact that is listed as the contact for a user, delete the user first. Then you can delete the contact. Because you must use the delete() method to perform the deletions, you must call UserService and ContactService.

However, if you want to delete a record that is a dependency for another record as part of an automated qualifier and action, you cannot delete both as part of the qualifier or action because both deletions cannot be part of the same transaction.

Deleting Dependency Records

When you want to delete a record that is a dependency for another record, you must first delete the record that has the dependency, then you can delete the dependency record. For example, if you want to delete a contact that is listed as the contact for a user, delete the user first. Then you can delete the contact. Because you must use the delete() method to perform the deletions, you must call UserService and ContactService.

However, if you want to delete a record that is a dependency for another record as part of an automated qualifier and action, you cannot delete both as part of the qualifier or action because both deletions cannot be part of the same transaction.

Other Service Classes

Any service classes that are not ResourceService classes initiate actions not specific to any model objects. These classes corresponds to different high-level functions in TeamConnect, including settings, security, and internationalization.

For examples of using these functions in the API, see the topics for the following classes: