HP TRIM

Software Version: 7.1

.NET SDK

Document Release Date: July 2011

Software Release Date: July 2011

Legal Notices
Warranty
The only warranties for HP products and services are set forth in the express warranty statements
accompanying such products and services. Nothing herein should be construed as constituting an additional
warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
The information contained herein is subject to change without notice.
Restricted Rights Legend
Confidential computer software. Valid license from HP required for possession, use or copying. Consistent
with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard
commercial license.
Copyright Notices
Copyright 2008-2011 Hewlett-Packard Development Company, L.P.
Trademark Notices
Microsoft, Windows, Windows XP and Windows Vista are U.S. registered trademarks of Microsoft
Corporation.

Documentation Updates
The title page of this document contains the following identifying information:

Software Version number, which indicates the software version.

Document Release Date, which changes each time the document is updated.

Software Release Date, which indicates the release date of this version of the software.

To check for recent updates or to verify that you are using the most recent edition of a document, go to:
http://h20230.www2.hp.com/selfsolve/manuals
This site requires that you register for an HP Passport and sign-in. To register for an HP Passport ID, go to:
http://h20229.www2.hp.com/passport-registration.html
Or click the New users - please register link on the HP Passport login page.
You will also receive updated or new editions if you subscribe to the appropriate product support service.
Contact your HP sales representative for details.

Support
Visit the HP Software Support web site at:
http://www.hp.com/go/hpsoftwaresupport
This Web site provides contact information and details about the products, services, and support that HP
Software offers.
HP Software online support provides customer self-solve capabilities. It provides a fast and efficient way to
access interactive technical support tools needed to manage your business. as a valued support customer,
you can benefit by using the support web site to:

Search for knowledge documents of interest

Submit and track support cases and enhancement requests

Download software patches

Manage support contracts

Look up HP support contacts

Review information about available services

Enter into discussions with other software customers

Research and register for software training

Most of the support areas require that you register as an HP Passport user and sign in. Many also require a
support contract. To register for an HP Passport ID, go to:
http://h20229.www2.hp.com/passport-registration.html
To find more information about access levels, go to:
http://h20230.www2.hp.com/new_access_levels.jsp

Contents

Introduction ........................................................................................................................................................6
Some Provenance .........................................................................................................................................6
Binary Compatibility ...................................................................................................................................6
The Object Browser......................................................................................................................................6
New Functionality........................................................................................................................................7
Lets Get Started.................................................................................................................................................8
Creating a reference to the .Net SDK .........................................................................................................8
Not on the environment path ......................................................................................................................8
Architecture HP TRIM .NETSDK .....................................................................................................................9
Programming into HPTRIM ............................................................................................................................10
Searching HP TRIM using the .NETSDK ................................................................................................10

.NET SDK

Introduction
This document aims to give an overview of programming against HP TRIMs new (version
7.0) .Net SDK. It will assume that you are:
1.

Familiar with HP TRIM, its concepts and usage.

2.

Familiar with programming using .Net based languages.

3.

Familiar with programming using the COM based HP TRIM SDK.

This document will concentrate on getting you started and will emphasise the differences
between the new HP TRIM .NetSDK and the older COM based API. Its is purely about using
the HP TRIMs .Net based API, it will not discuss the HP TRIM Web Service.
This document is still under development The latest version will be available on the HP SSO
(Self Support online) website.
*A note on terminology. The term SDK (Software Development Kit) refers to all
programmable interfaces available for a product. For HP TRIM this now involves the COM
based API, the .NetSDK, and the HP TRIM Web Service. Technically the .Net SDK is an
API, but the usage of the terms SDK and API has blurred and are now commonly used
interchangeable.

Some Provenance
To ensure binary compatibility any objects, methods or properties introduced with or since
HP TRIM 5.0 have had to stay in the COM API even if their function may have been
deprecated. This has lead to a bit of clutter and confusion. The .Net SDK is however a clean
slate, and our past experiences have helped develop a cleaner, clearer interface not
dissimilar to what you are used to with the COM API.

Binary Compatibility
HP will endeavour to maintain binary compatibility of both of the .Net and COM APIs into
the future. This means that a program developed against the HP TRIM 7.0 API will not need
to be recompiled against future releases of HP TRIM in order to run. It does NOT mean that
your applications will continue function in the same way! Testing of your applications
against new releases of HP TRIM is essential. It does NOT mean that your code wont get
compile errors when recompiled against future releases of HP TRIM. The reason for any
compile errors or changes in functionality will be found in the SDK release notes which
document the history of API changes from version to version of HPTRIM.

