You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@syncope.apache.org by co...@apache.org on 2016/08/25 10:56:29 UTC
syncope git commit: More work on the docs - notifications, policies,
workflow.
Repository: syncope
Updated Branches:
refs/heads/master 9c3180662 -> d9848ecd6
More work on the docs - notifications, policies, workflow.
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/d9848ecd
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/d9848ecd
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/d9848ecd
Branch: refs/heads/master
Commit: d9848ecd605c87da2644722d008a3b815ee06f1b
Parents: 9c31806
Author: Colm O hEigeartaigh <co...@apache.org>
Authored: Thu Aug 25 11:56:08 2016 +0100
Committer: Colm O hEigeartaigh <co...@apache.org>
Committed: Thu Aug 25 11:56:24 2016 +0100
----------------------------------------------------------------------
.../reference-guide/concepts/notifications.adoc | 12 +--
.../reference-guide/concepts/policies.adoc | 82 ++++++++++----------
.../reference-guide/concepts/workflow.adoc | 12 +--
3 files changed, 53 insertions(+), 53 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/syncope/blob/d9848ecd/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
index 2646603..988e6ab 100644
--- a/src/main/asciidoc/reference-guide/concepts/notifications.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/notifications.adoc
@@ -51,7 +51,7 @@ 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
+Notification (and <<audit-events,Audit>>) events are essentially a means of identifying the invocation of specific methods
within the <<core>>, in line with _join points_ in the
https://en.wikipedia.org/wiki/Aspect-oriented_programming[Aspect Oriented Programming (AOP)^].
@@ -70,7 +70,7 @@ for `TASK` the various <<tasks-custom>> Tasks configured, for `PROPAGATION`, `PU
. 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.
+The admin console provides <<console-configuration-notifications,tooling>> to assist with the specification of valid events.
[TIP]
====
@@ -94,7 +94,7 @@ successful execution of the event identified by the `unexpected identification`
[NOTE]
====
-Custom events can be used when in need of triggering notifications from non-predefined joint points, as BPMN `userTask`
+Custom events can be used to trigger notifications from non-predefined joint points, as BPMN `userTask`
instances within the <<activiti-user-workflow-adapter>>, <<propagationactions>>, <<pushactions>>, <<pullactions>> or
other custom code.
====
@@ -106,13 +106,13 @@ to be used respectively for plaintext and HTML e-mails, and is available for sel
[NOTE]
====
-Notification templates can be easily managed either via <<console-configuration-notifications,admin console>> or
-<<eclipse-ide-plugin>>.
+Notification templates can be easily managed either via the <<console-configuration-notifications,admin console>> or
+the <<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
+For example, the `user` variable, an 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::[]
http://git-wip-us.apache.org/repos/asf/syncope/blob/d9848ecd/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 c18fece..694bfa4 100644
--- a/src/main/asciidoc/reference-guide/concepts/policies.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/policies.adoc
@@ -18,37 +18,37 @@
//
=== Policies
-Policies control different aspects of the <<provisioning,provisioning>> process and can be used to fine-tune and adapt
-the overall mechanism to the particularities of the spefic domain in which a given Apache Syncope deployment is running.
+Policies control different aspects of the <<provisioning,provisioning>> process. They can be used to fine-tune and adapt
+the overall mechanism to the particularities of the specific domain in which a given Apache Syncope deployment is running.
[[policy-composition]]
[TIP]
.Policy Composition
====
-When defining policies and associating to different realms and resources, it is common to observe that several policies
-of the same kind have to be enforced to the same user, group or any object.
+When defining policies and associating them with different realms and resources, it is common to observe that several policies
+of the same type have to be enforced on the same user, group or any object.
-In such cases, Apache Syncope transparently composes all the candidate policies and obtains a single applicable policy
-which contains all conditions of the composing policies; this process, however, is not guaranteed to be successful,
-as different policies of the same kind might provide conflicting clauses.
+In such cases, Apache Syncope transparently composes all of the candidate policies and obtains a single applicable policy
+which contains all the conditions of the composing policies; this process, however, is not guaranteed to be successful,
+as different policies of the same type might provide conflicting clauses.
====
[[policies-account]]
==== Account
-Account policies allow to impose constraints on username values, and are involved in the authentication process.
+Account policies allow the imposition of constraints on username values, and are involved in the authentication process.
[NOTE]
====
-When set for realm R, an account policy is enforced to all Users of R and sub-realms.
+When set for realm R, an account policy is enforced on all Users of R and sub-realms.
-When set for resource R, an account policy is enforced to all Users that have R assigned.
+When set for resource R, an account policy is enforced on all Users that have R assigned.
====
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
+* propagate suspension - when suspended as a consequence of too many authentication failures, should Users also be
suspended on associated resources or not?
* pass-through resources - which <<external-resource-details,external resources>> are involved with
<<pass-through-authentication,pass-through authentication>>
@@ -74,16 +74,16 @@ https://github.com/apache/syncope/blob/master/common/lib/src/main/java/org/apach
endif::[]
) contains the following controls:
-* maximum length - the minimum length to allow; `0` means no limit set;
-* minimum length - the maximum length to allow; `0` means no limit set;
+* maximum length - the maximum length to allow; `0` means no limit set;
+* minimum length - the minimum length to allow; `0` means no limit set;
* pattern - http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[Java regular expression pattern^] to
match; `NULL` means no match is attempted;
* all uppercase - are lowercase characters allowed?
* all lowercase - are uppercase characters allowed?
-* words not permitted - list of words that cannot be present, even as substring;
-* schemas not permitted - list of <<schema,schemas>> whose values cannot be present, even as substring;
-* prefixes not permitted - list of strings that cannot be present as prefix;
-* suffixes not permitted - list of strings that cannot be present as suffix.
+* words not permitted - list of words that cannot be present, even as a substring;
+* schemas not permitted - list of <<schema,schemas>> whose values cannot be present, even as a substring;
+* prefixes not permitted - list of strings that cannot be present as a prefix;
+* suffixes not permitted - list of strings that cannot be present as a suffix.
[TIP]
====
@@ -110,34 +110,34 @@ endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/master/core/persistence-api/src/main/java/org/apache/syncope/core/persistence/api/dao/AccountRuleConfClass.java[@AccountRuleConfClass^]
endif::[]
-referring to configuration class
+referring to the configuration class
====
===== Pass-through Authentication
-During user authentication, if the <<policy-composition,resulting>> account policy to apply defines pass-through
-resources, the provided credentials are verified prior against the internal storage then against each configured
+During user authentication, if the <<policy-composition,resulting>> applicable account policy defines pass-through
+resources, the provided credentials are verified first against the internal storage, then against each configured
external resource (provided that the underlying <<connector-instance-details,connector instance>> has the `AUTHENTICATE`
-capability set): the first check succeeding will successfully authenticate the user.
+capability set): the first check that succeeds will successfully authenticate the user.
-This feature allows, for example, to avoid storing password values in the internal storage and to reuse credentials
-contained in Identity Stores (with no need of pulling them out), or to implement authentication chains.
+This feature allows, for example, to reuse credentials contained in Identity Stores (without extracting them),
+instead of storing password values in the internal storage. It also facilitates implementing authentication chains.
[[policies-password]]
==== Password
-Password policies allow to impose constraints on password values.
+Password policies allow the imposition of constraints on password values.
[NOTE]
====
-When set for realm R, a password policy is enforced to all Users of R and sub-realms.
+When set for realm R, a password policy is enforced on all Users of R and sub-realms.
-When set for resource R, a password policy is enforced to all Users that have R assigned.
+When set for resource R, a password policy is enforced on all Users that have R assigned.
====
When defining a password policy, the following information must be provided:
-* allow null password - whether password is mandatory for Users or not
+* allow null password - whether a password is mandatory for Users or not
* history length - how many values shall be considered in the history
* rules - set of password rules to evaluate with the current policy
@@ -161,13 +161,13 @@ https://github.com/apache/syncope/blob/master/common/lib/src/main/java/org/apach
endif::[]
) contains the following controls:
-* maximum length - the minimum length to allow; `0` means no limit set;
-* minimum length - the maximum length to allow; `0` means no limit set;
+* maximum length - the maximum length to allow; `0` means no limit set;
+* minimum length - the minimum length to allow; `0` means no limit set;
* non-alphanumeric required
* alphanumeric required
* digit required
* lowercase required
-* uppwecase required
+* uppercase required
* must start with digit
* must not start with digit
* must end with digit
@@ -180,11 +180,11 @@ endif::[]
* must end with non-alphanumeric
* must not end with alphanumeric
* must not end with non-alphanumeric
-* username allowed - whether username value can be used
-* words not permitted - list of words that cannot be present, even as substring;
-* schemas not permitted - list of <<schema,schemas>> whose values cannot be present, even as substring;
-* prefixes not permitted - list of strings that cannot be present as prefix;
-* suffixes not permitted - list of strings that cannot be present as suffix.
+* username allowed - whether a username value can be used
+* words not permitted - list of words that cannot be present, even as a substring;
+* schemas not permitted - list of <<schema,schemas>> whose values cannot be present, even as a substring;
+* prefixes not permitted - list of strings that cannot be present as a prefix;
+* suffixes not permitted - list of strings that cannot be present as a suffix.
[TIP]
====
@@ -211,7 +211,7 @@ endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/master/core/persistence-api/src/main/java/org/apache/syncope/core/persistence/api/dao/PasswordRuleConfClass.java[@PasswordRuleConfClass^]
endif::[]
-referring to configuration class
+referring to the configuration class
====
[[policies-pull]]
@@ -219,14 +219,14 @@ referring to configuration class
Pull policies are evaluated during the execution of <<tasks-pull,pull tasks>> and are meant to:
-. help matching existing Users, Groups and Any Objects during <<provisioning-pull,pull>>, thus generating update events
-(rathern than create)
+. help match existing Users, Groups and Any Objects during <<provisioning-pull,pull>>, thus generating update events
+(rather than create)
. determine which action shall be taken in case such match is not unique (e.g. what to do if the same external account
can be mapped to two distinct Users in Apache Syncope?)
[NOTE]
====
-When set for resource R, a pull policy is enforced to all Users, Groups and Any Objects pulled from R.
+When set for resource R, a pull policy is enforced on all Users, Groups and Any Objects pulled from R.
====
When defining a pull policy, the following information must be provided:
@@ -251,7 +251,7 @@ endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/PlainAttrsPullCorrelationRule.java[default^]
endif::[]
-implementation available attempts to match entities on the basis of the values of the provided plain attributes,
+implementation attempts to match entities on the basis of the values of the provided plain attributes,
according to the available <<mapping,mapping>>.
[TIP]
@@ -273,5 +273,5 @@ Push policies are evaluated during the execution of <<tasks-push,push tasks>>.
[NOTE]
====
-When set for resource R, a push policy is enforced to all Users, Groups and Any Objects pushed to R.
+When set for resource R, a push policy is enforced on all Users, Groups and Any Objects pushed to R.
====
http://git-wip-us.apache.org/repos/asf/syncope/blob/d9848ecd/src/main/asciidoc/reference-guide/concepts/workflow.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/workflow.adoc b/src/main/asciidoc/reference-guide/concepts/workflow.adoc
index c7394fb..3e7a37e 100644
--- a/src/main/asciidoc/reference-guide/concepts/workflow.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/workflow.adoc
@@ -20,9 +20,9 @@
Workflow manages the internal identity lifecycle by defining statuses and transitions that every user, group or any
object in Apache Syncope will traverse. A workflow instance is started once identities get created, and shut down when
-removed.
+they are removed.
-Workflow is triggered during the <<provisioning,provisioning>> process as first step to create, update or delete
+Workflow is triggered during the <<provisioning,provisioning>> process as the first step in creating, updating or deleting
identities into the internal storage.
[NOTE]
@@ -97,7 +97,7 @@ and presents several advantages and more features, if compared to the default us
. Besides mandatory statuses, which are modeled as BPMN `userTask` instances, more can be freely added
at runtime, provided that adequate transitions and conditions are also inserted; more details about available BPMN
-constructs in the http://www.activiti.org/userguide/index.html#bpmnConstructs[Activiti User Guide^]. +
+constructs are available in the http://www.activiti.org/userguide/index.html#bpmnConstructs[Activiti User Guide^]. +
Additional statuses and transitions allow the internal processes of Apache Syncope to better adapt to suit organizational flows.
. Custom logic can be injected into the workflow process by providing BPMN `serviceTask` instances.
. http://www.activiti.org/userguide/index.html#forms[Activiti forms^] are used for implementing <<approval,approval>>.
@@ -113,7 +113,7 @@ Every transition in the Activiti user workflow definition can be subjected to ap
The underlying idea is that some kind of self-modifications (group memberships, external resource assignments, ...)
might not be allowed to 'plain' Users, as there could be conditions which require management approval.
-Managers could also be asked for completing the information provided before the requested operation is completed.
+Managers could also be asked to complete the information provided before the requested operation is finished.
In order to define an approval form, a dedicated BPMN `userTask` needs to be defined, following the rules established
for http://www.activiti.org/userguide/index.html#forms[Activiti forms^].
@@ -147,8 +147,8 @@ read-only form input can be defined by setting `writable="false"`
be defined by setting `required="true"`
====
-Once the form is defined, any modification subject to that approval will be manageable via admin console, according to
-the following flow (the actual operations on admin console for the sample above are reported <<console-approval,below>>):
+Once the form is defined, any modification subject to that approval will be manageable via the admin console, according to
+the following flow (the actual operations on the admin console for the sample above are reported <<console-approval,below>>):
. administrator A sees the new approval notifications +
. administrator A claims the approval and is then allowed to manage it