Islandora Sync Use and Configuration
The Islandora Sync module provides a method of importing and exporting content between Fedora Commons and Drupal. Content operations (ingest, modification, purging) which are to be persisted to Fedora Commons, must be done through Islandora if they are to be synced to Drupal. Islandora provides a set of event-based programmatic hooks that enable the Islandora Sync module to "listen" for changes done through Islandora to Fedora Commons content. Islandora Sync allows users to configure which events are synced and the timing of those operations (in real time or asynchronously via Drupal's cron).
Fedora Commons and Drupal have independent data storage architectures that required a number of assumptions be made about how the two systems should be integrated in a manner that also allows for flexibility and user configuration of content synchronization. Fedora Commons digital objects are mapped to Drupal nodes through a relationship between the Fedora content model and the Drupal content type.
Fedora Commons Content Model <--> Drupal Content Type (Entity->Bundle)
Configuration of the mapping between a Fedora content model and a Drupal content type is done by visiting /admin to get the system Administration and clicking "Structure" then "Content types" then "edit" for the Drupal content type you are configuring, then click the "Fedora Commons" tab.
"Sync nodes to Fedora" - exports Drupal nodes to Fedora Commons, currently this only works for node creation
"Sync objects to Drupal" - imports Fedora content to Drupal
"Sync Timing" - if "Real time" is selected, content is synchronized to Drupal immediately after being modified in Islandora. If "Cron" is selected, synchronization tasks are queued and executed when the next Drupal cron is run
"Sync object creation" - if checked, objects created in Fedora Commons are synced to Drupal
"Sync object updates" - if checked, object modification, datastream ingest, modification, and deletion are synced to Drupal
"Sync object deletion" - if checked, object purging in Fedora Commons is synched to Drupal
"Content model" - select which Fedora Commons content model the Drupal content type should be mapped to
Drupal stores the content of entities (and nodes) in fields. Because Fedora Commons does not have an analogous construct, a mapping of fields to datastreams and datastream segments (XML elements) is provided. The configuration of a Drupal field can be modified by clicking the "Manage Fields" tab and then clicking the "fedora" link for the desired field.
"Sync with Fedora Commons" - if checked, this field can be synced to or from Fedora Commons
"Fedora Commons data structure" - "XML value" is used if a field value will be pulled from an XML document (stored as a Fedora datastream). "Managed datastream" is used if the complete contents of a Fedora managed datastream is to be synced to the field. "Relationship" is used if the field value should be extracted from the Fedora object's RELS-EXT datastream.
"Datastream ID" - if "XML value" or "Managed datastream" is selected in the previous form field, the datastream that the value will be synced from should be entered.
"XML Settings -> Create" - if "XML value" is selected, "Create Settings" are used to enter xpath information for creating the XML element when syncing from Drupal to Fedora Commons
"XML Settings -> Read" - if "XML value" is selected, "Read Settings" are used to enter xpath information to pull content from XML documents into Drupal fields.
If content is to be synced to or from an XML document in Fedora Commons, the Islandora Sync module requires information about how that XML document should be constructed and used. To configure an XML datastream, go to /admin and then click "Islandora" and then "XML Datastream Settings." Click "Add XML Datastream Settings" to add information about a new XML datastream.
"Datastream ID" - the datastream ID that the XML document is saved as in Fedora Commons
"Root Element" - the root element of the XML document
"Namespace URI" - if the document is namespaced, the URI of the namespace
Drupal content types can be structured so that the fields are arranged and nested in a manner similar to an XML document. If you find it easier to learn from a working example, the MODS Basic Image Feature contains all of the field and configuration to emulate the metadata form of the Islandora Basic Image Solution Pack. The feature can be downloaded here and requires the Drupal features module and a number of other modules. Enabling the feature will create a Drupal content type, it's fields, and the configuration data necessary for Islandora Sync to sync a MODS XML document between Fedora Commons and Drupal.
Repeating XML elements can be emulated with Drupal fields by configuring the number of values the Drupal field may have. The field settings form has a selector for "Number of values."
Nested fields can be accomplished using the Drupal field_group module. The parent field group can be configured to create/read XML values, allowing for its children to be nested in the parent XML element.
Repeating groups of fields can be emulated in Drupal using the field_collection module. Fields can be grouped and repeated using this module. If this functionality is used to read/write XML with Islandora Sync, the Islandora Sync Field Collection integration module must be enabled (shipped as a sub-module of Islandora Sync).
Relationships between Fedora Commons objects can synced to Drupal through the use of the relation module. A relation field can be added to a content type and configured with Islandora Sync as a "Relationship" type. The Islandora Sync Relation integration module must be enabled for this functionality (shipped as a sub-module of Islandora Sync). One way relationships can be created if both Fedora objects have been synced to Drupal at the time of the relationship sync.
Taxonomy, file, and image fields are supported by the Islandora Sync module.
Views integration is provided at the level of exposing the islandora_sync_map database table to views. This allows for views that relate the Drupal node to the Fedora Object's pid. This can be useful if you would like to exclude large media files from syncing, but be able to access them in views by hardcoding a path to the file's datastream ID view URL. Two default views are provided with a Block display for the convenience of linking back and forth between a Drupal node and the Islandora object.
The blocks are currently named:
- View: Islandora Sync: Fedora object to Node ID
- View: Islandora Sync: Node to Fedora Pid
The corresponding views which generate the blocks can be referenced for the creation of custom views.