Create a new scanning task

The following example defines a scheduled scanning task that triggers a sunset script:

The following example uses one of the available array fields in IDM, frIndexedMultivalued1, as described in General purpose extension attributes. Adjust this value to one of the available array fields in your tenant.

The fields task-completed, task-started, and date are items under the array.

It is recommended to create tasks via REST as the IDM admin UI does not allow for complex query filters.

{
  "enabled" : true,
  "type" : "simple",
  "repeatInterval" : 3600000,
  "persisted": true,
  "concurrentExecution" : false,
  "invokeService" : "taskscanner",
  "invokeContext" : {
    "waitForCompletion" : false,
    "numberOfThreads" : 5,
    "scan" : {
      "_queryFilter" : "/frIndexedMultivalued1/date lt \"${Time.now}\") AND !(/frIndexedMultivalued1/task-completed pr",
      "object" : "managed/realm-name_user",
      "taskState" : {
        "started" : "/frIndexedMultivalued1/task-started",
        "completed" : "/frIndexedMultivalued1/task-completed"
      },
      "recovery" : {
        "timeout" : "10m"
      }
    },
    "task" : {
     "script" : {
        "type" : "text/javascript",
        "source" : "var patch = [{ \"operation\" : \"replace\", \"field\" : \"/active\", \"value\" : false }, { \"operation\" : \"replace\", \"field\" : \"/accountStatus\", \"value\" : \"inactive\" }];\n\nlogger.debug(\"Performing Task on {} ({})\", input.mail, objectID);\n\nopenidm.patch(objectID, null, patch); true;"
      }
    }
  }
}

The schedule configuration calls an inline script. 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 frIndexedMultivalued1/date field. You can add a frIndexedMultivalued1/date field to user entries over REST. To make the field visible in the IDM admin UI, you must add it to your managed object configuration by making the property searchable (for more information, refer to Property configuration properties).

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

curl \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '[{
 "operation" : "add",
 "field" : "frIndexedMultivalued1/date",
 "value" : "2019-12-20T12:00:00Z"
}]' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_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".
source: The inline script to execute.

For more information about using functions in scripts, refer to scripting functions.

PingOne Advanced Identity Cloud

Create a new scanning task