Creating an Account

The following sample creates an account record. During account creation, you can set objects in the account record, such as the account name.

Account newAccount = accountService.newAccount("name", allocationLimit, startOnDate, endOnDate);

Creating a Child Account

The following sample creates a child account record. During child account creation, you can use API interface methods to set objects in the account, such as the parent account.

Account newChildAccount = accountService.newAccount("name", 
allocationLimit, startOnDate, endOnDate);
newChildAccount.setParentAccount(parentAccount);

Reading an Account

The following sample reads an account record. When you read an account, you retrieve the account so that you can make changes to it, such as activating or transferring money from it.

//The id initialized here is the id of an existing account 
Long id = 1234567890L;
Account account = accountService.read(id);

Activating an Account

The following sample activates an account record.

accountService.activateAccount(accountToBeActivated);

Deactivating an Account  

The following sample deactivates an account record.

accountService.deactivateAccount(account);

Allocating Money to an Account  

The following sample allocates money to an account record. When you allocate money to an account, a parent account must already exist.

//Allocating money to an account - $5000 accountService.allocateMoney(account, amount, "description");

Transferring Money between Accounts  

The following sample transfers money between two accounts. When you transfer money, a parent and child account must already exist.

accountService.transferMoney(accountFrom, accountTo, amount, "description");

Withdrawing money from an Account  

The following sample withdraws money from an account record.
//Withdrawing from an account - $5000

Deleting an Account  

The following sample deletes an account record. When you delete an account, the account must not have a balance.

//Account cannot have a balance before deletion. Make necessary withdrawals.
accountService.withdrawMoney(parentAccount, new BigDecimal("1000"), "Withdraw to zero");
accountService.withdrawMoney(childAccount, new BigDecimal("234"), "Withdraw to zero");
//When deleting a parent account with attached child accounts, the child accounts also cannot have a balance. The deletion of a parent will delete its child accounts as well.
accountService.delete(parentAccount);

Creating an Appointment  

The following sample creates an appointment. During appointment creation, you can use API interface methods to set objects in the appointment, including the start date, end date, and category.

// Retrieve the appointment service from the platform provided by the API 
AppointmentService appointmentService = platform.getAppointmentService();

// Set up the initial required arguments to create a valid appointment 
long fourDaysInMilliseconds = 86400000 * 4;
Date startOn = new Date();
Date endOn = new Date(startOn.getTime() + fourDaysInMilliseconds);

// Create a new appointment, passing in the arguments created above.
Appointment appointment = appointmentService("Appointment Subject", startOn, endOn);

// Any non-required fields on the appointment may be set or added now 
appointment.setAllDay(true); 
appointment.addCategory("APPT_CATE_CUST");

Updating an Appointment  

The following sample updates an appointment. When you update an appointment, you can use API interface methods to set objects in the appointment, including the primary key, new attendees, and custom fields.

Retrieve the appointment service from the platform provided by the API. 
AppointmentService appointmentService = platform.getAppointmentService();

// Retrieve the desired appointment. long primaryKeyForAppointment = 2;
Appointment appointment = appointmentService.read(primaryKeyForAppointment);

// Modify fields. appointment.addAttendee(platform.getUserService().findUserByUsername("TestUser"
), AttendanceType.WILL_ATTEND); 
appointment.setBooleanFieldValue("customBooleanField", false);

Deleting an Appointment  

The following sample deletes an appointment.

// Retrieve the appointment service from the platform provided by the API.
AppointmentService appointmentService = platform.getAppointmentService();

// An appointment can be deleted simply by passing in the primary key. 
long primaryKeyForAppointment = 8; appointmentService.delete(primaryKeyForAppointment);

// Or, you can pass in the appointment object.
Appointment appointment = appointmentService.read(primaryKeyForAppointment); 
appointmentService.delete(appointment);

// In a rule, the delete will be committed when the rule completes.
// Otherwise, the delete will be committed immediately.

Searching for an Appointment  

The following sample searches for all appointments in Room 101.

// Retrieve the appointment service from the platform provided by the API. 
AppointmentService appointmentService = platform.getAppointmentService();

// Find all appointments located in Room 101 SearchCriteria criteria = new SearchCriteria(new
StringCriterion(Appointment.LOCATION).equalTo("Room 101"));

// Sort results by start date
SearchParameters parameters = new SearchParameters(new SortField(Appointment.START_ON));

// Execute search and return results
return appointmentService.search(criteria, parameters);

Creating a Person Contact  

The following sample creates a person contact record. During contact creation, you can use API interface methods to set objects in the contact record, including the contact address.

Person personContact = ContactService.newPerson("Bob", "Dole");
Address address = person.add
Address("ADDR_HOME");
address.setStreet("1234 Fake St.");
address.setCity("Austin");
address.setState("TX"); address.setPostalCode("78704"); 
address.setCountry("USA");

