Client Proxy

The 3rd party SOAP toolkit should provide a class that creates a client proxy to translate the programming language used in your client application to the XML message format defined in the WSDL files. In your client application, you need to instantiate the given client proxy.

Client API Path

For each client proxy you also need to reference the class name of the client API that will be used. You can do this by passing the target entity name to populate the resulting client API qualified class name. For example, you'd construct the string for the class path to a client interface like :

"com.mitratech.teamconnect.webservice." + entityName.toLowerCase() + "repository." + entityName + "Repository"

(where depending on the repository type you are working with, you would pass in the corresponding entityName, such as Contact)

For more a more detailed example, see the Client Proxy Sample Code section of the Client Application Components (Java/Apache CXF) appendix.

Web Service URL

For each client proxy you also need to reference the URL of the TeamConnect Web Service that will be used. You can do this by passing the target entity name to populate the resulting TeamConnect Web Service URL. For example, you'd construct the string for a TeamConnect Web Service URL like:

"http://" + SERVER + ":" + PORT + "/" + APP NAME + "/webservice/" + StringUtils.uncapitalize(entityName) + "Repository"

(where depending on the repository type you are working with, you would pass in the corresponding entityName, such as Contact)

The format of the resulting Web Service URL would be like:

http://localhost:8080/teamconnect/we...tactRepository

For more a more detailed example, see the Client Proxy Sample Code section of the Client Application Components (Java/Apache CXF) appendix.

SOAP Message Security Header

For each client proxy you can define an interceptor with SOAP message security header content (for TeamConnect authentication). The interceptor should be added to the client proxy once and afterward, the corresponding security header will be automatically inserted into each XML message resulting from a Web Service request.

The interceptor for the message security header needs to contain the following:

• A string variable for the TeamConnect user name used to authenticate to the system.
  If you are writing a Web Service client application in a Software as a Service (SaaS) environment, the user name should use the format: user@domain
• A string variable for the TeamConnect user password used to authenticate to the system. During message transfer the password will be sent as unencrypted clear text.
  If you need to transmit the password in a more secure manner, you can set up SSL between your client application and the TeamConnect instance.

For a more detailed example, see the Security Headers Sample Code section of the Client Application Components (Java/Apache CXF) appendix.

The TeamConnect Web API is compliant with the WS-Security 1.1 OASIS standard. Currently only authentication using the UsernameToken is supported. For more information, see:

http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss

Sample SOAP Message Security Header for Authentication

In your custom application, you should define a security header for SOAP/HTTP requests that looks like:

<soap:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/ oasis-200401-wss-wssecurity-secext-1.0.xsd" soap:mustUnderstand="1">
<wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/ 01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-1809471" xmlns:wsse="http://docs.oasis- open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:Username xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/ oasis-200401-wss-wssecurity-secext-1.0.xsd">administrator</ wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-
200401-wss-username-token-profile-1.0#PasswordText" xmlns:wsse="http://docs.oasis-open.org/wss/2004/...is-200401-wss- wssecurity-secext-1.0.xsd">password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
//administrator should be replaced with a valid TeamConnect user name with sufficient rights to perform required functions.
//password should be replaced with the administrator user's password.

Putting Components Together in a Client Application

In a client application there are two key items to do:

• Instantiate a client proxy and type cast the proxy with the Web Service client interface that corresponds to the entity type you pass as parameter. For example, if you use the entityName, Contact, then you'd cast the proxy as type ContactRepository.
• Add the interceptor for SOAP security header to the client proxy. Afterward you would use the client proxy to make Web Service request calls.

For more a more detailed example, see the Client Application Sample Code section of the Client Application Components (Java/Apache CXF) appendix.

Common Functions

This section shows how you can use TeamConnect® Enterprise Web Services for common functions such as creating, updating, reading, searching, deleting records.

Each TeamConnect Web Service is represented by a repository WSDL file. Each Web Service corresponds to a TeamConnect entity or object type (for example, contacts, projects, accounts, invoices). There are a few recurring methods or operations that are common across all TeamConnect® Enterprise Web Services:

• Creating (Inserting) a record
• Updating a record
• Reading a record
• Searching for records
• Deleting a record

Some TeamConnect® Enterprise Web Services may have additional functions that are particular to that object, for example, posting or voiding records (such as invoices, expenses, tasks), and uploading documents, etc.

Note: Some common functionality is not supported for involved party records.

Creating Records

