Creating Contacts

When creating a contact record, you need to further specify the type of contact you are creating. This is done through the contact argument. To specify a person type contact, pass in a contact created through the PersonCreate object. To specify a company type contact, pass in a contact created through the CompanyCreate object. When you instantiate the PersonCreate or CompanyCreate objects, they are used to store contact record properties. Both the PersonCreate and CompanyCreate objects extend ContactCreate, an abstract class.

Code Snippet for creating a contact of type person and populating a property from a system lookup table

protected ContactRepository contactRepository; PersonCreate person = new PersonCreate();
//firstName is a required field person.setFirstName("John");
//lastName is a required field person.setLastName("Doe");
ContAddressCreate address = new ContAddressCreate(); 
address.setTypeUniqueKey("HOME");
//where the typeUniqueKey value, "HOME", is an existing item's Tree Position value under the system lookup table, Address Type
address.setStreet("2468 Washington Ave."); 
address.setCity("Los Angeles"); address.setState("CA"); 
address.setPostalCode("90026");
person.getAddressCreates().add(address);
String uniqueKey = contactRespository.insertContact(person);
//when you create a contact, the record's unique key is returned
//alternatively you could create a company contact like contactRespository.insertContact(company)
//where company would be an instance of the CreateCompany object

Code Snippet for creating a contact of type company

protected ContactRepository contactRepository; 
CompanyCreate company = new CompanyCreate(); 
//name is a required field company.setName("ACME Inc.");
//taxNumber is used to identify vendor contacts if you are using CSM/Collaborati 
company.setTaxNumber("0112498531");
String uniqueKey = contactRespository.insertContact(company);
//when you create a contact, the record's unique key is returned 

Code Snippet for adding categories and custom fields to a person (contact)

protected ContactRepository contactRepository;
PersonCreate person = createPerson();
String personUniqueKey = contactRepository.insertContact(person); 
private PersonCreate createPerson() { 
    String firstName = "first" + new Date().getTime(); 
    PersonCreate person = new PersonCreate(); 
    person.setFirstName(firstName); 
    person.setBirthdate(Calendar.getInstance().getTime()); 
    ContAddressCreate address = new ContAddressCreate(); 
    address.setTypeUniqueKey("ADDR_HOME"); address.setCity("Portland");
    address.setState("OR"); address.setCountryCodeUniqueKey("COUN_0002"); 
    person.getAddressCreates().add(address); Category cat = new Category();
    //the next two lines identify a category and then add the category to the contact record
    cat.setUniqueKey("CONT_EXTE"); 
    person.getCategories().add(cat); 
    Category cat2 = new Category(); 
    person.getCategories().add(cat2); 
    cat2.setUniqueKey("CONT");
    //the next four lines create a placeholder for an existing Boolean custom field, identify the known custom field name 
    (synched), set the custom field value, and add the custom field placeholder to its parent category
    BooleanCustomField synched = new BooleanCustomField(); synched.setFieldName("synched"); 
    synched.setValue(true); 
    cat2.getBooleanCustomFields().add(synched); 
    TextCustomField primaryLanguage = new TextCustomField(); 
    primaryLanguage.setFieldName("primaryLanguage"); 
    primaryLanguage.setValue("Englishe US"); 
    cat2.getTextCustomFields().add(primaryLanguage);
    return person;
} 

Updating Contacts

When updating contacts, use the PersonUpdate or CompanyUpdate objects as parameters to the ContactRepository updateContact method.

Some data associated with a contact record is stored through separate objects. For example, a contact's rates are added through the ContRateCreate object. In addition, contact rates are updated through the ContRateUpdate object. The same concepts apply to a contact's mailing addresses (ContAddressCreate), email addresses (ContEmailAddressCreate), internet addresses (ContInetAddressCreate), phone numbers (ContPhoneNumberCreate), fax numbers (ContFaxNumberCreate), relations (ContRelationCreate), skills (ContSkillCreate), and territories (ContTerritoryCreate).

To delete certain data associated with a contact record (for example, rates, mailing addresses, email addresses, internet addresses, phone numbers, fax numbers, relations, skills, territories), use the following:

PersonUpdate.getRateDeleteUniqueKeys().add(newItem);

