Creating a Project With Assignees and a Custom Field

Creating a project record is done using the ProjectRepository object. For example, use the ProjectRepository's insertProject (ProjectCreate project) method. The resulting record's unique key is returned. The insertProject call will result in a SOAP/HTTP request and requires authentication.

When creating a project you can also add one or more assignees. From the type class, ProjectCreate, you need to use the getAssigneeCreates() method (see the example below for how to add items to the resulting list of ProjectAssigneeCreate).

Before you can start, you must get the unique key for the target assignee role and the unique key for the user to add as assignee either from the TeamConnect Designer GUI or from the database.

Note: After you understand how to add assignees to a project, you can apply a similar concept to the procedure for adding relations to a project.

Code Snippet

//in the sample below, basic require fields are commented but it is recommended to 
verify whether additional required fields 
have been defined from the TeamConnect custom object definition or from the 
responsible solution developer
protected ProjectRepository projectRepository; 
ProjectCreate project = createProject(); 
projectRepository.insertProject(project);
private ProjectCreate createProject() throws Exception { 
    Date date = new Date();
    //the EntityTypeUniqueKey is an object's 4-character unique code; 
    look this value up either in the Designer area Object Definitions list or from the database
    String Entity_Type_Unique_Key = "DISP"; ProjectCreate project = new ProjectCreate();
    //entityTypeUniqueKey is a required field project.setEntityTypeUniqueKey(Entity_Type_Unique_Key);
    //name is a required field
    project.setName("Small Claims Forster vs. Gloucster");
    //idNumber is a required field project.setIdNumber("Dispute_1001"); 
    project.setClosedOn(date);
    //the next three lines add a category to the project Category cat = new Category(); cat.setUniqueKey("DISP EXTE"); 
    project.getCategories().add(cat);
    //the next four lines create a placeholder for an existing Text custom field, identify the known custom field name 
    (statusSummary), set the custom field value, and add the custom field placeholder to its parent category
    TextCustomField statusSummary = new TextCustomField(); 
    statusSummary.setFieldName("statusSummary"); 
    statusSummary.setValue("Dispute has been resolved. Settlement reached."); 
    cat.getTextCustomFields().add(statusSummary); project.getAssigneeCreates().addAll(getAssigneeCreates());
    return project;
}
public List<ProjectAssigneeCreate> getAssigneeCreates() { 
    Date date = new Date();
    List<ProjectAssigneeCreate> assignees = new List<ProjectAssigneeCreate>(); 
    ProjectAssigneeCreate assignee1 = new ProjectAssigneeCreate(); 
    assignee1.setRoleUniqueKey("RPRT");
    assignee1.setAssignedOn(date); assignee1.setUnassignedOn(date); 
    assignee1.setUserUniqueKey("USER9614"); 
    assignee1.setActive(True); 
    assignees.add (assignee1);
    ProjectAssigneeCreate assignee2 = new ProjectAssigneeCreate(); 
    assignee2.setRoleUniqueKey("RPRT"); assignee2.setAssignedOn(date); 
    assignee2.setUnassignedOn(date); assignee2.setUserUniqueKey("USER9630"); 
    assignee2.setActive(False);
    assignees.add (assignee2); 
    return assignees;
}

Updating a Project by Adding an Embedded Object Record

Updating a project is similar to updating other record types, such as contacts. You need to use the ProjectRepository's updateProject method. In addition, from the type class, ProjectUpdate, use provided methods to identify the target record and update its property values. Before you can start, you need to know the target project record's unique key.

You can add one or more embedded object records either at the time you update or create a project record. The example below illustrates how to add an embedded object record (Damage) to an existing project record (Dispute).

Note: Adding an embedded object record to a project is analogous to adding an assignee or relation to a project.

Code Snippet

