Repository: syncope Updated Branches: refs/heads/master cfd499d3b -> 715820744
More reference guide grammatical fixes Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/71582074 Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/71582074 Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/71582074 Branch: refs/heads/master Commit: 715820744403fcab711e1de531885f762b2a68f2 Parents: cfd499d Author: Colm O hEigeartaigh <cohei...@apache.org> Authored: Mon Aug 29 10:56:57 2016 +0100 Committer: Colm O hEigeartaigh <cohei...@apache.org> Committed: Mon Aug 29 10:56:57 2016 +0100 ---------------------------------------------------------------------- .../workingwithapachesyncope/customization.adoc | 24 ++++++++++---------- .../restfulservices.adoc | 12 +++++----- .../systemadministration/activitimodeler.adoc | 4 ++-- .../configurationparameters.adoc | 6 ++--- .../configureconnidlocations.adoc | 4 ++-- .../systemadministration/dbms.adoc | 2 +- .../systemadministration/domainsmanagement.adoc | 4 ++-- .../systemadministration/highavailability.adoc | 2 +- .../systemadministration/importexport.adoc | 15 ++++++------ .../systemadministration.adoc | 14 ++++++------ 10 files changed, 44 insertions(+), 43 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc index 4d73273..dff29f6 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc @@ -19,14 +19,14 @@ === Customization [CAUTION] -Only Maven projects can be customized: if using Standalone, Debian packages or GUI installer, none of the customizations +Only Maven projects can be customized: if using Standalone, Debian packages or the GUI installer, none of the customizations discussed below can be applied. -Apache Syncope is conceived for being as much flexible as possible, to best suite the various environments +Apache Syncope is designed to be as flexible as possible, to best suit the various environments in which it can be deployed. Besides other aspects, this means that every feature and component can be extended or replaced. -Once created the project from the provided Maven archetype, the generated source tree is available for either adding +Once the project has been created from the provided Maven archetype, the generated source tree is available for either adding new features or replacing existing components. [[override-behavior]] @@ -63,19 +63,19 @@ endif::[] This general behavior might have exceptions, as highlighted below. ==== -As a general way to operate, the Embedded Mode (see the +In general, the Embedded Mode (see the ifeval::["{backend}" == "html5"] http://syncope.apache.org/docs/getting-started.html[Apache Syncope Getting Started Guide] endif::[] ifeval::["{backend}" == "pdf"] http://syncope.apache.org/docs/getting-started.pdf[Apache Syncope Getting Started Guide] endif::[] -for details) allows to work comfortably from a single workstation, with no need of additional setup; such mode is +for details) allows the user to work comfortably from a single workstation, with no need of additional setup; it is effectively implemented as the `all` https://maven.apache.org/guides/introduction/introduction-to-profiles.html[Maven profile^], where the available optional components and extensions are enabled. + When deploying the generated WAR artifacts into an external <<javaee-container>> however, the required components and -extensions need to be explicitly selected and enabled, as shown in the following. +extensions need to be explicitly selected and enabled, as shown in the following text. [[deployment-directories]] .Deployment directories @@ -83,7 +83,7 @@ extensions need to be explicitly selected and enabled, as shown in the following Apache Syncope needs three base directories to be defined: * bundles - where the <<external-resources,connector bundles>> are stored; -* log - where all system logs are written; +* log - where all the system logs are written; * conf (optional) - where configuration files are located, if overriding the default values is needed. [WARNING] @@ -109,7 +109,7 @@ mvn clean verify \ -Dlog.directory=/opt/syncope/log .... -After downloading all of the needed dependencies, three WAR files will be produced: +After downloading all of the dependencies that are needed, three WAR files will be produced: . `core/target/syncope.war` . `console/target/syncope-console.war` @@ -170,20 +170,20 @@ https://github.com/apache/syncope/blob/master/ext/camel/rest-cxf/src/main/java/o endif::[] for reference. -By following such conventions, the new REST endpoint will be automatically picked up alongside with default services. +By following such conventions, the new REST endpoint will be automatically picked up alongside the default services. ==== [WARNING] ==== The <<override-behavior,override behavior>> might have exceptions; if you need to customize one of the -Spring context definitions as +Spring context definitions. For example, if you want to customize ifeval::["{snapshotOrRelease}" == "release"] https://github.com/apache/syncope/blob/syncope-{docVersion}/core/spring/src/main/resources/securityContext.xml[securityContext.xml^] endif::[] ifeval::["{snapshotOrRelease}" == "snapshot"] https://github.com/apache/syncope/blob/master/core/spring/src/main/resources/securityContext.xml[securityContext.xml^] endif::[] -for example, you will also need to replace, in `core/src/main/webapp/WEB-INF/web.xml`, +, you will also need to replace the following text in `core/src/main/webapp/WEB-INF/web.xml`, .... classpath*:/*Context.xml @@ -290,7 +290,7 @@ The files in use by the Apache Wicket-based backend are still subject to the gen [[customization-extensions]] ==== Extensions -<<extensions>> can be part of a local project, to encapsulate special features which are specific of a given deployment. +<<extensions>> can be part of a local project, to encapsulate special features which are specific to a given deployment. For example, the http://www.chorevolution.eu/[CHOReVOLUTION^] IdM - based on Apache Syncope - provides https://tuleap.ow2.org/plugins/git/chorevolution/syncope?p=syncope.git&a=tree&f=ext/choreography[an extension^] http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc index bfc9d30..99a4e68 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc @@ -42,14 +42,14 @@ where `protocol`, `host` and `port` reflect your Java EE container installation. ==== [TIP] -The <<swagger,Swagger extension>> might be greatly helpful when working with RESTful services. +The <<swagger,Swagger extension>> might also help greatly when working with RESTful services. ==== Client Library -The Java client library is meant for simplifying the interaction with the <<core>> by hiding the underlying HTTP +The Java client library simplifies the interaction with the <<core>> by hiding the underlying HTTP communication details and providing native methods and payload objects. -The library is available as Maven artifact: +The library is available as a Maven artifact: [source,xml,subs="verbatim,attributes"] ---- @@ -83,7 +83,7 @@ endif::[] [discrete] ===== Initialization -You need first to build an instance of `SyncopeClientFactoryBean` by providing the deployment base URL, as follows: +First you need to build an instance of `SyncopeClientFactoryBean` by providing the deployment base URL, as follows: [source,java] ---- @@ -92,7 +92,7 @@ SyncopeClientFactoryBean clientFactory = new SyncopeClientFactoryBean(). ---- You might also select a specific <<domains,domain>> - other than `Master`, choose to exchange XML payloads - rather -than JSON (default), or to select the +than JSON (default), or to select https://en.wikipedia.org/wiki/HTTP_compression[HTTP compression^] (more options in the http://syncope.apache.org/apidocs/2.0/org/apache/syncope/client/lib/SyncopeClientFactoryBean.html[Javadoc^]): @@ -195,7 +195,7 @@ PagedResult<GroupTO> matchingGroups = groupService.search( ---- <1> get the total number of users available in the given deployment (and <<domains,domain>>) <2> get users in the root realm with username matching the provided wildcard expression -<3> get users in the root realm with no values for `loginDate`, e.g. that have never authenticated to the +<3> get users in the root realm with no values for `loginDate`, i.e. that have never authenticated to the given deployment <4> get users in the root realm with <<roles,role>> `Other` assigned <5> get all any objects in the root realm with <<anytype,type>> `PRINTER` http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/activitimodeler.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/activitimodeler.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/activitimodeler.adoc index 4ab1e9d..6ff9696 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/activitimodeler.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/activitimodeler.adoc @@ -26,7 +26,7 @@ interface for Activiti BPM, into any Apache Syncope artifact; thus, some manual working Apache Syncope deployment, for use with the admin console. [WARNING] -This procedure requires Apache Maven since it is using a fake project to perform all required setup tasks. +This procedure requires Apache Maven since it is using a fake project to perform all of the required setup tasks. First of all, generate a new Maven project as described in the ifeval::["{backend}" == "html5"] @@ -42,5 +42,5 @@ mvn -P all clean install .... At this point, copy the `console/target/activiti-modeler/` directory in the desired location of the host where the -admin console is deployed, then set the value of `activitiModelerDirectory` with such path in the `console.properties` +admin console is deployed, then set the value of `activitiModelerDirectory` with this path in the `console.properties` file. http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc index f45973a..3fb6d15 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc @@ -32,8 +32,8 @@ frequently the pending <<tasks-notification,notification tasks>> are processed: * `token.length` - the length of the random tokens that can be generated as part of various <<workflow,workflow>> processes, including <<password-reset,password reset>>; * `token.expireTime` - the time after which the generated random tokens expire; -* `selfRegistration.allowed` - whether self-registration (tipically via the enduser application) is allowed; -* `passwordReset.allowed` - whether the <<password-reset,password reset>> feature (tipically via the enduser +* `selfRegistration.allowed` - whether self-registration (typically via the enduser application) is allowed; +* `passwordReset.allowed` - whether the <<password-reset,password reset>> feature (typically via the enduser application) is allowed; * `passwordReset.securityQuestion` - whether the <<password-reset,password reset>> feature involves security questions; * `authentication.statuses` - the list of <<workflow,workflow>> statuses for which users are allowed to authenticate; @@ -41,4 +41,4 @@ application) is allowed; * `tasks.interruptMaxRetries` - how many attempts shall be made when interrupting a running <<task,task>>; * `return.password.value` - whether the hashed password value shall be returned when reading users. -Besides this default set, new configuration parameters can be define to support <<customization,custom>> code. +Besides this default set, new configuration parameters can be defined to support <<customization,custom>> code. http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configureconnidlocations.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configureconnidlocations.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configureconnidlocations.adoc index 59eef00..74dade5 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configureconnidlocations.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configureconnidlocations.adoc @@ -18,7 +18,7 @@ // ==== Configure ConnId locations -Apache Syncope can be configured for using either local and remote <<external-resources,connector bundles>>: +Apache Syncope can be configured to use either local or remote <<external-resources,connector bundles>>: * *local* connector bundles are located somewhere in the same filesystem where the Java EE container running Apache Syncope is deployed; @@ -30,7 +30,7 @@ are particularly useful when it is needed to deal with architectural security co requires to run on a specific platform OS (say MS Windows) while Apache Syncope is deployed on another platform OS (say GNU/Linux). -The `connid.properties` file holds the configuration for defining which ConnId locations (either local and remote) +The `connid.properties` file holds the configuration for defining which ConnId locations (either local or remote) will be considered. The format is quite straightforward: http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc index 446a690..79658ef 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc @@ -82,7 +82,7 @@ quartz.sql=tables_mariadb_innodb.sql .... [WARNING] -This assumes that the InnoDB engine is enabled in your MriaDB instance - if this is not the case, then change the value +This assumes that the InnoDB engine is enabled in your MariaDB instance - if this is not the case, then change the value for `quartz.sql` to `tables_mariadb.sql`. In `domains/Master.properties` (for the `Master` domain): http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/domainsmanagement.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/domainsmanagement.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/domainsmanagement.adoc index 5c56152..612ed30 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/domainsmanagement.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/domainsmanagement.adoc @@ -26,10 +26,10 @@ that the domain name is `Two`, such files are: * `domains/TwoContent.xml` - for content <<deal-with-internal-storage-export-import,initialization>>. When adding a new domain to an existing deployment it is possible to copy, rename and edit the files available for -the `Master` dommain, always present. +the `Master` domain, which is always present. [CAUTION] Adding a new domain requires re-deploying the <<core>> application and restarting the Java EE container. -Once a new domain is added, the admin credentials for such domain can be set via admin console, CLI or +Once a new domain is added, the admin credentials for such domain can be set via the admin console, CLI or barely invoking the REST layer through http://curl.haxx.se/[curl^]. http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc index 0398d99..8e6605e 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/highavailability.adoc @@ -18,7 +18,7 @@ // ==== High-Availability -When deploying multiple Apache Syncope instances insisting on a single database or database cluster, it is of +When deploying multiple Apache Syncope instances with a single database or database cluster, it is of fundamental importance that the contained OpenJPA instances are correctly configured for http://openjpa.apache.org/builds/2.4.1/apache-openjpa/docs/ref_guide_event.html[remote event notification^]. + Such configuration, in fact, allows the OpenJPA data cache to remain synchronized when deployed in multiple JVMs, thus http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/importexport.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/importexport.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/importexport.adoc index 024ec63..48f555f 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/importexport.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/importexport.adoc @@ -18,13 +18,13 @@ // ==== Deal with internal storage export - import -Almost every configurable aspect of a given deployment is contained into the <<persistence,internal storage>>: +Almost every configurable aspect of a given deployment is contained in the <<persistence,internal storage>>: schemas, connectors, resources, mapping, roles, groups, tasks and other parameters. -During the implementation phase of an Apache Syncope-based project, it might be handful to move such configuration back +During the implementation phase of an Apache Syncope-based project, it might be useful to move such configuration back and forth from one Apache Syncope instance to another (say developer's laptop and production server). + -An option is clearly acting at low level by empowering DBMS' dump & restore capabilities, but what if developer is -running MySQL (or even in-memory H2) while sysadmin features Oracle? +One option is clearly to act at a low level by empowering DBMS' dump & restore capabilities, but what if the developer is +running MySQL (or even in-memory H2) while the sysadmin features Oracle? [CAUTION] .Wipe existing content @@ -64,7 +64,7 @@ lower_case_table_names=1 ===== Export -This task can be accomplished either via admin console, CLI or by barely invoking the REST layer through +This task can be accomplished either via the admin console, CLI or by barely invoking the REST layer through http://curl.haxx.se/[curl^], for example: .... @@ -74,8 +74,9 @@ curl -X GET -u admin:password -o MasterContent.xml \ ===== Import -Basically, all you need to do is to replace the local `MasterContent.xml` with the one exported as explained above; but -where such file located? +Basically, all you need to do is to replace the local `MasterContent.xml` with the one exported as explained above; this +file is located at: + * `$TOMCAT_HOME/webapps/syncope/WEB-INF/classes/domains/MasterContent.xml` for Standalone * `/usr/share/tomcat8/webapps/syncope/WEB-INF/classes/domains/MasterContent.xml` for Debian packages http://git-wip-us.apache.org/repos/asf/syncope/blob/71582074/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc index 302b1e3..016c391 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc @@ -19,10 +19,10 @@ === System Administration [[properties-files-location]] -.Where are the configration files? +.Where are the configuration files? **** -Depending on which Apache Syncope distribution you are running on, the configuration files mentioned in the following -might reside in different locations. +Depending on which Apache Syncope distribution you are running, the configuration files mentioned in the following +text might reside in different locations. Standalone:: Assuming that `$CATALINA_HOME` is the Apache Tomcat base directory created when the distribution archive was unzipped, the configuration files are located under @@ -31,18 +31,18 @@ was unzipped, the configuration files are located under * `$CATALINA_HOME/webapps/syncope-console/WEB-INF/classes/` * `$CATALINA_HOME/webapps/syncope-enduser/WEB-INF/classes/` -Debian packages:: The configuration files will be fist searched in `/etc/apache-syncope`, then under +Debian packages:: The configuration files will be first searched in `/etc/apache-syncope`, then under * `/usr/share/tomcat8/webapps/syncope/WEB-INF/classes/` * `/usr/share/tomcat8/webapps/syncope-console/WEB-INF/classes/` * `/usr/share/tomcat8/webapps/syncope-enduser/WEB-INF/classes/` -GUI installer:: Assuming that `$CONF_DIRECTORY` is the one selected from installer, the configuration files will be fist +GUI installer:: Assuming that `$CONF_DIRECTORY` is the directory selected from the installer, the configuration files will be first searched in `$CONF_DIRECTORY`, then under the selected Java EE container's application classpath. -Maven project:: Assuming that `$CONF_DIRECTORY` is the one passed among +Maven project:: Assuming that `$CONF_DIRECTORY` is the directory passed among <<deployment-directories,deployment directories>> at build time and that `$SOURCE` is the path where the Maven project -was generated, the configuration files will be fist searched in +was generated, the configuration files will be first searched in `$CONF_DIRECTORY`, then under the selected Java EE container's application classpath, according to the content of * `$SOURCE/core/target/classes/`
