Location tracking

From CollectiveAccess Documentation
Revision as of 16:59, 15 October 2018 by Julia (talk | contribs) (Location Tracking Across Object Hierarchies)
Jump to: navigation, search

Updated for v1.6

Overview

Prior to version 1.5 collection object location and use history were tracked using standard metadata elements and relationships, in the same ways as other object-level information. Storage locations could be defined hierarchically and objects could be related to specific locations. Additional metadata could be recorded in the object and/or location records. For simple tracking this arrangement worked well enough, but it proved problematic for users seeking to maintain location histories, record complex per-move data (packing, insurance, etc.) or tracking usage across different classes of activity records (eg. loans, exhibitions, conservation, as well as movement). Starting with version 1.5, the available options have been expanded, with specialized tools for tracking location and use history of collection objects. (Of course, existing systems can continue to use the pre-1.5 location tracking methods if they wish.)

One size does not fit all when it comes to location tracking. To handle the range of tracking methodologies required by different types of museum and archival collections CollectiveAccess now offers three different mechanisms to track the location of collection objects:

  1. Direct object-location references. Location is recorded using relationships between object and storage location records. Relationships are dated, with the most recent date considered "current". This allows construction of simple location histories and is similar to the pre-1.5 method save for the dating.
  2. Movement-based location tracking. Location is recorded for objects in related movement records. Each movement record records details about a specific change in location for one or more objects. The current location for an object is considered to be the location referred to by the most recent movement by date. Movement of entire storage locations within the location hierarchy can be configured to record a movement, allowing current location tracking based upon individual object moves as well as movements of containers or other storage units.
  3. Workflow-based location tracking. Location is recorded for an object across a range of record types representing various related activities, including loans, movements, occurrences (typically recording exhibitions), deaccession and location relationships. Locations recorded using direct object-location or movement-based location tracking can be part of the range of data used by to derive current location.

Although it is possible to simultaneously employ more than one of these mechanisms in your system, in general you should choose only one to use.

Which method should I use?

Direct object-location reference is the simplest option and is suitable for collections that have fairly uniform location reporting requirements. If everything in your collection has a standard location and there are relatively informal movements of items between locations use this option. Many archives, historical societies and house museums and the like will find this an effective and easy to deploy option.

Movement-based location tracking records detailed information about how one or more objects are transferred between locations, in addition to the location history. This option is intended for collections where documenting chain of custody, insurance and packing are critical. This additional documentation comes at the expense of added complexity and additional required data entry. Every movement of an object or group of objects to a new location requires completion of a full movement record. Collections that routinely move valuable, sensitive or fragile materials (fine art museums, artists studios, archives with privacy concerns) may find this option preferable.

Workflow-based location tracking is designed for institutions with a robust notion of location and expands upon either of the preceding two options. In contrast with other methods, which all record relationships between objects and locations (with or without movements), workflow-based location tracking takes into consideration several types of records to determine the current location of an object, including direct object-location or movement-based tracking. With this method location can be based upon a combination of reported storage location, occurrence (often an exhibition or event), loan, movement or deaccession. For institutions that often loan or exhibit objects workflow-based tracking can reduce redundant data entry by using the loan or exhibition record itself as documentation of location, rather than requiring hacky double entry and pseudo "loan" or "on exhibit" storage locations. This flexibility comes at the cost of more complex configuration and, potentially, additional required data entry.

For most users direct object-location tracking should be sufficient. Movement-based or workflow-based location tracking should only be considered if you require the specific functionality they provide.

Location Tracking Across Object Hierarchies

In some CollectiveAccess configurations object records are structured hierarchically. In these systems a collection object may have various components, such as a tea set that's comprised of a pot and several cups. The tea set may have a "parent" record that captures the basic metadata about the item and individual records that track the unique aspects of each element. Before v 1.7 Location Tracking was typically established only at the "parent" level, which is to say that an object was expected to move as a whole. In v1.7 and later a new tool allows users to move individual elements and optionally show or hide "child" location activity at the "parent" level.