Creating a Company Contact  

The following sample creates a company contact record. During contact creation, you can use API interface methods to set objects in the contact record, including the contact address and email.

Company companyContact = ContactService.newCompany("myLittleCompany");
Address address = company.addAddress("ADDR_BUS1");
address.setStreet("1234 Fake St.");
address.setCity("Austin");
address.setState("TX");
address.setPostalCode("78704");
address.setCountry("USA");
Email email = company.addEmail("MAIL_BUS1", "you@yourcompany.com");

Updating a Contact  

The following sample updates a contact record. When you update a contact, you can use API interface methods to update objects in the contact record, including the contact fax number, email, and web address.

//Adding or updating a business fax number
FaxNumber faxNumber = person.addFaxNumber("FAXX_BUS1", "5123827322");

//Adding or updating a personal email
Email email = person.addEmail("MAIL_PER1", "you@yourcompany.com");

//Adding or updating a mobile phone number
PhoneNumber phoneNumber = person.addPhoneNumber("PHON_MOBI", "5123827322");

//Adding or updating a business web address
InternetAddress internetAddress = person.addInternetAddress("INET_BWEB", "www.mitratech.com");

//Adding or updating a default skill
Skill skill = person.addSkill("SKIL_DEFA", 2);

Reading a Contact  

The following sample reads a contact record. When you read a contact, you retrieve the contact so that you can make changes to it, such as updating or deleting it.

/The id initialized here is the id of an existing person contact 
long personId = 49L;
Person personContact = ContactService.readPerson(personId);
//The id initialized here is the id of an existing company contact 
long companyId= 23L;
Company companyContact = ContactService.readCompany(CompanyId);

Deleting a Contact  

The following sample deletes a contact record. When you delete a contact, if the contact is associated with a user or any other object, remove the association first.

ContactService.delete(personContact);
ContactService.delete(companyContact);

Creating a Document Record  

The following sample creates a document. During document creation, you can add the document to a folder, create a shortcut for the folder, and check in the file, among other things.

DocumentService documentService = platform.getDocumentService();

// Get attachment folder of a record Folder attachmentFolder =
documentService.getAttachmentFolderForDocumentOwner(getRecord());

// Create a folder under the attachment folder
Folder folder = attachmentFolder.addFolder("New Folder");

// Create a file directly under the attachment folder FileContentType contentType =
platform.getLookupItemService().getFileContentTypeByFileExtension("txt"); byte[] fileContent = new byte[0];
File file = attachmentFolder.addFile("New File", fileContent, contentType);

// Create a hyperlink
Hyperlink hyperlink = folder.addHyperlink("Mitratech", "http:// www.mitratech.com");

// Create a shortcut to a folder
Shortcut shortcutToFolder = folder.addShortcut(folder);

// Create a shortcut to a file
Shortcut shortcutToFile = folder.addShortcut(file);

//Checkout file 
documentService.checkOut(file);

//Checkin file
documentService.checkIn(file, fileContent, "check in comment");

Reading a Document Using its Path  

The following sample returns a document using its folder path.

// Returns a document from the repository using its folder path 
Document document = documentService.findDocumentByPath("path");

Retrieving the Root Folder  

The following sample returns the root document folder.

// Returns the root document folder
Folder rootFolder = documentService.getRootFolder();

Copying a Document  

The following sample copies a document to a new folder.

/ Returns an exact duplicate of a given entity object
Document duplicateDocument = documentService.copyEntity(originalDocument);

// Copies a document to a new parent folder
documentService.copyDocument(document, parentFolder);

Moving a Document  

The following sample moves a document to a new folder.

// Changes the location of a file 
documentService.moveDocument(document, parentFolder);

Checking Out a Document  

The following sample checks out a file and locks it so that other users cannot check it out.

// Checks out and locks a file for a single user to update 
documentService.checkOut(file);

Undoing a Document Checkout  

The following sample reverses a document checkout. The document remains unchanged and has no version number.

// Reverses the checkout of a file. documentService.undoCheckOut(file);

Checking in a Document  

The following sample checks in a document by converting the existing file to the new file version and replacing the file contents the byte array of the new contents.

// Checks in a file.
documentService.checkIn(file, data, "versionText");

Reverting a Document to a Previous Version  

The following sample reverts a document to a previous version by converting the existing file to a different file version and replacing the file contents with the byte array of the new contents.

// Revert a document to a prior version
FileVersion version = documentService.getFileVersions(file).get(0); 
documentService.revertTo(version);

Creating an Expense  

The following sample creates an expense record. During expense creation, you can use API interface methods to set objects in the expense record, including the user who is responsible for the expense and a description of the expense.

//Expense description is a mandatory field
Expense expense = expenseService.newExpense("Brand New Test Description");
User user = platform.getUserService().findUserByUsername("Expenser");
expense.setExpensedBy(user);
//Date will be converted to midnight GMT, then back to the local date/time relative to GMT midnight
Calendar cal = Calendar.getInstance(); cal.set(2014, 01, 30); 
expense.setExpenseDate(new CalendarDate(cal));

