Advanced Topics

Table of Contents

• Different ways to fetch a TrimMainObject
  • Object constructor by Name
  • Object name properties
  • Database find methods
  • TrimMainObjectSearch
• Document access alternatives
  • Overview
  • Record.GetDocument
  • DocumentPathInClientCache
  • DocumentPathInWGSCache
  • DocumentStream
  • DownloadNotifier
  • Other object types
• Localised strings
  • TrimMessages
  • Captions
    • Enum captions
    • Property Captions
    • Search Clause Captions
    • Menu items
  • FormDefinition
• Fetching LookupSet Items
  • Example: Adding a new LookupItem
  • Example: Fetching lookup items
• Create a Record using manual numbering
  • Example: Manual Record Number

Different ways to fetch a TrimMainObject

Accessing a Record is discussed briefly in the help but there are a variety of ways to get a TrimMainObject.

Object constructor by Name

As discussed in the help use the Name or Uri to instantiate the object.

Code example

This example fetches a Classification by number.

Classification classification = new Classification(database, "Accommodation - Domestic - General");
Console.WriteLine(classification.Title);

Object name properties

As can be seen a certain knowledge of the object type is required to fetch by name. For example the name property for each object type is different, for most object types the name property is Name, here is a list of those object types where that rule does not apply:

Object Types	Name Property
ActionDef	ActionName
AgendaItem	Number
Alert	Description
Classification	Title
Communication	Description
Consignment	Number
ConsignmentApprover	Record
ConsignmentIssue	Record
History	EventDescription
Location	SortName
MinuteItem	Description
Notification	Description
OfflineRecord	Title
Record	Number
RecordAction	ActionName
Request	Record
SavedSearch	FullName
ScheduledTask	Description
SharePointItem	UniqueId
Space	Number
TodoItem	Description
UserLabel	FullName
ZipCode	Postcode

Even with this information there are still things to be aware of, for example:

• LocationSortName is not necessarily unique, if you use it in a Location constructor and there is more than one match an exception will be thrown.
• While ClassificationTitle is the name property for Classification ClassificationTitle will also work.

Database find methods

There are a number of methods available on the Database object. They key difference between these and the object constructors is that these return null if the object cannot be found where the object constructors throw an exception. These methods are:

• FindTrimObjectByName
• FindTrimObjectByUri
• FindTrimObjectByURN

Code samples

// fetch by Record Number
Record record1 = database.FindTrimObjectByName(BaseObjectTypes.Record, "REC_1") as Record;
Console.WriteLine(record1.Title);

// Fetch by Uri
Record record2 = database.FindTrimObjectByUri(BaseObjectTypes.Record, 9000000001) as Record;
Console.WriteLine(record2.Title);

// Fetch by URN
Record record3 = database.FindTrimObjectByURN("trim:I1/rec/9000000001") as Record;
Console.WriteLine(record3.Title);

Note: The URN property is typically used when you need to persist a database and object type independent identifier for the object.

TrimMainObjectSearch

TrimMainObjectSearch may be used in place of the constructor and Database methods of fetching a document. One benefit when fetching by name, where the name may not be unique, is that you can respond better to the various scenarios.

Code sample

// Find all Locations where the name starts with David
TrimMainObjectSearch locationSearch = new TrimMainObjectSearch(database, BaseObjectTypes.Location);
locationSearch.SelectByPrefix("david");

foreach (Location location in locationSearch)
{
    Console.WriteLine(location.FullFormattedName);
}

// Find the Locations with the Uri 1
TrimMainObjectSearch locationSearch = new TrimMainObjectSearch(database, BaseObjectTypes.Location);
locationSearch.SelectByUris(new long[] { 1 });

foreach (Location location in locationSearch)
{
    Console.WriteLine(location.FullFormattedName);
}

// Find all Locations who are direct members of the group 'Adelaide'
TrimMainObjectSearch locationSearch = new TrimMainObjectSearch(database, BaseObjectTypes.Location);
locationSearch.SelectThoseWithin(new Location(database, "Adelaide"));

foreach (Location location in locationSearch)
{
    Console.WriteLine(location.FullFormattedName);
}


// Find all Locations where the sort name is david
// You may want to return an error if there is more than one result, if you are looking for a unique Location
TrimMainObjectSearch locationSearch = new TrimMainObjectSearch(database, BaseObjectTypes.Location);
locationSearch.SetSearchString("locSortName:david");

foreach (Location location in locationSearch)
{
    Console.WriteLine(location.FullFormattedName);
}

---

Document access alternatives

Overview

