CollectiveAccess Cookbook

From CollectiveAccess Documentation
Revision as of 19:59, 23 July 2013 by Julia (talk | contribs) (Enabling a "cross-table" hierarchy)
Jump to: navigation, search

Welcome to the CollectiveAccess Cookbook. Here you'll find common problems and solutions in an easy-to-access to format. More in depth documentation is available elsewhere, so make sure to check out the "See Also" links for more detailed information.

Contents

Installing CollectiveAccess

Quick installation for evaluation

Problem
You want to install CollectiveAccess quickly, without worrying about server configuration, for evaluation purposes.
Solution
Try the quick start installation package for Mac or Windows: http://collectiveaccess.org/download
See also
Downloads

Basic requirements

Problem
You want to make sure your server meets the basic CollectiveAccess requirements.
Solution
Basic server requirements include:
  • Operating system - Linux, Windows (Server 2003, Server 2008, Windows XP and Windows 7 verified to work), Solaris 9+, Mac OS X 10.5+.
  • Server memory - For typical uses and small media (eg. 10 meg TIFF images or 2 meg JPEG images) 1gig of memory is usually adequate to ensure reasonable performance.
  • Data storage - A simple formula for estimating storage requirements requires an expected number of media items to be catalogued and an average size for those media items. Once these quantities are known an estimate can be derived using some simple multiplication: <storage required> = <# of media items> * <average storage requirements per media item> * 1.5. The factor 1.5 is used to take into account the overhead of storing derivatives.
  • Processor - Any modern CPU should provide adequate performance.
See also
Getting started

Core software requirements

Problem
You are configuring a server to run CollectiveAccess and are checking that all the software requirements are in place.
Solution
Core requirements include:
  • MySQL version 5.0, 5.1 or 5.5. Make sure your MySQL installation supports InnoDB tables.
  • PHP version 5.3.6 or better is required. 5.4 is supported. You will need to make sure your PHP installation includes the following extensions: ZIP, libXML, DOM, mbstring, iconv, EXIF, JSON, MySQL, and posix
  • Apache HTTPD version 2.0 or 2.2 is recommended. Other web servers that support the PHP programming language will work as well.
Media processing software for type-specific media handling includes:
  • ImageMagick version 6.5 or better
  • ffmpeg
  • Ghostscript
  • and more depending on media type
See also
Software requirements

Configuring PHP

Problem
You are configuring PHP prior to installation.
Solution
Your PHP configuration file is usually named php.ini. Check the following settings:
  • post_max_size - the default value is 8 megabytes. If you are uploading large media files (and most CollectiveAccess users are) you will need to raise this to a value larger than the largest file size you are likely to encounter.
  • upload_max_filesize - set this to the same value you set post_max_size.
  • memory_limit - the default is 128 megabytes which should be enough for many systems, unless you are (a) uploading large images or (b) reindexing the search index of a large database. If you received memory limit exceeded errors, you should increase this limit.
  • display_errors - in some installation this is set to "off" by default. It is suggested that while installing and testing CA you set this option to "On"
See also
Configuring PHP

Installing from git