protected ProjectRepository projectRepository; ProjectUpdate project = updateProject(); 
projectRepository.updateProject(project);
private ProjectUpdate updateProject() throws Exception { 
    String date = String.valueOf(new Date().getTime());
    //the EntityTypeUniqueKey is an object's 4-character unique code; 
    look this value up either in the Designer area Object Definitions list or from the database
    String Entity_Type_Unique_Key = "DISP"; ProjectUpdate project = new ProjectUpdate();
    //the next line identifies which record to update by its unique key project.setUniqueKey("DISP_2468"); 
    project.setEntityTypeUniqueKey(Entity_Type_Unique_Key); project.setName("Small Claims Forster vs. Gloucster"); 
    project.setClosedOn(date);
    project.setIdNumber("Dispute_1001");
    //the next three lines add a category to the project Category cat = new Category();
    //the category must already be created in TeamConnect ; you need to get the unique 
    key from the TeamConnect GUI or database
    cat.setUniqueKey("DISP EXTE"); project.getCategories().add(cat);
    project.getEmbeddedEntityCreates().add(getEmbeddedEntityCreates()); 
    return project;
}
public EmbeddedEntityCreate getEmbeddedEntityCreates() { 
    Date date = new Date();
    // List<EmbeddedEntityCreate> embeddedEntities = new List<EmbeddedEntityCreate>();
    EmbeddedEntityCreate embeddedEntity = new EmbeddedEntityCreate();
    embeddedEntity.setName("Damage_1002");
    //the embedded object or project object definition must already exist in TeamConnect ; 
    you need to get the embedded object's 
    4-character unique key (Unique Code) from the TeamConnect GUI or database
    embeddedEntity.setEntityTypeUniqueKey("DAMA"); 
    embeddedEntity.setContactUniqueKey("cont_1004"); 
    embeddedEntity.setIdNumber("Damage_1002"); 
    Category catEmbedded = new Category();
    //the embedded object's category must already exist in TeamConnect; 
    you need to get the corresponding category's 
    unique key from the TeamConnect GUI or database
    catEmbedded.setUniqueKey("DAMG"); 
    embeddedEntity.getCategories().add(catEmbedded); 
    return embeddedEntity;
}

Changing a Project's Phase

When changing a project's phase, you must have already gathered the record's unique key as well as the unique key of the target phase to transition to. The ProjectRepository changePhase method will be validated against existing Phase Transition definitions for the project object definition.

Code Snippet

proj.Repository.changePhase("DISP_1004", "OPNN_OPEN");

Reading Projects

Reading a project record is similar to reading a contact record. A main difference would be when you request the categories property in the resulting project record's returned property values. By default, the returned list of categories also stores all property values associated with all project categories.

Code Snippet

//for this example, it is assumed that you already know the target project record's unique key 
(where uniqueKey is a String variable)
protected ProjectRepository projectRepository; public void readProject() throws Exception {
Project project = (Project) 
projectRepository.readProject(uniqueKey, getPropertiesToRead());
}
private List<String> getPropertiesToRead() { 
    List<String> properties = new List<String>(); 
    properties.add("name"); properties.add("idNumber"); 
    properties.add("currentPhase.storedValue"); 
    properties.add("assignees"); 
    properties.add("categories");
    return properties;
}

Reading Child Projects for a Record

The sample below illustrates how you can read child projects of a project record by the child project type (project's 4-character unique code).

Code Snippet

// in this sample, it is assumed there is an existing parent project record with a unique key String, parentKey
// it is also assumed that there are one or more child project records (where the custom object definition's unique code is 
"CLAI")
protected ProjectRepository projectRepository;
public void readChildProjectsForEntityType() throws Exception {
    // in the list of child Projects returned, only the name properties will be returned
    List<Project> children = 
    projectRepository.readChildProjectsForEntityType(parentKey, "CLAI", 
    Arrays.asList("name"));
}

Searching for Projects

Searching for projects is similar to searching for other object types. The following example illustrates how to search among projects for the following criteria: a given project phase, and given main assignee (by their user name).

Code Snippet

