SharedRecords Integration

This page describes the integration between the Shared Records service and TiddlyWiki.

November 2006 Version

This section summarises the interfaces present in the initial implementation that was completed in November 2006.

There are two plugins:

• ImportSharedRecordsMetaData which imports records from a Shared Records server, with an optional user interface
• SharedRecordsSyncPlugin which synchronises modified records back to a Shared Records server

These discussions are based on changeset:1280. I've glossed over several purely local UI concerns, and minor issues like ISO date format conversion.

The ImportSharedRecordsMetaData Plugin

• Installs a hack to make commands.saveTiddler() automatically assign the following the extended fields on each new tiddler:
  • sharedRecords.recordUID - set to the first line of the tiddler named "SharedRecordsAutoSyncRecordUIDs"
  • sharedRecords.url - set to "http://sra.sharedrecords.org:8080/SRCDataStore/AddJsonMetaDataEntriesServlet"
  • sharedRecords.sequenceNumber - set to "0"
• Installs a paramifier that implements automatically imports a record at startup
  • Syntax: http://www.tiddlywiki.com/#recordID:{guid} (where <guid> is a 40 digit hex string)
  • ...which is equivalent to the macro "<<importSharedRecordsMetaData {guid} quiet>>"
• At startup, interprets each line of the tiddler named "SharedRecordsAutoSyncRecordUIDs" as a record GUID, and attempts to import each one
• Installs the importSharedRecordsMetaData macro, described below

The importSharedRecordsMetaData Macro

This macro accepts these parameters:

• record: the 40 digit hex string GUID of the record to read
• quiet: "yes"/"no" to determine whether a UI is displayed

In operation, it:

1. Prompts for a server URL. The default is "http://sra.sharedrecords.org:8080/SRCDataStore/GetJsonMetaDataEntriesServlet". The prompting is skipped in quiet mode.
2. Prompts for a record GUID if not provided as a macro parameter. The default is "d19905e85b097d18f9984dd6a651ebfce22c65e0".
3. Performs an HTTP GET to the composite URL: {server}?recordUID={guid}
4. If the TiddlyWiki was loaded from an http URL, then the GET URL is overridden to be the servlet "GetJsonMetaDataEntriesServlet?" in the same path as the source URL (eg, http://www.tiddlywiki.com/index.jsp -> http://www.tiddlywiki.com/GetJsonMetaDataEntriesServlet)
5. The response text is parsed as JSON according to [this spec for the JSON metadata format]
6. Tiddlers are created for each metadata entry, with the default of "Anonymous" for the "modifier" field and "No Title" for the "title" field
7. Depending on the 'Quiet' flag, the user is prompted to approve overwriting existing tiddlers
8. Each new tiddler is also given the extended fields "sharedrecords.url", "sharedrecords.recordUID", "sharedrecords.sequenceNumber" from the similarly named metadata fields

SharedRecordsSyncPlugin

1. Installs a mechanism to increment the extended field "changeCount" whenever a tiddler is modified (this has subsequently been integrated into the TW core code)
2. Installs the "sharedRecordsSync" plugin, described below

The sharedRecordsSync Plugin

This macro has no parameters. It appears as a button labelled 'sync' which when clicked initiates these operations:

1. Select all the tiddlers that have the extended fields "sharedRecords.recordUID", "sharedRecords.url" and "sharedRecords.sequenceNumber" and a non-zero changeCount
2. Compose a JSON string of those tiddlers extended fields combined with the core fields "title","modified","modifier","created","tags" and "text", along with the highest sequence number in amongst all the tiddlers (see the "MetaData Addition" section here for the current spec)
3. Extract a URL from the extended attribute "sharedRecords.url" of the first tiddler in the list
4. POST to the URL with the payload parameters being the "recordUID" as the GUID of the record and "payload" as the JSON body and a custom header "X-Requested-With" that identifies TiddlyWiki

Phase 2 Planning

The following changes are required in the next phase:

1. Remove the behaviour whereby "If the TiddlyWiki was loaded from an http URL, then the GET URL is overridden"