Updating an Expense  

The following sample updates an expense record. When you update an expense, you can use API interface methods to update objects in the expense, including the expense name.

expense.setShortDescription("Expense Description Update");
//Adding new unit price for expensed item ($150) and quantity of units (2) 
expense.setUnitPrice(BigDecimal.valueOf(150)); 
expense.setQuantity(BigDecimal.valueOf(2));  

Reading an Expense

The following sample reads an expense record. When you read an expense, you can retrieve the last saved version of the expense to post, delete, or do something else with the record.

/The expenseHandle here is a preexisting Expense object
Expense lastSavedExpense = expenseService.readLastSaved(expenseHandle);

Posting an Expense  

The following sample posts an expense record. When you post an expense, you can use API interface methods to prepare an expense for posting.

//Ensure that these options are enabled in an account to post an expense account.setAllowPosting(true); account.getAccountPostingCriteria().setAllowExpense(true); expenseService.postExpense(expense)

Voiding an Expense

The following sample voids an expense record.

//An expense must be posted to be voided expenseService.voidExpense(expense);

Deleting an Expense  

The following sample deletes an expense record.

expenseService.delete(expense);

Getting Transactions for an Expense  

The following sample returns a list of transactions for an expense record.

List<AccountTransaction> transactions = expenseService.getTransactionsForExpense(expense);

Getting Transactions for an Expense Associated with an Account  

The following sample returns a list of transactions for an expense record that is associated with an account.

List<AccountTransaction> transactions = expenseService.getTransactionsForExpense(account, expense);

Searching for Expenses 

The following sample searches for expenses with a start date of January 2012.

Calendar cal = Calendar.getInstance(); 
cal.set(2012, 1, 1);
Date startDate = cal.getTime();

Calendar cal = Calendar.getInstance(); 
cal.set(2012, 1, 31);
Date endDate = cal.getTime();

DateCriterion dateCriterion = new 
DateCriterion(Expense.EXPENSE_DATE).between(startDate, endDate);

List<Expense> expenses = platform.getExpenseService().search(new 
SearchCriteria(dateCriterion));

Creating a Group  

The following sample creates a group. To create a group, you need to create a group account.

During group creation, you can use API interface methods to set objects in the group, such as its description.

//create a new group account with specified unique name and display name.
GroupAccount groupAccount = groupService.newGroupAccount("GroupUniqueName", 
"GroupDisplayName");
groupAccount.setDescription("Description");

Updating a Group  

The following sample updates a group. When you update a group, you can use API interface methods to update the group account, such as its description.

//get group with specified name.
Group group = groupService.getGroupForName("GroupName");

//retrieve the group account from the group.
GroupAccount groupAccount = groupService.getGroupAccountForGroup(group);
groupAccount.setDescription("newDescription");

Reading a Group  

The following sample reads a group. When you read a group, you retrieve the group account so that you can make changes to it, such as updating or deleting it.

//read group and user accounts.
GroupAccount groupAccount = groupService.read(1L); UserAccount userAccount = userService.read(1L);
//get the group and user from their corresponding accounts.
Group group = groupService.getGroupForGroupAccount(groupAccount); User user = userService.getUserForUserAccount(userAccount);
groupService.addUserToGroup(group, user);

Finding a Group  

The following sample finds a particular group. You can use the unique to find the group.

//get group based on its unique key.
Group group = groupService.getGroupForKey("uniqueKey");
//get all groups.
List<Group> allGroups = groupService.getAllGroups();
//get all users for a group.
List<User> usersForGroup = groupService.getAllUsersForGroup(group); //get all user accounts for group account.
GroupAccount groupAccount = groupService.read(1L); List<UserAccount> userAccountsForGroupAccount = groupService.getAllUserAccountsForGroupAccount(groupAccount);
//get all groups for a user.
User user = userService.findUserByUsername("username"); List<Group> groupsForUser = groupService.getGroupsForUser(user); 

Deleting a Group  

The following sample deletes a group by deleting the group account.

GroupAccount groupAccount = groupService.read(1L); 
groupService.delete(groupAccount);
//same as groupService.delete(groupAccount.getPrimaryKey());; 

Creating a History Entry  

The following sample creates a history entry. During history creation, you can use API interface methods to set objects in the entry, such as the history description and the category.

// Creates an empty history object.
History newHistory = historyService.newHistory("history", parentEntity);

Reading a History Entry  

The following sample returns a history entry using its primary key.

// Reads the Entity object based on the primary key provided historyService.read(primaryKey);

Finding a History Entry  

The following samples return all history entries for a particular entity and the most recent entry for an entity.

