Object Purposes

About

Purposes allows a developer to filter the results of a search to only include results fit for a particular purpose. This will exclude objects based on built-in business rules, the active date range and access controls. Purposes are particularly useful when building a user interface, as you filter search results to only include objects useful in the current context.

Warning

Purposes may be used either via TrimMainObjectSearch.SetPurpose(), or TrimObject.IsValidFor(). There are many purposes which do not get applied when using TrimMainObjectSearch.SetPurpose(). For these you need to to either:

• filter your search results using TrimObject.IsValidFor() (or TrimMainObjectSearch.IsValidForPurpose()), or
• display all results and call TrimObject.IsValidFor() when the user selects an item, and notify them at this point that it is not valid.

Extra information

Some purposes require extra information in the form of either an enum value or an object. For example, finding records that are fit for the purpose of containing records of a particular record type. The documentation below lists those purposes that require extra information.

Purpose metadata

For those who need to determine which purpose enum and extra objects are available, the ObjectDef class contains various purpose related properties and methods. The code sample below demonstrates their usage. In addition, when using the FormDefinition class, each page item that supports an object lookup contains the properties EditPurpose and EditPurposeExtra.

Code sample - searching

The sample below only lists those Record Types that are valid for creating folders.

using (Database database = new Database())
{
    database.Id = "J1";
    database.WorkgroupServerName = "local";
    database.Connect();
 
    TrimMainObjectSearch search = new TrimMainObjectSearch(database, BaseObjectTypes.RecordType);
    search.SelectAll();
 
    search.SetPurpose((int)RecordTypeFilter.FolderToCreate);
 
    foreach (RecordType rec in search)
    {
        Console.WriteLine(rec.Name);
    }
}

Code sample - post search

Many purposes cannot be efficiently applied in a database search and therefore must be run on the results once returned. The code below sets the purpose on the search but then uses TrimMainObjectSearch.IsValidForPurpose() to do the actual filtering. This code will find all Records which are valid containers for a Record of type Document.

using (Database database = new Database())
{
    database.Id = "J1";
    database.WorkgroupServerName = "local";
    database.Connect();
 
    TrimMainObjectSearch search = new TrimMainObjectSearch(database, BaseObjectTypes.Record);
    search.SelectAll();
 
    search.SetPurpose((int)RecordPurposes.DefaultContainer, new RecordType(database, "Document"));
 
 
    foreach (Record rec in search)
    {
        if (search.IsValidForPurpose(rec))
        {
            Console.WriteLine(rec.Title);
        }
    }
}

Code sample - object definition

This code sample demonstrates how to interrogate an ObjectDef to determine whether it supports purpose filtering, and if so, which of the purpose enum values support extra information.

using (Database database = new Database())
{
    database.Id = "J1";
    database.WorkgroupServerName = "local";
    database.Connect();
 
    foreach (ObjectDef objectDef in ObjectDef.SelectAllMainObjects(database))
    {
 
        if (objectDef.PurposeEnum != AllEnumerations.Unknown)
        {
            Console.WriteLine(objectDef.PurposeEnum);
            TRIM.SDK.Enum purposeEnum = new TRIM.SDK.Enum(objectDef.PurposeEnum, database);
 
            Console.WriteLine("****  {0}  ({1})****", objectDef.Caption, purposeEnum.Caption);
            foreach (EnumItem purposeItem in purposeEnum.GetItemArray())
            {
                if (objectDef.HasExtraPurposeParameter(purposeItem.Value))
                {
                    AllEnumerations extraItem = objectDef.ExtraPurposeEnum(purposeItem.Value);
 
                    if (extraItem == AllEnumerations.Unknown)
                    {
                        Console.WriteLine("Purpose object type: {0}", objectDef.ExtraPurposeObjectType(purposeItem.Value));
                    }
                    else
                    {
                        Console.WriteLine("Purpose enum: {0}", extraItem);
                    }
                }
            }
        }
    }
}

List of objects with related purpose enum

TRIM.SDK.ActionDef

ActionPurpose

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
ActionPurpose.AssignToRecord
ActionPurpose.AttachStep		ActionDef

