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/09/08 10:25:58 UTC
syncope git commit: [SYNCOPE-753] Migration chapter in the reference
guide
Repository: syncope
Updated Branches:
refs/heads/master a9c4d5838 -> e83cac047
[SYNCOPE-753] Migration chapter in the reference guide
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/e83cac04
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/e83cac04
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/e83cac04
Branch: refs/heads/master
Commit: e83cac047a28a4eea6b934e73dbc9fa207770244
Parents: a9c4d58
Author: Francesco Chicchiricc� <il...@apache.org>
Authored: Thu Sep 8 12:25:50 2016 +0200
Committer: Francesco Chicchiricc� <il...@apache.org>
Committed: Thu Sep 8 12:25:50 2016 +0200
----------------------------------------------------------------------
.../reference-guide/concepts/tasks.adoc | 8 +
.../workingwithapachesyncope/migration.adoc | 259 +++++++++++++++++++
.../workingwithapachesyncope.adoc | 2 +
3 files changed, 269 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/syncope/blob/e83cac04/src/main/asciidoc/reference-guide/concepts/tasks.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/tasks.adoc b/src/main/asciidoc/reference-guide/concepts/tasks.adoc
index 5218b97..8b8432c 100644
--- a/src/main/asciidoc/reference-guide/concepts/tasks.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/tasks.adoc
@@ -97,6 +97,14 @@ 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.
+====
+
[[tasks-push]]
==== Push
http://git-wip-us.apache.org/repos/asf/syncope/blob/e83cac04/src/main/asciidoc/reference-guide/workingwithapachesyncope/migration.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/migration.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/migration.adoc
new file mode 100644
index 0000000..5d85c61
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/migration.adoc
@@ -0,0 +1,259 @@
+//
+// 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.
+//
+=== Migration from Apache Syncope 1.2
+
+Apache Syncope 2.0 brings
+https://cwiki.apache.org/confluence/display/SYNCOPE/Jazz[several enhancements and new features^], compared to 1.2.
+
+For this reason, it is not possible to _update_ an existing 1.2 deployment but it is rather necessary to _migrate_ the
+whole configuration, users and roles to a brand new 2.0 deployment.
+
+==== Preparation
+
+With reference to 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::[]
+perform the following steps:
+
+. Install the CLI application
+. Create a new Maven project for Apache Syncope 2.0 then add the following dependency to `core/pom.xml`
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.syncope.core</groupId>
+ <artifactId>syncope-core-migration</artifactId>
+ <version>{docVersion}</version>
+</dependency>
+----
+
+==== Migrate configuration
+
+[discrete]
+===== Export configuration from 1.2
+
+First, export the configuration from the 1.2 deployment via
+
+....
+curl -X GET -u username:password -o content.xml protocol://host:port/syncope/rest/configurations/stream
+....
+
+where `username`, `password`, `protocol`, `host` and `port` reflect the Java EE container installation for the 1.2
+deployment. +
+The configuration of the 1.2 deployment is now in the `content.xml` file.
+
+[discrete]
+===== Obtain configuration file for 2.0
+
+Now process the exported configuration of the 1.2 deployment to obtain a basic 2.0 configuration, by invoking the CLI as
+follows:
+
+.On GNU / Linux - Mac OS X
+....
+./syncopeadm.sh migrate --conf /path/to/context.xml /dest/path/to/MasterContent.xml
+....
+
+.On Windows
+....
+syncopeadm.bat migrate --conf \path\to\context.xml \dest\path\to\MasterContent.xml
+....
+
+The result of such invocation is the generated `MasterContent.xml` file and possibly an output message like as follows:
+
+....
+You are running: migrate --conf /path/to/context.xml /dest/path/to/MasterContent.xml
+
+Virtual items, require manual intervention:
+<?xml version='1.0' encoding='UTF-8'?><dataset>
+ <VirSchema key="virtualdata"/>
+ <VirSchema key="virtualPropagation"/>
+ <VirSchema key="rvirtualdata"/>
+ <VirSchema key="mvirtualdata"/>
+ <VirSchema READONLY="1" key="virtualReadOnly"/>
+ <MappingItem extAttrName="name" mapping_id="1" intAttrName="virtualdata"
+ mandatoryCondition="type == 'F'" password="0" purpose="BOTH"/>
+ <MappingItem password="0" mapping_id="11" extAttrName="givenname"
+ intAttrName="virtualReadOnly" mandatoryCondition="false" purpose="BOTH"/>
+ <MappingItem password="0" mapping_id="11" extAttrName="givenname"
+ intAttrName="virtualPropagation" mandatoryCondition="false" purpose="BOTH"/>
+ <MappingItem extAttrName="businessCategory" mapping_id="1"
+ intAttrName="rvirtualdata" mandatoryCondition="false" password="0" purpose="BOTH"/>
+ <MappingItem mapping_id="17" password="0" extAttrName="USERNAME"
+ intAttrName="virtualdata" mandatoryCondition="false" purpose="BOTH"/>
+ <MappingItem mapping_id="17" password="0" extAttrName="SURNAME"
+ intAttrName="virtualPropagation" mandatoryCondition="false" purpose="BOTH"/>
+</dataset>
+
+
+ - Migration completed; file successfully created under /dest/path/to/MasterContent.xml
+....
+
+<<virtual,Virtual schemas>> and associated <<mapping,mapping>> cannot be automatically migrated: take note of the
+message above for further operations.
+
+[discrete]
+===== Finalize configuration for 2.0
+
+After putting the generated `MasterContent.xml` file under the `core/src/test/resources/domains` folder in the new 2.0
+Maven project, build and start in embedded mode, while always watching the log files under:
+
+* `core/target/log/`
+* `console/target/log/`
+* `enduser/target/log/`
+
+If errors are found, make appropriate corrections into `core/src/test/resources/domains/MasterContent.xml` - this might
+involve migrating custom classes originally developed for 1.2 into their respective
+<<customization-core,2.0 counterparts>>.
+
+When no exceptions are reported in the logs, log in the admin console and check if all configuration items
+(schema definitions, external resources, notifications, ...) were correctly migrated. If anything is missing, take care
+of re-adding manually.
+
+If using delegated administration under 1.2, reconstruct <<roles,roles>> and <<entitlements,entitlements>> under the
+new security model.
+
+Now, define the virtual schema and mapping items according to the output message obtained above when invoking the
+CLI.
+
+[WARNING]
+If making modifications via the admin console, do not forget to <<deal-with-internal-storage-export-import,export>>
+the updated configuration before shutting down the embedded mode, then use the downloaded file to update
+`core/src/test/resources/domains/MasterContent.xml`.
+
+Finally, verify that all operations (create, updated, delete, propagate, sync / push) about users and roles used in the
+1.2 deployment are working fine (create, updated, delete, propagate, pull / push) with users and groups in the 2.0
+Maven project.
+
+When everything works as expected, <<deal-with-internal-storage-export-import,export>>
+the updated configuration before shutting down the embedded mode and use the downloaded file to update both
+`core/src/main/resources/domains/MasterContent.xml` and `core/src/test/resources/domains/MasterContent.xml`.
+
+==== Migrate users and roles
+
+After deploying the 2.0 Maven project into one of supported <<javaee-container,Java EE containers>>, with internal
+storage set to one of supported <<dbms,DBMSes>>, ensure that the 1.2 deployment's internal storage DBMS is reachable.
+
+The steps below are to be performed on the 2.0 deployment.
+
+[discrete]
+===== Define migration <<anytypeclass>>
+
+Create the following <<plain,plain schemas>>:
+
+. `migrationCipherAlgorithm` - string, read-only
+. `migrationResources` - string, multi-value, read-only
+. `migrationMemberships` - string, multi-value, read-only
+
+Then, define the `migration` AnyTypeClass and assign the three plain schemas above.
+
+[discrete]
+===== Create migration <<connector-instance-details,Connector>>
+
+Create an instance of the https://connid.atlassian.net/wiki/display/BASE/Scripted+SQL[Scripted SQL^] bundle:
+
+. set connection details to the 1.2 deployment's internal storage DBMS
+. download the Groovy
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/tree/syncope-{docVersion}/core/migration/src/main/resources/scripted[scripts^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/tree/master/core/migration/src/main/resources/scripted[scripts^]
+endif::[]
+and configure accordingly
+. assign the `SEARCH` and `SYNC` capabilities
+
+[discrete]
+===== Create migration <<external-resource-details,External Resource>> and <<mapping>>
+
+Create an External Resource for the Connector created above, and set the <<provision,provisioning>> rules for:
+
+* `USER` as `\\__ACCOUNT__`, with at the least the following mapping:
+|===
+| Internal Attribute | External Attribute | Other
+
+| `username`
+| `username`
+| flagged as remote key, mandatory, purpose: `PULL`
+
+| `password`
+|
+| flagged as password, mandatory, purpose: `PULL`
+
+| `migrationCipherAlgorithm`
+| `cipherAlgorithm`
+| mandatory, purpose: `PULL`
+
+| `migrationResources`
+| `\\__RESOURCES__`
+| purpose: `PULL`
+
+|===
+* `GROUP` as `\\__GROUP__`, with at the least the following mapping:
+|===
+| Internal Attribute | External Attribute | Other
+
+| `name`
+| `name`
+| flagged as remote key, mandatory, purpose: `PULL`
+
+| `migrationResources`
+| `\\__RESOURCES__`
+| purpose: `PULL`
+
+| `migrationMemberships`
+| `\\__MEMBERSHIPS__`
+| mandatory, purpose: `PULL`
+
+|===
+
+[WARNING]
+More attributes should be added to the mapping information in order to pull values from the 1.2 deployments.
+
+[discrete]
+===== Setup migration <<tasks-pull,Pull Task>>
+
+Setup a pull task for the External Resource created above, set it for `FULL_RECONCILIATION` <<pull-mode,mode>> and
+configure the
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/migration/src/main/java/org/apache/syncope/core/migration/MigrationPullActions.java[MigrationPullActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/migration/src/main/java/org/apache/syncope/core/migration/MigrationPullActions.java[MigrationPullActions^]
+endif::[]
+class among <<pullactions>>.
+
+[discrete]
+===== Migrate
+
+Before actual migration, use the admin console features to explore the External Resource and check that all expected
+information is reported.
+
+Another check to perform is to run the pull task set up above with the <<dryrun,DryRun>> option and watch the execution
+results.
+
+Finally, execute the pull task and check the execution results.
+
+[TIP]
+If the number of users and roles to import from the 1.2 deployment is high, it is suggested to change the pull mode to
+`FILTERED_RECONCILIATION` for a relevant subset of entities to migrate, check the results and eventually switch back
+to `FULL_RECONCILIATION`.
http://git-wip-us.apache.org/repos/asf/syncope/blob/e83cac04/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
index 7b6f69e..1ed9621 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
@@ -39,3 +39,5 @@ include::restfulservices.adoc[]
include::customization.adoc[]
include::systemadministration/systemadministration.adoc[]
+
+include::migration.adoc[]