HP TRIM

Software Version: 7.35

.NET SDK

Document Release Date: August 2014

Software Release Date: August 2015

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-2015 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
Getting started .................................................................................................................................................... 8
Creating a reference to the .NET SDK ....................................................................................................... 8
Not on the environment path ...................................................................................................................... 8
Architecture HP TRIM .NET SDK .................................................................................................................... 9
The main objects .......................................................................................................................................... 9
HP TRIM .NET SDK Abstract classes ................................................................................................. 9
The TrimApplication object................................................................................................................... 9
Programming into HP TRIM ........................................................................................................................... 10
Searching HP TRIM using the .NET SDK ............................................................................................... 10
Searching for TRIM objects................................................................................................................. 10
Retrieving the results of the search ................................................................................................... 12
Other search features .......................................................................................................................... 12

.NET SDK

Introduction
This document aims to give an overview of programming against HP TRIMs .NET SDK from
version 7. It assumes 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 concentrates on getting you started and emphasises the differences between
the new HP TRIM .NET SDK and the older COM based API. It is purely about using HP
TRIMs .NET based API, it will not discuss the HP TRIM Web Service.
This document is still under development The latest version 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 .NET SDK, 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 endeavours 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 does not need to
be recompiled against future releases of HP TRIM to run. However, it does not mean that
your applications will continue to function in the same way. Testing of your applications
against new releases of HP TRIM is essential. It does not mean that your code will not
produce compile errors when recompiled against future releases of HP TRIM. Reasons for
compile errors or changes in functionality can be found in the SDK release notes which
document the history of API changes from version to version of HP TRIM.

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 .NET SDK 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 objects, methods and
properties available in the .NET SDK. These can be seen when using the object browser.
Using the object browser to search for, for example, 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:

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 enable you to do more
using the API

Page 7 of 12

.NET SDK

Getting 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 will not 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 in the environment path.

Page 8 of 12

.NET SDK

Architecture HP TRIM .NET SDK

Most HP TRIM .NET SDK objects now have constructors and can be created directly. There
are no longer constructors in the database object.

The main objects

The .NET SDK 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 .NET SDK 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 HP TRIM

Searching HP TRIM using the .NET SDK
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. .NET SDK 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
Page 10 of 12

.NET SDK
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.
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);
Page 11 of 12

.NET SDK
// add the sort item
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