There are a variety of ways to retrieve an electronic document attached to a Record (or other object type), these are:

• Record.GetDocument()
• DocumentPathInClientCache
• DocumentPathInWGSCache
• DocumentStream
• DownloadNotifier

Record.GetDocument

Record.GetDocument is the primary way to get an electronic document from a Record and will be used for most .Net SDK applications. It allows the user to fetch a copy of the document from the document store to their local hard drive. If the document is already in the user's cache then it will be retrieved from their rather than from the store.

Checkout without getting the document

You may wish to set the Record edit status to checked out without fetching the Record, in this case simply call GetDocument with a null outputDocumentName. For example:

Record record = new Record(database, "REC_430");
record.GetDocument(null, true, null, null);

DocumentPathInClientCache

This method of fetching documents was added to better support web services. The advantage it has over Record.GetDocument is that it does not require you to store a new copy of the document, copying it from your local cache to the path in the outputDocumentName parameter. If document store caching is disabled this property will be empty, unless your application is running as a service or web service.

Example

TrimApplication.SetAsWebService("c:\\hptrim\\mytest");

using (Database database = new Database())
{
    database.Id = "I1";
    database.WorkgroupServerName = "local";
    database.TrustedUser = "itu_tenduser";
    database.Connect();

    Record record = new Record(database, "REC_430");
    if (!record.IsDocumentInClientCache)
    {
        record.LoadDocumentIntoClientCache();
    }
    Console.WriteLine(record.DocumentPathInClientCache);
}

DocumentPathInWGSCache

If your workgroup server has document caching enabled an application running on that server (not on a client machines) can use this property to get the Location of the document in the workgroup cache. The benefit of this is that the workgroup server cache can be pre-emptively loaded so the document can be in the cache before event the first time you ask for it.

Example

Record record = new Record(database, "REC_430");
Console.WriteLine(record.DocumentPathInWGSCache);

DocumentStream

The DocumentStream class has two advantages over the other methods of getting documents:

1. it starts returning bytes almost immediately, rather than you having to wait until the entire file has been copied from the document store, and
2. you may start part way through a file.

DocumentStream is of particular use in web applications where you will want to start downloading the file to the end user as soon as possible rather than waiting until the entire file has been fetched from the document store, and also where you may wish to have a resumable download.

Example

This sample wraps the DocumentStream in a .Net Stream, once you have done this you can use it like any other stream, for example copy it to another stream.

Record record = new Record(database, "REC_430");
TrimDocumentStream docStream = new TrimDocumentStream(record);

var fileStream = File.Create("C:\\MyTest\\" + record.SuggestedFileName);

docStream.CopyTo(fileStream);
fileStream.Close();

The essential part of using DocumentStream is calling GetAvailabelData(). Remember to use Thread.Sleep() to wait until data has actually returned, the background thread that pulls the document from the document store is probably fractionally slower than your code.

DocumentStream _docStream = new DocumentStream(_record, false, null, null);

...
public override int Read(byte[] buffer, int offset, int count)
{
    uint bytesRead = 0;

    while (!_docStream.Done() && bytesRead == 0)
    {
        bytesRead = _docStream.GetAvailableData(buffer);

        if (bytesRead == 0)
        {
            Thread.Sleep(100);
        }

        _bytesSoFar += bytesRead;

    }
    return Convert.ToInt32(bytesRead);
}

DownloadNotifier

DownloadNotifier is designed as a simpler more flexible replacement for DocumentStream. As of Content Manager 9.0 it is still in an experimental phase and its interface will likely change in an upcoming release, avoid it for now.

Other object types

While this document has focused primarily on Records other main and child objects also implement ITrimDocument and therefore also support electronic documents. These objects will at least support the Client Cache method of getting the document and may also implement a method returning an ExtactDocument (such as LocationEAddress )

Localised strings

When building a user interface base on the Content Manager SDK it can be helpful to use the captioned and localised strings provided by Content Manager, rather. Most strings used by Content Manager are available from the SDK in a way that will account for the user's language choice and changes to captions.

TrimMessages

TrimApplication.GetMessage() is used to fetch error and other messages from Content Manager. These messages will automatically account for any custom captions.

Code Sample

//This code will display the following string, replacing the word 'record' with the custom caption for 'record' if set.
//
// This record has  alternate contents. You can use the Show Alternate Contents button if you wish to load these relationships.

string message = TrimApplication.GetMessage(database, MessageIds.bob_recHasAltContentsMsg);
Console.WriteLine(message);

Captions

Many custom strings can be fetch from an objects Caption property. This is particularly important when captions have been customised.

Enum captions

