Common API Functions

Last updated
Save as PDF

If you need to perform common functions using the API, you can use the UtilityService interface. This interface encompasses miscellaneous methods that you might use throughout your code.

These methods do not set anything in TeamConnect, but instead they retrieve information or run your code as a different user.

Note: Use the following code to access UtilityService: UtilityService utilityService = platform.getUtilityService();

UtilityService includes methods for the following types of actions:

Converting or changing formats—For example, you can use the booleanValueForString() method to convert a string to a boolean and the formatDateByUserSetting() method to format the date based on the user's date settings, as shown in the following code samples.

UtilityService utilityService = platform.getUtilityService();

//Converting strings to booleans and returning boolean true. 
utilityService.booleanValueForString("YES"); 
utilityService.booleanValueForString("TRUE"); 
utilityService.booleanValueForString("1");

//Converting strings to booleans and returning boolean false. 
utilityService.booleanValueForString("NO"); 
utilityService.booleanValueForString("FALSE"); 
utilityService.booleanValueForString("0");

//Formatting the date for the user based on the current settings for that User user = utilityService.getCurrentUser();
Date today = new Date();
String formattedDate = utilityService.formatDateByUserSetting(today, user);

Retrieving information based on the current day, time, or user—For example, you can also use the getCurrentUser() method to retrieve the user object for the user currently running the code. You can also use the getBeginningOfToday() method to return the start of the current day in the current user's time zone, as shown in the following code sample.

Date date = utilityService.getBeginningOfToday();

Retrieving information about single-project object definitions—For example, you can use the getSingletonForObjectDefinition() method to return the single project for an object definition, as shown in the following code sample.

// Unique 4-letter code for custom project. String projectDefinitionUniqueCode = "PROJ";
Project singletonProject = utilityService.getSingletonForObjectDefinition(projectDefinitionUniqueCode);

Retrieving system information—For example, you can use the getDatabaseInfo() to return information about the TeamConnect database, as shown in the following sample.

DatabaseInfo databaseInfo = utilityService.getDatabaseInfo(); String serverName = databaseInfo.getServerName();
String databaseName = databaseInfo.getDatabaseName();
Date databaseCreatedOn = databaseInfo.getDatabaseCreatedOn(); String version = databaseInfo.getVersion();
DatabaseProduct product = databaseInfo.getDatabaseProduct();

Comparing two different days—For example, you can use the isDayAfter() method to determine whether one date occurs before or after another date, as shown in the following sample about comparing the created on date for two different invoices.

//find two invoices
Long invoiceId1 = 1L;
Invoice invoice1 = invoiceService.read(invoiceId1);
Long invoiceId2 = 2L;
Invoice invoice2 = invoiceService.read(invoiceId2);
//Determine if invoice2 was created after invoice1
if (utilityService.isDayAfter(invoice2.getCreatedOn(), invoice1.getCreatedOn()))
{
//do something
}

Sorting a list—You can use the sortUsingPath() method to sort a list, as shown in the following sample.

List<User> users = platform.getUserService().getAllUsers();
//sort users based on the contact primary city. In ascending order.
FieldPath pathToContactsPrimaryCity = new FieldPath(User.CONTACT).add(Contact.PRIMARY_ADDRESS).add(Address.CITY);
boolean isAscending = true;
List sortedUsers= platform.getUtilityService().sortUsingPath(users, 
pathToContactsPrimaryCity, isAscending);

Running code as a different user—You can use the runAsSystemUser() method to run code as the system user. You can also use the runAsUser() method to run code as a specific user, as shown in the following sample.

//get current user
User user = utilityService.getCurrentUser(); //run a call as the user utilityService.runAsUser(user, new Callable() {
@Override
public void call() {
//do something }
});

Running Code as the System User

Because every record is subject to security, change to a user you know has the appropriate rights to ensure that your code runs. To execute code regardless of your functional or record security rights, you can run code as if you are the system user.

Note: If you want code to fail if the current user does not have the appropriate rights, you do not need to run code as the system user.

The system user, which has the username "system" and contact name "system, system" includes the following characteristics:

Has all rights at all times.
Cannot be added to a group.
Cannot be denied security rights in a record's Security tab.
Can always execute any method in the API.

To run code as the system user inside a call, use utilityService.runAsSystemUser().

UtilityService includes four runAsSystemUser() methods. The method you use depends on whether you want to return data and/or execute additional code if the call throws an exception.

utilityService.runAsSystemUser(new Callable() { public void call() {
// Place your code here.
}
});

The following code snippet indicates how to execute code as a system user without returning any results:

String username = utilityService.runAsSystemUser(new CallableWithReturn<String>() {
public String call() { String answer = "";
// Place your code here. return answer;
} });

The following code snippet indicates how to execute code as a system user and return data:

try {
utilityService.runAsSystemUser(new CallableWithException<FileNotFoundException> callable() {
public void call() throws FileNotFoundException { throw new FileNotFoundException();
} });

The following code snippet indicates how to execute code as a system user without returning any results and also executing additional code if the call throws an exception:

} catch (FileNotFoundException e) { System.out.println("Couldn't find file!");
}

You can combine the last two code snippets to execute code that returns data or that executes additional code in the case of an error.

Getting Current User Information

The current user is the user who is triggering a rule or invoking an action. When you want code to execute regardless of the current user's rights, you change the current user to the system user. Because the user running the code can change, you may need to retrieve the current user.

To retrieve the user object for the current user, use the utilityService.getCurrentUser() method.

The following code sample retrieves the username of the current user. This code is useful when the current user is a required condition. You can use the username to determine whether the current user meets the condition.

String username = UtilityService.getCurrentUser().getUsername();

The following code sample retrieves the contact record of the current user.

User currentUser = utilityService.getCurrentUser();
Contact userContact = userService.getUserAccountForUser(user).getContact();

The following code sample retrieves the groups to which the current user belongs.

utilityService.getCurrentUser.getGroupList();

The following code sample checks the list of groups for the current user to find out if the user is part of a specific group. You can use this code as a template to check other conditions in addition to the group membership of the current user.

// Initialize services.
UtilityService utilityService = platform.getUtilityService(); 
GroupService groupService = platform.getGroupService();

//get group list for user.
User currentUser = utilityService.getCurrentUser();
List<Group> groupsForUser = groupService.getGroupsForUser(currentUser);

//Check to see if specific group is part of the list. 
for (Group group : groupsForUser) {
    if (group.getDisplayName().equals("specifiedGroupName")) { 
        return false;