//
// 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.
//
[[provisioning-push]]
==== Push

With push, the matching set of internal entities can be sent to Identity Stores - mainly for
(re)initialization purposes; for each external resource, one or more <<tasks-push,push tasks>> can be defined, run and 
scheduled for period execution.

Push task execution involves querying the internal storage for all <<mapping,mapped>> <<anytype, any types>>, sorted
according to the order defined by a custom implementation of
ifeval::["{snapshotOrRelease}" == "release"]
https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/ProvisionSorter.java[ProvisionSorter^]
endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/4_0_X/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/ProvisionSorter.java[ProvisionSorter^]
endif::[]
or its default implementation
ifeval::["{snapshotOrRelease}" == "release"]
https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/DefaultProvisionSorter.java[DefaultProvisionSorter^]
endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/4_0_X/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/DefaultProvisionSorter.java[DefaultProvisionSorter^]
endif::[]
.

Each entity is then processed in an isolated transaction; an internal entity can be:

. _matching_ if a corresponding remote entity was found, according to the <<policies-push,push policy>> set for the
enclosing external resource;
. _unmatching_ otherwise.

Once this has been assessed, entities are processed according to the matching / unmatching rules specified for the push task:
by default, unmatching entities are pushed to Identity Stores, and matching entities are updated.

.Matching Rules
****
* `IGNORE`: do not perform any action;
* `UPDATE`: update matching entity;
* `DEPROVISION`: delete internal entity;
* `UNLINK`: remove association with external resource, without performing any (de-)provisioning operation;
* `LINK`: associate with external resource, without performing any (de-)provisioning operation;
* `UNASSIGN`: unlink and delete.
****

.Unmatching Rules
****
* `IGNORE`: do not perform any action;
* `UNLINK`: remove association with external resource, without performing any (de-)provisioning operation;
* `ASSIGN`: create externally, assign the external resource;
* `PROVISION`: create externally, do not assign the external resource.
****

===== PushActions

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