Great Symbol Shift

Introduction

This page describes how XDI graphs can be migrated through the "Great Symbol Shift" using xdi2-tools. For more information about this shift, see great-symbol-shift on the main XDI2 wiki.

Resources

The term "old XDI2" refers to an XDI2 server and/or graph that still uses the old symbols.

The term "new XDI2" refers to an XDI2 server and/or graph that uses the new symbols.

The following links are useful for this process:

• An instance of the "old XDI2" web tools: http://server.xdi2.org/pre-symbol-shift/
• An instance of the "new XDI2" web tools: http://server.xdi2.org/
• A snapshot of the "old XDI2" code base: https://github.com/projectdanube/xdi2/tree/snapshot-0.2-pre-symbol-shift
• The xdi2-tools: https://github.com/projectdanube/xdi2-tools

Manual process

To convert a single graph, the following process should be used:

1. Obtain a serialization of the "old XDI2" graph (either "XDI/JSON" or "XDI DISPLAY" format) in a text file or clipboard.
2. For example, the graph can be copied out of an "old XDI2" admin web interface.
3. Open the "old XDI2" XDI Converter tool: http://server.xdi2.org/pre-symbol-shift/XDIConverter
4. Paste the graph into the tool
5. As output format, select "XDI DISPLAY SHIFT", click Go.
6. This returns the converted "new XDI2" graph.
7. For example, the "new XDI2" graph can then be copied into a "new XDI2" admin web interface.

Automatic process

To convert all graphs known to an XDI2 server, the following process should be used:

1. Deploy the xdi2-tools on the "old XDI2" server environment.
2. xdi2-tools itself is agnostic to either "old XDI2" or "new XDI2", but make sure it is using the "old XDI2" core code base.
3. Make sure xdi2-tools has access to the "old XDI2" server applicationContext.xml configuration file(s), as well as to all the XDI2 plugins used by the server (e.g. xdi2-mongodb, xdi2-connector-facebook, etc).
4. Make sure xdi2-tools has access to the persistence layer (e.g. MongoDB).
5. Launch xdi2-tools with the following parameters: backup-graphs mybackup.zip text/xdishift [path-to-applicationContext.xml]
6. This should output the file mybackup.zip, containing serialized "new XDI2" graphs
7. Look into the .zip file, make sure it contains the expected number of graphs, and open a few of them to see if they look good
8. Stop the XDI2 server, and migrate the "old XDI2" server environment to "new XDI2".
9. Manually clear the contents of the persistence layer (e.g. MongoDB).
10. Launch xdi2-tools with the following parameters: restore-graphs mybackup.zip [path-to-applicationContext.xml]
11. This should restore all graphs into the "new XDI2" server environment. If individual graphs cannot be restored, xdi2-tools should skip them and print an exception.
12. Start the XDI2 server, and make sure everything looks good.