You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@syncope.apache.org by il...@apache.org on 2016/08/12 13:55:42 UTC
syncope git commit: [SYNCOPE-700] Notifications
Repository: syncope
Updated Branches:
refs/heads/master 577d05774 -> 660aa70ad
[SYNCOPE-700] Notifications
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/660aa70a
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/660aa70a
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/660aa70a
Branch: refs/heads/master
Commit: 660aa70adee1154ac7da46dcfa92274a0a4c3073
Parents: 577d057
Author: Francesco Chicchiricc� <il...@apache.org>
Authored: Fri Aug 12 15:55:29 2016 +0200
Committer: Francesco Chicchiricc� <il...@apache.org>
Committed: Fri Aug 12 15:55:35 2016 +0200
----------------------------------------------------------------------
.../architecture/architecture.adoc | 5 +-
.../reference-guide/concepts/concepts.adoc | 6 +-
.../concepts/externalresources.adoc | 2 +-
.../reference-guide/concepts/notifications.adoc | 152 +++++++++++++++++++
.../reference-guide/concepts/policies.adoc | 6 +-
.../adminconsole/configuration.adoc | 9 +-
6 files changed, 172 insertions(+), 8 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/syncope/blob/660aa70a/src/main/asciidoc/reference-guide/architecture/architecture.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/architecture/architecture.adoc b/src/main/asciidoc/reference-guide/architecture/architecture.adoc
index c4a1373..3bd9692 100644
--- a/src/main/asciidoc/reference-guide/architecture/architecture.adoc
+++ b/src/main/asciidoc/reference-guide/architecture/architecture.adoc
@@ -60,5 +60,6 @@ Java <<client-library,Client Library>> (the basis of Admin UI, End-user UI and C
==== Eclipse IDE Plugin
-The Eclipse IDE plugin allows remote management of notification e-mail and report templates, and constitutes an example
-of a Java application relying on the Client Library for interacting with the Core via REST.
+The Eclipse IDE plugin allows remote management of <<notification-templates,notification e-mail>> and
+<<report-templates,report>> templates, and constitutes an example of a Java application relying on the Client Library
+for interacting with the Core via REST.
http://git-wip-us.apache.org/repos/asf/syncope/blob/660aa70a/src/main/asciidoc/reference-guide/concepts/concepts.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/concepts.adoc b/src/main/asciidoc/reference-guide/concepts/concepts.adoc
index 09db683..5bfe6e9 100644
--- a/src/main/asciidoc/reference-guide/concepts/concepts.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/concepts.adoc
@@ -36,7 +36,7 @@ include::policies.adoc[]
include::workflow.adoc[]
-=== Notifications
+include::notifications.adoc[]
=== Tasks
@@ -57,6 +57,10 @@ include::workflow.adoc[]
=== Reports
+==== Report Templates
+
=== Audit
+==== Audit Events
+
=== Domains
http://git-wip-us.apache.org/repos/asf/syncope/blob/660aa70a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
index 37f6b92..587cdc6 100644
--- a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
@@ -31,7 +31,7 @@ provisioning. For each entity supported by the related connector bundle (user, g
==== Connector Instance details
-When defining a connector instance, the following information is to be provided:
+When defining a connector instance, the following information must be provided:
* connector bundle - one of the several
https://github.com/Tirasa/ConnId/blob/master/README.md#available-connectors[already available^], or some to be
http://git-wip-us.apache.org/repos/asf/syncope/blob/660aa70a/src/main/asciidoc/reference-guide/concepts/notifications.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/notifications.adoc b/src/main/asciidoc/reference-guide/concepts/notifications.adoc
new file mode 100644
index 0000000..605a3db
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/concepts/notifications.adoc
@@ -0,0 +1,152 @@
+//
+// 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.
+//
+=== Notifications
+
+Apache Syncope can be instructed to send out notification e-mails when certain <<notification-events,events>> occur.
+
+Every notification generates one or more <<tasks-notification,notification tasks>>, holding the actual
+e-mails to be sent. The tasks are ordinarily scheduled for execution according to the value provided for
+`notificationjob.cronExpression` - see <<configuration-parameters, below>> for details - and can be saved for later
+re-execution.
+
+When defining a notification, the following information must be provided:
+
+* <<notification-templates,notification template>> - template for e-mail generation
+* sender - e-mail address appearing in the `From` field of the generated e-mail(s)
+* subject - text used as e-mail subject
+* recipient e-mail attribute - which user attribute shall be considered as e-mail address for delivery (as users might
+in principle have different e-mail attributes)
+* recipient(s) - the actual e-mail recipient(s) which can be specified either as:
+** list of static e-mail addresses
+** matching condition to be applied to available users
+** Java class implementing the
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/notification/NotificationRecipientsProvider.java[NotificationRecipientsProvider^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/notification/NotificationRecipientsProvider.java[NotificationRecipientsProvider^]
+endif::[]
+interface
+* <<notification-events,notification event(s)>> - event(s) triggering the enclosing notification
+* about - the condition matching Users, Groups or Any Objects which are evaluated for the specified events; for users,
+the matching entities can be also considered as additional recipients
+* trace level - control how much tracing (including logs and execution details) shall be carried over during execution
+of the generated <<tasks-notification,notification tasks>>
+
+==== Notification Events
+
+Notification (and <<audit-events,Audit>>) events are essentially a mean to identify the invocation of specific methods
+within the Apache Syncope <<core>>, in line with _join points_ in the
+https://en.wikipedia.org/wiki/Aspect-oriented_programming[Aspect Oriented Programming (AOP)^].
+
+An event is identified by the following five coordinates:
+
+. type - which can be one of
+** `LOGIC`
+** `TASK`
+** `PROPAGATION`
+** `PULL`
+** `PUSH`
+** `CUSTOM`
+. category - the possible values depend on the selected type: for `LOGIC` the <<logic>> components available,
+for `TASK` the various <<tasks-generic>> Tasks configured, for `PROPAGATION`, `PULL` and `PUSH` the defined Any Types
+. subcategory - completes category with external resource name, when selecting `PROPAGATION`, `PULL` or `PUSH`
+. event type - the final identification of the event; depends on the other coordinates
+. success or failure - whether the current event shall be considered in case of success or failure
+
+The admin console provides <<console-configuration-notifications,tooling>> for assisted specification of valid events.
+
+[TIP]
+====
+An event is uniquely identified by a string of the following form:
+
+[source]
+----
+[type]:[category]:[subcategory]:[event type]:[SUCCESS|FAILURE]
+----
+
+Some samples:
+
+* `[PushTask]:[group]:[resource-db-scripted]:[matchingrule_deprovision]:[SUCCESS]` +
+successful Group <<provisioning-push,push>> to the external resource `resource-db-scripted`, when deprovisioning
+matching entities
+* `[LOGIC]:[RealmLogic]:[]:[create]:[FAILURE]` +
+unsuccessful Realm creation
+* `[CUSTOM]:[]:[]:[unexpected identification]:[SUCCESS]` +
+successful execution of the event identified by the `unexpected identification` string
+====
+
+[NOTE]
+====
+Custom events can be used when in need of triggering notifications from non-predefined joint points, as BPMN `userTask`
+instances within the <<activiti-user-workflow-adapter>>, <<propagationactions>>, <<pushactions>>, <<pullactions>> or
+other custom code.
+====
+
+==== Notification Templates
+
+A notification template is defined as a pair of http://commons.apache.org/proper/commons-jexl/[JEXL^] expressions,
+to be used respectively for plaintext and HTML e-mails, and is available for selection in the notification specification.
+
+[NOTE]
+====
+Notification templates can be easily managed either via <<console-configuration-notifications,admin console>> or
+<<eclipse-ide-plugin>>.
+====
+
+The full power of JEXL expressions - see http://commons.apache.org/proper/commons-jexl/reference/syntax.html[reference^]
+and http://commons.apache.org/proper/commons-jexl/reference/examples.html[some examples^] - is available. +
+Among others, the `user` variable, instance of
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/common/lib/src/main/java/org/apache/syncope/common/lib/to/UserTO.java[UserTO^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/common/lib/src/main/java/org/apache/syncope/common/lib/to/UserTO.java[UserTO^]
+endif::[]
+with actual value matching the _about_ condition as introduced above, can be used.
+
+.Plaintext notification template
+====
+[source]
+----
+Hi ${user.plainAttrMap["firstname"].values[0]} ${user.plainAttrMap["surname"].values[0]},
+ welcome to Syncope!
+
+Your username is ${user.username}.
+Your email address is ${user.plainAttrMap["email"].values[0]}.
+
+Best regards.
+----
+====
+
+.HTML notification template
+====
+[source,html]
+----
+<html>
+ <body>
+ <h3>Hi ${user.plainAttrMap["firstname"].values[0]} ${user.plainAttrMap["surname"].values[0]},
+ welcome to Syncope!</h3>
+ <p>Your username is ${user.username}.<br/>
+ Your email address is ${user.plainAttrMap["email"].values[0]}.</p>
+ <p>Best regards.</p>
+ </body>
+</html>
+----
+====
http://git-wip-us.apache.org/repos/asf/syncope/blob/660aa70a/src/main/asciidoc/reference-guide/concepts/policies.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/policies.adoc b/src/main/asciidoc/reference-guide/concepts/policies.adoc
index de4bd01..c18fece 100644
--- a/src/main/asciidoc/reference-guide/concepts/policies.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/policies.adoc
@@ -45,7 +45,7 @@ When set for realm R, an account policy is enforced to all Users of R and sub-re
When set for resource R, an account policy is enforced to all Users that have R assigned.
====
-When defining an account policy, the following information is to be provided:
+When defining an account policy, the following information must be provided:
* max authentication attempts - how many times Users are allowed to fail authentication before getting suspended
* propagate suspension - when suspended as consequence of too many authentication failures, should Users also be
@@ -135,7 +135,7 @@ When set for realm R, a password policy is enforced to all Users of R and sub-re
When set for resource R, a password policy is enforced to all Users that have R assigned.
====
-When defining a password policy, the following information is to be provided:
+When defining a password policy, the following information must be provided:
* allow null password - whether password is mandatory for Users or not
* history length - how many values shall be considered in the history
@@ -229,7 +229,7 @@ can be mapped to two distinct Users in Apache Syncope?)
When set for resource R, a pull policy is enforced to all Users, Groups and Any Objects pulled from R.
====
-When defining a pull policy, the following information is to be provided:
+When defining a pull policy, the following information must be provided:
* conflict resolution action
** `IGNORE` - do nothing
http://git-wip-us.apache.org/repos/asf/syncope/blob/660aa70a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/configuration.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/configuration.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/configuration.adoc
index ae13817..2f5335f 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/configuration.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/configuration.adoc
@@ -21,40 +21,47 @@
The configuration tab allows the admin to customize the syncope deployment to fit the needs of the
organization. It provides the following functionality
+[[console-configuration-audit]]
Audit::
Allows the admin to inspect the functionality of various components of the syncope deployment.
+[[console-configuration-logs]]
Logs::
The admin can set the level of logs that are to be displayed. For example, the admin can set it
to display only the errors of io.swagger, in which case the warnings and information logs will
not be displayed.
+[[console-configuration-notifications]]
Notifications::
This allows the admin to set events and corresponding templates for mail notification to be sent
to the Users. Trace level defines the condition in which an event will trigger the sending of a
notification. Templates for such notifications can also be added and edited using this tab.
+[[console-configuration-parameters]]
Parameters::
Presents the user with a list of key value pairs containing variables used in the syncope
deployment such as token.expireTime and password.cipher.algorithm . These can be edited by the
admin to further customize the deployment.
+[[console-configuration-policies]]
Policies::
Allows the admin to define rules for account, passwords and pulls. Accounts and password policies
are defined using java classes while pull policies are defined from within the console using
correlation rules.
+[[console-configuration-roles]]
Roles::
Displays and provides editing functionality for roles and their corresponding entitlements along
with the realms that they are enforced upon.
-Security Question::
+[[console-configuration-security-questions]]
+Security Questions::
The admin can use this to define a set of security questions which the endUsers can choose from
to allow them to recover their account in case of a forgotten password.