Using a TaskHistoryCollector

A TaskHistoryCollector lets you gather information about tasks. You create a TaskHistoryCollector using the TaskManager.CreateCollectorForTasks method.

To create a TaskHistoryCollector

1	Identify the type of Task objects that you want to collect, and create an instance of a TaskFilterSpec data object that specifies your filter criteria.

The TaskFilterSpec includes an taskTypeId property, which you use to limit the set of collected task objects to specific types. You can also provide a time range in the TaskFilterSpec by defining an TaskFilterSpecByTime data object for its time property. See the vSphere API Reference.

2	Obtain the managed object reference to the TaskManager on your server instance.

3	Submit the filter and the reference to the server in the CreateTaskHistoryCollector method. The server returns a reference to a TaskHistoryCollector object.

After a HistoryCollector has been created, the server appends new objects that meet the filter criteria to the collection as they occur. The system appends the new object to the collection by placing it in the first position of the latestPage and removes the oldest object from the collection. The latestPage property of the TaskHistoryCollector object has a property that consists of the 1000 most recent objects in the collection. Use a PropertyCollector to obtain the items from the latestPage property.

A HistoryCollector exists only for the duration of the session that instantiated it. Call the HistoryCollector.DestroyCollector method to delete the collector before the session ends.

Creating a TaskHistoryCollector Filter

When you create a TaskHistoryCollector, you can define filters. For example, rather than returning all Task objects associated with virtual machines, you might create a filter to collect only Task objects associated with virtual machines that were executed by the backup-administrator between 2:00 and 4:00 a.m. on a specific date.

The TaskFilterSpec object allows you to specify the collection criteria. Most of the properties are optional and can be submitted as null values. The TaskFilterSpec lets you collect tasks based on user name, entity type, time, and state of the Task.

Managing the HistoryCollector

The HistoryCollector managed object provides operations for managing the life-cycle and scrollable views of a collection.

■	DestroyCollector – A HistoryCollector exists only for the current session. Invoke the DestroyCollector operation to explicitly destroy the collector before the session ends.

■	ResetCollector – Adjusts the starting position for the subset of objects from the collector to the object immediately preceding the current latestPage.

■	RewindCollector – Positions the latestPage to the oldest item in the array. When a HistoryCollector is created, this is the default location.

■

SetCollectorPageSize – Accepts an integer parameter to set the size of the latestPage property of a HistoryCollector. The default size of a HistoryCollector is an array with a maximum of 1000 objects of the appropriate type (Task, Event). The array is sorted by creation date and time of the objects.