List<History> histories = historyService.getHistories(entity);
// Return most recent history with specified category and for a particular entity
History lastHistory = historyService.getLastHistory(entity, "HIST_STAT");

Deleting a History Entry  

The following samples delete a history entity.

// Deletes the Entity object
historyService.delete(history);
// Deletes the Entity object based on the primary key provided historyService.delete(primaryKey); 

Creating an Invoice with Line Items  

The following sample creates an invoice and adds line items. During invoice creation, you can use API interface methods to set objects in the invoice record and line items, including the line item rate, quantity, discount, and total.

// vendor is an existing contact
Company vendor = platform.getContactService().readCompany(45L);

CalendarDate invoiceDate = new CalendarDate();
Invoice invoice = invoiceService.newInvoice("456", vendor, invoiceDate); //the line item original rate.
BigDecimal originalRate = new BigDecimal("23.00");
//the line item original quantity.
BigDecimal originalQuantity = new BigDecimal("500");
//the line item original discount.
BigDecimal originalDiscount = new BigDecimal("17.56");
//the line item original total.
BigDecimal originalTotal = new BigDecimal("34805743570");

LineItem newLineItem = invoiceService.newExpenseLineItem(invoice, invoiceDate,
"LNI$_EXPS_OCEX_E100_E101", originalRate,
originalQuantity).setOriginalDiscount(originalDiscount).setOriginalTotal(origina lTotal); 

Updating and Adjusting an Invoice  

The following sample updates and adjusts an invoice. When you update an invoice, you can use API interface methods to set objects in the invoice record, including the start date. You also use API interface methods to adjust an invoice, such as for reducing an amount to a new amount.

CalendarDate periodStartDate = new CalendarDate(); 
invoice.setPeriodStartDate(periodStartDate);
AdjustmentInformation information =
new AdjustmentInformation(AdjustmentMethod.REDUCE_BY_AMOUNT, 
new BigDecimal("45.00"));
invoiceService.adjustInvoiceFees(invoice, information); 

Adjusting Invoice Line Items  

The following sample adjusts an invoice line item. When you adjust a line item, you can use API interface methods to adjust the line item, such as changing a line item amount to a new amount.