Each TeamConnect Web Service provides a method for creating a corresponding record. The general form of the method is insertObject (objectDataType). For example, for the Contact repository the corresponding method is insertContact (ContactCreate). The resulting record's unique key is returned.

Updating Records

Each TeamConnect Web Service provides a method for updating a corresponding record. The general form of the method is updateObject (ObjectUpdate). For example, for the Contact repository the corresponding method is updateContact (ContactUpdate). Among the properties of the ContactUpdate object that you need to set, the unique key of the target record to update is required. There is no return value.

An updateObject method does not retrieve all of a record's data before updating its properties. The target record to update is identified by its unique key, then you use set methods to update existing property values or populate empty property values.

To clear existing property values and reset the values to null, use the getClearedProps method provided in the ObjectUpdate class. For example, to update a contact of type person by clearing existing property values, use the PersonUpdate.getClearedProps().add(Item) method. Otherwise use the PersonUpdate.getClearedProps().addAll(Items) method where Items is a list of contact property names whose values to clear.

Reading Records

Each TeamConnect Web Service provides a method for reading a record of its object type. The general form of the method is readObject (String uniqueKey, List<String> properties). For example, for the Contact repository the corresponding method is readContact (String uniqueKey, List<String> properties). The corresponding contact record is returned with only the specified property values.

You can find the list of available properties in the types.wsdl file. For example, to find the properties available for contact records, look for the complex types: company, contact, or person. Each element for those types represents a property that can be returned on read. Similarly you can find the properties in the corresponding client-side source code (for example, in the Contact, Person, Company, ContAddress, ContEmailAddress objects, etc.). For more information, refer to Web Service API Reference.

Searching Records

Each TeamConnect Web Service provides a method for searching records by an object type and by additional search criteria. The general form of the method is readObjectsByCriteria (SearchCriteria criteria, int limit, List<String> properties). For example, for the Contact repository the corresponding method is readContactsByCriteria (SearchCriteria criteria, int limit, List<String> properties). A list of record objects that meet the search criteria is returned with only the specified property values.

Note: When defining the list of property values to return, remember that some of the entity properties are objects. In these cases you need to explicitly specify the property of the property (where the property type is object) to return. For an example, see Code Snippet for readContactsByCriteria (specify return properties of contact property of type object).

The search method provided in TeamConnect® Enterprise Web Services is designed to search among a moderate number of records (for example, if you expect less than 100 records in the search results). For the limit parameter, it is recommended to enter 100 as the maximum number of records to return. If you need to search across a larger volume of records, you may want to use the application UI.

A detailed description of how to define search criteria is provided below. The properties parameter in the readContactsByCriteria method is defined and used in the same way as for the readContact method (described above).

Search Criteria

You need to define search criteria. From the \types directory you need to use the FieldSearchClause object to hold your search criteria. For each search, you need to define the following:

• one or more field criterion
• Field criterion are defined according to the data type for the field you are searching. For example, you can define field criterion for comparing a field that is a String type using the StringComparator and StringFieldCriterion objects.
• an operator (for example, AND or OR) that defines how the field criterion are combined in the search if you are using multiple field criteria

Each field criterion is made up of three parts: a field path (pointer to the database table/column that you will query), a comparator (defines how you are comparing the database record values against a literal value), and a literal value. The parts of a field criterion are illustrated in the following search fields screenshot.

In the contact search screenshot, First Name (1.) corresponds to the field path; Equal To (2.) corresponds to the comparator; and John (3.) is the literal value. Corresponding sample code for search criteria is in the Code Snippet section. See Searching for Contacts for a JAVA example of how to set search criteria.

Searching Records By Custom Field

When defining search criteria where you want to search for a record by a custom field value, you need to define the searchKeyPath using the following format: TCCategoryTreePosition + " " + detailFieldName (where there are two underscores, "_", between the tree position and detail field name).

For example, fieldPathExpression.setSearchKeyPath("DISP CorrectiveActionDeadlineDI");

For a more detailed example, see Code Snippet for readContactsByCriteria (search by custom field value).

