Custom Tasks API: Appendix B

Task Splitting / Task Creation

 

Task Splitting is a new concept within Clarity. The use case is when a task has so many individual items to "process" that it makes sense to divide-and-conquer. This is done by having the task recognize the situation, and divide the items into batches, and kick off "sub-tasks" which will perform a subset of the items in question.

 

The Clarity Custom Tasks API provides both high-level and mid-level classes to support this kind of dynamic task creation, but it is up to each task author to implement the capabilities...

 

The high-level task splitting classes rely on using these conventions for Task Parameter names - while it is possible to use others, it may require further adjustments to the code:

• Split Large Tasks?    (Yes/No) - should the task attempt to split?
• Split if larger than X items:    (integer) - if there are more than X items, it should be split.
• Split into batches of:  (integer) - split into batches of no more than this size

The Mid-Level Classes:

• CreateTaskApiManager:  A static class designed to simplify the creation of sub-tasks.
• TaskCreateOptions: Options for modifying the sub-task when created
• TaskServerInstructionOverrides: Special instructions for task servers processing sub-tasks

The High-Level Classes:

• DividerTaskParameters: Class to identify the task configuration with respect to splitting.
• DividerSetOfViews: Class to help divide into batches when the items are Revit View/Sheets.
• TaskDivider<T> : Class to perform the division of tasks into sub-tasks

CreateTaskApiManager

The CreateTaskApiManager is a static class used to create and monitor tasks and sub-tasks.

Method	Returns	Description
CreateTask( Task template, TaskCreateOptions options = null, TaskServerInstructionOverrides taskServerInstructions = null)	Task Id	Given an existing task object to use as a template, create and launch a subtask, with additional options for task creation and special instructions for task servers.
GetTaskStatuses( Task template, List<int> taskIds)	TaskStatusResults	Retrieve the task statuses of one or more task Ids that you know of.
GetTaskStatusesAndWaitForCompleted( Task template, List<int> taskIds, int maxWaitTimeInSeconds)	TaskStatusResults	Monitor the task statuses of one or more tasks thay you know the ID of. Return when all tasks are in a completed state or the maximum wait time has expired.

 

TaskCreateOptions

Options for modifying a sub-task when created from a template.

Property	Type	Description
Target	String	Fill in if the Task Target should be different than the template task.
ScheduleId	int	Fill in if the TaskSchedule being used as a template should be different than the template task
AddedParameters	List<TaskCreateParameter>	Any additional task parameters that should be added to what was already in the task.
ModifiedParameters	List<TaskCreateParameter>	Any modifications to existing task parameters that should be made when the new task is created.

 

TaskServerInstructionOverrides

Normally the created sub-tasks will have the identical behavior to any other tasks. However, there are certain situations where you may wish to provide extra special instructions for how sub-tasks should behave (such as not running on the same machine as the original task).

NOTE: This is an abstract class that you can inherit from. Use the TaskServerInstructionOverridesDefault as the default implementation.

Property	Type	Description
UseThisTaskServerOnly	bool	Use the same task server as the task was created on.
DoNotUseThisTaskServer	bool	Do Not Claim this task on the same task server that it was created on.
DoNotCombineWithOtherTasks	bool	Should not follow the standard Clarity behavior for combining tasks with the same target for claiming and executing.
ShutdownImmediately	bool	After execution (in a Revit context) shutdown Revit immediately rather than seeking new tasks to execute.

 

DividerTaskParameters

A class which reads the task/task parameters to determine how you have configured whether task splitting should work and the particular configuration for it.

Typical Usage:    var divideParams = DividerTaskParameters.CreateDefault( myTask );

NOTE: This class implements IDividerTaskParameters interface - if you want to use your own task parameters, make your own class that implements the same.

Property	Type	Description
SplitLargeTasks	bool (readonly)	Should the task be split if appopriate (based on the configuration)
SplitIfGreaterThanXItems	int (readonly)	Split if there are more than X items to process.
BatchSize	int (readonly)	What is the maximum batch size if the tasks are to be split
IsSubTask	bool	Is the currently running task ALREADY a sub-task?
SubTaskItemIds	IList<String>	If the current task is a sub-task, what are its list of items to process?

 

DividerSetOfViews

A class that represents a set of Revit Views/Sheets that potentially need to be split.

NOTE: This is an implementation of IDividedSet<T> class that you can also inherit from if you need a different behavior or different type of elements.

Typical Usage:  

  var divideParams = DividerTaskParameters.CreateDefault( myTask );
  var dividedSheets = new DividerSetOfViews( divideParams.BatchSize, myListOfSheets.ToArray() );
// Then send the divider set of views to make your TaskDivider<View>.

Property	Type	Description
static GetSubset( Document doc, IList<string> subTaskItems );	IList<View>	Used to re-create the list of sheets/views to process from the list carried by a sub-task.
(constructor) DividerSetOfViews( int batchSize, View[] views )	DividerSetOfViews	Construct the object that will help the dividing into subsets and reading/writing data to the sub-tasks.
GetChunkListAsSubset(int i)	string	returns the string version of a subset of views, for use as a task parameter in the subtask.
RetrieveItems( IList<string> items)	View[]	From a list of text items, pull the list of views/sheets from the model which matches.

 

TaskDivider<T>

The high-level method to divide a set of items of type <T> into sub-tasks.

Typical Usage: 

   var taskDivider = new TaskDivider<string>(t, files);
   if (taskDivider.ShouldDivide())
   {
      // Divide, and reset our list of files to the first batch.
      files = taskDivider.Divide();
   }

Method	Returns	Description
static  GetTaskDividerForStrings( Task t, string[] listOfStrings, IDividerTaskParameters tp = null)	TaskDivider<string>	Retrieve a fully-configured task divider intended for String items, based on the existing task and the full list of items needed.
(constructor) TaskDivider( Task t, IDividerSet<T> set, IDividerTaskParameters = null)	TaskDivider<T>	Set up a fully-configured task divider intended for a set of type <T>.
ShouldDivide()	bool	Should the task be subdivided, based on the provided set and the rules?
Divide()	T[]	Given the rules and the provided set, split the task (create subtasks). Divide the items into batches, and return back the first batch to the caller, so that it can take care of the first batch.
Wait( int maxWait = 1200)	TaskStatusResults	Wait for all sub-tasks launched by the divider to get to a completed state. Wait for up to a specified maximum amount of time (seconds).
LogAllSubTaskCurrentStatuses	void	Check the current status of all subtasks, and log the information to the task logger.