--- title: Create a new scanning task description: The following example defines a scheduled scanning task that triggers a sunset script: component: pingoneaic page_id: pingoneaic:idm-schedules:task-scanner-config canonical_url: https://docs.pingidentity.com/pingoneaic/idm-schedules/task-scanner-config.html --- # Create a new scanning task | | | | - | ------------------------------------------------------------------------------------------------------------------------ | | | You can [schedule jobs](../identities/manage-scheduled-jobs.html) directly in the Advanced Identity Cloud admin console. | 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](../identities/user-identity-properties-attributes-reference.html#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 console does not allow for complex query filters. | ```json { "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 `${Time.now}` macro object fetches the current time and is available only when you configure a scanning task query filter. You can't use the macro outside of this context. | 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 console, you must add it to your managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint.)* by making the property `searchable` (for more information, refer to [Property configuration properties](../idm-objects/appendix-managed-objects.html#managed-object-property-config-properties)). This example command adds a `frIndexedMultivalued1/date` field to `bjensen`'s entry, over REST: ``` curl \ --header "Content-Type: application/json" \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '[{ "operation" : "add", "field" : "frIndexedMultivalued1/date", "value" : "2019-12-20T12:00:00Z" }]' \ "https:///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). 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 object configuration. * `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](../idm-scripting/scripting-func-engine.html). |