protected ProjectRepository projectRepository; 
public void searchProjects() throws Exception {
    StringFieldCriterion fieldCriterion1 = new StringFieldCriterion(); 
    fieldCriterion.setComparator(StringComparator.EQUALS_ENFORCE_CASE);
    LegacySearchFieldPathExpression fieldPathExpression1 = new LegacySearchFieldPathExpression();
    fieldPathExpression1.setSearchKeyPath("currentPhase.storedValue"); 
    fieldCriterion1.setFieldPath(fieldPathExpression1);
    //need clarification if unique key or name
    //if unique key, then filtering for projects that are in phase, Closed fieldCriterion.getValues().add("CLOS");
    FieldSearchClause searchCriteria = new FieldSearchClause(); 
    searchCriteria.setOperator(LogicOperator.AND); 
    searchCriteria.getCriteria().add(fieldCriterion1);
    //the following section defines a second fieldCriterion item for StringFieldCriterion 
    fieldCriterion2 = new StringFieldCriterion(); 
    fieldCriterion.setComparator(StringComparator.EQUALS);
    LegacySearchFieldPathExpression fieldPathExpression2 = new LegacySearchFieldPathExpression();
    fieldPathExpression2.setSearchKeyPath("mainAssignee.user.username"); 
    fieldCriterion2.setFieldPath(fieldPathExpression2); 
    fieldCriterion.getValue().add("JohnDoe"); 
    searchCriteria.getCriteria().add(fieldCriterion2);
    List<Project> projects = projectRepository.readProjectsByCriteria(searchCriteria, 100,
    getPropertiesToRead());
}
private List<String> getPropertiesToRead() { 
    List<String> properties = new List<String>(); 
    properties.add("name"); 
    properties.add("idNumber");
    return properties;
}

Deleting a Project

The following sample deletes a project record. You must get the unique key value for record to delete.

Code Snippet

//for this sample it is assumed that a project record exists with the unique key equal to a String, uniqueKey
protected ProjectRepository projectRepository;     
projectRepository.deleteProject(uniqueKey);

Involved Records

An involved is a unique record typically associated with a matter or project.

Inserting Involved records

Inserts or creates an involved party record (associated with a project/matter). Often, an involved will be created and added to a project record at the same time as the project creation. This example assumes a project has already been created.

Code Snippet

protected InvolvedRepository involvedRepository;
String uniqueKey = Repository.insertInvolved(involved); private void createInvolved() {
    InvolvedCreate involved = new InvolvedCreate();
    //the following are required fields
    //in the following line, "DINV" is the unique code of the Involved object definition, 
    which is a child of the related Dispute 
    (project) object definition
    involved.setEntityTypeUniqueKey("DINV");
    //in the following line, "DISP_2008" is the existing dispute record unique key 
    involved.setProjectUniqueKey("DISP_2008");
    //in the following line, "CONT_5497" corresponds to the unique key of the contact 
    record for the person you are adding as the 
    involved to a project
    involved.setContactUniqueKey("CONT_5497"); involved.setActive(true);
    Category cat = new Category();
    //the next two lines identify a category and then add the category to the involved record; 
    this category corresponds to the involved party's default role
    cat.setUniqueKey("DINV_MNGR"); involved.getCategories().add(cat); return involved;
}

Updating Involved records

Updating an involved is similar to updating other record types, such as contacts, except that you will be updating only the involved record's categories, custom field values, or clearing existing property values. You need to use the InvolvedRepository's updateInvolved method. Before you can start, you need to know the target record's unique key.

Code Snippet

private InvolvedRepository involvedRepository; Date date = new Date();
InvolvedUpdate involved = new InvolvedUpdate(); Category cat = new Category();
//the next two lines identify a category and then add the category to the involved record
cat.setUniqueKey("INPA_ARBI"); 
involved.getCategories().add(cat); 
Category cat2 = new Category(); 
involved.getCategories().add(cat2); 
cat2.setUniqueKey("INPA_MEDI");
//the next four lines create a placeholder for an existing DateTime custom field, identify the known custom field name 
(InactiveDateDI), set the custom field value, and add the custom field placeholder to its parent category
DateTimeCustomField dateTime1 = new DateTimeCustomField(); 
dateTime1.setFieldName("InactiveDateDI"); 
dateTime1.setValue(date); 
cat2.getDateTimeCustomFields().add(dateTime1); 
DateTimeCustomField dateTime2 = new DateTimeCustomField(); 
dateTime2.setFieldName("InvolvementDateDI"); dateTime2.setValue(date); 
cat2.getDateTimeCustomFields().add(dateTime2); 
involvedRepository.updateInvolved(involved);