Note: If you will search by a custom field value that is associated with a child category, then the TCCategoryTreePosition should be constructed like parentObjectRootCategoryTreePosition + "_" + childCategoryTreePosition " " + detailFieldName (where there is a single underscore, "_", between the root category tree position and its child category tree positions. Also note that an object's root category tree position is the same as the object definition's unique code.

Working with Categories

Web Services support enabling categories for a record, disabling categories for a record, and reading categories (and category properties) for a record.

Before You Begin

You need to get the following information before working with categories using Web Services:

• Category unique key—This value is constructed like <projectUniqueCode + "_" + categoryTreePosition>
  For example, if you are adding a parent category, Contracts, to a dispute record, then the category unique key would be "DISP_CONT"
  (where the tree position for Contracts is "CONT"; and the unique code for the Dispute object is "DISP")
  
  Another example would be if you are adding a child category, Confidentiality Breach, to a dispute record, then the category unique key would be "DISP_CONT_COBR"
  (where the following apply:
  • the tree position for the child category, Confidentiality Breach, is "COBR"
  • the tree position for the parent category, Contracts, is "CONT"
  • the unique code for the Dispute object is "DISP")
• Category name

Enabling Categories

When creating or updating a record, you can enable categories for the record. You can enable multiple categories for a record with the exception of invoice line items, tasks, and expenses.

Important: A category must already exist in TeamConnect before you can enable the category for a record using Web Services. Web Services do not support creating a category for an object definition. Use the TeamConnect Designer UI area to create new categories.

When creating records that are system object or custom object types, the TeamConnect system automatically sets the default category to the corresponding object definition's root category (for example an account record's root category is Account). As a result, you are not required to set a category for records with the exception of invoice line items.

When creating an invoice line item record where the line item type is set to EXPENSE, you need to explicitly set one Expense Category. Otherwise, when creating an invoice line item record where the line item type is set to FEE, you need to explicitly set one Fee/Task Category.

Caution: If you set multiple categories for a line item, only the last set category will be saved.

Note: If a validation rule exists that requires new projects or matters to be saved with a category other than the root category, you may need to enable or add a category to the record when you create it using Web Services.

From the Category type class, use the setUniqueKey (String) method to identify which category you want to add to (enable for) a record. From an ObjectCreate class, you would use the getCategories() method to add an instance of the Category class for the type of record you are creating. For example:

Category cat = new Category();
cat.setUniqueKey("CONT_EXTE");
PersonCreate person = PersonCreate();
person.getCategories().add(cat);

Use the getCategories() method to:

• enable categories for a record during record creation or
• enable additional categories for a record during record update

Reading Primary Categories

If a record has multiple categories and you are only interested in getting the primary category, include primaryCategory in the properties parameters.

Disabling Categories

When updating a record, use the getCategoryDeleteUniqueKeys() method to disable a category for that record. For example:

PersonUpdate person = PersonUpdate();
person.getCategoryDeleteUniqueKeys().add("CONT_INTR");
\\where "CONT_INTR" is the unique key of the category to disable

Reading Categories

Reading categories for a record is different from reading other record properties in that in the properties (List of string property names) parameter, you include "categories". The returned record object will include a list of category objects for that record (including all of that record's custom fields).

Important: Reading categories is the exception to the general rule that when you specify a record's properties to read, for properties that are objects, you need to specify the non-object property of the parent object property to retrieve.

For example:

Person readPerson = (Person)contactRepository.readContact(uniqueKey,
getPropertiesToRead());
}
private List<String> getPropertiesToRead() {
    List<String>
    properties = new ArrayList<String>();
    properties.add("firstName");
    properties.add("lastName");
    properties.add("address.type");
    properties.add("categories");
    return properties;
}

Working with Custom Fields

Web Services support populating, editing, clearing, and reading custom field values.

PersonCreate person = createPerson();
Category cat2 = new Category();
cat2.setUniqueKey("CONT");
BooleanCustomField synched = new BooleanCustomField();
synched.setFieldName("Synchronized");
synched.setValue(true);
cat2.getBooleanCustomFields().add(synched);
person.getCategories().add(cat2);

Clearing Custom Field Values

Use the custom field type class' setValue() method to clear a custom field's value. For example:

PersonUpdate person = PersonUpdate();
Category cat2 = new Category();
cat2.setUniqueKey("CONT");
BooleanCustomField synched = new BooleanCustomField();
synched.setFieldName("Synchronized");
synched.setValue();
//in this case set the value to null to clear the current custom field value. if the custom field were a String type, you'd set the value to ""
cat2.getBooleanCustomFields().add(synched);
person.getCategories().add(cat2);

Deleting Records

Each TeamConnect Web Service provides a method for deleting a corresponding record. The general form of the method is deleteObject (String uniqueKey). For example, for the Contact repository the corresponding method is deleteContact (String uniqueKey). There is no return value.