AdjustmentInformation information =
new AdjustmentInformation(AdjustmentMethod.NEW_AMOUNT, new BigDecimal("22.56");
invoiceService.adjustLineItemRate(lineItemToAdjust, information); 

Reading an Invoice  

The following sample reads an invoice record. When you read an invoice, you retrieve the invoice so that you can make changes to it, such as updating or posting to it.

// id of existing invoice.
long id = 4982340L;
Invoice invoice = invoiceService.read(id); 

Searching for an Invoice  

The following sample searches for an invoice record.

// Returns all invoices that have an invoice date within the last 10 days
SearchCriteria criteria = new SearchCriteria(new RelativeDateCriterion(Invoice.INVOICE_DATE).withinLast(10));
List<Invoice> invoices = invoiceService.search(criteria);

Posting an Invoice  

The following sample posts an invoice.

invoiceService.postInvoice(invoiceToBePosted);

Voiding an Invoice  

The following sample voids an invoice.

invoiceService.voidInvoice(invoiceToBeVoided);

Deleting an Invoice  

The following sample voids an invoice.

invoiceService.delete(invoiceToBeDeleted);

Creating a Task  

The following sample creates a task record. During task creation, you can use API interface methods to set objects in the task record, including the current assignee, associated project, and task rate.

Project project = platform.getProjectService().read(0L);
User assignee = platform.getUserService().findUserByUsername("task assignee"); Task task = taskService.newTask("This is a new task", assignee); task.setActualHours(BigDecimal.TEN);
task.setRateAmount(BigDecimal.ONE);
task.setNote("Note: This is a new task");
task.setProject(project); 

Reading a Task  

The following sample reads a task record. When you read a task, you retrieve the task so that you can make changes to it, such as updating or posting to it.

//the primary key of an existing task long id = 12345678910L;
Task task = taskService.read(id);

Searching for Tasks  

The following sample searches for tasks with a start date of January 2012.

Date startDate = new SimpleDateFormat("yyyy-MM-dd").parse("2012-01-01");
Date endDate = new SimpleDateFormat("yyyy-MM-dd").parse("2012-01-31"); 
DateCriterion dateCriterion = new DateCriterion(new FieldPath(Task.START_DATE));

List<Task> tasksStartingInJanuary2012 = taskService.search(new SearchCriteria(dateCriterion.between(startDate, endDate))); 

Posting a Task  

The following sample posts a task record. When you post a task, you can use API interface methods to update the task at the same time.

//the primary key of an existing task
long id = 12345678910L;
Task task = taskService.read(id); 
task.setCompletedDate(new CalendarDate()); 
task.setCompletedPercent(BigDecimal.valueOf(100)); 
taskService.postTask(task); 

Voiding a Task  

The following sample voids a task record.

//the primary key of an existing task long id = 12345678910L;
Task task = taskService.read(id); taskService.voidTask(task);

Reassigning a Task  

The following sample reassigns a task to another user.

//the primary key of an existing task
long taskId = 12345678910L;
Task task = taskService.read(taskId);

//the primary key of an existing user
long userId = 12345678910L;
User user = platform.getUserService().findUserByUsername("new assignee");

taskService.reassign(task, user); 

Deleting a Task  

The following sample deletes a task record.

//the primary key of an existing task 
long taskId = 12345678910L;
Task task = taskService.read(id);
taskService.delete(task);

Getting a List of Transactions for a Task  

The following sample returns a list of transactions for a task record.

//the primary key of an existing task 
long taskId = 12345678910L;
Task task = taskService.read(id);

List<AccountTransaction> transactions = 
taskService.getTransactionsForTask(task);

Getting a List of Transactions for a Task associated with an Account  

The following sample returns a list of transactions for a task record that is associated with an account.

//the primary key of an existing task long taskId = 12345678910L;
Task task = taskService.read(id);

//the primary key of an existing account 
long accountId = 12345678910L;
Account account = accountService.read(id); 

Voiding a Task  

The following sample voids a task record.

//the primary key of an existing task long id = 12345678910L;
Task task = taskService.read(id); taskService.voidTask(task); 

Reassigning a Task  

The following sample reassigns a task to another user.

//the primary key of an existing task long id = 12345678910L;
Task task = taskService.read(id); taskService.voidTask(task); 
long taskId = 12345678910L;
Task task = taskService.read(taskId);
//the primary key of an existing user
long userId = 12345678910L;
User user = platform.getUserService().findUserByUsername("new assignee");
taskService.reassign(task, user); 

Deleting a Task  

The following sample deletes a task record.

//the primary key of an existing task long taskId = 12345678910L;
Task task = taskService.read(id);
taskService.delete(task); 

Getting a List of Transactions for a Task  

The following sample returns a list of transactions for a task record.

//the primary key of an existing task long taskId = 12345678910L;
Task task = taskService.read(id);
List<AccountTransaction> transactions = taskService.getTransactionsForTask(task); 

Getting a List of Transactions for a Task associated with an Account  

The following sample returns a list of transactions for a task record that is associated with an account.

//the primary key of an existing task long taskId = 12345678910L;
Task task = taskService.read(id);
//the primary key of an existing account long accountId = 12345678910L;
Account account = accountService.read(id); 

Creating a User  

The following sample creates a user record. You can use the newUser() and newUserAcccount() methods to create a user account and its associated user, the saveUserAccount() method to save the user, and the getUserForUserAccount() method to extract the user from its account.

During user creation, you can use API interface methods to set objects in the user record, including the corresponding contact, username, and password. Before creating a user, a corresponding contact record must already exist in TeamConnect or you must create a new contact using ContactService. As shown in the sample, when creating a user record, you must also create the user account.

//read or create a contact
Contact contact = contactService.readPerson(1L);

//create a limited privilege user account.
UserAccount limitedUserAccount = userService.newLimitedPrivilegeUserAccount("username", "password", contact, true);
limitedUserAccount.setActive(true); limitedUserAccount.setChangePasswordNextLogin(true);
limitedUserAccount.setShortDescription("Description for limited privilage user account");

//get user from limited privilege user account.
User limitedUser = userService.getUserForUserAccount(limitedUserAccount);

//create a normal user account.
UserAccount normalUserAccount = userService.newNormalUserAccount("username", "password", contact);
normalUserAccount.setActive(true); normalUserAccount.setChangePasswordNextLogin(true); normalUserAccount.setShortDescription("Description for normal user account"); //get user from normal user account.
User normalUser = userService.getUserForUserAccount(normalUserAccount);

//create a super user account.
UserAccount SuperPowerfulUserAccount = userService.newSuperUserAccount("username", "password", contact);
SuperPowerfulUserAccount.setActive(true); SuperPowerfulUserAccount.setChangePasswordNextLogin(true);
SuperPowerfulUserAccount.setShortDescription("Description for a super powerful user account");

//get user from super user account.
User superUser = userService.getUserForUserAccount(SuperPowerfulUserAccount); 

Updating a User  

The following sample updates a user record. When you update a user, you can use API interface methods to update fields in the user record, including the username, password, and active setting.

//read or create a user account.
UserAccount userAccount = userService.read(1L); 
userAccount.setUsername("newUsername"); 
userAccount.setPassword("newPassword"); 
userAccount.setActive(true); 

Reading a User  

The following sample reads a user record. When you read a user, you retrieve the user so that you can make changes to the user account, such as updating or deleting it.

//read a user account.
UserAccount userAccount = userService.read(1L);
//get the user from the user account.
User user = userService.getUserForUserAccount(userAccount); 

Finding a User  

The following sample find a particular user record. You can use a username to find the user.

User user = userService.findUserByUsername("username");

Deleting a User  

The following sample deletes a user record.

serAccount userAccount = userService.read(1L); 
userService.delete(userAccount);
//same as userService.delete(userAccount.getPrimaryKey()); 

Adding an Embedded Project to a Parent Project  

The following samples update a project record by adding an embedded project to the project. As shown in these samples, you can use Project methods to add the embedded project.

EmbeddedEntity embeddedProject = project.addEmbeddedEntity("unique code"); //or
EmbeddedEntity embeddedProject = project.addEmbeddedEntityWithName("unique code", "name");
//or
EmbeddedEntity embeddedProject = project.addEmbeddedEntityWithNumberString("unique code", "id number as a string");
//or
EmbeddedEntity embeddedProject = project.addEmbeddedEntity("unique code", "name", "id number as a string"); 

Changing a Project's Phase  

The following sample changes the phase of a project and updates the record. While making these changes, you can use API interface methods to update objects in the project record, such as the project name.

project.setContact(contact); 
project.setMainAssignee(assignee);
projectService.changePhaseWithUpdate(project, "phase code of the phase to change to");

Reading Child Projects for a Record  

The following sample returns the child projects of a parent project.

List<Project> childProjects = projectService.getChildProjects(project, "unique code of the child Custom Object Definition");

Searching for a Project  

The following samples return an existing project. The second sample includes a

/Reading a project
//The id initialized here is the id of an existing project Long id = 1234567890L;
Project project = projectService.read(id);
//Searching for a project
List<Project> search("unique code", "search view key"); 

Deleting a Project  

The following sample deletes and existing project.

//The id initialized here is the id of an existing project Long id = 1234567890L;
projectService.delete(id);

Adding an Involved Party to a Project

The following sample adds a new Involved party to a project.

During Involved party creation, you can to set objects in the Involved party record, including the Involved party unique code and the associated project.

 Involved newInvolved = involvedService.newInvolved(project, contact, 
 "INPA_EXPE"); 

Reading an Involved Party

The following sample returns an Involved party.

//The id initialized here is the id of an existing project Long id = 1234567890L
Involved involved = involvedService.read(id);  

Searching for an Involved Party

The following sample creates an Involved party record. The sample includes an InvolvedService.search() method. This search() method is different from the ResourceService.search() methods because the InvolvedService.search() method includes the unique code of an existing project as a parameter.

 List<Involved> involveds = involvedService.search("unique code", "search view key") 

Deleting an Involved Party

The following samples delete an Involved party record.

involvedService.delete(involved);
//or
//The id initialized here is the id of an existing project Long id = 1234567890L;
involvedService.delete(id); 

Getting Related Records of Projects

When you edit a field with a related record in a project record, you retrieve that field using the Project interface. When you cannot edit a related record field in the project record, the ProjectService interface has methods for retrieving information related to a project. Use the following methods to obtain related records for a project:

• ProjectService.getChildProjects()—Retrieves all child projects records of a particular type related to a Project record.
• ProjectService.getInvolved()—Retrieves all Involved party records related to a Project record.
• Project.getParentProjecct()—Retrieves the parent project of a Project record.
• Project.getEmbeddedProjects()—Retrieves all embedded project records of a particular type related to a Project record.
• Project.getRelations()—Retrieves all projects related to a Project record. The API retrieves information about each relation using the ProjectRelation class.

Note: In some cases, when you need to narrow down the list of related records you are looking for, you may need to search.

For complete samples in Java, see the Looping through Related Records of Projects and Copying Values from Parent to Multiple Child Records samples.

Sub-Objects in the API  

Each sub-object is part of a main object. You retrieve sub-objects using a get method in the main object class. For example, if you want to retrieve a list of attendees for an appointment, use the Appointment.getAttendees method. If you want to retrieve the phone numbers for a contact, use the Contact.getPhoneNumbers method.

You can also add and remove sub-objects using the corresponding methods in the owner interfaces. For example, if you want to add an attendee to an appointment, use the Appointment.addAttendee method. If you want to remove an attendee from an appointment, use the Appointment.removeAttendee method.

Sub-Object Classes  

The following table includes all the frequently used sub-objects and their classes.

Sub-Objects of Main Team Connect Objects  

Project and Task Assignees

Assignees are sub-objects of users assigned to a project or task. The methods for assignees in respective Task and Project interfaces reflect the differences between task and project assignees.

Project and Task Assignee Differences  

Instances of ProjectAssignee or TaskAssignee are always associated with a user. When you add an assignee to a task or project, you must provide a user in order to create the assignee.

For example, the Project.addAssignee() method assigns a project to an existing user, as shown in the following sample, and returns ProjectAssignee with the assigned user.

project.addAssignee("ROLE_TREE_POSI", user);

Contact Sub-Objects

Contacts have many sub-objects, including the sub-objects with the following interfaces:

• Address
• Email
• FaxNumber
• InternetAddress
• PhoneNumber
• DefaultRate
• TaskRate
• InvoiceTaskRate
• ContactRelation
• Skill

In some sub-object lists for a contact, one of the list items is the primary item. Specific methods for getting and setting the primary sub-objects are available in the Contact interface. For example, the phone and fax sub-objects have a primary phone number and a primary fax number. You can retrieve these primary sub-objects with the getPrimaryPhoneNumber() and getPrimaryFaxNumber() methods.

All of the sub-objects of contact have types, which describe the values you enter. Most sub-objects store these types in the system lookup tables, with the exception of the rate sub-objects. The rate sub-objects (DefaultRate, TaskRate, and InvoiceTaskRate) are categories and instances of CategoryDefintion.

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."

Adding or Deleting Categories in Records

If you want to select a category for a record, you can use the addCategory() method from the object's model class. The following code sets External, with a tree position of CONT_EXTE, as a category for a contact:

contact.addCategory("CONT_EXTE");

If you want to deselect a category from a record, you can use the removeCategory() method from the object's model class. The following code removes External from the list of selected categories for a contact:

contact.removeCategory("CONT_EXTE");

For a sample, see Updating Added Categories.

Returning Categories for a Record

If you want to know the categories that are selected for a record, you can use the EnterpriseEntity.getAllCategories() method. The following code returns all selected categories, including the parent categories, for a contact:

List<Category> allCategories = contact.getAllCategories();

If you want to know the lowest-level categories that are selected for a record, you can use the getCategories() method from the object's model class. The lowest-level categories include all the categories that do not have any child categories. If a selected category has lower-level categories that are not selected, getCategories() only returns the selected category. For example, the circled categories in the following image are the lowest-level selected categories.

If the contact record has the categories selected in the previous image, the following code returns the Contact, Federal, Court, and Expert categories for the contact:

List<Categories> categories = contact.getCategories();

In this example, the code does not return Agency because Federal is a lower level category, and it returns Court because none of the lower level categories for Court are selected.

Getting and Setting Primary Categories

If you want to set the primary category of an object, you can use the EnterpriseEntity.setPrimaryCategory() method. The following code sample provides an example of how to create a new contact and set its primary category:

// Retrieve the contact service
ContactService contactService = platform.getContactService();
// Create a new, blank contact. The vendor record is a contact which has // previously been created. Set some categories for the contact record Contact contact = contactService.newCompany("vendor"); contact.setPrimaryCategory("CONT_EXTE_LAWF"); contact.addCategory("CONT_EXTE_VEND");
// Save the contact to the database contactService.create(contact); 

If you want to return the primary category of an object, you can use the EnterpriseEntity.getPrimaryCategory() method. The following code sample returns the primary category of a contact:

Category primaryCategory = contact.getPrimaryCategory();

For a complete sample, see the Checking the Default Role in Related Involved Records sample.

Checking Records for Specific Categories

To return whether a record has a particular category, you can use the hasCategory() method and the full tree position of the category. The following code sample checks if a contact has the "Vendor" category:

boolean isVendor = contact.hasCategory("CONT_EXTE_VEND");

For a sample, see the Checking Lists of Added Categories sample.

Requirements for Getting or Setting Custom Field Values

You can get and set most custom fields using methods in the EnterpriseEntity interface. The Project interface has methods to get and set custom fields of Involved type.

To get or set a value in a custom field, you need the following information to locate the necessary field:

• (If the field is not under a root category) The full tree position of the category for the field. You can find the full tree position of a category in the UI of the TeamConnect Setup.
• The name of the custom field, not its label.

You can find field names on the Custom Fields tab of the corresponding object definition in the TeamConnect user interface.

• The type of custom field.

Depending on the field type, you use different methods to get or set the value in the custom field.

• (If the custom field is of type List) The full tree position of the lookup table item in the list.

The following table lists all the methods from the EnterpriseEntity and Project interfaces that allow you to get or set custom field values according to field type.

Lookup Tables in the API  

In the API, you represent lookup tables and their items with the following interfaces:

• LookupItemService—Includes methods that you use to return information about lookup tables and items. For example, you can use the getCustomLookupItems() method to retrieve a list of items in a custom lookup table:

lookupItemService.getCustomLookupItems("CODE");

Note: Use the following code to access LookupItemService: LookupItemService lookupItemService = platform.getLookupItemService();

• LookupItem—Includes methods for retrieving information about lookup table items. For example, the following code uses the getStoredValue() method to retrieve the stored value of a lookup table item:

contact.getLookupFieldValue("categoryFullTreePosition", "fieldName").getStoredValue();

• EnterpriseEntity—Includes methods that system objects and other interfaces extend. For example, you can use the getLookupFieldValue() method with the Contact model interface to return the value for a custom lookup field:

contact.getLookupFieldValue(String treePosition, String fieldName);

LookupItemService Interface  

Most LookupItemService methods return information about the following types of lookup tables and lookup table items:

• System lookup tables—You can retrieve all system lookup tables. Each system lookup table in TeamConnect has a LookupItemService method. For example, use lookupItemService.getContactPhoneNumberTypes() to return a list of the lookup table items for the phone number field in a contact.
• Custom lookup tables—You can retrieve a custom lookup table and item. getCustomLookupItemForTreePostion() returns one item in a lookup table, and getCustomLookupItems() returns the list of items in a custom lookup table.
• Currency—You can retrieve and update the currency lookup table. getCurrencyItemList() returns the list of currencies in the lookup table, and updateCurrencyRates() adds a currency entry to the lookup table.
• Expenses—You can retrieve information about an expense category. readLineItemExpenseCode() returns an item in the expense category lookup table, and readLineItemExpenseUnitPrice() and readExpenseRateScaleValue() return rates and units associated with a category.
• Document types—You can retrieve document types. For example, getAllDocumentTypes() returns the list of document types in a lookup table.

System Lookup Table Tree Positions

The full tree position of a system lookup table item is a combination of the following codes with underscores as delimiters:

• The full tree position of the lookup item's parent item.
• The partial tree position of the item.

In the following image, the Territory Type lookup table in contact records has the code of TERR. If Orange County has the partial tree position OCNT and Southern California has the partial tree position SOCA, the full tree position of Orange County is TERR_SOCA_OCNT.

The following code samples provide examples of how you can use the tree position to retrieve a system lookup table item.

LookupItemService lookupItemService = platform.getLookupItemService();

// Retrieving the “Apple” item within the Fruits custom table
CustomLookupItem apple = lookupItemService.getCustomLookupItemForTreePosition("FRUI_APPL");

// Retrieve all items in the Fruits custom table
List<CustomLookupItem> fruits = lookupItemService.getCustomLookupItems("FRUI");

// Retrieving the “Mobile” item within the Phone Type system table;
SystemLookupItem mobile = lookupItemService.getSystemLookupItemForTreePosition("PHON_MOBI"); 

The following table includes all system lookup tables, their associated LookupItemService method, and their unique codes. Use the unique code of each system lookup table at the beginning of the full

tree position for a lookup table item. The table also lists API model interfaces associated with the lookup tables. If the lookup tables are not associated with a string field, the API class column does not apply.

System Lookup Table Names  

Custom Lookup Table Tree Positions

When you create a custom lookup table, you specify the unique code of the lookup table in the form of a 4-character alphanumeric combination. For example, the unique code of the Occupations custom lookup table might be OCCU.

The full tree position of the root node includes the unique code of the custom lookup table and ROOT. For example, the full tree position of the root node of the Occupations lookup table is OCCU_ROOT.

The full tree position of non-root custom lookup table items include the following with underscores as delimiters:

• The unique code of the custom lookup table.
• The partial tree position of the root node (ROOT).
• The partial tree position of any parent items.
• The partial tree position of the item.

For example, the Occupations custom lookup table in the following image has an HR Associate item with a partial tree position of HRAS and a Human Resources item with the partial tree position HURE. As a result, the full tree position of the HR Associate item is OCCU_ROOT_HURE_HRAS.

The following code samples provide examples of how you can use the tree position to retrieve a custom lookup table item.

lookupItemService.getCustomLookupItemForTreePosition("treePosition");

//Retrieving “Big Budget Hits” custom item in the “Released Movies” custom table 
//Table Code: RMOV, Item Tree Position: BBHT
CustomLookupItem movie = lookupItemService.getCustomLookupItemForTreePosition("RMOV_ROOT_BBHT");

//Retrieving “Comedy” child item of the “Big Budget Hits” custom item 
//Table Code: RMOV, Item Tree Position: CMDY

CustomLookupItem comedy = lookupItemService.getCustomLookupItemForTreePosition("RMOV_ROOT_BBHT_CMDY"); 

Getting or Setting Values in List Custom Fields

The following sections demonstrate how to get or set values in List custom fields.

Setting Values in Lists  

When you set values in List custom fields, you must include the following information:

• The full tree position of the category for the custom field.
• The name of the List custom field.
• The full tree position of the item in the lookup table.

You can use the EnterpriseEntity.getLookupFieldValue() without the full tree position of the category, as shown in the following code sample.

contact.setLookupFieldValue("HR Associate", "OCCU_ROOT_HURE_HRAS");

If you know the tree position, you can also use it as one of the parameters for the method:

contact.setLookupFieldValue("APPT_AAAA_BBBB", "HR Associate", "OCCU_ROOT_HURE_HRAS");

For a complete sample of custom list fields in Java, see Checking and Setting Values in Custom Fields of Type List.