where newItem is the unique key of the rate to delete. Note that you need to repeat the line above for each rate to delete.

Also see the code snippets under Creating Contacts for comments about required contact fields.

Code Snippet for updating existing properties

protected ContactRepository contactRepository;
//for this example, it is assumed that you already know the target contact record's unique key 
(where uniqueKey is a String variable)
PersonUpdate personUpdate = new PersonUpdate(); 
personUpdate.setUniqueKey(uniqueKey); 
personUpdate.setLastName("Doe II"); 
contactRepository.updateContact(personUpdate);

Code Snippet for clearing existing property values

protected ContactRepository contactRepository;
//for this example, it is assumed that you already know the target contact record's unique key 
(where uniqueKey is a String variable)
PersonUpdate personUpdate = new PersonUpdate(); 
personUpdate.setUniqueKey(uniqueKey); 
personUpdate.getClearedProps().addAll(getPropertiesToClear()); 
private List<String> getPropertiesToClear() {
List<String> properties = new List<String>(); 
properties.add("firstName"); 
properties.add("lastName"); 
properties.add("address.type"); 
properties.add("address.state");
return properties;
}

Code Snippet for adding contact rates

protected ContactRepository contactRepository;
//for this example, it is assumed that you already know the target contact record's unique key 
(where uniqueKey is a String variable)
PersonUpdate personUpdate = new PersonUpdate(); 
personUpdate.setUniqueKey(uniqueKey); 
ContRateCreate rate = new ContRateCreate(); 
Date today = new Date(); 
rate.setFirstEffectiveDate(today);
rate.setLastEffectiveDate(new Date(today.getTime() + 100000)); 
rate.setRate(new BigDecimal(20)); 
rate.setTaskCategoryCode("TASK_DEFA"); 
personUpdate.getRateCreates().add(rate); 
contactRepository.updateContact(personUpdate);

Code Snippet for updating a contact's custom field values

protected ContactRepository contactRepository;
//for this example, it is assumed that you already know the target contact record's unique key 
(where uniqueKey is a String variable)
PersonUpdate personUpdate = new PersonUpdate(); 
personUpdate.setUniqueKey(uniqueKey);
Category cat = new Category(); 
personUpdate.getCategories().add(cat);
//The category should already exist. You should get its unique key (tree position) from TeamConnect.
cat.setUniqueKey("CONT_EXTE");
TextCustomField primaryLanguage = new TextCustomField(); 
cat.getTextCustomFields().add(primaryLanguage); 
primaryLanguage.setFieldName("primaryLanguage"); 
primaryLanguage.setValue("Chinese PRC"); 
contactRepository.updateContact(personUpdate);

Reading Contacts

When reading a contact record, identify the target record by unique key. Use the ContactRepository readContact method.

Code Snippet

//for this example, it is assumed that you already know the target account record's unique key
(where uniqueKey is a String variable)
protected AccountRepository accountRepository; 
public void readAccount() throws Exception {
    Person readPerson = (Person) contactRepository.readContact(uniqueKey, getPropertiesToRead());
}
private List<String> getPropertiesToRead() {
    List<String> properties = new List<String>(); 
    properties.add("firstName"); 
    properties.add("lastName"); 
    properties.add("address.type"); 
    properties.add("address.state");
    return properties; 
} 

Searching for Contacts

When searching for contacts, use the ContactRepository readContactsByCriteria method. Use the Person, Company, and Contact data objects to reference the field names you can use in the search criteria and include in the properties list for values to return with the search results (contact records). From the search results, the numeric limit value you set determines how many contact records will be returned. Similar to when you are reading a contact record, you must specify the names of property values to return with search results.

For more general information about how to define search criteria, see Searching Records.

Code Snippet for readContactsByCriteria

