Importing Resources
By Miller Prosser, February 2016
The following article describes how to import and link resources.
The basic goal is to add resources to your project, define them with properties, link each to another database item, and upload to a server location.
Typical examples include:
Import PDF files and link as supporting resources
Import images and link to objects, people, places, etc.
In the following article we use the following terms:
File: an item on your local computer or server; like a pdf, jpg, or tif.
Resource: the representation of the file in your OCHRE project.
Object: an item in the Locations & objects hierarchy of your project.
Typically an object has resource links that point to files on a project server. The file can be any one of various types: pdf, GIS shape file, image, etc. The resource item in OCHRE loads this file for viewing and analysis. The resource links to the object as supporting or defining information.
Example
In this example we import 345 PDF files and link them to the ceramic objects for which they serve as supporting documentation.
We begin with a local directory of the PDF files: C:\Users\...\Desktop\ZINCPDFS\pottery_analysis
Preliminary steps in OCHRE:
Create a resource hierarchy to serve as the destination for the resource import.
NOTE: You can import new resources into a hierarchy with existing resources, but we recommend importing to a temporary “Import” hierarchy then dragging the resources to their permanent location. This allows you to quickly review the results of the import for accuracy and delete the entire batch if necessary.
Configure the server access on the hierarchy including HTTP/FTP credentials and path specifications.
If you want OCHRE to load files from or upload to a server location, you will need to configure your server to allow FTP access from OCHRE. You can provide a user ID and PW for OCHRE to use in the process. Provide these credentials on the Access/Paths tab in OCHRE.
Importing from a local drive:
On the Utilities tab of the resource hierarchy
Click Import Resources then browse for your local drive
Click the Load folder button to read in the list of files with attributes.
NOTE: You may filter for file types by typing the file extension in the small text field to the left of the Load folder button. In this example, I could have typed “pdf” in this small field if my directory contained other file types. Because my sample directory contains only pdf files, this was not necessary.
You will see the following columns in the import table, only a few require comment:
OCHRE MESSAGE: This column will display the results of a PREVIEW or COMMIT function. Do not filter or sort on the results in this column.
File Name: The name of the file on your local drive, including the file extension
File extension
File Date
File Size
File URI: The file URI is a field generated by OCHRE for your use on import. In many cases the File URI will be the same as the file name. However, this field will also include sub-directories as part of the File URI if present. This can be useful if you plan to include a portion of the directory in the File URI of your resource. In the case of our example, we want File URIs to follow the formula "pottery_analysis/C12-1.pdf. To achieve this result, I browsed to the parent directory ZINCPDF which contains the sub-directory called pottery_analysis. By loading this parent directory as the import directory in OCHRE, the File URI field includes the sub-directory as part of the File URI.
Root Folder: reports the full path of the file
Folder#: If OCHRE finds sub-directories, it will create a new column for each.
OCHRE UUID: On import, OCHRE reports the UUID of the item.
Here are the columns loaded in our example.
NOTE the File URI column that contains the desired prefix to the file name.
Make selections in the Auto-link section
Select auto-link category and scope: use this pick list to select the category to which the imported resources will be linked. In this case, we are going to link to Locations & objects because the objects are found in the context of archaeological excavation. In this case, we cannot select a more specific context because the objects may appear all throughout the hierarchy. In some cases, it may be necessary to further scope the auto-link hierarchy to restrict linking to a specific subset of data. For example, you may be adding resources to a specific grid, square, or other location.
This import looks for an object with the same name as the PDF resource. The import uses the File Name column to perform the search for matching objects. Note that the import tool allows you to apply derivations to the PDF name to find the correct object. You need to check this box if you want to make any of the following selections. In this case, we do not need to remove ".pdf" as a suffix from the file name because OCHRE removes file extensions by default.
THIS PART IS IMPORTANT: The PDF files on my local hard drive are named in such a way to allow an easy match to the objects: C12-1.pdf matches object C12-1. You will make the process much easier if your files are named logically, following predictable patterns that allow them to be linked easily to objects in your project. It is not always possible to name the files the same as the objects in your project. Therefore, OCHRE provides some tools to aid in the auto-linking process. Use the Prefix and Suffix fields to modify the file name to produce a match with the database item. Use the +/- buttons to add or remove text as a Prefix or Suffix. In the Suffix and Prefix fields, type a specific text string to be added or removed; not a number of characters, but the actual text string. Alternatively, you may also instruct the import to consider the file name up until a specific character: space, dash, underscore, comma, or other. For example, you may have object drawings named OBJ-1234_drawing.jpg. In this case, to match against the object called OBJ-1234 in your project, you would tell the import to derive the name for auto-linking up to the underscore. If you have multiple images of the same item, do not use file names like OBJ-1234a.jpg because these will be difficult to use in the auto-linking process. Instead, use a format like OBJ-1234_a.jpg. In this case, you can auto-link up to the underscore. A brief note on the Other field: (1) you can specify your own character here if your file names all contain something other than the predefined characters space, dash, underscore, or comma; (2) by typing a number in this field you can specify the number of characters to use as the match (e.g. 8 would indicate that OCHRE should use the first 8 characters of the file name).
It is HIGHLY RECOMMENDED that you rename your files prior to importing them into OCHRE. Strip all inconsistencies and disallowed characters. Use the free program Advanced Renamer (or something similar) to apply multiple renaming commands to an entire batch of files. Prior to importing, your directory of files should be highly consistent and should contain a string of characters that can match against objects in your project. For example, if your files are named along the lines of OBJ-1234_a.jpg and the objects in your project are named along the lines of Spindle Whorl, it will be slightly more difficult to import and link automatically. In this case, we might recommend that the object be given the alias or abbreviation OBJ-1234_a.
Naming the Imported Resource
By default, OCHRE will name the new resource according to the File Name. However, you can rename the Resources using the Prefix/Suffix options.
You can also replace all underscores with spaces to create a more pleasing Resource name.
By default, OCHRE strips the file extension from the resource name. So, you do not need to type ".pdf" into the Suffix field.
Adding Properties to the Resource
Select a predefinition to apply properties to the Resources. Set up the predefinition ahead of time in the Predefinitions hierarchy. These properties will be assigned to each newly created resource. For example, you may wish to identify pdf files as field reports, or images as pottery drawings.
Importing from a server directory
Remember, your server must be configured to allow FTP connections and allow OCHRE to connect in order to load files from a server or upload files to a server.
The access path on the directory points OCHRE to the server directory from which to load and import resources. You do not need to change the http: path to ftp: because OCHRE will use the path after the // as the location of the ftp directory. In other words, the access path on the directory should remain the same as it would be to view an item on your server.
The process of reading a server directory is identical to reading a local directory, except in this case you click the Load remote folder button.
Uploading files to a server
Again, if your server allows an FTP connection, you can use the import tool to upload from a local directory to the server. In this process, OCHRE can create image thumbnails for you. OCHRE will use the alternative root folder and alternate file suffix to create the thumbnail files and post them to the appropriate server directory.
NOTE: if you've loaded a server directory as the source of resources, you cannot also upload to a server as part of the import process.
NOTE: spaces in directory names, e.g. "1986 Photos", may prevent OCHRE from successfully uploading images via FTP. Use "1986_Photographs" instead.
Preview and Commit the import
Once your directory is loaded, your auto-linking rules are set, and your resource naming is defined, you can preview the import. Click the PREVIEW button. OCHRE will preview the import of each item and report on the result that would have happened. The first column of the import spreadsheet will tell you if the import found an object to match, if the file already exists on the server (for uploads), etc. Alternatively, you can double click a single cell in the first column to preview one item. ALWAYS PREVIEW THE IMPORT! Even with the best intentions, it can be difficult to predict the unintended consequences of the chosen import settings. Once the preview reports that the import will perform as expected, it is recommended that you import a small subset of your data and check the objects where they were expected to link. Again, because the network of data in OCHRE is so extensive, it can be difficult sometimes to visualize the results of an import. With everything configured and tested, click the COMMIT button to import the files as resources and link to objects. The import process usually runs fairly quickly, however it may take longer if the import does not find items in the auto-link process. While running the COMMIT process, OCHRE reports on the success of each item. You can save the resulting spreadsheet by clicking the save button located to the right of the load buttons. The resulting spreadsheet may be useful in troubleshooting why files did not match.
This may seem like a bulky or time-consuming process. However, after the first few times you’ll find that you likely will not use every feature. You’ll find that you perform the same type of import over and over, making the process much easier in subsequent imports. You’ll find that you make the process much easier for yourself if your files are named well. Also, consider the time this process saves over adding and linking each item one at a time. And in the end, consider that you are doing more than simply adding resources to your project, you are creating another set of highly linked data.