11.5.1. Configuring the Task Scanner

The task scanner is essentially a scheduled task that queries a span of managed users. The task scanner is configured in the same way as a regular scheduled task, in a schedule configuration file named (schedule-task-name.json), with the "invokeService" parameter set to "taskscanner. The "invokeContext" parameter defines the details of the scan, and the task that should be executed when the specified condition is triggered.

The following example defines a scheduled scanning task that triggers a sunset script. This sample configuration file is provided in the OpenIDM delivery as openidm/samples/taskscanner/conf/schedule-taskscan_sunset.json. To use this sample file, you must copy it to the openidm/conf directory. 

{
    "enabled" : true,
    "type" : "cron",
    "schedule" : "0 0 * * * ?",
    "invokeService" : "taskscanner",
    "invokeContext" : {
        "waitForCompletion" : false,
        "maxRecords" : 2000,
        "numberOfThreads" : 5,
        "scan" : {
            "object" : "managed/user",
            "_queryId" : "scan-tasks",
            "property" : "sunset/date",
            "condition" : {
                "before" : "${Time.now}"
            },
            "taskState" : {
                "started" : "sunset/task-started",
                "completed" : "sunset/task-completed"
            },
            "recovery" : {
                "timeout" : "10m"
            }
        },
        "task" : {
            "script" : {
                "type" : "text/javascript",
                "file" : "script/sunset.js"
            }
        }
    }
}

The "invokeContext" parameter takes the following properties:

"waitForCompletion" (optional)

This property specifies whether the task should be performed synchronously. Tasks are performed asynchronously by default (with waitForCompletion set to false). A task ID (such as {"_id":"354ec41f-c781-4b61-85ac-93c28c180e46"}) is returned immediately. If this property is set to true, tasks are performed synchronously and the ID is not returned until all tasks have completed.

"maxRecords" (optional)

The maximum number of records that can be processed. This property is not set by default so the number of records is unlimited. If a maximum number of records is specified, that number will be spread evenly over the number of threads.

"numberOfThreads" (optional)

By default, the task scanner runs in a multi-threaded manner, that is, numerous threads are dedicated to the same scanning task run. Multithreading generally improves the performance of the task scanner. The default number of threads for a single scanning task is ten. To change this default, set the "numberOfThreads" property.

"scan"

Defines the details of the scan. The following properties are defined:

"object"

Defines the object type against which the query should be performed.

"_queryId"

Specifies the query that is performed. The queries that can be set here are defined in the database configuration file (either conf/repo.orientdb.json or conf/repo.jdbc.json).

"property"

Defines the object property against which the range query is performed.

"condition" (optional)

Indicates the conditions that must be matched for the defined property.

In the previous example, the scanner scans for users for whom the property sunset/date is set to a value prior to the current timestamp at the time the script is executed.

You can use these fields to define any condition. For example, if you wanted to limit the scanned objects to a specified location, say, London, you could formulate a query to compare against object locations and then set the condition to be: 

            "condition" : {
                "location" : "London"
            },

For time-based conditions, the "condition" property supports macro syntax, based on the Time.now object (which fetches the current time). You can specify any date/time in relation to the current time, using the + or - operator, and a duration modifier. For example: "before": "${Time.now + 1d}" would return all user objects whose sunset/date is before tomorrow (current time plus one day). You must include space characters around the operator (+ or -). The duration modifier supports the following unit specifiers:

s - second
m - minute
h - hour
d - day
M - month
y - year
"taskState"

Indicates the fields that are used to track the status of the task.

"started" specifies the field that stores the timestamp for when the task begins.
"completed” specifies the field that stores the timestamp for when the task completes its operation.
"recovery" (optional)

Specifies a configurable timeout, after which the task scanner process ends. In a scenario with clustered OpenIDM instances, there might be more than one task scanner running at a time. A task cannot be executed by two task scanners at the same time. When one task scanner "claims" a task, it indicates that the task has been started. That task is then unavailable to be claimed by another task scanner and remains unavailable until the end of the task is indicated. In the event that the first task scanner does not complete the task by the specified timeout, for whatever reason, a second task scanner can pick up the task.

"task"

Provides details of the task that is performed. Usually, the task is invoked by a script, whose details are defined in the "script" property:

"type" - the type of script. Currently, only JavaScript is supported.
"file" - the path to the script file. The script file takes at least two objects (in addition to the default objects that are provided to all OpenIDM scripts): "input" which is the individual object that is retrieved from the query (in the example, this is the individual user object) and "objectID" which is a string that contains the full identifier of the object. The objectID is useful for performing updates with the script as it allows you to target the object directly, for example: openidm.update(objectID, input['_rev'], input);. A sample script file is provided in openidm/samples/taskscanner/script/sunset.js. To use this sample file, you must copy it to the openidm/script directory. The sample script marks all user objects that match the specified conditions as "inactive". You can use this sample script to trigger a specific workflow, or any other task associated with the sunset process. For more information about using scripts in OpenIDM, see the Scripting Reference.