| // |
| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License. |
| // |
| === Commands |
| |
| A Command is defined via an <<implementations,Implementation>> of type `COMMAND`, providing a Java or Groovy class |
| for the |
| ifeval::["{snapshotOrRelease}" == "release"] |
| https://github.com/apache/syncope/blob/syncope-{docVersion}/core/idrepo/logic/src/main/java/org/apache/syncope/core/logic/api/Command.java[Command^], |
| endif::[] |
| ifeval::["{snapshotOrRelease}" == "snapshot"] |
| https://github.com/apache/syncope/blob/master/core/idrepo/logic/src/main/java/org/apache/syncope/core/logic/api/Command.java[Command^], |
| endif::[] |
| interface, designed to optionally take parameters. |
| |
| The typical use case is to encapsulate, in a single logical unit, the equivalent of two or more <<rest,REST>> calls. |
| |
| Once defined, Commands can be executed via dedicated REST endpoints, or via <<engagements,Console UI>>. |
| |
| === Tasks |
| |
| Tasks control the effective operations that are ongoing in the <<core>>. |
| |
| Whilst tasks define what and how to perform, they are supposed to be run by some entity (depending on the actual task |
| type, see below for details); their execution result can be saved for later examination. |
| |
| [[tasks-propagation]] |
| ==== Propagation |
| |
| A propagation task encapsulates all the information that is required - according to the defined <<mapping,mapping>> - to create, |
| update or delete a given User, Group or Any Object, to / from a certain Identity Store: |
| |
| * operation - `CREATE`, `UPDATE` or `DELETE` |
| * connObjectKey - value for ConnId |
| http://connid.tirasa.net/apidocs/1.5/org/identityconnectors/framework/common/objects/Uid.html[unique identifier^] |
| on the Identity Store |
| * oldConnObjectKey - the former unique identifier on the Identity Store: bears value only during updates involving the |
| unique identifier |
| * attributes - set of ConnId |
| http://connid.tirasa.net/apidocs/1.5/org/identityconnectors/framework/common/objects/Attribute.html[attributes^] built |
| upon internal identity data and configured mapping |
| * resource - related <<external-resources,external resource>> |
| * objectClass - ConnId |
| http://connid.tirasa.net/apidocs/1.5/org/identityconnectors/framework/common/objects/ObjectClass.html[object class^] |
| * entity - reference to the internal identity: User, Group or Any Object |
| |
| [NOTE] |
| ==== |
| Propagation tasks are automatically generated via the configured |
| ifeval::["{snapshotOrRelease}" == "release"] |
| https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/DefaultPropagationManager.java[PropagationManager^], |
| endif::[] |
| ifeval::["{snapshotOrRelease}" == "snapshot"] |
| https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/DefaultPropagationManager.java[PropagationManager^], |
| endif::[] |
| executed (by default) via the |
| ifeval::["{snapshotOrRelease}" == "release"] |
| https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/PriorityPropagationTaskExecutor.java[PriorityPropagationTaskExecutor^] |
| endif::[] |
| ifeval::["{snapshotOrRelease}" == "snapshot"] |
| https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/PriorityPropagationTaskExecutor.java[PriorityPropagationTaskExecutor^] |
| endif::[] |
| during the <<propagation,propagation>> process, and are permanently saved - for later re-execution or for examining |
| the execution details - depending on the trace levels set on the related |
| <<external-resource-details,external resource>>. |
| |
| Automatic retry in case of failure can be configured by mean of a <<policies-propagation,propagation policy>>, for the |
| related external resource. |
| ==== |
| |
| [[tasks-pull]] |
| ==== Pull |
| |
| Pull tasks are required to define and trigger the <<provisioning-pull,pull>> process from Identity Stores. |
| |
| When defining a pull task, the following information must be provided: |
| |
| * related <<external-resources,external resource>> |
| * chosen <<pull-mode,pull mode>> |
| * destination <<realms,Realm>> - where entities selected for creation are going to be placed |
| * whether creation, update or deletion on internal storage are allowed or not |
| * whether <<remediation,remediation>> is enabled |
| * whether to synchronize the status information from the related identity store |
| * selected <<provisioning-pull,matching and unmatching rules>> |
| * optional <<pullactions,pull action(s)>> |
| * <<pull-templates,entity templates>> |
| * scheduling information: |
| ** when to start |
| ** https://docs.spring.io/spring-framework/reference/integration/scheduling.html#scheduling-cron-expression[cron expression^] |
| |
| [NOTE] |
| ==== |
| Pull tasks are executed, either upon request or due to a schedule, via the |
| ifeval::["{snapshotOrRelease}" == "release"] |
| https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/PullJobDelegate.java[PullJobDelegate^] |
| endif::[] |
| ifeval::["{snapshotOrRelease}" == "snapshot"] |
| https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/PullJobDelegate.java[PullJobDelegate^] |
| endif::[] |
| during the <<provisioning-pull,pull>> process, and are permanently saved - for later re-execution or for examining |
| the execution details - depending on the trace level set on the related |
| <<external-resource-details,external resource>>. |
| ==== |
| |
| [[dryrun]] |
| [TIP] |
| .DryRun |
| ==== |
| It is possible to simulate the execution of a pull (or push) task without performing any actual modification by |
| selecting the _DryRun_ option. The execution results will be still available for examination. |
| ==== |
| |
| [[concurrent-tasks-pull]] |
| [TIP] |
| .Concurrent Pull Task Executions |
| ==== |
| By default, pull tasks are set to accept and sequentially process the objects received from the configured External |
| Resource; it is also possible to configure a pull task to work on several objects at once in order to speed up the |
| overall execution time. |
| ==== |
| |
| [[tasks-push]] |
| ==== Push |
| |
| Push tasks are required to define and trigger the <<provisioning-push,push>> process to Identity Stores. |
| |
| When defining a push task, the following information must be provided: |
| |
| * related <<external-resources,external resource>> |
| * source <<realms,Realm>> - where entities to push will be read from |
| * filter information for selecting which internal entities will be pushed onto the identity store |
| * whether creation, update or deletion on the identity store are allowed or not |
| * whether to synchronize the status information with internal storage |
| * selected <<provisioning-push,matching and unmatching rules>> |
| * optional <<pushactions,push action(s)>> |
| * scheduling information: |
| ** when to start |
| ** https://docs.spring.io/spring-framework/reference/integration/scheduling.html#scheduling-cron-expression[cron expression^] |
| |
| [NOTE] |
| ==== |
| Push tasks are executed, either upon request or due to a schedule, via the |
| ifeval::["{snapshotOrRelease}" == "release"] |
| https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/PushJobDelegate.java[PushJobDelegate^] |
| endif::[] |
| ifeval::["{snapshotOrRelease}" == "snapshot"] |
| https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/PushJobDelegate.java[PushJobDelegate^] |
| endif::[] |
| during the <<provisioning-push,push>> process, and are permanently saved - for later re-execution or for examining |
| the execution details - depending on the trace level set on the related |
| <<external-resource-details,external resource>>. |
| ==== |
| |
| [[concurrent-tasks-push]] |
| [TIP] |
| .Concurrent Push Task Executions |
| ==== |
| By default, push tasks are set to sequentially send items to the configured External Resource; it is also possible to |
| configure a push task to work on several objects at once in order to speed up the overall execution time. |
| ==== |
| |
| [[tasks-notification]] |
| ==== Notification |
| |
| A notification task encapsulates all the information that is required to send out a notification e-mail, according to the |
| specification provided in a given <<notifications,notification>>: |
| |
| * entity - reference to the internal identity - User, Group or Any Object - the notification task refers to |
| * sender e-mail address |
| * e-mail subject |
| * effective e-mail recipient(s) |
| * e-mail body as plaintext and / or HTML |
| |
| [NOTE] |
| ==== |
| Notification tasks are automatically generated via the |
| ifeval::["{snapshotOrRelease}" == "release"] |
| https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/notification/DefaultNotificationManager.java[NotificationManager^], |
| endif::[] |
| ifeval::["{snapshotOrRelease}" == "snapshot"] |
| https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/notification/DefaultNotificationManager.java[NotificationManager^], |
| endif::[] |
| executed via the |
| ifeval::["{snapshotOrRelease}" == "release"] |
| https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/job/notification/NotificationJob.java[NotificationJob^] |
| endif::[] |
| ifeval::["{snapshotOrRelease}" == "snapshot"] |
| https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/job/notification/NotificationJob.java[NotificationJob^] |
| endif::[] |
| and are permanently saved - for later re-execution or for examining the execution details - depending on the trace level |
| set on the related <<notifications,notification>>. |
| ==== |
| |
| [[tasks-macro]] |
| ==== Macros |
| |
| Macro tasks are meant to group one or more <<commands>> into a given execution sequence, alongside with |
| arguments required to run. |
| |
| When defining a macro task, the following information must be provided: |
| |
| * commands to run, with their args |
| * <<realms,Realm>> for <<delegated-administration,delegated administration>> to restrict the set of users entitled to |
| list, update or execute the given macro task |
| * scheduling information: |
| ** when to start |
| ** https://docs.spring.io/spring-framework/reference/integration/scheduling.html#scheduling-cron-expression[cron expression^] |
| |
| [[tasks-scheduled]] |
| ==== Scheduled |
| |
| Scheduled tasks allow for the injection of custom logic into the <<core>> in the area of execution and scheduling. |
| |
| When defining a scheduled task, the following information must be provided: |
| |
| * job delegate class: Java class extending |
| ifeval::["{snapshotOrRelease}" == "release"] |
| https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/job/AbstractSchedTaskJobDelegate.java[AbstractSchedTaskJobDelegate^] |
| endif::[] |
| ifeval::["{snapshotOrRelease}" == "snapshot"] |
| https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/job/AbstractSchedTaskJobDelegate.java[AbstractSchedTaskJobDelegate^] |
| endif::[] |
| providing the custom logic to execute |
| * scheduling information: |
| ** when to start |
| ** https://docs.spring.io/spring-framework/reference/integration/scheduling.html#scheduling-cron-expression[cron expression^] |
| |
| [TIP] |
| ==== |
| Scheduled tasks are ideal for implementing periodic checks or clean-up operations, possibly in coordination with other |
| components; some examples: |
| |
| * move users from "pending delete" to "deleted" status 15 days after they reached the "pending delete" status (requires |
| interaction with <<flowable-user-workflow-adapter>>) |
| * send out notification e-mails to users whose password is about to expire on an Identity Store |
| * disable all users not logging into the system for the past 6 months |
| ==== |