Fun with the distributed Agent tasks handler in the Content Server

Lets take a look on the API. We are here in the CSIDE/oScript realm

Introduction

Developers may define their own task handlers which will be used to execute tasks. There are two types of task handler:

• Job Chain
• Simple Job

A Job Chain task handler is used to create a hierarchy of tasks, where each sub-task's results are bubbled up to the parent task. This is similar to a map/reduce implementation. A Simple Job is one where the results of a task execution are not required to be passed up the line.

Quick Start

This section provides a quick menue of what needs to be done to create a Simple Job task handler for the Distributed Agent system.

1. Create your task.Orphan $DistributedAgent : DistributedAgent Objects : WorkerTask : SimpleJobsSet fEnabled to trueSet fKey (best practices are to include your module name as a prefix e.g. ic_AssertionReport)Set fName (this is a display name for the task)
2. Update GetFingerprint to return something specific as the fingerPrint (e.g. fingerPrint = Str.Format( "%1 dataid:%2", .Key(), dataPkg.DataID ) )
3. If the task can be automatically divided into smaller tasks, then implement Split to do this; otherwise, the default Split implementation can be used.
4. Code that you want executed goes in Map
5. Schedule the task from your code.
6. Call $DistributedAgent.MapReducePkg.Map( prgCtx, handlerID, taskData, priority, activationDate) where:
7. handlerID is the key of the WorkerTask (fKey)
8. taskData has all the specific parameters for this task (for your task handler's Map & GetFingerprint functions and is used to create taskrec )
9. fpriority is optional. The priority of the task. This is important when sending multiple tasks and subsequent tasks are executed at lower priority.
10. activationDate is optional. State when the task becomes active, the task will not be run until then. This is excellent for repetitive tasks.

Example code snippet:

        Assoc taskData      
       taskData.nodeID = node.pID
        taskData.parentNodeID = node.pParentID
        taskData.someOtherData = true
        checkVal = $DistributedAgent.MapReducePkg.Map( prgCtx, "CopyNode", taskData )
 if ( checkVal.ok == TRUE )
                      //successfully scheduled the task!
 else
                     ok = FALSE
 errMsg = checkVal.errMsg
 apiError = checkVal.apiError
end        

Job Chain task handler definition is similar. To create a Job Chain handler, orphan $DISTRIBUTEDAGENT : DistributedAgent Objects : WorkerTask: JobChains in addition to implementing the Map script. Also, implement Reduce, which aggregates the results of sub-tasks and passes them, in turn, to the parent task; and Finalize, which is executed when the entire tree has been executed.

WorkerTask

Features

fEnabled (Boolean)

Set this to TRUE to enable the task.

fKey (String)

This is an identifier for your task. Open Text recommends that you include your module name in the key to avoid collisions with worker tasks created in other modules (e.g. ic_assertionReports).

fMaxAttempts (Boolean)

Set this to the number of times that a task may be rerun if it gets interrupted.

fName (String)

Display name for the task type; this is used for logging.

fPrgCtx (Object)

The fPrgCtx feature is set automatically and is available for reference from the GetFingerprint, Map,  Reduce, and Finalize scripts. This program session is allocated as the user that submitted the task for execution.

fPriority (Integer)

This number is to set the priority of your task. It must be in the range of 0-100 where 0 is low priority and 100 is high priority. The default is 50 and should be considered relevant for most tasks.

fRequestHandler (Dynamic)

A reference to the request handler that is triggering the task execution. This is provided as a convenience where a request handler object reference might be needed.

fSimpleJob (Boolean)

This indicates whether the task is a simple job or job chain. This should not be overridden.

fTaskData (Dynamic)

This feature is set with the data required for execution of the GetFingerprint,  Map, Reduce, and Finalize scripts.

fWorker (Dynamic)

Reference to the current worker thread that is executing the task. This is primarily available for logging purposes.

Scripts

GetFingerprint

This script will create a fingerprint string that will be used to uniquely identify tasks. This is created from the data in the task data, e.g. fingerprint = Str.Format( "%1:%2", .Key(), taskData.DataID ). This value will be inserted into the WorkerQueuePending table. If two tasks in the worker system have the same fingerprint then the first one will be executed and subsequent ones will be deleted.

Arguments

None

Returns

• ok (Boolean): TRUE if no error, FALSE otherwise
• errMsg (String): Error message if ok is FALSE
• apiError (String): API error object if error occurred
• fingerprint (String): String that represents the unique identifier for the worker task.

GetPriority

Get the priority of a task. Basic implementation returns fPriority.

Arguments

None

Returns

• Priority (Integer)

Key

This method gets the unique identifier for a set of taskBasic implementations and returns fKey.

Arguments

None

Returns

• Key (String)

Finalize

When all of the reductions have been completed, their results will be passed as a list to Finalize. This method is intended to perform any final operations required, and is executed once per task submitted.

Note: This script is only used for Job Chains, and not for Simple Jobs.

Arguments

• childResults (List): List of results of all reduce steps

Returns

• ok (Boolean): TRUE if no error, FALSE otherwise
• errMsg (String): Error message if ok is FALSE
• apiError (String): API error object if error occurred

Map

This method will perform the task. Code included here is what gets executed when the task is run. The output of this task is fed into the Reduce script when complete.

Arguments

None

Returns

• ok (Boolean): TRUE if no error, FALSE otherwise
• errMsg (String): Error message if ok is FALSE
• errDetail (RecArray): Array of error details

Reduce

This method will take the results of Map and aggregate them for use in Finalize. If there are any tasks which were created as sub-tasks, then their results will be included in the childResults parameter.

This script is only used for Job Chains, and not for Simple Jobs.

Arguments

• childResults (List): List of results of sub-tasks

Returns

• ok (Boolean): TRUE if no error, FALSE otherwise
• errMsg (String): Error message if ok is FALSE
• errDetail (RecArray): Array of error details

Congratulation. You made it. You tamed the Diistributed Agent