Problem
Your server is configured and you want to pull from git to install CollectiveAccess.
Solution
Set up an empty MySQL database for your installation. Run the following command from the parent of the directory into which you want to install CA:
git clone http://github.com/collectiveaccess/providence.git providence where the trailing "providence" is the name of the directory you want your installation to be in. Git will create the directory for you.
Copy the setup.php-dist file (in the root directory of the CA distribution) to a file named setup.php. Edit setup.php, changing the various directory paths and database login parameters to reflect your server setup. Make sure the permissions on the app/tmp, app/lib/core/Parsers/htmlpurifier/standalone/HTMLPurifier/DefinitionCache and server root directories are such that the web server can write to them. In a web browser navigate to the web-based installer (http://www.myCollectiveaccessSite.org/install). Enter your email address and select the installation profile that best fits your needs. Then click on the "begin" button.
See also
Installing Providence

Installing on shared servers

Problem
You want to install CollectiveAccess on a cheap, shared server.
Solution
Look for a host that can provide support for InnoDb tables for MySQL, PHP 5.3.6+ and ideally git, ffmpeg, and Image Magick.
See also
Installing on Cheap Shared Servers

Media upload issues on shared servers

Problem
You're having issues uploading media after installing on a cheap, shared server.
Solution
Take a look at Manage > Administration > Configure check. You may need to increase the values of some of the suhosin configurations. On a shared server you'll need to set this in the php.ini or phprc file.
See also
Installing on Cheap Shared Servers

Installation Profiles

Changing a field's repeatability

Problem
You want to create a field that can repeat up to 3 times in an object record.
Solution
Set the "maxAttributesPerRow" in the typeRestrictions for the metadataElement to 3.
        <restriction>
          <table>ca_objects</table>
          <settings>
            <setting name="minAttributesPerRow">1</setting>
            <setting name="maxAttributesPerRow">3</setting>
            <setting name="minimumAttributeBundlesToDisplay">1</setting>
          </settings>
        </restriction>
See also
Type Restrictions

Restricting a field by type

Problem
You've created a "Duration" field and you want it only to display for objects of the type "video."
Solution
Set the <type> tag in the typeRestrictions for the metadataElement to match the code for "video." The type code is the item idno in the list object_types.
        <restriction>
          <table>ca_objects</table>
          <type>video</type>
          <settings>
            <setting name="minAttributesPerRow">1</setting>
            <setting name="maxAttributesPerRow">1</setting>
            <setting name="minimumAttributeBundlesToDisplay">1</setting>
          </settings>
        </restriction>
See also
Type Restrictions

Dealing with Subtypes in Type Restrictions

Problem
An object type has multiple subtypes and you want to make sure your type restriction applies to all of these.
Solution
Use the "includeSubtypes" setting and set it to "1"
<restriction code = "r1">
           <table> ca_objects</table>
           <type> document</type>
           <includeSubtypes> 1</includeSubtypes>
           <settings>
             <setting name = "minAttributesPerRow"> 0</setting>
             <setting name = "maxAttributesPerRow"> 255</setting>
             <setting name = "minimumAttributeBundlesToDisplay"> 1</setting>
          </settings>
         </restriction>

If, however, you want to include a few subtypes, or even all subtypes save one, you need to list each one individually.

<restriction  code = "r1" >
             <table>ca_objects </table>
            <type>program </type>
             <settings>
               <setting  name = "minAttributesPerRow" >0 </setting>
               <setting  name = "maxAttributesPerRow" >255 </setting>
               <setting  name = "minimumAttributeBundlesToDisplay" >1
          </setting>
             </settings>
           </restriction>
            <restriction  code = "r2" >
             <table>ca_objects </table>
             <type>letter </type>
             <settings>
               <setting  name = "minAttributesPerRow" >0 </setting>
               <setting  name = "maxAttributesPerRow" >255 </setting>
               <setting  name = "minimumAttributeBundlesToDisplay" >1
        </setting>
             </settings>
           </restriction>

Creating a Relationship record

Problem
You want to catalog metadata about a relationship between two records on the relationship.
Solution
(Valid v1.4) Create a relationship user interface, just as you would a normal user interface, with the relationshipTable name set as the type.
    <userInterface code="entity_relationship_ui" type="ca_entities_x_entities">
      <labels>
        <label locale="en_US">
          <name>Interstitial Entity Editor</name>
        </label>
      </labels>
      <screens>
        <screen idno="basic" default="1">
          <labels>
            <label locale="en_US">
              <name>Basic info</name>
            </label>
          </labels>
          <bundlePlacements>
            <placement code="ca_attribute_relationshipDate">
              <bundle>ca_attribute_relationshipDate</bundle>
            </placement>
          </bundlePlacements>
        </screen>
      </screens>
    </userInterface>
You'll also need to have created metadata elements to populate the user interface, for example:
    <metadataElement code="relationshipDate" datatype="DateRange">
      <labels>
        <label locale="en_US">
          <name>Relationship date</name>
          <description/>
        </label>
      </labels>
     <settings/>
      <typeRestrictions>
        <restriction code="r1">
          <table>ca_entities_x_entities</table>
          <settings>
            <setting name="minAttributesPerRow">1</setting>
            <setting name="maxAttributesPerRow">1</setting>
            <setting name="minimumAttributeBundlesToDisplay">1</setting>
          </settings>
        </restriction>
      </typeRestrictions>
    </metadataElement>
See also
Relationship Records

Restricting a Relationship by Type

Problem
You want to restrict a "related entities" field to just one type - "related playwrights."
Solution
Override the default "related entities" label and restrict to type "playwrights" using the following code:
 <screen idno="relationships" default="0">
          <labels>
            <label locale="en_US">
              <name>Relationships</name>
            </label>
          </labels>
     <bundlePlacements>
        <placement code="ca_playwrights">
                <bundle>ca_entities</bundle>
                  <settings>
                   <setting name="restrict_to_relationship_types">playwright</setting>
                   <setting name="label" locale="en_US">Related playwrights</setting>
                  </settings>
         </placement>
        <placement code="ca_director">
                <bundle>ca_entities</bundle>
                  <settings>
                   <setting name="restrict_to_relationship_types">director</setting>
                   <setting name="label" locale="en_US">Related directors</setting>
                  </settings>
         </placement>
  </bundlePlacements>
 </screen>

Where the setting "playwright" in "restrict_to_relationship_types" exactly matches the relationship type defined between the record type your screen is for (i.e. objects) and the relationship field type (i.e. entities).

Restricting a Screen

Problem
You need to restrict a relationship to just one object type's editing UI - for example, you want a "related director" for videos, but not for photos, and a "related photographer" field for photos, but not videos.
Solution
You need to create two separate screens, one for videos and one for photos, and restrict the entire screen by type using the following code:
<screen idno="relationships_video" default="0">
         <labels>
           <label locale="en_US">
             <name>Relationships</name>
           </label>
         </labels>
        <typeRestrictions>
           <restriction code="video" type="video"/>
         </typeRestrictions>
    <bundlePlacements>
       <placement code="ca_director">
               <bundle>ca_entities</bundle>
                 <settings>
                  <setting name="restrict_to_relationship_types">director</setting>
                  <setting name="label" locale="en_US">Related directors</setting>
                 </settings>
        </placement>
 </bundlePlacements>
</screen>
<screen idno="relationships_photo" default="0">
         <labels>
           <label locale="en_US">
             <name>Relationships</name>
           </label>
         </labels>
        <typeRestrictions>
           <restriction code="photo" type="photo"/>
         </typeRestrictions>
    <bundlePlacements>
       <placement code="ca_photographer">
               <bundle>ca_entities</bundle>
                 <settings>
                  <setting name="restrict_to_relationship_types">photographer</setting>
                  <setting name="label" locale="en_US">Related photographers</setting>
                 </settings>
        </placement>
 </bundlePlacements>
</screen>

Formatting a Container

Problem
You need to fit multiple sub-elements in a container and you don't want them to spill off the screen.
Solution
Format your container with line breaks so that not all sub-elements are in the same row using setting "lineBreakAfterNumberofElements":
      <settings>
        <setting name="lineBreakAfterNumberOfElements">2</setting>
      </settings>
See also
Attribute settings: Container

Setting default for checkboxes

Problem
You want to use a yes/no checkbox, but you need it to default to "no."
Solution
Use the following code:
<list code="yes_no" hierarchical="0" system="0" vocabulary="0">
      <labels>
        <label locale="en_US">
          <name>Yes/No</name>
        </label>
      </labels>
      <items>
        <item idno="yes" rank="1" enabled="1" default="0">
          <labels>
            <label locale="en_US" preferred="1">
              <name_singular>Yes</name_singular>
              <name_plural>Yes</name_plural>
            </label>
          </labels>
        </item>
        <item idno="no" rank="2" enabled="1" default="1">
          <labels>
            <label locale="en_US" preferred="1">
              <name_singular>No</name_singular>
              <name_plural>No</name_plural>
            </label>
          </labels>
        </item>
      </items>
    </list>

in which you've added "rank."

Validating the profile

Problem
Your installation fails because your profile is invalid. Maybe you've gotten the message: There were errors parsing the profile(s): Profile validation failed. Your profile doesn't conform to the required XML schema.
Solution
Validate your profile against the profile syntax XML schema. The schema is located in install/profiles/xml/profile.xsd. Simply copy the schema to the same directory as the profile you are editing and use a validating XML editor such as OxygenXML.
See also
Troubleshooting Profiles
Installation Profile Syntax

Creating a login

Problem
You need to create an administrator login within the profile.
Solution
Use the code:
<logins>
   <login user_name="admin" password="password" fname="CollectiveAccess" lname="Administrator"
     email="you@email.com">
     <role code="admin"/>
     <group code="admin"/>
   </login>
 </logins>

Creating a display

Problem
You need to create custom default displays within the configuration profile.
Solution
Use the following code, adding bundle placements for whichever metadata elements you wish to see in the display:
 <displays>
    <display code="general_object_report" type="ca_objects" system="1">
        <labels>
            <label locale="en_US">
                <name>General Object Report</name>
            </label>
        </labels>
        <bundlePlacements>
            <placement code="idno">
                <bundle>ca_objects.idno</bundle>
            </placement>
            <placement code="preferred_labels">
                <bundle>ca_objects.preferred_labels</bundle>
            </placement>
            <placement code="description">
                <bundle>ca_objects.description</bundle>
            </placement>
            <placement code="dimensions">
                <bundle>ca_objects.dimensions</bundle>
            </placement>
            <placement code="date">
                <bundle>ca_objects.date</bundle>
            </placement>
            <placement code="entities">
                <bundle>ca_entities</bundle>
            </placement> 
            <placement code="locations">
                <bundle>ca_storage_locations</bundle>
            </placement>          
        </bundlePlacements>
    </display>    
    <display code="entity_report" type="ca_entities" system="1">
        <labels>
            <label locale="en_US">
                <name>General Entity Display</name>
            </label>
        </labels>
        <bundlePlacements>
            <placement code="preferred_labels">
                <bundle>ca_entities.preferred_labels</bundle>
            </placement>  
            <placement code="address">
                <bundle>ca_entities.address</bundle>
            </placement> 
            <placement code="email">
                <bundle>ca_entities.email</bundle>
            </placement> 
            <placement code="telephone">
                <bundle>ca_entities.telephone</bundle>
            </placement> 
            <placement code="related_objects">
                <bundle>ca_objects</bundle>
            </placement>         
        </bundlePlacements>
    </display>
</displays>

Formatting a Display

Problem
You need to style your display so that a.) it only includes a heading when there is content in the field and b.) the heading is in bold text for easier viewing.
Solution
Use an <ifdef> tag to create a conditional heading, and format the text using HTML. When creating a display through the profile be sure to enclose the format template in <![CDATA[ ]] otherwise it will be parsed:
<placement code="cataloguer">
          <bundle>ca_objects.museum_cataloguer</bundle>
          <settings>
         <setting name="format"><![CDATA[<ifdef code="cataloguers_museum"><b>Catalogued by: </b></ifdef> ^cataloguers_museum </ifdef> <ifdef code="dates_catalogued"><b>Date:</b></ifdef> ^dates_catalogued <ifdef code="cataloguer_notes"><b>Cataloguer Notes:</b></ifdef> ^cataloguer_notes]]>
          </setting>
          </settings>
        </placement>

