From c4456abd715f3d3af2c55a3b6e2f132e4254d10e Mon Sep 17 00:00:00 2001
From: Stan Silvert <ssilvert@redhat.com>
Date: Wed, 5 Oct 2016 13:45:17 -0400
Subject: [PATCH] Add note that migrate-json should only be used with old
 standalone.xml files.

---
 topics/MigrationFromOlderVersions.adoc | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/topics/MigrationFromOlderVersions.adoc b/topics/MigrationFromOlderVersions.adoc
index 161ec550a9..0a733ace76 100644
--- a/topics/MigrationFromOlderVersions.adoc
+++ b/topics/MigrationFromOlderVersions.adoc
@@ -25,6 +25,18 @@ support for keycloak-server.json.
 To convert your keycloak-server.json, you will use a new jboss-cli operation called `migrate-json`.  
 It is recommended that you run this operation while the server is not running.
 
+The `migrate-json` operation assumes you are migrating with an xml configuration file from an old version.  For example,
+you should not try to migrate your keycloak-server.json to a standalone.xml file that already contains <spi> and <theme>
+tags under the keycloak subsystem.  Before migration, your keycloak subsystem should look like the one below:
+
+.standalone.xml
+[source,xml]
+----
+<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
+    <web-context>auth</web-context>
+</subsystem>
+---- 
+
 The jboss-cli tool is discussed in detail in link:{{book.installguide.link}}[{{book.installguide.name}}].
 
 ==== migrate-json in Standalone Mode