TRIM.SDK.Activity

ActivityPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
ActivityPurposes.BrowseTemplate

TRIM.SDK.AgendaItem

MeetingPurpose

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
MeetingPurpose.AddAgendaItem

TRIM.SDK.AgendaItemType

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.AutoPartRule

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.CheckinPlace

CheckinToolPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
CheckinToolPurposes.UserCheckin
CheckinToolPurposes.ServerCheckin
CheckinToolPurposes.PersonalMaintenance
CheckinToolPurposes.GroupMaintenance		Location
CheckinToolPurposes.IntegrationDefault
CheckinToolPurposes.DocumentQueueDefault

TRIM.SDK.CheckinStyle

CheckinToolPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
CheckinToolPurposes.UserCheckin
CheckinToolPurposes.ServerCheckin
CheckinToolPurposes.PersonalMaintenance
CheckinToolPurposes.GroupMaintenance		Location
CheckinToolPurposes.IntegrationDefault
CheckinToolPurposes.DocumentQueueDefault

TRIM.SDK.Classification

ClassificationPurpose

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
ClassificationPurpose.ForRecordCreation		RecordType
ClassificationPurpose.RecordSelection
ClassificationPurpose.RecordTypeStart
ClassificationPurpose.Maintain
ClassificationPurpose.Unspecified
ClassificationPurpose.FindContainerFor		RecordType
ClassificationPurpose.AttachDocument
ClassificationPurpose.EditDocument
ClassificationPurpose.BrowseRecords
ClassificationPurpose.ViewDocument
ClassificationPurpose.AttachRendition
ClassificationPurpose.RelocateRecord
ClassificationPurpose.DefaultContainer		RecordType
ClassificationPurpose.FindAlternateContainerFor		RecordType
ClassificationPurpose.GpsSearch

TRIM.SDK.Consignment

ConsignmentPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
ConsignmentPurposes.Maintain
ConsignmentPurposes.DoDisposal

TRIM.SDK.ConsignmentTemplate

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.DocumentQueue

QueueUsageType

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
QueueUsageType.Unspecified
QueueUsageType.Process
QueueUsageType.Maintain
QueueUsageType.CheckoutTo
QueueUsageType.AutoProcess

TRIM.SDK.ElectronicStore

StorePurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
StorePurposes.Default
StorePurposes.Replacement		ElectronicStore
StorePurposes.Maintain
StorePurposes.InactiveDocuments
StorePurposes.MipOrigin

TRIM.SDK.ExternalLink

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.ExternalWorkflowType

ExternalWorkflowTypePurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
ExternalWorkflowTypePurposes.Start
ExternalWorkflowTypePurposes.Initiate		Record
ExternalWorkflowTypePurposes.Search
ExternalWorkflowTypePurposes.Maintain

TRIM.SDK.FieldDefinition

FieldPurposeType

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
FieldPurposeType.UseItem
FieldPurposeType.SearchByItem
FieldPurposeType.MaintainItem
FieldPurposeType.ScheduleTriggerDate
FieldPurposeType.TagsMetadata
FieldPurposeType.AlertMetaSubscriber

TRIM.SDK.History

HistoryPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
HistoryPurposes.BrowseHistory
HistoryPurposes.BrowseForObject	BaseObjectTypes
HistoryPurposes.BrowseRecordSearchHistory
HistoryPurposes.BrowseRecordHistory		Record

TRIM.SDK.Hold

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.HtmlLayout

LayoutPurpose

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
LayoutPurpose.Maintain
LayoutPurpose.Publish	BaseObjectTypes

TRIM.SDK.Jurisdiction

JurisdictionPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
JurisdictionPurposes.Maintain
JurisdictionPurposes.AttachToRecord
JurisdictionPurposes.LocationDefault
JurisdictionPurposes.RecordTypeDefault
JurisdictionPurposes.ClassificationDefault
JurisdictionPurposes.ScheduleTrigger
JurisdictionPurposes.ScheduleKeepForeverList
JurisdictionPurposes.AddChildJurisdiction

TRIM.SDK.Keyword

KeywordPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
KeywordPurposes.Attach
KeywordPurposes.AttachTitle
KeywordPurposes.Remove
KeywordPurposes.Relate		Keyword
KeywordPurposes.Find
KeywordPurposes.Maintain

TRIM.SDK.Location

LocationPurpose

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
LocationPurpose.Current
LocationPurpose.Contact
LocationPurpose.Home
LocationPurpose.Owner
LocationPurpose.Requester
LocationPurpose.SearchOwner
LocationPurpose.WorkflowAssignee
LocationPurpose.WorkflowSupervisor
LocationPurpose.WorkflowStatsGroup
LocationPurpose.MailRecipient
LocationPurpose.MailRecipientSupervisor
LocationPurpose.ReplacementFor		Location
LocationPurpose.AddToMemberOf		Location
LocationPurpose.AddToBossedBy		Location
LocationPurpose.AddToOtherOf		Location
LocationPurpose.AddToHasMembers		Location
LocationPurpose.AddToBossOf		Location
LocationPurpose.AddToHasOthers		Location
LocationPurpose.ProfileProvider
LocationPurpose.AccessControl
LocationPurpose.AddressProvider
LocationPurpose.MaintainLocations
LocationPurpose.NoPurpose
LocationPurpose.LocationDirectory
LocationPurpose.MaintainStaff
LocationPurpose.MaintainExternal
LocationPurpose.MaintainInternal
LocationPurpose.MaintainContacts
LocationPurpose.MaintainOrganizations
LocationPurpose.MaintainUnits
LocationPurpose.MaintainPositions
LocationPurpose.MaintainGroups
LocationPurpose.MaintainUnknown
LocationPurpose.AddToDelegateOf		Location
LocationPurpose.AddToHasDelegates		Location
LocationPurpose.MaintainCommittees
LocationPurpose.MaintainProjectTeams
LocationPurpose.Communicator
LocationPurpose.MaintainVenues
LocationPurpose.MaintainWorkgroups
LocationPurpose.ApproveAgendaItems
LocationPurpose.MeetingVenue
LocationPurpose.TodoAssignee
LocationPurpose.ApproveClassification
LocationPurpose.AddToAdministeredBy		Location
LocationPurpose.AddToAdministratorOf		Location
LocationPurpose.AddCaveatTo		SecurityCaveat
LocationPurpose.RemoveCaveatFrom		SecurityCaveat
LocationPurpose.MaintainStorageProviders
LocationPurpose.SetDefaultSearchForm
LocationPurpose.ArchiveTransfer
LocationPurpose.AlertSubscriber
LocationPurpose.EmailLinkOwner
LocationPurpose.ConsignmentArchivist
LocationPurpose.GpsSearch
LocationPurpose.Editor
LocationPurpose.Reviewer
LocationPurpose.Authorizer
LocationPurpose.UserFieldValue		FieldDefinition
LocationPurpose.SearchUserFieldValue		FieldDefinition
LocationPurpose.ConsignmentApprover
LocationPurpose.Creator
LocationPurpose.Census
LocationPurpose.LabelOwner
LocationPurpose.MeetingAttendee

TRIM.SDK.LookupItem

LookupItemPurposeType

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
LookupItemPurposeType.UseItem		LookupSet
LookupItemPurposeType.SearchByItem		LookupSet
LookupItemPurposeType.MaintainItem		LookupSet
LookupItemPurposeType.ForFieldValue		FieldDefinition

TRIM.SDK.LookupSet

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.MailTemplate

MailTemplatePurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
MailTemplatePurposes.UseItem
MailTemplatePurposes.MaintainItem
MailTemplatePurposes.Alert	BaseObjectTypes

TRIM.SDK.Meeting

MeetingPurpose

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
MeetingPurpose.AddAgendaItem

TRIM.SDK.MeetingType

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.MinuteItemType

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.OfflineRecord

OfflineRecordPurpose

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
OfflineRecordPurpose.AttachToRecord
OfflineRecordPurpose.SelectFolder
OfflineRecordPurpose.CleanupEmptyFolder
OfflineRecordPurpose.Manage

TRIM.SDK.Origin

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.Record

RecordPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
RecordPurposes.Any
RecordPurposes.FindContainerFor		RecordType
RecordPurposes.AttachDocument
RecordPurposes.FindSeries
RecordPurposes.EditDocument
RecordPurposes.RelateTo		Record
RecordPurposes.BrowsingWithinClass
RecordPurposes.ViewDocument
RecordPurposes.AttachRendition
RecordPurposes.DefaultContainer		RecordType
RecordPurposes.SelectClient
RecordPurposes.SelectMatter		Record
RecordPurposes.BrowseClientMatter
RecordPurposes.FindAltContainerFor		RecordType
RecordPurposes.GpsSearch
RecordPurposes.FindTemplate
RecordPurposes.ConsignmentReview
RecordPurposes.ConsignmentApprove
RecordPurposes.UserFieldValue		FieldDefinition
RecordPurposes.ShowRecycleBin
RecordPurposes.SendCommunication

TRIM.SDK.RecordType

RecordTypeFilter

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
RecordTypeFilter.All
RecordTypeFilter.Electronic
RecordTypeFilter.AllForCreate
RecordTypeFilter.ElectronicForCreate
RecordTypeFilter.AllForCreateNoManual
RecordTypeFilter.ElectronicForCreateNoManual
RecordTypeFilter.SuitableForNumberingBy		RecordType
RecordTypeFilter.ForRecordSearch
RecordTypeFilter.OdmaCreateDirect
RecordTypeFilter.FolderToCreate
RecordTypeFilter.FolderToCreateElectronic
RecordTypeFilter.RecordWithinClassification
RecordTypeFilter.RecordWithinClassificationElectronic
RecordTypeFilter.SimpleWebCreate
RecordTypeFilter.ClientCreate
RecordTypeFilter.MatterCreate
RecordTypeFilter.MatterItemCreate
RecordTypeFilter.MatterItemCreateElectronic
RecordTypeFilter.SharePointListItemRecordCreate
RecordTypeFilter.AutoSubfolderCreation		RecordType
RecordTypeFilter.AutoClassificationSubFolder		Record
RecordTypeFilter.SdmFolder
RecordTypeFilter.SdmDocument
RecordTypeFilter.ExternalLinkUsage
RecordTypeFilter.PsoBox
RecordTypeFilter.FasFolder
RecordTypeFilter.FasDocument

TRIM.SDK.Report

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.Request

RequestPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
RequestPurposes.Maintain
RequestPurposes.DeleteRecordRequest		Record

TRIM.SDK.Revision

RevisionPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
RevisionPurposes.BrowseForRecord		Record
RevisionPurposes.PromoteToRecord		Record
RevisionPurposes.PurgeFromRecord		Record
RevisionPurposes.StorageTransfer		Record
RevisionPurposes.ViewMostRecent		Record

TRIM.SDK.SavedSearch

SearchPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
SearchPurposes.Execute	BaseObjectTypes
SearchPurposes.Subselect	BaseObjectTypes
SearchPurposes.Maintain
SearchPurposes.SelectParent	BaseObjectTypes

TRIM.SDK.Schedule

SchedulePurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
SchedulePurposes.UseItem
SchedulePurposes.SearchByItem
SchedulePurposes.MaintainItem
SchedulePurposes.ReplaceReferences		Location
SchedulePurposes.ShowOldVersions

TRIM.SDK.ScheduledTask

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.SearchForm

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.SecurityCaveat

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.SecurityGuide

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.SecurityLevel

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.Space

SpacePurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
SpacePurposes.RecordHome
SpacePurposes.RecordHomeStrict
SpacePurposes.SearchHome	SpaceRecordsSelection

TRIM.SDK.TodoItem

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.UserLabel

LabelPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
LabelPurposes.Attach
LabelPurposes.Remove
LabelPurposes.Find	BaseObjectTypes
LabelPurposes.Maintain		Location
LabelPurposes.SetParent

TRIM.SDK.Workflow

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.WorkflowTemplate

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem

TRIM.SDK.WorkingCopy

GenericPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
GenericPurposes.UseItem
GenericPurposes.SearchByItem
GenericPurposes.MaintainItem