Notation Shift

Introduction

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

Resources

The term "old XDI2" refers to an XDI2 server and/or graph based on the old graph model and serializations.

The term "new XDI2" refers to an XDI2 server and/or graph based on the new graph model and serializations.

The following links are useful for this process:

• An instance of the "old XDI2" web tools: http://server.xdi2.org/pre-notation-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.5-pre-notation-shift
• The xdi2-tools: https://github.com/projectdanube/xdi2-tools

Client considerations

For XDI clients the following considerations apply:

1. XDI clients have to make sure they are sending XDI messages in either one of the supported formats after the shift, i.e. either what used be XDI DISPLAY "normal notation", or XDI/JSON "short notation".
2. The addresses of link contracts do NOT change, i.e. XDI clients refer to link contracts the same way before and after the shift.

Manual process 1 ("editing")

To convert a single not very large 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-notation-shift/XDIConverter
4. Paste the graph into the tool
5. As output format, select "XDI DISPLAY NSHIFT", 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.

Manual process 2 ("messaging")

For large graphs, this process should be used instead of manual process 1.

1. Stop the XDI2 server.
2. Migrate the "old XDI2" server environment to "new XDI2".
3. Start the XDI2 server.
4. Open the "new XDI2" admin web interface. It should have a function to execute arbitrary messages against a messaging target. Alternatively, it is also possible to send "real" messages using an XDI client.
5. Using $del messages, remove 1. the /$is$ref/([+]!:uuid:0000) "I am" statement, and 2. all known link contracts in the graph.
6. Restart the XDI2 server. The BootstrapInterceptor should recreate the standard link contracts.
7. Manually recreate any non-standard link contracts using $set messages.

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. Stop the XDI2 server.
6. Launch xdi2-tools with the following parameters: rebuild-graphs text/xdinshift [path-to-applicationContext.xml]
7. This should rebuild all graphs into the "old XDI2" server environment. If individual graphs cannot be restored, xdi2-tools should skip them and print an exception.
8. Migrate the "old XDI2" server environment to "new XDI2".
9. Start the XDI2 server, and make sure everything looks good.