Reading Involved records

Reading an involved record is similar to reading a contact record.

Code Snippet

//for this sample, it is assumed there exists an involved record with the unique key equal to a String, invUniqueKey
private InvolvedRepository involvedRepository; private List<String> getPropertiesToRead() {
    List<String> props = new List<String>(); 
    props.add("uniqueKey"); props.add("contact"); 
    props.add("project"); 
    props.add("project.name"); 
    props.add("contact.uniqueKey");
    return props;
}
public void test_readInvolved throws Exception {
    // Search the involved record
    Involved involved = involvedRepository.readInvolved(invUniqueKey, 
    getPropertiesToRead());
}

Reading Involved Parties for a Project Record

The following sample gets requested properties for involved party records that are associated with a project record, given the unique key of the project record.

Code Snippet

readInvolvedsForProject
private InvolvedRepository involvedRepository; 
private List<String> getPropertiesToRead() {
    List<String> props = new List<String>(); 
    props.add("uniqueKey"); 
    props.add("contact"); 
    props.add("project"); 
    props.add("project.name"); 
    props.add("contact.uniqueKey");
    return props;
}
public void test_readInvolvedsForProject throws Exception {
    // Search the involved records for a project
    //in the following operation, "DISP_5941" is the unique key of the project record whose 
    involved party records will be returned
    List<Involved> involvedParties = involvedRepository.readInvolvedsForProject("DISP_5941",
    getPropertiesToRead());
}

Searching Involved Party Records

The following sample searches involved party records by entity type and contact last name.

Code Snippet

//for this sample, it is assumed there exists an involved record with the unique key equal to a String, invUniqueKey
private InvolvedRepository involvedRepository; private List<String> getPropertiesToRead() {
    List<String> props = new List<String>(); 
    props.add("uniqueKey"); 
    props.add("person.lastName"); 
    props.add("person.firstName"); 
    props.add("project"); 
    props.add("project.name"); 
    props.add("contact.uniqueKey");
    return props;
}
public void searchInvolveds() throws Exception {
    StringFieldCriterion fieldCriterion1 = new StringFieldCriterion(); 
    fieldCriterion.setComparator(StringComparator.EQUALS_ENFORCE_CASE);
    LegacySearchFieldPathExpression fieldPathExpression1 = new LegacySearchFieldPathExpression();
    fieldPathExpression1.setSearchKeyPath("entityType.uniqueCode"); 
    fieldCriterion1.setFieldPath(fieldPathExpression1);
    //filtering for involved party records defined by the Involved object 
    definition with the TeamConnect unique code, "DINV"
    fieldCriterion.getValue().add("DINV");
    FieldSearchClause searchCriteria = new FieldSearchClause(); 
    searchCriteria.setOperator(LogicOperator.AND); 
    searchCriteria.getCriteria().add(fieldCriterion1);
    //the following section defines a second fieldCriterion item for StringFieldCriterion fieldCriterion2 = new 
    StringFieldCriterion(); fieldCriterion.setComparator(StringComparator.EQUALS);
    LegacySearchFieldPathExpression fieldPathExpression2 = new LegacySearchFieldPathExpression();
    fieldPathExpression2.setSearchKeyPath("contact.person.lastName"); 
    fieldCriterion2.setFieldPath(fieldPathExpression2); 
    fieldCriterion.getValue().add("Doe"); 
    searchCriteria.getCriteria().add(fieldCriterion2);
    public void test_readInvolvedsByCriteria throws Exception {
    // Search the involved records
    Involved involved = involvedRepository.readInvolvedsByCriteria(searchCriteria, 100,
    getPropertiesToRead());
}

Deleting an Involved

The following sample deletes an involved party record. You must get the unique key value for record to delete.

Code Snippet

//for this sample it is assumed that an involved party record exists 
with the unique key equal to a String, uniqueKey
protected InvolvedRepository involvedRepository; 
involvedRepository.deleteInvolved(uniqueKey);