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 started 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.