//for this example, it is assumed that at least one contact record that meets the search criterion already exists
protected ContactRepository contactRepository;
public void searchPersonContacts() throws Exception { 
    StringFieldCriterion fieldCriterion = new StringFieldCriterion(); 
    fieldCriterion.setComparator(StringComparator.EQUALS_ENFORCE_CASE);
    LegacySearchFieldPathExpression fieldPathExpression = new LegacySearchFieldPathExpression();
    fieldPathExpression.setSearchKeyPath("firstName"); 
    fieldCriterion.setFieldPath(fieldPathExpression); 
    fieldCriterion.getValue().add("John");
    FieldSearchClause searchCriteria = new FieldSearchClause(); 
    searchCriteria.setOperator(LogicOperator.AND); 
    searchCriteria.getCriteria().add(fieldCriterion);
    List<Contact> contacts =
    contactRepository.readContactsByCriteria(searchCriteria, 100, 
    getPropertiesToRead());
}
private List<String> getPropertiesToRead() { 
    List<String> properties = new List<String>(); 
    properties.add("firstName"); 
    properties.add("lastName"); 
    properties.add("addresses.type"); 
    properties.add("addresses.state");
    return properties;
}

Code Snippet for readContactsByCriteria (specify return properties of contact property of type object)

//for this example, it is assumed that at least one contact record that meets the search criterion already exists
//the last three properties defined in the properties list illustrate how you specify contact search return property values 
where the contact property is an object
protected ContactRepository contactRepository;
public void searchPersonContacts() throws Exception { 
    StringFieldCriterion fieldCriterion = new StringFieldCriterion(); 
    fieldCriterion.setComparator(StringComparator.EQUALS_ENFORCE_CASE);
    LegacySearchFieldPathExpression fieldPathExpression = new 
    LegacySearchFieldPathExpression();
    fieldPathExpression.setSearchKeyPath("firstName"); 
    fieldCriterion.setFieldPath(fieldPathExpression); 
    fieldCriterion.getValue().add("John");
    FieldSearchClause searchCriteria = new FieldSearchClause(); 
    searchCriteria.setOperator(LogicOperator.AND); 
    searchCriteria.getCriteria().add(fieldCriterion); 
    List<Contact> contacts =
    contactRepository.readContactsByCriteria(searchCriteria, 100, 
    getPropertiesToRead());
}
private List<String> getPropertiesToRead() { 
    List<String> properties = new List<String>(); 
    properties.add("firstName"); properties.add("lastName");
    properties.add("primaryPhoneNumber.number");
    //where number is a property of the contact property, primaryPhoneNumber (type object)
    properties.add("primaryEmailAddress.address");
    //where address is a property of the contact property, primaryEmailAddress (type object)
    properties.add("defaultRates.rate");
    //where rate is a property of the contact property, defaultRates (type object) return properties;
}

Code Snippet for readContactsByCriteria (search by custom field value)

//for this example, it is assumed that at least one contact record that meets the search criterion already exists
//also assume that a category, Employee (with unique code, EMPL) has been defined for the Contact object definition
//also assume that a custom string field, DLNumb (driver's license number) has been define for the Contact category, 
Employee
protected ContactRepository contactRepository;
public void searchPersonContacts() throws Exception { 
    StringFieldCriterion fieldCriterion = new StringFieldCriterion(); 
    fieldCriterion.setComparator(StringComparator.EQUALS_ENFORCE_CASE);
    LegacySearchFieldPathExpression fieldPathExpression = new LegacySearchFieldPathExpression();
    fieldPathExpression.setSearchKeyPath("CONT_EMPL__DLNumb");
    //note there are two underscores between "EMPL" and "DLNumb" in the searchKeyPath above
    fieldCriterion.setFieldPath(fieldPathExpression); 
    fieldCriterion.getValue().add("B301792Z"); 
    FieldSearchClause searchCriteria = new FieldSearchClause(); 
    searchCriteria.setOperator(LogicOperator.AND); 
    searchCriteria.getCriteria().add(fieldCriterion); 
    List<Contact> contacts =
    contactRepository.readContactsByCriteria(searchCriteria, 100, 
    getPropertiesToRead());
}
private List<String> getPropertiesToRead() { 
    List<String> properties = new List<String>(); 
    properties.add("firstName"); 
    properties.add("lastName"); 
    properties.add("addresses.type"); 
    properties.add("addresses.state");
    return properties;
}

Deleting Contacts

When deleting a contact record, use the ContactRepository deleteContact method. Identify the target record to delete by its unique key.

Code Snippet

//for this example, it is assumed that you already know the target contact record's unique key 
(where uniqueKey is a String variable)
protected ContactRepository contactRepository; 
contactRepository.deleteContact(uniqueKey);