The Object Browser

When developing a HP TRIM based application you occasionally come to a point where you
are not sure what objects, method or properties the .NetSDK has available to perform a
specific function. This is where the object browser in your IDE comes in handy. HP has
created help strings which provide a simple explanation of all of the objects, methods and
properties available in the .NetSDK these can be seen when using the object browser. Using
the object browser to search for say renditions will give you an idea of what methods or
properties have the rendition in them, from that point using the help strings you can
probably figure out how to do what you are trying to do.

Page 6 of 12

.NET SDK

New Functionality
The areas of major change and new functionality are:Searching Now works for a wider scope of objects, generally more powerful.
Object model The API now has a true object model.
Increased functionality - New Objects, Methods and Properties allow you to do more using
the API.

Page 7 of 12

.NET SDK

Lets Get Started

Creating a reference to the .Net SDK
There is no longer a need for an interop assembly. It was simply a wrapper that allowed
COM components to work within a .Net environment, you now have a native .Net API. From
your .Net IDE you need to find add a reference and then select the HP.HPTRIM.SDK
reference.
You might want to add using HP.HPTRIM.SDK;(C#) or your languages equivalent to your
code, so that you no longer need to reference it for each HP TRIM method and property.

Not on the environment path

HP HP TRIM is not on the Windows environment path, as was the case in some previous
releases. This means that Windows will not be able to find some of the assemblies required
and you will see this error:
Load Exception file not found

Remember it, as you will see it from time to time, here is one solution:Put HP TRIM on the path within the .Net application process before any other HP TRIM
calls. This wont affect the path outside of the process. For example in C# you could do the
following:
using HP.HPTRIM.SDK;
using System;
namespace TestSDK
{
class Program
{
static void Main(string[] args)
{
string trimInstallDir = @"C:\Program Files\Hewlett
Packard\HP TRIM";
string temp = Environment.GetEnvironmentVariable("PATH")
+ ";" + trimInstallDir;
Environment.SetEnvironmentVariable("PATH", temp);
DoTrimStuff();
}
public static void DoTrimStuff()
{
using ( Database db = new Database() )
{
db.Connect();
Console.WriteLine(db.Id);
}
Console.ReadKey();
}
}
}
The lines to note are those placing the HP TRIM folder into the environment path.

Page 8 of 12

.NET SDK

Architecture HP TRIM .NETSDK

Most HP TRIM .NETSDK objects now have constructors and can be created directly. There
are no longer constructors in the Database object.
The main objects
The .NetSDK has a few abstract classes from which most of its objects descend. While it will
be helpful to keep these in mind and understand the object hierarchy they will generally not
be used for simple tasks.
HP TRIM .NETSDK Abstract classes :TrimObject
TrimMainObject
TrimChildObject
TrimChildObjectList
TrimPropertySet
TrimUserOptionSet
TrimSearchStackItem
The following are Objects that you will be using frequently in most situations.
TrimApplication
TrimMainObjectSearch
As well as objects that you are already familiar with which include :Database
Record
Location
The TrimApplication Object
Many of the functions of the COM SDKs Database object have been moved to the
TrimApplication object.

Page 9 of 12

.NET SDK

Programming into HPTRIM

Searching HP TRIM using the .NETSDK
Searching for TRIM Objects
One of the most powerful features of TRIM is the wide range of search criteria that can be
applied to select obects from the Database. SDK.Net provides the TrimMainObjectSearch
class to provide this functionality. This class allows you to combine a number of search
criteria together using boolean logic and then iterate through a resulting set of objects. Note
that the rimMainObjectSearch class can only be used to search for objects of a specified type,
for instance, you can create a TrimMainObjectSearch to retrieve records. As its name
implies, this class can be used to search for any TRIM SDK object that inherits from
TrimMainObject.
Constructing a TrimMainObjectSearch
C# Example
// Construct a search object to search for records
TrimMainObjectSearch records = new TrimMainObjectSearch(db,
BaseObjectTypes.Record);
Specifying the Search Criteria
The TrimMainObjectSearch class provides a number of simple canned methods for
searching that do not involve any boolean logic. These are simple to use if you have a
straightforward query, they include:
SelectByPrefix
SelectFavorites
SelectByUserLabel
SelectNone
SelectAll
SelectByUris
SelectTopLevels
SelectThoseWithin
C# Example
// Construct a search object to search for all records
TrimMainObjectSearch records = new TrimMainObjectSearch(db,
BaseObjectTypes.Record);
records.SelectAll();
The second option is to used the string search syntax available in TRIM (refer to the TRIM
Help file for examples of the syntax). There are three main components to a string search
the primary search string, a set of filters (these work as if they were combined with the
primary search string using a boolean and) and the sort specification. To create a query in
this way, you use the SetSearchString method to specify the primary search string, and then
you can optionally specify any filters using SetFilterString and specify a sort using
SetSortString. This approach is useful if you want to provide the user with a simple edit
control for specifying a search, and is also very useful for web-based applications.
Page 10 of 12

.NET SDK
C# Example
// Construct a search object to search for records
TrimMainObjectSearch records = new TrimMainObjectSearch(db,
BaseObjectTypes.Record);
records.SetSearchString(createdOn:this week and assignee:me)
records.SetFilterString(type:document);
records.SetSortString(createdOn);
A third option is to work with TrimSearchStackItem objects. The primary search criteria is
represented internally as an array of TrimSearchStackItem objects, arranged as a reversepolish stack to indicate operator precedence. A TrimSearchStackItem can be an operator
(TrimSearchOperator) or a search clause (TrimSearchClause). You can build up a query
using the internal search stack of the TrimMainObjectSearch, by using such methods as
AddSearchClause, And, Or and Not. A read of the Wikipedia article on Reverse Polish
notation would be most beneficial for developers unfamiliar with this style of expression.
Because filters are all automatically and-ed together, they are simply represented as an
array of TrimSearchClause items. For sorting, there is a TrimSearchSortItem class and a
corresponding array.
C# Example
// Construct a search object to search for records
TrimMainObjectSearch records = new TrimMainObjectSearch(db,
BaseObjectTypes.Record);
// set up the individual search clauses
TrimSearchClause recordsCreated new
TrimSearchClause(BaseObjectTypes.Record, db,
SearchClauseIds.CreatedOn);
recordsCreated.SetCriteriaFromString(this week);
TrimSearchClause recordsAssigned = new
TrimSearchClause(BaseObjectTypes.Record, db, SearchClauseIds.Assignee);
recordsCreated.SetCriteriaFromString(me);
// apply the clauses to make a reverse polish stack.
records.AddClause(recordsCreated);
records.AddClause(recordsAssigned);
records.And();
// set up the filter
TrimSearchClause documents = new
TrimSearchClause(BaseObjectTypes.Record, db, SearchClauseIds.Type);
recordsCreated.SetCriteriaFromString(document);
// add the filter clause
Records.AddFilter(documents);
// setup a sort item
TrimSearchSortItem sortByDate = new
TrimSearchSortItem(SearchClauseIds.CreatedOn);
// add the sort item
Page 11 of 12

.NET SDK
Records.AddSort. AddSortItemAscending(sortByDate);
These individual classes provide extra features that allow even more elaborate queries to be
built.
Retrieving the results of the search
The TrimMainObjectSearch derives from IEnumerable and so you can use a standard
foreach loop to retrieve items that match the selection. In addition, there are two methods
that will return the search result as an array of unique object identifiers ( corresponds to the
Uri property of a TrimMainObject).
C# Example
// Construct a search object to search for records
TrimMainObjectSearch records = new TrimMainObjectSearch(db,
BaseObjectTypes.Record);
records.SetSearchString(createdOn:this week and assignee:me)
records.SetFilterString(type:document);
records.SetSortString(createdOn);
// iterate through the records mathcing the search
foreach ( Record resultRecord in records )
{
Console.WriteLine(resultRecord.Title);
}
Other search features
Purpose Filtering
You can specify that the items in the selection are eventually intended for a specific pupose.
This may apply additional hidden filtering to the selection, although not always. As you are
iterating through the results, you can use the IsValidForPurpose method to test if the item is
suitable for the purpose specified. Each TrimMainObject has an purpose enumeration
associated with it use this enumeration to specify suitable purpose values for the object you
are selecting.
Persisting a Search
The TrimMainObjectSearch has a SearchAsXML property which will convert the search,
filter and sort criteria to an XML string. This string is language-independent and is
therefore useful if you wish to re-use the same search at some later stage,. Perhaps in a
different locale.
Item Matching
The TrimMainObjectSearch provides an ItemMatches method which allows you to test
whether an existing TrimMainObject matches the search criteria contained within the
search.

Page 12 of 12