PingIDM 7.5.0

Create a new scanning task

The following example (openidm/samples/example-configurations/task-scanner/conf/schedule-taskscan_sunset.json) defines a scheduled scanning task that triggers a sunset script:

{
  "enabled" : true,
  "type" : "simple",
  "repeatInterval" : 3600000,
  "persisted": true,
  "concurrentExecution" : false,
  "invokeService" : "taskscanner",
  "invokeContext" : {
    "waitForCompletion" : false,
    "numberOfThreads" : 5,
    "scan" : {
      "_queryFilter" : "((/sunset/date lt \"${Time.now}\") AND !(/sunset/task-completed pr))",
      "object" : "managed/user",
      "taskState" : {
        "started" : "/sunset/task-started",
        "completed" : "/sunset/task-completed"
      },
      "recovery" : {
        "timeout" : "10m"
      }
    },
    "task" : {
      "script" : {
        "type" : "text/javascript",
        "file" : "script/sunset.js"
      }
    }
  }
}

The schedule configuration calls a script (sunset.js). To test the sample, copy this file to your project’s script directory or replace "file" : "script/sunset.js" with the script source ("source" : "contents of sunset.js"). 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.

The task will only execute on users who have a valid sunset/date field. You can add a sunset/date field to user entries over REST. To make the field visible in the admin UI, you must add it to your managed object configuration.

This example command adds a sunset/date field to bjensen's entry, over REST:

curl \
--header "Content-Type: application/json" \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '[{
  "operation" : "add",
  "field" : "sunset/date",
  "value" : "2019-12-20T12:00:00Z"
}]' \
"http://localhost:8080/openidm/managed/user?_action=patch&_queryFilter=userName+eq+'bjensen'"

The remaining properties in the schedule configuration are as follows:

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. Multi-threading generally improves the performance of the task scanner. The default number of threads for a single scanning task is 10. To change this default, set the numberOfThreads property. The sample configuration sets the default number of threads to 5.

scan

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

_queryFilter

The query filter that identifies the entries for which this task should be run.

The query filter provided in the sample schedule configuration (/sunset/date lt \"${Time.now}\") AND !(/sunset/task-completed pr) identifies managed users whose sunset/date property is before the current date and for whom the sunset task has not yet completed.

The sample query supports time-based conditions, with the time specified in ISO 8601 format (Zulu time). You can write any query to target the set of entries that you want to scan.

For time-based queries, it’s possible to use the ${Time.now} macro object (which fetches the current time). You can also specify any date/time in relation to the current time, using the ` or `-` operator, and a duration modifier. For example: changing the sample query to `${Time.now + 1d}` would return all user objects whose `/sunset/date` is the following day (current time plus one day). Note: 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

object

Defines the managed object type against which the query should be performed, as defined in the managed.json file.

taskState

Indicates the names of the fields in which the start message, and the completed message are stored. These fields 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. The completed field is present as soon as the task has started, but its value is null until the task has completed.

recovery (optional)

Specifies a configurable timeout, after which the task scanner process ends. For clustered IDM instances, there might be more than one task scanner running at a time. A task cannot be launched 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 script type.

IDM supports "text/javascript" and "groovy".

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 IDM scripts):

input

The individual object that is retrieved from the query (in the example, this is the individual user object).

objectID

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);.

For more information about using scripts, refer to Scripting function reference.