src/main/asciidoc/reference-guide/concepts/tasks.adoc

//
// 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^]

===== MacroActions

Macro task execution can be decorated with custom logic to be invoked around task execution, by associating
macro tasks to one or more <<implementations,implementations>> of the
ifeval::["{snapshotOrRelease}" == "release"]
https://github.com/apache/syncope/blob/syncope-{docVersion}/core/idrepo/logic/src/main/java/org/apache/syncope/core/logic/api/MacroActions.java[MacroActions^]
endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/3_0_X/core/idrepo/logic/src/main/java/org/apache/syncope/core/logic/api/MacroActions.java[MacroActions^]
endif::[]
interface.

[[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
====