Changing terminology

Problem
You need to change a default CollectiveAccess term, Object Lots, to a custom one, Accesssions
Solution
Open and edit messages.po using a GetText-compatible editor such as POEdit and translate each English string into your target language. If using POEdit, the .mo file will be automatically created or updated every time you save your .po file. Then, change the display names in the "Find" and "New" menus using navigation.conf:
"navigation" = {
"object_lots" = {
"displayName" = _("Accessions"),
See also
Translations


Changing how List elements are displayed

Problem
You have a metadata element of datatype=List and you need to render its display to something other than a drop-down menu.
Solution
List elements can be rendered in numerous other ways besides drop-down menus. The can be configured as checklists, radio buttons, hierarchy browsers, and type-ahead lookups, and others. In <settings> for the metadata element, use the following syntax to render a List a certain way:
      <settings>
        <setting name="render">radio_buttons</setting>
      </settings>
Options:
Yes/no checkbox (code="yes_no_checkboxes");
Radio buttons (code="radio_buttons");
Checklist (code="checklist");
Type-ahead lookup (code="lookup");
Horizontal hierarchy browser (code="horiz_hierbrowser");
Horizontal hierarchy browser with search (code="horiz_hierbrowser_with_search");
Vertical hierarchy browser (code="vert_hierbrowser")
See also
Attribute_settings:_List


Customizing display of metadata in Relationship Bundles

Problem
You want to display metadata attached to related items in relationship bundles. For example, if you want to display both the name and life dates for related entities you can use a bundle display template to both extract and format the metadata.
Solution
Set the relationship list format to 'list.' Then, use bundle display template formatting to configure the metadata inside the display_template setting. You must wrap the display template in <![CDATA[ ]] otherwise the template will be parsed:
           <placement code="ca_entities">
              <bundle>ca_entities</bundle>
              <settings>
                <setting name="restrict_to_types">individual</setting>
                <setting name="label" locale="en_US">Related Entities</setting>
                <setting name="list_format">list</setting> 
                <setting name="display_template"
                   <![CDATA[<l>^ca_entities.preferred_labels</l>
                   <ifdef code="ca_entities.life_dates">Life Dates:   
                   </ifdef>^ca_entities.life_dates]]></setting>
               </settings>
            </placement> 
See also
Bundles
Bundle_Display_Templates


Placing a Local Subject Authority on a UI

Problem
You will be using a local subject authority and you want to place "subjects" on your Object Editing UI.
Solution
use "ca_list_items" and place on the UI in the following format:
<placement code="ca_list_items">
              <bundle>ca_list_items</bundle>
              <settings>
                <setting name="restrict_to_lists">local_vocab</setting>
                <setting name="label" locale="en_US">Subject Access</setting>
                <setting name="add_label" locale="en_US">Add term</setting>
              </settings>
            </placement> 

in which the list holding your subject authority will be specified in the setting "restrict_to_lists."

Changing the Size of a Preferred Labels Text Box

Problem
You want to make the Preferred Labels text box wider, but it's not listed among the other metadata elements because it's a baked-in element.
Solution
You can simply add "height" and "width" settings to the bundle placement in the UI.
<placement code="preferred_labels">
              <bundle>preferred_labels</bundle>
              <settings>
                <setting name="label" locale="en_US">Object Name</setting>
                <setting name="add_label" locale="en_US">Add Object Name</setting>
                <setting name="height">1</setting>
                <setting name="width">90</setting>
              </settings>
            </placement>

Make sure that the "height" and "width" settings don't include locale settings, as this will create errors.

Using the DateRange Calendar Feature

Problem
You've noticed that there's a small calendar icon inside DateRange elements, but nothing happens when you click on it.
Solution
You need to use the "useDatePicker" setting when configuring the metadata element and be sure that it is set to "1."
<metadataElement code="start" datatype="DateRange">
          <labels>
            <label locale="en_US">
              <name>Exhibit Start Date</name>
            </label>
          </labels>
        <settings>
        <setting name="fieldWidth">40</setting>
        <setting name="fieldHeight">1</setting>
        <setting name="minChars">0</setting>
        <setting name="maxChars">65535</setting>
        <setting name="useDatePicker">1</setting>
      </settings>
    </metadataElement>


Using hierarchical records

Problem
You want to create a record hierarchy for example nested Collection records.
Solution
In app.conf, set:
ca_collections_show_add_child_control_in_inspector = 1
Then make your record types hierarchical either through the installation profile:
<list code="collection_types" hierarchical="1" system="0" vocabulary="0">
      <labels>
        <label locale="en_US">
          <name>Collection types</name>
        </label>
      </labels>
      <items>
        <item idno="collection" enabled="1" default="1">
          <labels>
            <label locale="en_US" preferred="1">
              <name_singular>collection</name_singular>
              <name_plural>collection</name_plural>
            </label>
          </labels>
          <items>
            <item idno="fonds" enabled="1" default="0">
              <labels>
                <label locale="en_US" preferred="1">
                  <name_singular>fonds</name_singular>
                  <name_plural>fonds</name_plural>
                </label>
              </labels>
              <items>
                <item idno="series" enabled="1" default="0">
                  <labels>
                    <label locale="en_US" preferred="1">
                      <name_singular>series</name_singular>
                      <name_plural>series</name_plural>
                    </label>
                  </labels>
                  <items>
                    <item idno="file" enabled="1" default="0">
                      <labels>
                        <label locale="en_US" preferred="1">
                          <name_singular>file</name_singular>
                          <name_plural>file</name_plural>
                        </label>
                      </labels>
                    </item>
                  </items>
                </item>
              </items>
            </item>
          </items>
        </item>
      </items>
    </list>
Or under Lists & Vocabularies in the graphical user interface:

ListVocabHier.png

The final step is to include the Location in hierarchy bundle on the Collections user interface, either through the installation profile:
<userInterface code="collection_ui" type="ca_collections">
      <labels>
        <label locale="en_US">
          <name>Collection editor</name>
        </label>
      </labels>
      <screens>
        <screen idno="basic" default="1">
          <labels>
            <label locale="en_US">
              <name>Basic Info</name>
            </label>
          </labels>
          <bundlePlacements>
            <placement code="hierarchy_location">
              <bundle>hierarchy_location</bundle>
            </placement>
or the graphical user interface under Manage > Administration > User interfaces > Collection editor > Basic info > Location in hierarchy bundle.
See also
Location_in_Hierarchy_Bundle


Enabling a "cross-table" hierarchy

Problem
You want to be able to nest Object records underneath Collections hierarchically.
Solution
In app.conf, set:
    ca_objects_x_collections_hierarchy_enabled = 1
    ca_objects_x_collections_hierarchy_relationship_type = part_of
Make sure part_of is defined as a relationship type between objects and collections:
    <relationshipTable name="ca_objects_x_collections">
      <types>
        <type code="part_of" default="1">
          <labels>
            <label locale="en_US">
              <typename>is part of</typename>
              <typename_reverse>contains</typename_reverse>
            </label>
          </labels>
          <subTypeLeft> </subTypeLeft>
          <subTypeRight></subTypeRight>
        </type>
      </types>
    </relationshipTable>
And back in app.conf, enable:
    ca_collections_show_add_child_control_in_inspector = 1
As with any hierarchical cataloging, you'll need to place the Location in hierarchy bundle on the user interfaces (Objects and Collections), either through the installation profile:
   <userInterface code="collection_ui" type="ca_collections">
      <labels>
        <label locale="en_US">
          <name>Collection editor</name>
        </label>
      </labels>
      <screens>
        <screen idno="basic" default="1">
          <labels>
            <label locale="en_US">
              <name>Basic Info</name>
            </label>
          </labels>
          <bundlePlacements>
            <placement code="hierarchy_location">
              <bundle>hierarchy_location</bundle>
            </placement>
or the graphical user interface under Manage > Administration > User interfaces > Collection editor > Basic info > Location in hierarchy bundle.
See also
Location_in_Hierarchy_Bundle


Data import

Importing a constant value

Problem
You want a list called "Language" in your CollectiveAccess system to be set as "English" for all records brought in through your import.
Solution
In the Rule Type column for that mapping row, chose Constant. In the Source column set the value, English, by using the unique list code for that item (i.e. "eng").
See also
Data Import: Creating and Running a Mapping (Settings and Constants)
Data Importer (Rule Types)

Grouping data

Problem
You want to map several fields to placements inside a single container.
Solution
Select an arbitrary group name and use it in the "Group" column of your mapping. Any row that includes that name will be linked inside a single placement of a container.
See also
Data Importer (Groups)
Data Importer (Common Problems)

Conditionally skipping data

Problem 1
You want to prevent import of the value "n/a" which has been input instead of data in some cases.
Solution 1
Use the "skipGroupIfValue" option. In this case, {"skipGroupIfValue": ["n/a"]}
Problem 2
You want to skip a whole row of data if a specific value is used in a particular column.
Solution 2
Use the "skipRowIfValue" option. Alternately, use the "skipRowIfNotValue" option.
Problem 3
You want to skip any values that may be in a "Date Type" column if there is no "Date" data.
Solution 3
Create a Group that binds the two columns and use the "skipGroupIfEmpty" option for the "Date" data.
See also
Data Importer (Groups)
Data Importer (Options)

Formatting a Title

Problem
You want to create titles for the records you're importing based on a set format.
Solution
Use the "formatWithTemplate" option. For example: {"formatWithTemplate": "Oral History #^15 with Interviewee ^12"} where ^15 and ^12 are references to columns in the data source where identifiers and entity names can be found.
See also
Data Importer (Options)
Data Import: Creating and Running a Mapping (Options)

Importing a list

Problem
You want to import a list, but the values in your data don't 100% match your values in CollectiveAccess.
Solution
Use the "Original values" and "Replacement values" columns in your mapping. For example if your data source includes "Y" and "N" but your CollectiveAccess list codes are "yes" and "no," simply input those values on your mapping with a line breaks (returns) between each value per column.
See also
Original Values and Replacement Values

Foreign Key Constraint in Object Lots

Problem
Your object lot import failed. You may have received the error: Could not insert new record Cannot add or update a child row: a foreign key constraint fails (`project`.`ca_object_lots`, CONSTRAINT `fk_ca_object_lots_lot_status_id` FOREIGN KEY (`lot_status_id`) REFERENCES `ca_list_items` (`item_id`))
Solution
Object lots have a non-optional "lot_status_id" that is a value taken from the "object lot statuses" list. It must be set to a valid value or a constant value, mapping to ca_object_lots.lot_status_id.
See also
Data Importer (Common Problems)

Mapping Object Lot Id Numbers

Problem
You want to map object lot id numbers (idnos).
Solution
Id numbers for ca_object_lots don't map to the normal ca_object_lots.idno but rather ca_object_lots.idno_stub.
See also
Data Importer (Common Problems)

Relating Lot records to Objects in an Objects Mapping

Problem
You are importing Object records and wish to relate them to their respective Lot record in the mapping.
Solution
Unlike Entities, Lists, Collections, and other Primary Types, you do not use a Splitter to relate Lot records to Objects in a mapping. Rather, set the source to the Lot id and the ca_table.element to: "ca_objects.lot_id". This works because an Object can be associated with one and only one Lot.

Importing Variable Relationship Types

Problem
You want to define a relationship type in a refinery parameter, but you realize that there is more than one type in your source column or field.
Solution
Instead of writing "relationshipType":"creator" or something else singular, use "relationshipType":"^2" in which the caret is followed by the data source from which you wish to draw relationship types (in this case "2" is just an example).
See Also
Data Import: Creating and Running a Mapping (Parameters)

Creating One Entity Record from Separate Sources

Problem
An entity's name is split up into two different columns in a source spreadsheet, but you want to merge both to create a single entity record
Solution
Use the entityJoiner refinery in your mapping, being sure to include full container paths in the attributes parameter (since you'll be creating a new record). Parameters include entityType, entityTypeDefault, forename, surname, other_forenames, middlename, display name, prefix, suffix, attributes, nonpreferred_labels, relationshipType, relationshipTypeDefault, and skipIfValue.
See Also
Data Import: Creating and Running a Mapping (Parameters)


Including Metadata in a Parameter

Problem
You are using an entitySplitter, and you want to use the parameter to import address information about the entity
Solution
Use parameter "attributes" and use the following syntax to include metadata within a container:
"attributes":{"address":{"address1":"^24", "address2":"^25","city":"^26", "stateprovince":"^27", "postalcode":"^28", "country":"^29"}}}

in which "address" is the container, all subelements are contained within internal curly brackets, and carets are followed by the source column number.

See Also
Data Import: Creating and Running a Mapping (Parameters)

Mapping Measurements from one Source to Separate Fields

Problem
All of the dimensions data in your source are in the same column, but you want to map them to separate fields in CollectiveAccess.
Solution
Use the measurementsSplitter refinery to divide the dimensions into fields of the dataType Length or Weight. Use the "delimiter" refinery parameter to separate the measurement values, use "units" to specify the unit of measurement, use "elements" to map the components of the dimensions to their respective fields, and use "attributes" to include any other elements (such as a notes field) that may be in a measurements container.
"elements": [{"quantityElement":"measurementWidth", "typeElement": "measurementsType",
"type":"width"},{"quantityElement":"measurementHeight", "typeElement":
"measurementsType2","type":"height"}] OR "elements": [{"quantityElement":"measurementsWidth"},
{"quantityElement":"measurementsHeight"}]
See Also
Data Importer: Refineries

Setting a Unit Specifier for Mapping Dimensions

Problem
You are mapping dimensions data but the unit specifier is not set within each data cell, but rather declared in a data column header.
Solution
Use the suffix formatting under "Options" in your mapping to set the unit specifier for all Dimensions in the source column:
{"suffix": "cm"}
{"suffix": "in"}

If some of the cells are empty, be sure to set a default value so that you don't get an error in which the "length" attribute type doesn't recognize a suffix attached to nothing:

{"suffix": "cm", "default":"0"}

Using a Hierarchical Delimiter for Storage Locations

Problem
The storage locations in your source are expressed only with numbers, 4.2.1 where 4 indicates a room, 2 indicates a rack, and 1 indicates a cabinet.
Solution
Use the storageLocationSplitter refinery with two key parameters that work in tandem: "hierarchicalStorageLocationTypes" and "hierarchicalDelimiter." The hierarchicalStorageLocationTypes adds labels to the numbers in order so that you know what they mean, and the hierarchicalDelimiter tells those labels where to go (as opposed to the regular "delimiter" parameter which would create new records on each delimiter.) In this example, the parameter would be expressed: {"hierarchicalStorageLocationTypes" : ["room", "rack", "cabinet"], "hierarchicalDelimiter":"."}
See also
Data Importer (Refineries)

Importing XML

Problem
You need to import data in an XML file.
Solution
Format-specific data reader code plugins are required to import XML formats. As of version 1.4 two XML formats are supported:
  1. FMPDSORESULT (Filemaker Pro XML data export format)
  2. InMagic XML (Export format for the InMagic archival application)
If you're working with FMPDSORESULT or InMagic XML, set the mapping document's inputType to "FMPDSO" or "Inmagic" respectively and format your source data as /xml_tag in place of <xml_tag>.
If you need to work with some other XML-based format, you'll need to develop a data reader plugin for it. For most formats you can start by copying the FMPDSORESULT plugin (in app/lib/ca/Import/DataReaders/FMPDSOResultReader.php) to a new file in app/lib/ca/Import/DataReaders/ with the name of the new format + "Reader.php" Then change the class name and specifics in the copy to align with your new format.
If you need assistance implementing a new import format please post your request on the support forum at [1]

Importing MARC

Problem
You are importing a MARC database, rather than XLSX or XLS.
Solution
Set the mapping document's inputType to "MARC" and format your source data by MARC Rule and Subfield as "rule/subfield" (ex. 035/a) and ignore indicators, if you choose.
If you do need to use MARC indicators, you append them after the sub-field and another '/'.
Example:
100/a (no indicators)
100/a/x (indicator 1=x)
100/a/xy (indicator 1=x; indicator 2=y)
A concrete example:
MARC:
245 18$aThe ... annual report to the Governor.
The Import mapping source would be:
245/a/18 (as in rule/subfield/indicator1indicator2).

Mapping a MARC element with multiple sub-fields

Problem
What about mapping MARC elements that contain multiple sub-fields?
Solution
Sub-fields are denoted by the "$" sign, which can be ignored in the mapping document. Use display formatting to map a MARC element with multiple sub-fields to a single metadata element.
For example:
245 10$aTrade Union Fellowship Program :$b[announcement].
Here, the source is set to 245/a, and the following format is set in options:
{"formatWithTemplate": "^245/a  ^245/b"}

Pawtucket

Adding elements to a "detail" page

Problem
You want to add fields (or metadata elements) to the display on an "detail" page.
Solution
To place metadata elements in the left column of a detail page, set ca_objects_detail_display_attributes, ca_entities_detail_display_attributes, ca_places_detail_display_attributes, ca_occurrences_detail_display_attributes and/or ca_collections_detail_display_attributes in app.conf to a list of the element codes you would like to appear.
See also
Detail Pages (Pawtucket)
Application Configuration (Pawtucket)

Adding a list element to a "detail" page

Problem
You want to add a list element to the display on an "detail" page.
Solution
You need to pass the convertCodesToDisplayText option to get() in the Detail view on your detail page (/themes/default/views/Detail). For example,
    if($va_material = $t_object->get('ca_objects.material', array('convertCodesToDisplayText' => true, 
    'delimiter' => ', '))) {<br /> print "<div class='unit'><b>"._t("Material")."</b> ".$va_material."</div>
    <!-- end unit -->";
See also
API Getting Data
Detail Pages (Pawtucket)
Application Configuration (Pawtucket)

Adding a relationship to a "detail" page

Problem
You want to display a relationship on a record's "detail" page.
Solution
You'll need to add the relationship(s) in the file for the specific detail page (i.e. ca_collections_detail_html.php) at themes/(your_theme)/views/Detail. Below shows Related Entities on a Collection detail page.
$va_entities = $t_collection->get("ca_entities", array("returnAsArray" => 1, 'checkAccess' =>$va_access_values)); if(sizeof($va_entities) > 0){	?><div class="unit"><h2><?php print _t("Related")." ".((sizeof($va_entities) > 1) ? _t("Entities") : _t("Entity")); ?></h2>
    <?php
foreach($va_entities as $va_entity) {print "<div>".(($this->request->config
>get('allow_detail_for_ca_entities')) ? caNavLink($this->request, $va_entity["label"], '', 'Detail', 'Entity', 'Show', array('entity_id' => $va_entity["entity_id"])) : $va_entity["label"]).(".$va_entity['relationship_typename'].")</div>\n";
				}
    ?>
				</div><!-- end unit -->
    <?php
			}
See also
Detail Pages (Pawtucket)
Application Configuration (Pawtucket)

Configuration Files

Browsing on a metadata element

Problem
You need to set up the browse so users are able to browse on a particular metadata element, such as a list.
Solution
In the browse.conf file, configure a browsing facet of type:Attribute for whichever primary type you need to browse for. You should only configure browsing on metadata elements that have a relatively small range of possible values. Browsing on List elements work quite well. Attributes with narrative text content will not work well.
First, locate the primary type for which you are configuring a browse (Objects, Entities, Collections, etc.). For example, all the browse facets for Objects are preceded by the following code:
# Configuration for object browse
ca_objects = {
	facets = {
Then, enter the following:
name_your_facet = {
type = attribute,
element_code = your_metadata_element_code,

group_mode = none,

label_singular = _("Enter a Label Here"),
label_plural = _("Enter a Label Here")
},
Where "your_metadata_element_code" would be replaced by the element code for your chosen field. Be sure to name_your_facet uniquely, and assign the appropriate labels for the facet as well.
See also
Browse.conf

Browsing on Related Authorities

Problem
You need to set up the browse so that users can browse for Objects by related authorities, such as Occurrences.
Solution
In browse.conf, Authority facets allow for browsing on cataloging applied to the browsed item from a related authority. Eg. if you want to browse for objects by place name, you'd set up a facet of type authority with options to cover the places authority. Here is an example of the code you would enter to browse by Related Occurrences:
		occurrence_facet = {
			type = authority,
			table = ca_occurrences,
			generate_facets_for_types = 1,
			relationship_table = ca_objects_x_occurrences,
			restrict_to_types = [],
			restrict_to_relationship_types = [],			
			
			groupings = {
				label = _("Name"), 
				type = _("Type"),
				relationship_types = _("Role"),
				ca_attribute_dates_value:years = _("Years"),
				ca_attribute_dates_value:decades = _("Decades")
			},
			
			group_mode = alphabetical,
			
			label_singular = _("occurrence"),
			label_plural = _("occurrences")
		},
Note that if there are multiple Occurrence types, and you wish for a unique browsing facet to be generated for each type, you can use the following setting:
                        generate_facets_for_types = 1,
On the other hand, if there are multiple Occurrence types and you wish to restrict the browse to a particular type or types, or if you wish to restrict the browse to particular relationship types, enter the List Identifier, or Relationship Type identifer in the following brackets:
			restrict_to_types = [],
			restrict_to_relationship_types = [],
See also
Browse.conf

Changing Currency Settings

Problem
You need a "Value" datatype to read "$" as CAD, rather than USD
Solution
In app.conf you can change the default dollar currency. If no currency is set, then the default will be "USD."
	default_dollar_currency = CDN		
See also
App.conf

Defining textual expressions of historic time periods for dateRange elements

Problem
You want your users to be able to type a commonly used textual expression to refer to a time period inside a Date field, but the 'dateRange' datatype only accepts valid dates.
Solution
In datetime.conf, You can actually define text expressions you wish to have the date/time parser convert to dates. The text expression on the left side of the equal sign must be all lowercase; the date/time expression on the right side must be valid and parsable.

Examples:

expressions = {
	us civil war = 1861 to 1865,
	world war 2  = 1939 to 1945,
	nickel empire = 1920s,
}

Adding Title types

Problem
You want to add a Title type drop-down list to your preferred and alternate label fields.
Solution
Create a list for your types in the installation profile. Make note of the list code. In app.conf find "#Label type lists" and input your list code for the correct option (i.e. ca_objects_preferred_label_type_list). As you will see there can be different lists for every record type.
See also
App.conf

Creating a search shortcut

Problem
You want to create a search shortcut to quickly find metadata values, for example: style:"stone sculpture" (where style searches two fields called Materials and Techniques).
Solution
Create an access point in search_indexing.conf by including the following in the ca_objects section:
	# ------------------------------------
	_access_points = {
		style = {
			fields = [ca_objects.materials, ca_objects.techniques],
			options = { DONT_INCLUDE_IN_SEARCH_FORM }
		},
where "materials" and "techniques" are the elementCodes of those fields.
See also
Search Indexing Configuration

Creating a search shortcut for a container

Problem
You want to create a search shortcut to quickly find specific metadata values in a single field within a container, for example: width:"5 in" (where width is inside a larger "measurements" container).
Solution
Create an access point in search_indexing.conf by including the following in the ca_objects section:
	# ------------------------------------
	_access_points = {
		width = {
			fields = [ca_objects.measurements.width],
			options = { DONT_INCLUDE_IN_SEARCH_FORM }
		},
where "measurements" is the elementCode of the whole container and "width" is the elementCode of the sub-element. Remember to use periods, as shown above.
See also
Search Indexing Configuration

Privileging the index of a field

Problem
You want a certain field to have more weight when sorting for relevance in your search index.
Solution
Use the field-level option BOOST to add weight. BOOST takes a numeric value, where a higher value counts for more weight. For example:
	ca_objects = {
		fields = {

			idno = { STORE, DONT_TOKENIZE, INDEX_AS_IDNO, BOOST = 100 },
See also
Search Indexing Configuration

Flexible indexing of identifiers

Problem
You want your identifier (idno) to be indexed with some flexibility so that different permutations are retrieved in a search. For example: a search for KA1 should return KA.0001.
Solution
Use the field-level option INDEX_AS_IDNO.
	ca_objects = {
		fields = {

			idno = { STORE, DONT_TOKENIZE, INDEX_AS_IDNO, BOOST = 100 },
See also
Search Indexing Configuration

Disabling Editors

Problem
You want to simplify your system so that Places, Movements, Loans, etc. don't appear in your "New" and "Find" drop-downs.
Solution
Scroll down to Editor "disable" switches in app.conf, and set all those you wish to disable to "1"
ca_objects_disable = 0
ca_entities_disable = 0
ca_places_disable = 1
ca_occurrences_disable = 0
ca_collections_disable = 0
ca_object_lots_disable = 0
ca_storage_locations_disable = 0
ca_loans_disable = 0
ca_movements_disable = 1
ca_tours_disable = 1
ca_object_representations_disable = 1
See also
App.conf

Enforcing a Strict Hierarchy

Problem
You have certain collection types that should only be catalogued as child records, and you don't want them to be accessible through the "New" menu.
Solution
Enforce a strict type hierarchy in app.conf and be sure to enable the appropriate "add child record" control.

First, set the desired type hierarchy to "1":

ca_objects_enforce_strict_type_hierarchy = 0
ca_entities_enforce_strict_type_hierarchy = 0
ca_places_enforce_strict_type_hierarchy = 0
ca_occurrences_enforce_strict_type_hierarchy = 0
ca_collections_enforce_strict_type_hierarchy = 1
ca_storage_locations_enforce_strict_type_hierarchy = 0
ca_loans_enforce_strict_type_hierarchy = 0
ca_tour_stops_enforce_strict_type_hierarchy = 0
ca_list_items_enforce_strict_type_hierarchy = 0

Then, be sure to set the appropriate "add child record" control to "1"

ca_objects_show_add_child_control_in_inspector = 0
ca_entities_show_add_child_control_in_inspector = 0
ca_places_show_add_child_control_in_inspector = 0
ca_occurrences_show_add_child_control_in_inspector = 0
ca_collections_show_add_child_control_in_inspector = 1
ca_storage_locations_show_add_child_control_in_inspector = 0
ca_loans_show_add_child_control_in_inspector = 0
ca_movements_show_add_child_control_in_inspector = 0
ca_tour_stops_show_add_child_control_in_inspector = 0
See also
App.conf

Translating "Find" and "New" Menus

Problem
You used poedit to change all instances of "Lots" in your system to "Accessions," but the "New" and "Find" menus still employ the old terminology.
Solution
Manually change the desired "displaynames" in nav.conf to reflect your chosen terminology.
"navigation" = {
			"object_lots" = {
				"displayName" = _("Accessions"),

Be sure to change the display name in both the New and Find menus.

Changing related item lookup settings

Problem
Only preferred labels are displayed inside the "draggable bubbles" in a relationship bundle, and you wish for the IDs to be displayed in addition to the preferred labels.
Solution
In App.conf, add the ca_table.element_code you wish to be displayed for the appropriate primary type in the section titled "related item lookup settings."

For example, you could change the following:

ca_entities_lookup_settings = [^ca_entities.preferred_labels]
ca_entities_lookup_delimiter = ➔

to

ca_entities_lookup_settings = [(^ca_entities.idno) ^ca_entities.preferred_labels]
ca_entities_lookup_delimiter = ➔

if you wanted Entity identifiers to be displayed inside parenthesis preceding Entity names.

More detailed formatting of relationship bundles can also be done through the UI. See this recipe and Bundle Display Templates for more information.

Setting Sort Order in a Hierarchy Browser

Problem
You've added a hierarchy browser to your configuration so that you can see Objects nested within Collections. However, you want the Objects to be sorted in alphabetical order by title instead of by idno.
Solution
Under "Hierarchy browser items" in app.conf you can set the hierarchy_browser_sort_values and sort_direction. First, find the table type for the values you want to sort in the browser. In this case you're working with Objects, so at the top of the list find
ca_objects_hierarchy_browser_sort_values = [ca_objects.idno_sort]

and then change the setting from [ca_objects.idno_sort] to [ca_objects.preferred_labels_sort] so that you see this:

ca_objects_hierarchy_browser_sort_values = [ca_objects.preferred_labels_sort]

Then, to set sort direction, visit the line below the values setting and, depending on your needs, set it to either "asc" (ascending) or "desc" (descending).

ca_objects_hierarchy_browser_sort_direction = asc

Configuring a Numbering System

Problem
You want child records to automatically generate id numbers in an ascending order based on the idno of the parent record.
Solution
Use the multipart_id_numbering.conf file to create a numbering format for the idno of the relevant table type. For example, say that you have a hierarchical collection system, in which one collection could have several sub-collections. In this case, scroll down to ca_collections in multipart_id_numbering.conf, and set the numbering convention for the parent type (named "main" in this example):
ca_collections = {
	main = {
			separator = .,
			elements = {
				collection_no = {
					type = FREE,
					width = 12,
					description = collection year,
				
					editable = 1

Then, for each sub-type (we'll show one, called "sub" in this example), repeat the settings for the parent record idno for the first half of the numbering system, and then set the second half as follows:

sub = {
			separator = .,
			elements = {
				collection_no = {
					type = FREE,
					width = 12,
					description = collection year,
				
					editable = 1
				},
				sub_number = {
					type = SERIAL,
					width = 4,
					description = sub#,
					editable = 1,
					zeropad_to_length = 2,
	
					table = ca_collections,
					field = idno,
					sort_field = idno_sort,
					
					child_only = 1
				}
			}
		}

The type "serial" will add a numeric value of 1,2,3,4,5, etc. after the initial portion of the idno, which will simply be a repeat of the idno for the parent record.

See also
Multipart_id_numbering.conf

My IDs are not coming up in the search, but I know they are there!

Problem
You are trying to search for objects or accession records by their identifier, but searches on valid ID numbers are returning zero results in the search.
Solution
The problem is likely because your Identifiers include punctuation necessary to keep them in tact, but are getting tokenized in the search index. This can be easily fixed in search.conf.
If your collection's ID numbering system follows a well-defined format, add the regular expression of the format to the "As Is Regexes" in search.conf. For example, the regex below allows searching on IDs following the form of 2013.7.2, or 2013-7-2.
asis_regexes = [
	"^[\d]+[\.\-][A-Za-z0-9\.\-]+$"
]
If the formatting of your Identifiers is less defined, you'll have better luck adding whatever punctuation is used (or may be used) to the indexing_tokenizer_regex and the search_tokenizer_regex in search.conf. These both represent character classes that will not be tokenized upon indexing and searching, respectively.
indexing_tokenizer_regex = ^\pL\pN\pNd/_#\@\&\.
search_tokenizer_regex = ^\pL\pN\pNd/_#\@\&\.

See also:

Search.conf
Search Indexing
For more about Regular Expressions, please visit [here]
Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools