Repository Classes

Before you begin, you should understand that each TeamConnect object type is associated with a repository class (for example, ContactRepository). Methods are provided per repository for common TeamConnect functions. For example:

• insertContact (ContactCreate contact)
• updateContact (ContactUpdate contact)
• readContact (String uniqueKey, List properties)
• readContactsByCriteria (SearchCriteria criteria, Int limit, List properties)
• deleteContact (String uniqueKey)

Note: For a list of available properties that can be retrieved per record, see the elements listed in the original types.xsd file under the webservices directory. For example, the complexTypes, person, has a list of elements whose names are available properties to read or search from TeamConnect .

One HTTP request results from each repository class call. However, there are multiple subclasses associated with each TeamConnect object type (or repository class) that you use to store data (such as field values) when inserting (creating), updating, reading, or deleting TeamConnect records.

In a client program you instantiate a repository class once but you can use that repository instance multiple times to work with multiple records. You use the type classes or record unique keys as parameters to identify which record you are working with per request.

Selective Record Updating and Reading

To maximize performance, methods to update type classes (TeamConnect records) and read type classes (TeamConnect records) allow you to specify the properties you want to update or read.

When you update a type class (TeamConnect record) using a Web Service, you identify the record to update by passing its unique key. The update request only updates your specified properties.

Unlike a record update made by a TeamConnect rule, the record does not need to be retrieved first in order to change a property. This feature offers better performance through fewer HTTP requests and smaller data packets.

When you read a type class (TeamConnect record) using a Web Service, you must specify which properties to return. Only the specified property values are returned with a corresponding object. This feature improves performance through smaller data packets.

Note: When a record is read by a TeamConnect rule, the returned object includes all of its property values.

Important: When reading records, any properties you do not include in the List<String> properties parameter may be returned with a null or 0 (zero) value. For example, if you are reading a contact record and specify three property values to return out of 24 properties available, then the remaining 21 properties will be returned with either null or 0 values. Note that you should ignore the null and 0 values for properties you did not explicitly retrieve.

Data Types

After you use a 3rd party tool (for example, Apache CXF wsdl2java) to generate client-side source code, you can view the resulting classes that provide information about data types in the corresponding directory: ...\com\mitratech\teamconnect\webservice\type

Dates and Time Zone Independence

When working with date fields (properties of type Date), dates can be either time-zone independent or time-zone dependent. You need to refer to the types.xsd and find the property's corresponding element type. If the element type is "dateTime" then the date value is time-zone dependent. If the type is "date" then the date value is time-zone independent.

Request and Response Formats

Each repository method (request) call in your client application will be translated by the client proxy (provided by the SOAP toolkit) into an XML message with a SOAP wrapper. Each repository method results in one SOAP request over HTTP to the Web Service (TeamConnect ) server.

Note: Each SOAP request requires authentication to the TeamConnect system. See SOAP Message Security Header for more information.

Error Handling

There are a few types of errors you may receive.

• Permission Denied errors will result if the user ID provided during authentication doesn't have sufficient access rights to perform the requested functions.
• Client-side errors. For example, an error would result if you tried to create a record but didn't populate one of its required fields.
• Server-side errors. After you generate client-side source code from the WSDL files, the WebServiceFaultDetail class provides a property, detailedErrorMessage, that is a wrapper for server-side error messages.

For server-side errors, the server throws the error, which is wrapped in an .XML message. This message is returned to the client and translated to a .JAVA object (or the appropriate programming language object equivalent) with the exception.

Record Unique Keys

Note: This section describes the current convention of a record's unique key. This definition may change in the future.

When updating, reading, or deleting records, you need to pass the desired record's unique key. The unique key format is like: TC_Object_Definition_Unique_Code + "_" + TC_record_primary_key (for example, an invoice's unique key might look like INVC_3055).

Note: The unique key value is not stored directly in the TeamConnect database. It is constructed by two values stored separately in the database.

If you don't know a record's unique key and want to read or retrieve its properties, you can alternatively use the readXByCriteria request. For example, to read a contact you can use the contactRepository readContactsByCriteria request. You can either specify the properties to read in the target record directly as a readContactsByCriteria parameter or you can just retrieve the uniqueKey property in the search results and pass this value in the readContact request. Typically you will search or use the readXByCriteria request to get a record's unique key. Then you can use the unique key for update, read, or delete operations.