Return to TRIM Web Service Samples

Search is the most fundamental operation that any TRIM API can provide. Due to the request/response nature of the TRIM Web Service architecture, every call done to the Web Service is stateless. This means the TRIM Web Service will never remember what a client application was looking at previously. Almost any tasks done using the TRIM Web Service will, by necessity, require a search operation.

The RecordSearch Operation exposes the TRIM Record Searching model. TRIM has a powerful and flexible model for searching for records, and in the TRIM Web Service, this is represented as a RecordSeach Operation. The RecordSearch Operation has no methods itself, just a collection of items that represent the search clauses.

Need to add the image showing the object hierarchy.

In order to conduct a search, the process is to create a Record Search Operation, create one or more RecordSearch Clauses, and to append those clauses to the RecordSearch Object. Once that’s been completed, append the search to the TrimRequest, and use the Engine object to execute that request.

If you view the object browser in your IDE you can see that the vast majority of objects created for the TRIM Web Service are RecordSearchClause Objects. These represent the different kinds of searches you can do, and they differ in the number and types of parameters that they take in order to perform a search. Most of these objects contain a property called “type” which allows you to further specify the kind of search you want to do. A typical example, one using text search:

RecordStringSearchClause clause = new RecordStringSearchClause();
clause.Type = RecordStringSearchClauseType.TitleWord;
clause.Arg = "reef";

The “type” of property on RecordStringSearchClause takes a value from an enumeration of RecordStringSearchClauseTypes. If we look at the enumeration in the object browser, we can see:

Need to get another image from the TRIMConnectivityToolkit.pdf

Generally speaking, if a Clause has a type property, it will correspond to an enumeration which lists all the search clauses of that type. There are exceptions – for instance the RecordClassificationSearchClause doesn’t have a type. Instead, it has a ClassificationUri property where you pass in the Uri of the classification you’re looking for. This is because there is only one record clause which takes a classification Uri.

Here is an example of setting up a basic search operation. As with any TRIM Web Service operation, the search consists of a TrimRequest object, which has one or more operations. The request is then passed through to the engine object, which returns a TrimResponse.

// Construct a request object
TrimRequest request = new TrimRequest();
// Construct a RecordStringSearchClause, with type
// TitleWord, and argument "reef"
RecordStringSearchClause clause = new RecordStringSearchClause();
clause.Type = RecordStringSearchClauseType.TitleWord;
clause.Arg = "reef";
// Construct a record search, and put our search clause in it
RecordSearch search = new RecordSearch();
search.Items = new RecordClause[] { clause };
// If we had more than one clause, it would look like:
// search.Items = new RecordClause[] { clause1, clause2, clause3 }
// Put our search operation into our TrimRequest
request.Items = new Operation[] { search };
// Send it off. Whatever comes back will be in response
Engine engine = new Engine();
engine.Credentials = new System.Net.NetworkCredential(username, password);
TrimResponse response = engine.Execute(request);

In this example, the final line that executes the request would return two result objects – a SuccessResult, indicating that the search completed successfully, and an EndResponse. If an operation executes successfully, the Web Service will return you a SuccessResult. If the operation fails, the Web Service will return an ErrorResult with an error message. There will be a SuccessResult or ErrorResult for each operation you execute.

An EndResponse indicates that the Web Service has dealt with everything, and has now forgotten about you. There will always be a single EndResponse.

In the previous example, we didn’t enquire about any of the properties of the Records, the TRIM Web Service conducted a search, noted the successful completion of the search, and finished. This may seem ultra-pedantic, but the reality is that TRIM Records can contain an enormous amount of data.

If you consider the relationship between Records, Locations and other Records, which are properties of a single Record, the possibility for TRIM to get locked in a recursive deathspiral if it returned everything it knew about a record in the results is quite high – so in order to alleviate this, the developers have left it entirely up to you. Additionally only returning the data that you need is the most effective way to use network resources.

To see how to get the properties of the returned records, see the Using the Fetch Operation example.

A search done through the Web Service will be made up of two things. The Search object will contain the information needed to find the object or objects in TRIM. The Fetch object will contain one or more SpecificationProperties objects, each of which indicates a property of the object (or objects) to be returned.

After executing a search, the TrimResponse object that is returned will contain one or more Result objects. A SuccessResult indicates that the operation executed without errors. An ErrorResult contains the details of why an operation failed. A FetchResult is made up of the values matching the SpecificationProperties passed in through the Fetch object. Finally, an EndResponse indicates the last Result object.