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

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

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);
}

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 )