Running OCHRE Offline
By Sandra Schloen, May 2014
Updated August 2017; June 2019; July 2021
As of the summer of May 2014, OCHRE is equipped with a new feature that allows for a powerful, albeit somewhat constrained, user experience that does not require a constant Internet connection. In particular, this gives archaeologists a new option for taking OCHRE into the field to do primary data capture on the spot.
Considerations Regarding Working Offline
The project administrator must first indicate that offline use is acceptable for the project by checking ON the option "Allow offline use" on the Project Preferences page. Offline use should not be allowed without due consideration and appropriate administrative supervision. OCHRE is generally used in a multi-user, collaborative, online environment so if this feature were to be abused, or if relevant workflow is not properly managed, there could well be undesirable data complications.
All offline sessions should be restored as soon as possible. Offline mode is a concession to necessary workflow. As much as it is possible, OCHRE work should be done online.
Special care must be taken while users are working offline so that the online structures are not changed in such a way that offline data will not be able to find its way back in. OCHRE does not currently enforce this as it would potentially cripple online work while users are offline. Workflow procedures, and structural accommodations, can be made to minimize problems. For example, create separate hierarchies, say, in Locations & Objects, for users to add to while offline, and include only those carefully constructed hierarchies in the offline session.
It is best to restore offline sessions one at a time, and when other users are not working online. Set aside a special time of the day for this process. This will minimize potential claims/conflicts which can be difficult to resolve.
Creating an Offline Session
The project administrator creates the definition for an offline environment for each User who needs access to OCHRE offline. This is done on the Offline tab of the User account. Using the Linked Items pane in the usual way, the project administrator creates a list of the items to which that users needs access offline. Hierarchies or sets of items can be added to this list, or just single items.
Note the following dependencies that are automatically included in an offline session:
If you add a hierarchy then the hierarchy and all of the items contained therein will be available to the offline session. Users should carefully consider implications of this for other project members.
If a specified single item is a parent item in a hierarchical context then the supporting context items (the required ancestors) and their basic content will be included automatically. The full set of contained sub-items within the specified parent context will also be included for offline access.
If a specified single item is a Set then the set and all of its members will be available to the offline session.
As of the summer of 2018, a Query can be added to the offline session. OCHRE will Perform the Query, then add the query results as a hierarchy to the offline session.
As of the summer of 2019, each Query will support a separate hierarchy, within which auto-numbering serial#-properties will function as if "Unique-to-hierarchy."
The User will also have available offline the following items:
The Project item, although this will not be editable offline, by definition
The User (self) item, although this will not be editable offline, by definition
A reduced, simplified taxonomy that is derived from the predefinition(s) requested. NOTE: do not add variables and values from the taxonomy to the Offline tab. Instead, add predefinitions that include the required taxonomic values.
Certain types of items are NOT eligible for offline access. These include:
The full Taxonomy; instead, a reduced taxonomy will be derived from the specified predefinition(s) as noted above.
Queries, Simulations, Thesaurus items.
Items contextualized within headings; select the full hierarchy instead, if necessary.
Any items from other projects, with the exception of borrowed property variables and/or values used in this project's predefinitions.
Each user simply clicks the Prepare offline environment button to initiate the download of the necessary items to create an offline session according to the given specification.
PLEASE NOTE: Do not add a single item (text, locus, person, etc.) if that item also occurs in a hierarchy set to use offline. For example, if including a hierarchy of loci, do not also include an individual locus that occurs in that hierarchy. Do not include a hierarchy of texts, then also add a text that occurs in that hierarchy.
Including an expanded Taxonomy branch
By default, OCHRE includes only those taxonomic properties needed to satisfy the requirements of all of the Predefinitions included in the offline session. You can force the inclusion of an entire branch of the Taxonomy by linking directly into the offline profile the Variable or Value, in its taxonomic context, that represents the top of the branch you wish to include.
In the example shown below, we are requesting that the entire branch of the taxonomy within "Botanical remains" be included in the offline session for our project's archaeobotanist. The ancestor items needed to provide context, along with all the child (sub-) items, will be included offline. Note that the Variable or Value needs to be selected within the context of the Taxonomy category (that is, not from within the Property Variables or Property Values categories).
Including image items
Hierarchies or Sets of images, or individual Resource items, can be included in your offline profile. If FTP settings (user name, password and, optionally, root folder) are entered in the fields provided on your project's Resources Inbox, the image thumbnails will be downloaded for offline use. You may want these just for reference, or for doing actual work like hotspotting.
A check-box option lets you choose to include thumbnails of linked images in your offline session. These are items that are not specifically included in your offline profile, but which are linked to other items that are included. If you include for use offline a hierarchy of Objects or Texts, for example, checking this option on will take along with those items the thumbnails of the images from their Links tab. Note, of course, that this will increase the time needed to prepare the offline environment in proportion to the number of images needed to be downloaded.
[Note that this option need not be checked for images, or Hierarchies or Sets of images, that are directly linked into the Offline list. This checkbox only applies to images that are incidental links on other primary items.]
Incidental Items
Some items will be included in the offline session even though they are not included in the list of offline items. These incidental items include the following:
Items that are ancestors of offline items. For example, if a parent level in a Locations & Objects hierarchy is specified as an offline item, OCHRE will derive its needed ancestry to provide basic context. The ancestor items will be downloaded as incidental items.
Items that are subitems of offline items. For example, if a hierarchy is specified as an offline item then all of its children will be included in the offline session as incidental items.
Items that are linked to primary offline items. Persons, periods, resources, property-links, etc., of primary items will all be included in the offline session as incidental items.
Property variable and value items used to describe both primary items and incidental items will be included in the offline session. That is, every offline item, both primary and incidental, should be presentable with most of its basic information intact. This does not mean that all of the full taxonomic structure is available for editing the incidental items.
A selective taxonomy will be generated based on the cumulative sets of properties needed for using the predefinitions which have been included as primary offline items.
Note that items not listed in the primary offline list are not necessarily eligible for full editing. Ancestor items, for example, that are included only to provide context for a requested offline item will be restricted. Inserting and deleting sub items of such incidental ancestor items is prevented, and moving (up/down) or deleting of the ancestor item itself is not permitted. Since the full range of potential siblings of the incidental ancestor items are not guaranteed to be available, and since the full depth of intrinsic content is not necessarily available, it seems prudent to be cautious in these contexts.
Serial Number Variables
Special issues arise for serial-number variables in offline mode. Normally the assignment of a value to a serial number variable is done after a query is used to determine the next available number, based on whether the variable is designated as having values unique to the project, or unique within any given hierarchy. While offline, querying for the next available number is not possible. As a result OCHRE handles serial number variables in the following ways:
If a serial number variable is designated as having values unique to the project, the variable can be assigned to an item but its value will be shown as <pending>. When the offline session is synced to the online session, all pending values will receive official serial numbers in an appropriate sequence. If the serial number variable is designated as the means by which the item is to be auto-labeled, the auto-label specification must include the variable name as part of the label.
If a serial number variable is designated as having values unique to a hierarchy, OCHRE will be able to manage the auto-increment feature offline. When the offline session is created, OCHRE will detect unique-to-hierarchy variables, and will determine the last-used serial number relative to any hierarchy (or query) as needed (currently available only for Locations & Objects hierarchies). This will prime the serial number variable appropriately for the offline session.Thereafter, throughout the offline session, appropriate serial numbers, unique within each hierarchy, will be assigned as needed. Note that this strategy is appropriate only if the auto-incrementing variables and the hierarchies in question are being used by only one user offline. Note that multiple hierarchies can be implicated by the same auto-incrementing serial# property and will retain distinct sequences even within a single offline session.
Be sure that the item with the maximally-assigned serial# is included in the query/hierarchy for the offline session. This will be natural, typically, as the most-recently-assigned items will generally be included in the current hierarchy/query used to specify the offline session.
Running an Offline Session
Start up OCHRE using your desktop icon in the usual way. IF you are not connected to the Internet and IF you have prepared an offline environment OCHRE will automatically start up in offline mode. Features that require that the full database be queried are disabled but many features remain available. Basic data entry of items -- inserting, describing with properties, adding links, notes and/or events -- can all take place as if one were working online. All of the items included in the offline session are fully available for reference purposes.
A user is allowed to have offline sessions for multiple projects, but only one offline session per project.
A user can close the offline session and come back to resume it (still offline) without penalty; OCHRE will pick up where the offline session left off.
Deleting Items Offline
Only items that are created offline can be deleted while offline. OCHRE is always careful never to allow an item to be deleted if any other item has any dependencies on it. When working online in the usual way an extensive query is performed prior to allowing the deletion of an item to ensure that no links will be broken if the item is deleted. Since such a query cannot be performed while running offline, deletion of items is not allowed. If, however, an item was created offline then we can be sure that no items in the online database will reference it, and so we allow it to be deleted if no offline items have referenced it.
Restoring an Offline Session
Users should regularly restore their offline sessions, re-syncing the offline activity with the online database. In fact, a user will not be allowed to work again online in any project for which they have a pending offline session. When a user starts up an online session after having worked offline, OCHRE will detect the presence of the offline session and will indicate to that user that the offline session must be restored before work online can proceed.
In fact, a user cannot run an online session if there is any offline session for the project already on that laptop/computer. Only a Project Administrator is authorized to restore a session for another user. Note that this means that if an offline session is pending on a computer, it will effectively block all online sessions from that computer until the offline session is resolved.
All offline sessions should be restored as soon as possible. Offline mode is a concession to necessary workflow. As much as it is possible, OCHRE work should be done online.
When an offline session is restored its offline folder is archived rather than deleted. We do this so that it is available for trouble-shooting if needed. Periodically a project administrator will want to use the Clear option (on the button bar at the bottom of the User's Offline profile) to purge all offline sessions.
If problems are encountered when restoring an offline session the restore process will terminate. Only a Project administrator, at his or her discretion, can bypass the restoration process (see below) and resolve the offline session. OCHRE will note that it was resolved with errors. In addition, the user will be prompted to save a folder of diagnostics to be sent to the OCHRE system administrator for resolution. Contact ochre@ochre.uchicago.edu to help resolve problems with restoring offline sessions.
Priority Restore
As of August 2017, OCHRE allows a Priority Restore option which bypasses the process of checking for contention with online OCHRE items, and which thereby speeds up the restore process.
Priority Restore option -- use with caution!
This option should only be used at the data manger's discretion when there is no possibility that there will be contention when posting offline edits. This might be true if all project personnel are logged out of OCHRE (e.g. known to be asleep in a different time zone!), or if the offline session was designed in such a way that only the offline user will have any interest in the data being posted. Because this process circumvents the normal "claim" checking, it can be considerably faster and less data intensive, but again, should be used with care!
Backing up an Offline Session
If an offline session is not able to be restored in a timely manner, for any reason, or if a session is intentionally offline for logistical reasons, you should consider backing up your offline session. Offline data should not be put at risk. Several Backup options are available on the Project menu for offline sessions. For example, you may not need to back up your GEO files if they are static files simply being used as reference in the offline session (e.g. a drone photo being used as a basemap). You will be prompted for a location on which to save a backup file which will be automatically named and timestamped. Obviously, this should be an external drive of some kind; it would not make sense to store the backup on the same laptop.
Several backup options let you safeguard offline data.
To restore an offline session from a backup file, if necessary, start up OCHRE offline on a computer that does not already have an offline session present. Finding none, OCHRE will ask if you want to restore a session from a backup. Select Yes, and OCHRE will prompt you through the process appropriately.
Security of an Offline Session
All offline data is encrypted so as not to expose project data unnecessarily. The "human-readable" XML OCHRE formats are thus not human-readable at all in this context.
Read-only Offline Sessions
As of August 2017 you can indicate that an offline session is read-only. This type of offline session can co-exist with online sessions, but it will (obviously) become out-of-date if related work is done online.
A Read-only offline session is indicated as such in the Title bar.
A read-only session might be useful, however, for a casual viewer, or a specialist, or a field supervisor who is not his- or herself editing data, but who is a consumer of the data being produced. If Internet conditions are less than ideal, it may be easier to access and reference data offline, rather than online. In this case, read-only offline sessions can be created without fear of accidentally editing or posting data online.
If a read-only offline session exists on a computer and the user of that computer starts up OCHRE online, the user will be warned that there is a read-only offline session present, but will be allowed to continue into online OCHRE. If the read-only session gets out of date, simply recreate it. It will be overwritten by the newly created session.
Read-only sessions are never re-integrated back into OCHRE, so data in those sessions can be taken offline safely in other offline sessions.
Working online is allowed even if a read-only offline session is active.
Features Available Offline
Many OCHRE features can be used offline as long as the appropriate items are included when preparing the offline environment. These include:
Building Locations & Objects hierarchies, e.g. as part of representing ongoing archaeological excavation
Creating hierarchies of image Resources and linking these to other items; hotspotting images
Importing Text items and organizing Discourse hierarchies
Agnostic variables are available for use offline automatically. OCHRE will determine whether or not they are being used and will take along any supporting details it needs to the offline session. The standard Measurements hierarchy from the OCHRE master project does not need to be included in the offline session.
Bibliography can be linked to other items unless the bibliography is managed exclusively through the Zotero API. If bibliographic entries are native to OCHRE, or there are OCHRE stubs for Zotero items, and if the offline user has Insert/Delete access to the Bibliography category, then bibliography links can be made offline.
Hotspotting of images can be done offline as long as the hierarchy containing the images is included in the offline session. Only thumbnails of images will be offloaded, and they will be cached locally to minimize downloading in subsequent sessions.
GEO features; basemaps and/or source files for shapes (geodatabases/shapefiles) will be detected and offlined as needed by the items participating in the offline session.
Note that if a hierarchy is offlined that has its own basemap, that hierarchy's basemap will be taken along offline and the GEO session will use that local basemap as if it were the project basemap.
If more than one hierarchy having an associated basemap is taken offline, the basemap specified on the first-listed hierarchy that has a basemap will be used as the session's basemap. Other hierarchies' basemaps will be available to be used as local basemaps.
If none of the hierarchies being taken offline have associated basemaps, the basemap specified on the Resources Inbox will automatically be taken offline to serve as the project-level basemap.
If the Resource category's Inbox is explicitly added to the Offline profile, and if the Inbox has a basemap specification, that basemap will be taken offline to serve as the project-level basemap; the other hierarchies' basemaps, if any, will be available to be used as local basemaps.
Inserting and linking images by using the camera installed on the offline computer is available when working offline. Consider carefully how to manage these images, either in a local folder (which you are responsible to backup and upload), or using a remote server folder to which the images are posted during the Restore of the offline session. See the Wiki article Add Images From Camera for more details.
Features Not Available Offline
The following tasks are among the features not available offline:
Editing the Taxonomy
Linking texts to Dictionaries or Writing Systems, including using the Wizards to parse or analyze texts
Running Queries or Find-by options
Changing GEO specifications
Trouble-Shooting
If, when offline, you get the error message stating that there is no basemap available for the offline GEO session:
Check that you have clicked ON the option to "Include GEO content offline" in the User's Offline profile. This is defaulted OFF since it would normally entail downloading a much more significant amount of geospatial data (raster images, shapefiles, etc.) and we don't want this to happen unintentionally.
Check that you have included a basemap with the User's Offline profile. This could be done by linking in the Resource Inbox (to get the project's default basemap), or by listing first a Locations & Objects hierarchy that has its own local basemap specified.
Troubles Restoring an Offline Session?
Particularly in the context of poor or unreliable Internet, there may occasionally be problems syncing up an offline session. If you get the following error, offering to let you bypass the problem, choose "NO"! OCHRE will shut down the sync session. Simply restart it and try again. In many cases this will solve the problem and your uploading can continue. If you have tried re-starting (several times) and you continue to get this message, and you are well and truly stuck, then go ahead and opt to bypass the problem. Expect potentially other followup errors if there are dependencies on the transaction that failed.
Bypass problem only if all other options fail
If you need to bypass such an error, OCHRE will give you the option to save a diagnostics-related zip file at the end of the syncing session. Please do save this file and send it to the OCHRE Data Service for followup.
If an error message indicates that there was a "claim" problem, ensure that all other users are logged out of the project whose data you are syncing up and try again. (Note, however, that sometimes the "claim" error is triggered by a failed response from the Internet and this message can be a red herring.)