To configure this behavior, set the directive hide_include_child_history_controls to 0 in app.conf or set this configuration through the profile or user interface. The directive "includeFromChildren" and optionally "childTemplate" should also be set for each table defined for your location tacking feature. See more details about these directives below.

Direct object-location reference

Configuration

Basic configuration of object-location tracking is done in app.conf using the following directives:

App.conf Setting Name Description
object_storage_location_tracking_relationship_type A single relationship type (identified by alphanumeric type code) used to indicate an object storage location. Must be set to a valid object-storage location relationship type.

Use

There are two bundles available to implement location tracking in your editing user interfaces. The ca_objects_location bundle displays the current location, location history and adds a control to change the current location in the object editor.

The ca_objects_location bundle provides the following options when used with direct object-location tracking. These can be set in your installation profile or in the web-based configuration UI:

Setting Name Name in UI Description Values Default
locationTrackingMode Track location using Determines whether the bundle uses object-location references or movements to track object location. ca_storage_locations for direct object-location references; ca_movements for movement-based tracking ca_movements
displayTemplate Object location display template Layout for current location of object when displayed in list (can include HTML). The template is evaluated relative to the object-movement or object-storage location relationship that is current. Element code tags prefixed with the ^ character can be used to represent the value in the template. For example: ^ca_storage_locations.preferred_labels.name (moved on ^ca_objects_x_storage_locations.effective_date). Valid display template.
historyTemplate Object location history template Layout for each previous location of object when displayed in history list (can include HTML). The template is evaluated relative to the object-movement or object-storage location relationship. Element code tags prefixed with the ^ character can be used to represent the value in the template. For example: ^ca_storage_locations.preferred_labels.name (moved on ^ca_objects_x_storage_locations.effective_date). Valid display template.
currentLocationColor Color for current location Color to use as highlight for the current location in the location history and in the current location tab. Hex color with leading hash (#) #eeeeee
pastLocationColor Color for current location Color to use as highlight for the pasts location in the location history. Hex color with leading hash (#) #eeeeee
futureLocationColor Color for current location Color to use as highlight for future-dated locations in the location history. Hex color with leading hash (#) #eeeeee
useHierarchicalBrowser Use hierarchy browser for storage locations? If set a hierarchical browser will be used to select storage location items; if not set an auto-complete lookup will be used. 0 or 1 1

The ca_storage_locations_contents will display a list of all objects currently resident in a storage location. It provides the following options, which can be set in your installation profile or in the web-based configuration UI:

Setting Name Name in UI Description Values Default
list_format Format of contents list Format used to display location contents listing. list for a list of objects; bubbles for left-floated bubbles bubbles
locationTrackingMode Track location using Determines whether the bundle uses object-location references or movements to track object location. ca_storage_locations for direct object-location references; ca_movements for movement-based tracking ca_movements
displayTemplate Display template Layout for each object in the storage location (can include HTML). The template is evaluated relative to each object-movement or object-location relationship. Element code tags prefixed with the ^ character can be used to represent the value in the template. For example: ^ca_objects.prefered_labels,name (^ca_objects.idno). Valid display template.
colorItem Object color Color to use as highlight for each object in the storage location. Hex color with leading hash (#) #ffffff

Note that when using direct object-location tracking, a ca_storage_locations relationship bundle placed in an object editor will display all object-location links, past, present and future, in a single undifferentiated list and can be configured to allow users to add object-location links. The ca_objects relationship bundle placed in a storage location editor will behave similarly. In general, the ca_objects and ca_storage_locations relationship bundles should not be placed in the storage location and objects editors respectively when direct object-location tracking is in use.

Movement-based location tracking

Configuration

Basic configuration of movement-based location tracking is done in app.conf using the following directives:

App.conf Setting Name Description
movement_storage_location_tracking_relationship_type A single relationship type (identified by alphanumeric type code) used to indicate a movement storage location. Must be set to a valid movement-storage location relationship type.
movement_object_tracking_relationship_type A single relationship type (identified by alphanumeric type code) used to link an object to a movement for tracking purposes. Must be set to a valid object-movement relationship type.
movement_storage_location_date_element The movement DateRange metadata element that stores the date the movement was executed. This is the date the movement was actually performed, not the date the record was created. Use the alphanumeric metadata element code without the table name. For example, if the element is ca_movements.date_of_move set this to date_of_move
record_movement_information_when_moving_storage_location If set a movement record will be generated for all objects currently in the storage location when the location itself is moved within the location hierarchy

Use

As with direct object-location tracking there are two bundles available to implement location tracking in your editing user interfaces. The ca_objects_location bundle displays the current location, location history and adds a control to change the current location in the object editor. The options are the same as for object-location tracking, but the locationTrackingMode option should be set to ca_movements.

The location of an object will be updated when any of the following occur:

  1. The location of an object is changed using the object location bundle in the object editor
  2. A storage location is moved within the location hierarchy and the record_movement_information_when_moving_storage_location option is app.conf is set
  3. A movement record is manually created, a storage location is set for it and objects added to it

Note that changing the storage location of an existing movement will change the storage location for all objects associated with that movement but not the date. It will be as if the new location had been chosen on the movement date.

Workflow-based location tracking

Configuration

Unlike other location tracking options, which explicitly record location in a specific place in the database, workflow-based location tracking calculates the current location of an object by looking at a range of related records, comparing their dates, and selecting the most recently dated. What types of records are considered and which date elements in those records are used for comparison are entirely configurable.

Workflow-based location tracking can supplement direct object-location reference or movement-based tracking. That is, locations recorded with those two methods may be part of the mix of records workflow-based tracking considers when calculating the current location, but they don't have to be.

Primary configuration is done in app.conf through the current_location_criteria directive. current_location_criteria is an associative array the keys of which are the primary types you want considered. Relevant primary types for location tracking are: ca_storage_locations, ca_loans, ca_movements, ca_object_lots and ca_occurrences. Each primary type has a sub-array the keys of which are sub-types (except for ca_storage_locations for which it is a relationship type). Each sub-type/relationship type in turn has an array of options. For example:

current_location_criteria = {
	ca_storage_locations = {
		related = { 
			template = ^ca_storage_locations.hierarchy.preferred_labels%delimiter=_➜_ 
		}
	},
	ca_movements = {
		shipping = { date = pickup_date, color = 9bae33 },
		framing = { date = pickup_date, color = 541353 },
		conservation = { date = pickup_date, color = 245442 },
		administrative = { date = pickup_date, color = 992222 },
	},
	ca_loans = {
		collection = { 
			date = loan_period,
			color = cccccc
		}
	},
	ca_occurrences = {
		exhibition = { 
			date = exh_dates,
			color = 00cc00
		}
	},
	# The entry for ca_objects controls if and how deaccessions are displayed
	ca_objects = {
		template = ^ca_objects.deaccession_notes (^ca_objects.deaccession_date),
		color = cc0000
	}
}

In this example, ca_movements is a primary type, shipping is a movement sub-type and date is an option for the shipping sub-type (and others as well) specifying what date element should be used to calculate this movement sub-types place in the object's history. (For the ca_storage_locations primary type in the example, related is an object-storage location relationship type, and template is an option of that relationship type).

Note that display of deaccessions (managed via the ca_objects_deaccession editor bundle) in the object use history is controlled using the ca_objects primary type. If it is present in the configuration deaccessions will be shown, formatted using the supplied template and color, as in the example above.

Sub-type/relationship type options affect both the what is considered current and how the current location is displayed. Options include:

Option Name Description Mandatory?
template A display template evaluated relative to the related record when it is calculated to be current No. Will default to displaying the preferred label of the record
date The code of the DateRange metadata element used when calculating current location. Yes for all primary types except ca_storage_locations, for which date is derived from the object-storage location relationship.
color A color to highlight entries of this type with. Should be six-digit hex color No

This configuration will be used to display current location in the editor inspectors, when browsing on workflow-based current location and by default in the Object Use History (ca_objects_history) editor bundle.

The Object Use History bundle is used to display the current location as well as a detailed history of previous use. It is intended as a convenient means to show where an object is and has been, but can also be configured to show any set of related records by date. The bundle has a variety of settings to customize the layout and contents of the location stream. All of these can be set in the current_location_criteria bundle in app.conf, described previously, and used as defaults in the bundle. Let's take a look at an example:

UseHistory.png

In the bundle seen above the cataloguer has configured different colors and templates to showcase Accession, Loan, and Storage Location activity and data. Each block is automatically sorted by the date chosen through the bundle settings for that table. For example, Artwork loans are sorted on the "Loan Period" as seen via the dates on the far right-hand side. When a new relationship is created to any of the three configured tables a new segment will appear in the stream in the appropriate order based on date. In addition to the tables shown in the example, Occurrences, Movements, and Deaccessions can also be configured.

The contents of each block in the stream are entirely configurable using metadata display templates. With this powerful syntax any metadata from the related record, or from those records related to the related record, can be displayed in the Use History bundle. An example of that relationship traversing can be seen above in the Artwork loan blocks. There, the "Borrower" is displayed using the below syntax which pulls entities related to the related loan:

<l>^ca_loans.preferred_labels</l><br>
<ifdef code="ca_loans.loan_period">Loan Period:</ifdef> ^ca_loans.loan_period<br>
Borrower: <unit relativeTo="ca_loans">
<unit relativeTo="ca_entities" delimiter=", " restrictToRelationshipTypes="borrower">^ca_entities.preferred_labels</unit></unit>

Configuring bundle-specific settings through an installation profile

To add the Use History bundle to the installation profile, simply include the bundle placement and relevant settings on the appropriate UI screen. The use history settings defined in app.conf are taken as a system-wide universal, but defining the ca_objects_history setting in the profile allows for UI-specific customizations.

            <placement code="ca_objects_history">
              <bundle>ca_objects_history</bundle>
              <settings>
                <setting name="ca_object_lots_purchase_dateElement">accession_date</setting>
                <setting name="ca_object_lots_purchase_color">#663A8C</setting>
              </settings>
            </placement>

The chart below lists settings per table that can be included in your profile. Be sure to replace #type# with the custom type configured in your profile. For example, if "purchase" was the item idno in your list ca_object_lot_types, then your setting would be: ca_object_lots_purchase_dateElement.

Note that there is no dateElement setting for storage locations. Storage locations are sorted on the date cataloged.

Setting Name Description
hide_add_to_loan_controls Set to 1 if you want to to hide the "Add to loan" controls in this bundle placement. Defaults to 0
hide_update_location_controls Set to 1 if you want to to hide the "Update Location" controls in this bundle placement. Defaults to 0
useHierarchicalBrowser Set to 1 if you want to provide an hierarchical browser when searching for an updated storage location
locationTrackingMode Sets method for tracking location of object within storage location hierarchy. Set to ca_storage_locations to use direct object-location references; set to ca_movements to use movement-based location tracking
useAppConfDefaults Set to 1 if you want to use the app.conf current_location_criteria settings. If you want to set specific settings for this bundle then set this to 0 and specify values for that various settings below
ca_object_lots_showTypes Sets which object lots types appear in the use history stream.

For all showTypes settings, repeat once for each type that should be included. Use the item idno i.e. <setting name="ca_object_lots_showTypes">purchase</setting>

ca_object_lots_#type#_dateElement Sets the date field that is used to sort object lots of this type in the use history stream.
ca_object_lots_#type#_color Sets the color for this type of object lot. Use hex colors with no pound sign, i.e. "B1AAF2"
ca_object_lots_#type#_displayTemplate Sets the template for metadata displayed for this type of object lot in the use history stream.
ca_occurrences_showTypes Sets which occurrence types appear in the use history stream.
ca_occurrences_#type#_dateElement Sets the date field that is used to sort this type of occurrence in the use history stream.
ca_occurrences_#type#_color Sets the color for this type of occurrence. Use hex colors with no pound sign, i.e. "B1AAF2"
ca_occurrences_#type#_displayTemplate Sets the template for metadata displayed for this type of occurrence in the use history stream
ca_movements_showTypes Sets which movement types appear in the use history stream.
ca_movements_#type#_dateElement Sets the date field that is used to sort this type of movement in the use history stream.
ca_movements_#type#_color Sets the color for this type of movement. Use hex colors with no pound sign, i.e. "B1AAF2"
ca_movements_#type#_displayTemplate Sets the template for metadata displayed for this type of movement in the use history stream
ca_loans_showTypes Sets which loan types appear in the use history stream.
ca_loans_#type#_dateElement Sets the date field that is used to sort this type of loan in the use history stream.
ca_loans_#type#_color Sets the color for this type of loan. Use hex colors with no pound sign, i.e. "B1AAF2"
ca_loans_#type#_displayTemplate Sets the template for metadata displayed for this type of loan in the use history stream
ca_storage_locations_showRelationshipTypes Sets which related storage locations will appear.
ca_storage_locations_color Sets the color for all storage locations types. Use hex colors with no pound sign, i.e. "B1AAF2"
ca_storage_locations_displayTemplate Sets the template for metadata displayed for storage locations of all types.
showDeaccessionInformation Sets whether or not Deaccessions are included in the stream. 1 = yes; 0 = no.
deaccession_color Sets the color for deaccessions. Use hex colors with no pound sign, i.e. "B1AAF2"
deaccession_displayTemplate Sets the template for deaccessions.
sortDirection Set the sort direction of the history list. Use ASC for ascending order, DESC for descending order (default). Available from version 1.7

Browsing by current location

Workflow-based location tracking will cache the current location of the object within the object record, which makes browsing possible. To set up a current location browse add a facet of type location in browse.conf. For example:

current_location = {
			type = location,
			restrict_to_types = [],
			
			group_mode = none,
			
			collapse = {
				ca_loans = On loan,
				ca_movements/conservation = In conservation,
				ca_movements/shipping = Shipped,
				ca_movements/administrative = Consigned
			},
			
			display = {
				ca_storage_locations = {
					related = { template = ^ca_storage_locations.hierarchy.preferred_labels%delimiter=_➜_ (storage) }
				},
				ca_occurrences = {
					exhibition = { template = ^ca_occurrences.preferred_labels.name (exhibition) }
				},
			},
			maximumBrowseDepth = 1,
			include_none_option = No location specified,
			
			label_singular = _("current location"),
			label_plural = _("current location")
		},

The collapse, display, maximumBrowseDepth and include_none_option directives are specific to location facets:

Directive Description Mandatory?
collapse The facet will list entries for each distinct storage location. By default this means the each individual loan, movement, storage location or occurrence will be listed in the facet. For storage locations and occurrences this usually exactly what you want. Listing individual loans and movements, however, often results in a long list of undifferentiated values that makes effective browsing difficult. collapse' directs the browse to consolidate all records of a given type (and optionally) sub-type into a single generic facet value. In the example above, collapsing on ca_loans results in all objects for which the current location is a loan being browsable via a single "On loan" facet item. For movements, facet items are presented for individual movement sub-types. No.
display Sets the display template used to generate the facet item for the specified type and sub-type (or in the case of storage locations, type and relationship type). Each template is generated relative to the related record. No.
include_none_option Enable browsing for objects that have no current location set. The values of this directive will be used as the text of the facet item. No
maximumBrowseDepth As of version 1.7: Enables the bucketing of storage locations into top-level facets. Child locations are grouped by their parent, based on the depth set through this configuration. A browse at the parent level will be inclusive of all child locations. For example, objects currently stored in the locations: Offsite Storage > Room 1 and Offsite Storage > Room 2 will return when a user browses on Offsite Storage if the maximumBrowseDepth is set to 1. No

Updating the cache

For performance reasons, the current location of the object is cached within the object record itself. Since locations are calculated based upon the settings in the app.conf current_location_criteria directive, and change in current_location_criteria will likely invalidate the cached data. To regenerate the cache and ensure accurate browse results be sure to run the following caUtils command on the command line:

bin/caUtils reload-object-current-locations

Browsing current location when using non-workflow-based location tracking options

Browsing on current location is only supported in workflow-based location tracking. Since workflow-based location tracking supplements the other tracking options, enabling browse for any kind of location tracking involves setting up a minimal workflow-based configuration like this:

In app.conf, if you are using direct object-location location tracking:

current_location_criteria = {
	ca_storage_locations = {
		[relationship type] = { 
			template = ^ca_storage_locations.hierarchy.preferred_labels%delimiter=_➜_ 
		}
	}
}

where [relationship type] is set to whatever you have object_storage_location_tracking_relationship_type in app.conf set to.

If you are using movement-based location tracking then:

current_location_criteria = {
	ca_movements = {
		[movement type] = { 
			date = pickup_date,
			template = ^ca_storage_locations.hierarchy.preferred_labels%delimiter=_➜_ 
		}
	}
}

where [movement type] is a type of movement you want considered as indicating current location. You can list more than one type if needed.

Then in browse.conf add a facet definition like this for direct object-location tracking:

current_location = {
			type = location,
			restrict_to_types = [],
			
			group_mode = none,
			
			display = {
				ca_storage_locations = {
					[relationship type] = { template = ^ca_storage_locations.hierarchy.preferred_labels%delimiter=_➜_ (storage) }
				}
			},
			
			include_none_option = No location specified,
			
			label_singular = _("current location"),
			label_plural = _("current location")
		},

where [relationship type] is set to whatever you have object_storage_location_tracking_relationship_type in app.conf set to.

For movement-based tracking:

current_location = {
			type = location,
			restrict_to_types = [],
			
			group_mode = none,
			
			display = {
				ca_movements = {
					[movement type] = { template = ^ca_storage_locations.hierarchy.preferred_labels%delimiter=_➜_ (storage) }
				}
			},
			
			include_none_option = No location specified,
			
			label_singular = _("current location"),
			label_plural = _("current location")
		},

where [movement type] is a type of movement you want considered as indicating current location. You can list more than one type if needed.

General maintenance

Both direct object-location and movement-based location tracking rely on dates embedded in relationships between related records. If you are updating an older system, change app.conf configuration or otherwise have reason to believe these dates may be out of sync with the underlying movement and location data from which they are derived you can run the following caUtils command on the command line to refresh values:

bin/caUtils reload-object-current-location-dates

For most data sets this command should take only seconds to a few minutes to run and will not have adverse effects. If you are getting odd ordering in use histories or display of current location try running this command to resolve the issues.

Displaying current locations in reports

As of version 1.6 an object's current location can be included in reports via the Displays editor. To include the location, simply drag the "Current Location" bundle (also shown as "Object Location") onto your Display.

By default this bundle will display the Current Location as it is defined by the current_location_criteria (see above). Put another way, the report will output the same formatting used for location tracking in the cataloging interface. To override this formatting, use the "display format" setting on the "Object Location" bundle. To include the activity date use the syntax: ^ca_objects.ca_objects_location_date. To show the current_location_criteria use the syntax: ^ca_objects.ca_objects_location

update_sphinx

Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools