Using 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. The 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 the 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, find 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 pragmatically which purpose enum and extra objects are available the ObjectDef contains various purpose related properties and methods. The code sample below demsontrates their usage. In addiiton when using the FormDefinition 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);
            HP.HPTRIM.SDK.Enum purposeEnum = new HP.HPTRIM.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

HP.HPTRIM.SDK.ActionDef

ActionPurpose

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

HP.HPTRIM.SDK.Activity

ActivityPurposes

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
ActivityPurposes.BrowseTemplate

HP.HPTRIM.SDK.AgendaItem

MeetingPurpose

Purpose Enum	Extra Purpose Enum	Extra Purpose Object
MeetingPurpose.AddAgendaItem

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Table of Contents

Using object purposes

About

Warning

Extra information

Purpose metadata

Code sample - searching

Code sample - post search

Code sample - object definition

List of objects with related purpose enum

HP.HPTRIM.SDK.ActionDef

HP.HPTRIM.SDK.Activity

HP.HPTRIM.SDK.AgendaItem

HP.HPTRIM.SDK.AgendaItemType

HP.HPTRIM.SDK.AutoPartRule

HP.HPTRIM.SDK.CheckinPlace

HP.HPTRIM.SDK.CheckinStyle

HP.HPTRIM.SDK.Classification

HP.HPTRIM.SDK.DocumentQueue

HP.HPTRIM.SDK.ElectronicStore

HP.HPTRIM.SDK.ExternalWorkflowType

HP.HPTRIM.SDK.FieldDefinition

HP.HPTRIM.SDK.History

HP.HPTRIM.SDK.HtmlLayout

HP.HPTRIM.SDK.Jurisdiction

HP.HPTRIM.SDK.Keyword

HP.HPTRIM.SDK.Location

HP.HPTRIM.SDK.LookupItem

HP.HPTRIM.SDK.LookupSet

HP.HPTRIM.SDK.Meeting

HP.HPTRIM.SDK.MeetingType

HP.HPTRIM.SDK.MinuteItemType

HP.HPTRIM.SDK.OfflineRecord

HP.HPTRIM.SDK.Origin

HP.HPTRIM.SDK.Record

HP.HPTRIM.SDK.RecordType

HP.HPTRIM.SDK.Report

HP.HPTRIM.SDK.Request

HP.HPTRIM.SDK.SavedSearch

HP.HPTRIM.SDK.Schedule

HP.HPTRIM.SDK.ScheduledTask

HP.HPTRIM.SDK.SearchForm

HP.HPTRIM.SDK.SecurityCaveat

HP.HPTRIM.SDK.SecurityGuide

HP.HPTRIM.SDK.SecurityLevel

HP.HPTRIM.SDK.Space

HP.HPTRIM.SDK.TodoItem

HP.HPTRIM.SDK.UserLabel

HP.HPTRIM.SDK.Workflow

HP.HPTRIM.SDK.WorkflowTemplate

HP.HPTRIM.SDK.WorkingCopy