This code displays the caption (and plural caption) of the DisposalType enum followed by the captions for each EnumItem.

HP.HPTRIM.SDK.Enum myEnum = new HP.HPTRIM.SDK.Enum(AllEnumerations.DisposalType, database);

Console.WriteLine(myEnum.Caption);
Console.WriteLine(myEnum.CaptionPlural);

foreach (EnumItem enumItem in myEnum.GetItemArray(null, true))
{
    Console.WriteLine(enumItem.Caption);
}

Property Captions

The PropertyDef class supplies captions for object properties, use the code below to get all writable property captions for the Location object. Other static methods to get PropertyDefs by object are:

• PropertyDef.GetAllProperties()
• PropertyDef.GetDataGridProperties()
• PropertyDef.GetViewPaneProperties()

foreach (PropertyDef propertyDef in PropertyDef.GetWriteableProperties(BaseObjectTypes.Location, database))
{
    Console.WriteLine(propertyDef.Caption);
}

Search Clause Captions

Search clause captions work similarly to property definitions except that you must get a list of SearchClause Ids and then construct a SearchClauseDef from the Id. The sample below writes the captions for all Activity search clauses.

foreach (SearchClauseIds clauseId in SearchClauseDef.GetAllSearchClauseIds(BaseObjectTypes.Activity, database))
{
    SearchClauseDef clauseDef = new SearchClauseDef(clauseId, database);

    Console.WriteLine(clauseDef.Caption);
}

Menu items

Menus in Content Manager are a subject to themselves. Once again a definition object, CommandDef, provides metadata such as the menu or status bar string for each menu item.

MenuPopup menuPopup = MenuPopup.GetMenuForTrimObject(database, BaseObjectTypes.Classification);

foreach (var menuItem in menuPopup)
{
    if (menuItem is CommandDef)
    {
        CommandDef cdef = menuItem as CommandDef;
        Console.WriteLine(cdef.GetMenuEntryString(BaseObjectTypes.Classification));
    }
}

FormDefinition

FormDefiniton is particularly useful for Records where it is possible to set custom captions on the various properties on the Record entry form. As with the other definition objects FormDefnition (and its related classes) are useful for much more than captios, in fact they are the foundation from which the Web Client forms are built.

RecordType recordType = new RecordType(database, "Document");
FormDefinition formDefinition = recordType.RecordPropertiesFormDefinition;

for (uint pageCount = 0; pageCount < formDefinition.PageCount; pageCount++)
{
    PageDefinition pageDefinition = formDefinition.GetPage(pageCount);

    Console.WriteLine(pageDefinition.Caption);

    for (uint itemCount = 0; itemCount < pageDefinition.ItemCount; itemCount++ )
    {
        PageItemDefinition itemDefinition = pageDefinition.GetItem(itemCount);
        Console.WriteLine(itemDefinition.Caption);

    }
}

Fetching LookupSet Items

In 82 LookupSet Items were freed from the restrictions of being of type TrimChildObject. This means that a lookup set item is now a TrimMainObject, at the same level as the lookup set itself. Why was this done? Mainly to allow for large lookup sets. The parent child relationship among RM objects has practical limits on the number of children a main object can have.

Example: Adding a new LookupItem

To add a new LookupItem instantiate it using the LookupSet as the constructor paramater.

LookupSet lookupSet = new LookupSet(database, 9000000000);
LookupItem lookupItem = new LookupItem(lookupSet);

lookupItem.Name = "My Test";
lookupItem.Save();

Example: Fetching lookup items

You can get a list of lookup items just as you would any other main object type (e.g. record or location), using the TrimMainObjectSearch, as seen here.

TrimMainObjectSearch lookupItemSearch = new TrimMainObjectSearch(database, BaseObjectTypes.LookupItem);
lookupItemSearch.SetSearchString("set:9000000000");

foreach (LookupItem item in lookupItemSearch)
{
    Console.WriteLine(item.Name);
}

Create a Record using manual numbering

When a Record Type has a Record Number containing both manual and automatic portions then user interaction is required to create the Record. This can be done in the SDK by first suggesting a number (to get the auto-generated portion) and then replacing the manual portion with whatever the user says.

Example: Manual Record Number

string manualPortion = "TRY-THIS";

RecordType rt = new RecordType(database, "RECORD TYPE NAME");

Record rec = new Record(rt);

rec.Title = "test";
string suggestedNumber = rec.GetSuggestedNumber(true);

suggestedNumber = suggestedNumber.Replace("zzz-aaaa", manualPortion);
rec.LongNumber = suggestedNumber;

rec.Save();