Arctos Procedures

Searching Other Identifiers

2011-07-12T11:50:00.011-08:00

[ moved to https://arctosdb.wordpress.com/documentation/catalog/#srch2 ]
Each specimen in Arctos receives a single catalog number, along with any number of identifying numbers, often referred to as "Other IDs." There are several ways, each with their own limitations, to search these numbers. The data available for searching vary wildly based on what collectors have recorded and what collections have entered. Some exploration is often involved in finding a particular set of specimens.

Catalog Numbers

Every specimen has exactly one catalog number. This number is used to form the URL to the specimen, and is the primary number (in conjunction with the collection identifier) which should be used by external resources (such as GenBank) to identify a specimen. See for example http://arctos.database.museum/guid/UAM:Mamm:19268, which has catalog number "19268." (See recataloging to change catalog numbers.) Catalog numbers are recorded as integers, although Arctos has the (unused) capability to include strings as prefix and suffix. Catalog numbers may be searched as integers ("1"), ranges ("1-4"), or lists ("1,3,4").

Other IDs

Along with catalog numbers, Arctos provides the capacity to attach any number of identifiers of various types to specimens.

Other Identifiers, like catalog numbers, have three components: A prefix, an integer, and a suffix. Individual collections define how these components should be used, acceptable values, and how data are to be entered, and these decisions affect what sorts of queries are possible. It is often not possible to deduce these rules and practices - contact us if you need help.

To get Other ID search, click More Options on the Identifiers pane of SpecimenSearch.

This will provide options to select Other ID Type and to provide an Other ID Number. (We generally use "number" in the sense of a license plate rather than an integer.) Additionally, you can choose whether the number is an exact match or a "contains" match. Exact match searches are case-sensitive.

It's often unclear what type of ID might have been assigned to a number, and the descriptions currently do little to clarify that problem. It is therefore possible (and often most practical) to search by the number component, entirely ignoring ID Type.

The above example finds all specimens with any type of identifier (except catalog number)
containing the string "123." As of this writing, that search returns 9330 specimens. Additional criteria, coupled with Arctos' sorting capability, is hopefully enough to find the specimen data of interest.

To get all search options, click Customize (near "Show More Options"), select a "My Other Identifier" (which will also then appear in results and on various forms), and choose "Show 3-part ID Search."

Click Close and the form will reload with total of eight search options. For this example, we'll use Collector Number. The simplest use case is to search for a string, here "1234":

This sends the query upper(customIdentifier.Display_Value) LIKE '%1234%' (display_value is a concatenation of prefix, number, and suffix). This returns specimens with Collector Numbers of:

ABC-1234-X
1234
1234567

regardless of how the data were entered and are stored. ("ABC-1234-X" could be entered as prefix="ABC-1234-X" or as prefix="ABC-", number="1234", suffix="-X"; "1234" could have been entered as a number or as a prefix.)

Changing the dropdown from "contains" to "is" will, of the above examples, return only "1234."

The "in list" option accepts a comma-separated list of values.

The above example sends SQL upper(customIdentifier.DISPLAY_VALUE) IN ('A','B','C'), and as of this writing returns three specimens:

The in range option works only for enforced-integer types of identifiers (currently only AF and NK). Attempting to use it for collector number will result in a datatype mismatch and return an error.

Three-part search to the rescue! (At least in the cases where data are entered correctly.) All of the above deal with the concatenation of prefix, number, and suffix. It is also possible to search these independently. Search for integer component=1234:

to send SQL customIdentifier.other_id_number = 1234.

This is a numeric match of the numeric part of other IDs. It will not find specimens which have the numeric information entered into prefix. This information is not available to public users, but is evident from the edit form. This specimen will NOT be found with the previous search!

Prefix and suffix work similarly. This search:

sends SQL AND upper(customIdentifier.other_id_prefix) LIKE '%A%' AND customIdentifier.other_id_number = 123 (note prefix is a CONTAINS match and is not case-sensitive) and returns these specimens:

Searching OCR text

2011-04-11T14:53:00.002-08:00

Nearly all 180,000 UAM Herbarium Vascular Plants (ALA) specimens have been imaged, but only about half have pre-existing, parsed data. OCR (Optical Character Recognition) processing is well underway, and this is available as single text strings representing all of the text recognized by the OCR program within an image. (Experimentation with parsing this text into standard fields is also underway.) All specimens have at least a crude "folder name," as a taxonomic name within their standard data field.

Particularly useful for the half of the collection for which parsed data is unavailable, you can now locate specimens (and their images) in Arctos by searching the raw OCR results. Many specimens have only taxonomic information, so combining OCR criteria with other criteria (such as geography or collectors) is likely to exclude possible matches. Additionally, there are many uncorrected errors in the raw OCR text, so short queries are more likely to be successful. In other words, a taxonomic criterion plus an OCR criterion is most likely to produce useful records.

From the Arctos SpecimenSearch page (http://arctos.database.museum/SpecimenSearch.cfm), click "Show More Options" in the Biological Individual pane.

Enter your search criteria in the OCR Text box, and click Search.

All matching specimens will be returned. Click the catalog number to go to Specimen Detail, where you may view the raw OCR text.

Data Loans

2011-04-07T10:33:00.001-08:00

[ moved to https://arctosdb.wordpress.com/documentation/loans/#dataloan ]
Data loans document data usage, and are generally used when a project downloads data from Arctos without examining specimens. Data loans form a special relationship between a loan and a cataloged item, rather than a loan and a specimen part. Data loans are not meant as a replacement for "digital" loans, in which a specimen part is imaged (or otherwise digitized), as "digital" loans concern physical objects and handling specimens. Subsequent usage of digital media (including that generated in "digital" loans) may best be recorded as data loans. Curators may wish to create a new loan number series for data loans, although this is not required.

This entry documents creation of a data loan for illustrative purposes.

Found publication vaguely citing Arctos
Created publication agents in Arctos
Since the available PDF was a reprint, used the DOI to look up original publication information (http://www.google.com/search?q=DOI%3A+10.1111%2Fj.1472-4642.2008.00547.x)
Created Publication in Arctos
Added Media to the publication
Created Arctos loan of type "data"
Downloaded data loan template
Searched Arctos for scientific names cited in publication
Downloaded results, copied catalog numbers to data loan template.
Filled in rest of values in data loan template, copy/paste to all cells. Save as CSV.
Uploaded to data loan loader, clicked OK a couple times.
Created project, added loan, publication, and media created for publication

Total time: ~10 minutes, mostly spent researching and creating Agents.

Result: http://arctos.database.museum/project/different-climatic-envelopes-among-invasive-populations-may-lead-to-underestimations-of-current-and-future-biological-invasions

The collections used, even though there was no formal loan request and no physical specimen usage, receive quantifiable credit for specimen data used. Future Hieracium added to Arctos will not be included in this loan, so it will be possible to quickly identify specimens which could not have been used, even though the lack of citations in the paper makes it impossible to determine which specimens were actually used. Additionally, if current Hieracium specimens are later determined to be some other species, those data will remain as part of the loan, perhaps explaining yet-undetected anomalies in the publication.

Media Bulkloader

2011-02-28T09:40:00.003-09:00

[ https://arctosdb.wordpress.com/documentation/media/#bulk ]
This entry describes one process to create Media on Arctos. It is not the only method possible, and may not be most suitable for any given need. MVZ has developed specialized procedures to fit their workflow, for example.

Get your Media - the binary objects - to a suitable web-accessible location. We recommend TACC, and they've provided various tools* to facilitate loading data. You may wish to create a preview of your Media at this time - you'll need to script that, do it manually, or coordinate with whomever is hosting your binary data.
Locate related objects in Arctos. The Media Bulkloader cannot handle all realationships, and how relationships are formed is not always intuitive. See the Media Bulkloader for details.
Populate the Media Bulkloader using the URI you've created in loading media, upload the CSV file, and follow the directions until you get a "spiffy" message.

* TACC tools include direct SCP access, various wrappers and tools using SCP access (such as the ALA Imaging project, which pushes DNG files from a local computer to TACC, creates thumbnails and high-resolution JPGs, and automatically associates images with barcoded specimens), a WEBDAV dropbox (contact us for access), and the ability to automatically push files uploaded to Arctos to TACC.

Customizing Arctos headers with CSS

2010-06-24T10:13:00.003-08:00

* IMPORTANT *

You will want to try this out in TEST before moving to production!

You must coordinate loading all images with the development team, or host them on your own site.

* IMPORTANT *

To customize the header for your collection, you may simply supply the required values under Manage Collections.

To customize beyond the defaults, you'll need to create a CSS file, coordinate loading it with the developers, and select it under STYLESHEET on the Manage Collection form.

Example: Use a dark background image for the header, and change the header links to be white for contrast.

Create a transparent-background logo approximately 100px in height. Load to Arctos (you'll need developer assistance), and select the image in HEADER_IMAGE. Set HEADER_COLOR to "white" or it will override your image with gray.
Create a background image of height=1px less than the logo you created in (1).
Create a CSS file. (// signifies a comment below. This is not valid CSS comment syntax!)
// header_color is the ID of Arctos header
#header_color {
    // this is the background image
    background:url("/images/DMNSHeaderBg2.png") repeat-x scroll 0 0 #1C3664;
}
// change the color for the large text
.headerInstitutionText, .headerCollectionText{
    color:white;
}
// and the links at the top-right
#headerLinks, #headerLinks a {
    color:white;
    size:small;
}
// add hover behavior to differentiate the links from text
#headerLinks a:hover {
    color:red;
}

Recataloging

2010-03-23T10:38:00.005-08:00

[ https://arctosdb.wordpress.com/documentation/catalog/#recatalog ]
It is sometimes necessary to move cataloged items from one collection or catalog number to another. When doing so, it is important to maintain a way of finding the specimen by it's original catalog number.

We recommend adding to the new cataloged item an explicit other_id_type, such as

UAM: University of Alaska Museum

and a complete GUID as other_id_number, such as

UAM:Mamm:12

Additionally, insert into table REDIRECT old and new paths, and Arctos will automatically redirect traffic. (From Arctos, Manage Data/Tools/Redirects).

For example, if DGR Mamm 123 is recataloged as MSB Mamm 456, enter:

old_path=/guid/DGR:Mamm:123; new_path=/guid/MSB:Mamm:456

This will cause http://arctos.database.museum/guid/DGR:Mamm:123 to redirect to http://arctos.database.museum/guid/MSB:Mamm:456, thereby maintaining any external links to DGR:Mamm:123 in Arctos (e.g., from GenBank).

Suspect Data

2009-08-24T14:14:00.017-08:00

I'd like to monitor what's going on with my collection. How can I do that?

Loan and Permit reminders are emailed to the listed contacts at 1 year, 6 months, 1 month, and upon the permit expiring or the loan becoming due. Any agent with an email address may act as a contact.

The following are available under the Management/Misc tab:

Publication Staging is a way to quickly capture very basic information about possible Citations in Arctos. Curators should periodically review and update the information in this form.
Management/Misc/Sync parent/child taxonomy finds specimens in a Parent Of/Child Of relationship which do not share current Identification, and provides a means to synchronize them.
Merge Dup Agents provides a means to reconcile agents in relationship "bad duplicate of".
Pending Relationships provides access to those cataloged item relationships created during Data Entry which have not been successfully formalized. Curatorial action is required for anything in this list.

The following are available under the Reports tab:

GenBank MIA is a script that periodically crawls GenBank looking for sequences that may be related to Arctos specimens and which do not already have an Arctos LinkOut (newly-linked may continue to appear in the table for a few days).
- Query type specimen_voucher:collection are GenBank sequences with which the collector has submitted a properly-formatted link to GenBank, and are almost certainly accurate.
- Other query types are various guesses, and may or may not accurately resolve to specimens.
Annotations are user-submitted annotations. The data quality contact (which may be set under Manage Collections) should also receive notification when annotations are filed.
Loan/Citation Stats summarizes loans by the borrower, loan status, number of citations against specimens which were loaned, and cited versus current Identification. Citations must be individually examined to determine from which loan they originated. Citation Counts may reflect repeated usage of individual specimens.
Audit SQL contains all UPDATE, DELETE, or INSERT statements, including those which were subsequently rolled back (e.g., due to constraint violations).
Oracle Roles is a summary of users by assigned roles. Curators should monitor this, particularly the collection roles (e.g., UAM_MAMM) to ensure that only authorized persons have access to their collections.
Funky Data/Suspect Data has several sub-options:
- Publications without Authors should always find nothing.
- Publications without Citations may find publications which do not properly cite specimens. This usage may still be reflected in a Project.
- Projects with Loans and without Publications may require followup with the borrower. Note that Publications may now include things like class reports, dissertations, and brochures.
- Loans without Specimens are probably legacy or incomplete loans and may not be effectively used to demonstrate collection usage.
Funky Data/Partless Specimens finds specimens which have zero specimen parts. Only observations should be in this list; all other cataloged items should have at least one part, even if that part has a disposition of "missing" or "used up."
Funky Data/Messy Taxonomy allows searching taxonomy by many criteria to identify various problems.
Funky Data/Catalog Number Gaps finds unused catalog numbers. There are no technical problems with nonsequential catalog numbers; this is purely an informational form.

Data Entry: Identification

2009-08-24T12:25:00.012-08:00

[ moved to https://arctosdb.wordpress.com/documentation/create/bulkloader/#taxa ]

Data entry (including the Arctos screen and specimen bulkloaders) try to seamlessly construct identifications linked to taxonomy by way of taxa formulae based on user input. However, for taxa formula A {string}, more explicit input is required.

The input string must contain a valid taxonomy.scientific_name, followed by a space, followed by an opening curly bracket, followed by the verbatim identification, followed by a closing curly bracket.

Example:

Input	Identification	Taxonomy	Problem
unidentifiable {granite}	unidentifiable	granite	none
granite			All identifications must be linked to taxonomy
unidentifiable{granite}			Incorrect format; missing space.

Linking to Arctos and GenBank

2009-03-06T14:17:00.003-09:00

Curators of Arctos collections should encourage researchers using their specimens for DNA sequences to submit GenBank accessions that cite the specimens by catalog number. At a meeting in early January 09, the Database Working Group of the Barcode of Life and GenBank agreed to use essentially our current three-part format for specimen citations. For example:
UAM:Mamm:123456
MVZ:Herp:78910
etc.
(Definition at TDWG)

If the correct term is entered by the owner of the GenBank accession under "source/specimen_voucher," then the catalog number will appear on the GenBank sequence page as a link to the specimen record.
(An example in GenBank.)

If the record is not cited this way, and the owner of the GenBank accession won't change it, then it can still be linked by including the GenBank accession number as an Other ID in the Arctos record. In these cases, the nightly-update links to Arctos from GenBank will appear in the LinkOut drop-down in GenBank accession records.

In an effort to lock down the abbreviations with which we are familiar, I have registered "UAM" and "MSB" with Biorepositories.org, and Berkeley has registered "MVZ." All three of these registrations have been confirmed. So, operations such as the Univeristy of Arkansas at Monticello will have to be more creative than we were! I also put in a few specific collections that I knew already had records in GenBank and listed the curators as contacts, so some of you have been contacted by Biorepositories as part of the confirmation process. This system may be too simplistic to survive the many potential conflicts, but humanity has come to accept internet domain names, so we can hope. In the meantime, what we're doing works. If your collection is not registered, you can either go do it at Biorepositories, or let me know of your interest, and I will start the process.

By including an Other ID Type of "BoLD barcode ID," Arctos records can be also linked to records in the Barcode of Life Database (BoLD). There are currently thirty Barcode IDs in Arctos. We are expecting reciprocal linkages from BoLD to Arctos soon.

Feel free to contact me with questions about this emerging process.

G.

Data Entry: Relationships

2009-02-03T12:48:00.005-09:00

Data Entry provides for pre-creating one relationship:

Simply pick a relationship, and specify a related individual by entering an other ID type and a unique identifying number.

There is no checking at this point, and the related individual is not required to exist at this point.

With the exception of catalog numbers (see above), the related ID must be entered as it will appear in coll_obj_other_id_num.display_value. Lists, concatenations, and other strangeness will not resolve.

After the specimen is loaded, the relationship will be saved to Pending Relationships. If the other ID entered in data entry corresponds to exactly one individual (e.g., "field number 1" probably won't), the relationship will be automatically created. Otherwise, curatorial intervention is required.

Tabs and Mac

2009-01-13T12:42:00.002-09:00

FireFox on Mac can display strange tabbing behavior.

From The How-To Geek:

Agent (and other) picks

2009-01-13T12:34:00.007-09:00

Some controlled vocabularies in Arctos (Agents, Taxonomy) are too extensive for drop-down menus, so a "pick" is used. Recent browsers sometimes interfere with the behind-the-scenes code used to control these picks. The following simplification will help you understand, and therefore hopefully self-debug, how these picks work.

First, a simple form that includes the pick function:

We type a name into the input box....

...and hit TAB (or otherwise leave the field, firing the JavaScript onChange event. This action opens a popup....

Clicking the desired entry populates the name and, normally behind the scenes, the ID field, and turns the Name field green:

This is a successful pick and will save properly.

However, on subsequent visits, your browser may try to be helpful and remember what you've previously typed into the name field:

Selecting one of these suggestions will not open a popup, will not lookup the ID (which is what's actually used to update the database), and will not turn the name field green:

We must somehow force the onChange event to occur if we are to get the information we need to successfully submit the form. The simplest way to do this is to backspace a character from the end of the suggested value and hit the TAB key to force the popup...

...resulting in a green Name field, an ID value, and a successful save.

Note that the popups will self-close if only one possible value is available. The popup opening and closing may be very quick - you may not even see it. However, successful popups will turn the name field green, and are likely to be quite noticeable on most computers.

Label Purchase Guidelines

2009-01-09T10:21:00.009-09:00

[ moved to https://arctosdb.wordpress.com/documentation/container/#purchase ]
Guidelines for barcode-containing labels:

Barcodes should be clearly replicated in a human-readable format. The value read by a scanner should be readable by a human as well. Note that XYZ123, 123, ZYX 123, and ZYX0123 are all very different values.
Avoid padding with leading zeroes. These may be handled differently by different applications. In order to keep the character strings all the same length, start the series at a high value. For example, instead of beginning a series at 000001, begin at 100001. Thus, the character string will always be six characters long, and the printed labels will format consistently.
Avoid non-printing characters. Humans, and sometimes machines, can't always tell if that hole represents a space, tab, linefeed, of any of the dozens of other possibilities.
Use big numbers if possible. XYZ1234567890 is less likely to cause unanticipated problems than XYZ1 is.
Don't try to be too clever. You'll learn to hate "L090207" (or was it L927? Maybe L0902007?). Dumb numbers with a locally-meaningful prefix, such as UAM or UAMMAMM, will be much more sustainable.
Check the Barcode Series Spreadsheet very early in the ordering process. Avoid anything that even remotely looks like it could be, or ever could become, a conflict. Duplicate barcodes will not be accepted.
Talk to the Arctos folks before doing anything else. Really. It's free, and we're here to help. Ordering unusable barcodes is not free, and we'll make fun of you for doing that.
Enter the series of barcodes into Arctos and update the Barcode Series Spreadsheet before placing an order or printing your barcodes.

SQL Data Entry Editor

2008-10-27T15:31:00.007-08:00

Data that have been entered to the Bulkloader may be manipulated using two forms:

1) Browse Bulk-->SQL

The SQL option from Browse Bulk opens a form where data administrators may review records entered by members of their data entry group and make changes to multiple records at once.

The initial page load contains all records that fit criteria specified on the Browse Bulk page (enteredby and accession number).

To filter records, enter up to three rules in the top (Create Filter) box. Click the Filter button to apply rules. The page will reload with only those records that meed your criteria. You may skip this step; updates will apply to whatever you see in the specimen grid at the bottom of the page. Filters are simply a way to reduce the number of records to which you apply updates.

Once only the records you are interested in appear in the Specimen Grid, use the Update box to apply updates to them all simultaneously. To update Accn for all records:

To flag all records as ready to load, pick Loaded in the Column side and Update To NULL. There is a link supplied, or you may type "NULL" in the Value field.

2) Browse Bulk --> View Table

The View Table option loads a Java applet which allows manipulation to individual cells in entered records. Simply enter any cell in the grid, change data as appropriate, and click Save Changes in Grid.

There is also a limited bulk operations widget at the top of this form. You may alter multiple record's LOADED value by selecting a new value and one filter option. The following updates all records LOADED value to NULL where specific locality, trimmed of leading or trailing spaces, is "fairbanks." This example will not get those records with the following locality information:

"Fairbanks" (this is a case-sensitive operation)
"Fairbanks Area" substrings are not considered)

However, terms with spaces will be affected:

"Fairbanks "
" Fairbanks"
" Fairbanks "

Agent Groups

2008-09-09T11:51:00.005-08:00

[ moved to https://arctosdb.wordpress.com/documentation/agent/#group ]

Agent Groups consists of:

An agent of type=group, and optionally
agents (generally of type=person) as group members

Groups may be useful for things like collecting expeditions.

Create groups as Other Agents, then manage group membership from the group's agent record.

Designing Reports

2008-05-29T11:32:00.007-08:00

I don't want funky labels anymore! I want nice ones, and I want to print them from Arctos.

This procedure explains how to design your own label, load it to Arctos, create handler(s) for the label, and use it to print almost anything that uses specimen data. You'll need to have mange_collections permissions to complete this procedure.

First, download and install the ColdFusion 8 Report Builder. You'll need a Windows box.

At setup, it will ask you a bunch of information about your ColdFusion environment. Just cancel out, or do whatever it takes to get it to stop bugging you; none of this will be useful. Once that's happy, fire up the Builder and create a new label.

Hint: Set the headers and footers to zero size for creating things like specimen labels. You can size any object precisely with the Properties menu to the right, or just drag things around until they look about right.

Adjust the size of individual labels, column count, etc. as necessary (see Report Properties by right-clicking on any unused part of the report). You should now have a blank label to work with. To add data fields, use the Field wizard (lightning-bolt icon). It will be necessary to know the name of fields that will be returned from the database (more on this later). Type the field into the Expression Builder and click OK. The following example is for a field named "some_database_query_variable."

Now, load your template to Arctos. From the Reports tab, choose Reporter. Click Browse, locate the CFR file on your drive, and upload it. When the page refreshes, you should see your report in the grid. Click the Create Handler link to get started.

Hint: Look at existing report handlers for SQL hints. You'll probably find something appropriate. Do not alter any handlers that are not yours!

A handler will be generated, and you'll be redirected to the Edit Handler page. Change the Report Name to something more intuitive. Make sure the Report Template is what you just uploaded. Select a Report Format. We'll come back to Pre-Function later.

Now, create the SQL you need to generate the data for your report. You may use built-in Oracle functions, some custom functions (ask a developer or see the branches/DDL/functions folder in the Arctos SVN Repository), and most ANSI SQL. Click Test SQL to see the results of your query. Click Save Handler when you're happy with your results.

Hint: See the gray box at the bottom of the Edit Handler page. Your SQL must use one of the pre-defined variables. Talk to a developer if you're having difficulties getting what you want. Oracle SQL may not be quite what you're used to, and we've probably done something like what you need before.

Sometimes it's not practical to use SQL to manipulate data. Concatenating locality elements into a string for label printing can be very tricky, for example. The Reporter has the ability to pass your query off to a ColdFusion Function, manipulate it using custom code (CFML or CFSCRIPT), and return the altered query object to your Report Template. Just contact a developer if you think you need this functionality. If you already have a function, you may simply type it's name into the Pre-Function box from the Edit Handler page.

A quick note about fonts. The designer runs only in Windows, while the template is executed from Linux. Only the fonts available to the Linux server may be printed. To print barcodes, you'll need to download the Free 3 of 9 fonts, install it on the machine you're developing the report from, and choose it as the font of the barcode. Both Free 3 of 9 and Extended 3 of 9 are available on Arctos. Most other common fonts are installed; talk to the development team before using anything uncommon. You will need to select "Embedded Font" from the field properties to print barcodes in PDF documents. FlashPaper documents always embed fonts.

You should now have a Report Template and an appropriate handler. Find some specimens and choose Print Any Report from the Management dropdown. Choose the handler that you just created from the list, click the button, and your report will print.

API

Variables

The reporter will accept three variables:

collection_object_id (=cataloged_item.collection_object_id)
transaction_id (=trans.transaction_id)
container_id

Both are integers or lists of integers.

These must be passed in via URL or form, and may be accessed by the Pre-Function or the SQL_Text. You must wrap variables with ## to access them from the SQL.

...and cataloged_item.collection_object_id IN (#collection_object_id#)...

Loan data are best accessed by simply leaving the SQL_Text block blank and calling function get_loan. A query containing all normal loan data for {transaction_id} will be returned.

Access

You may call reports by accessing the URL

/Reports/report_printer.cfm?[collection_object_id={list] | transaction_id={list}] [report={name}]
[sort={sort column list}]

Omitting the report parameter will allow you to select a report for printing. Including it will print a report without prompting. Report is a case-insensitive character match (no substrings).

Including Sort={list} will append an "order by {list}" clause to your SQL if doing so won't cause errors. If it will (i.e., you try to sort by a column that's not in the query), the sort parameter will simply be ignored.

Arctos Procedures

2008-05-20T14:02:00.002-08:00

We have begun this manual by adding responses to some recent questions and common issues. Content development is up to you, the Arctos community. Gordon and Dusty are available to provide technical information and to coordinate effort. Consider the following suggestions:

Communicate. Use the Arctos group to "claim" subjects or suggest content. Leave comments for posts that need expansion or correction.
Be as generic as possible. Write to a wide audience, and avoid unnecessary particulars that may be affected by minor changes to Arctos.
Resolve differences in the Arctos group. There is one best way to do much of what we do; we should strive to find it. If that is impossible, summarize and link to the appropriate subject in the Arctos group.
Write atomically and link to other subjects. Don't explain how to create an accession when describing data entry, for example. Create, as a "stub" if necessary, and/or link to the entry for Accessions.
Use labels. Click "view all" beside the "Labels for this post" box to see current values. Create a new label only when necessary.
Refer to the Arctos Definitions and Standards where appropriate.

MVZ Permit Report

2008-04-23T08:38:00.008-08:00

So you want to print a permit report. Great!

First you search for your permit. Then when you have found the permit you want, select "Permit Report".Then you'll come to a screen like this.
If you want all of the specimens that were collected using this permit, hit "Generate the PDF". Otherwise, you may only want items from December of 2003. First, sort by date.
In this case, let's get rid of all the other months. What you want to do is "X" the rest of the dates. Each time you hit an "X" by a date, it will uncheck all specimens that are on the same date. In this case, I hit "X" by all the dates that weren't in December 2003, so I had hit a couple of "X"s
If I accidently hit "O" next to a wrong date (that selects all of them based on date), then I can just hit the "X" button to deselect them again.

Ok then. Let's look at the report.Looks great!

Printing Specimen labels for MVZ

2008-04-21T13:50:00.014-08:00

Suppose you want to print a bunch of labels to go along with your specimens in MVZ. Then, depending on your collection, you'll want to use "MVZ narrow labels" or "MVZ wide labels" from the specimen results page.
Then you'll face a page looking like this.
Now is the time to see if your labels are fine as is. Click on "Generate the PDF". On the next page, click "Get the PDF". Then the PDF with your labels will be downloaded. Open it up (if it isn't already opened) and see if it is ready for printing.As seen in this example, the geography is too long for catalog numbers 200045 and 200046, so they need to be modified. In this case, we want to change "Campground" to "Cmpgnd" for catalog numbers 200045-20046, but none of the others.

In this case, we need to use the Geography Modifiers.
Click the "Add new geography modifier" button. This will add a line containing three text inputs and one button. Find is what it looks for. Replace is what it replaces it with. Scope is which labels to affect. The button deletes the modifier.

I also put in the scope input "200045-200046".Then hit "Generate the PDF" and "Get the PDF" and see if your problems are solved.Hoorah! Notice how the other ones geographies were not changed.

In some cases, the parts list is too long. In that case, you need to use the Parts Matrix. If you need to use the Parts Matrix, then you can deselect a checkbox which will make the specimen of that row not have the part of that column.
In this case, Mammal 200040 will not have the "whole animal (alcohol)" part appear in its parts list when you next "Generate the PDF" and "Get the PDF". Additionally, one can hit "Select All" or "Deselect All" to change whether that part appears for all of the specimens, and this will simply check of uncheck all of the boxes in that column.

I hope this gives you an idea on how to use it.

Print labels using Access

2008-04-02T11:28:00.007-08:00

How do I print funky little labels for MSB Mammal specimens?

Sign in to Arctos and search for specimens in the usual way. Select Label Data Download in the Manage menu and click Go.

Right-click and save the resulting CSV file. The name and location of this file will be important later. Put it somewhere convenient, and accept the default name.

Download the MSB_Labels.mdb Access template from the Arctos Group Files site.

From the Access Tables tab in the file you just downloaded, click New at the top.

Choose Link Table in the resulting popup and click OK.

Change Files of type to "Text." Find and select the file you just downloaded from Arctos. It should be named ArctosLabelData.csv.
Click Link.

Select Delimited in the resulting window, then click Next.

Change Text Qualifier to quote ( " ). Do this first or you'll get scary but harmless Microsoft errors.

Pick Comma as delimiter.

Check First Row Contains Field Names.

Click Finish.

From the main menu, click Reports. msbLabelReport (the only report currently in the DB) will contain labels for the file you downloaded from Arctos.

To print another group of labels, simply close Access (to prevent lock conflicts), search Arctos, and download the CSV as before. You should be prompted to over-write the existing CSV file. The new data will then automatically be available from the Access report.

If you wish to change anything with the MDB file, you can either request that I make the changes or make them yourself, but make sure to send me the updated version. I'll keep that on the download site so it's always available. I can change the data download as needed.

This is not intended to be a permanent solution. We'll find something better someday.

Creating Other Identifiers

2007-12-03T11:31:00.009-09:00

[ https://arctosdb.wordpress.com/documentation/catalog/#parse_otherid is current ]

Under individual specimen records, Other Identifiers are a three-part field:

Prefix (text)
Number (integer)
Suffix (text)

All search features rely on a (stored) concatenation of these fields, called Display_Value.

The specimen bulkloader has only one field for (each of several) Other Identifiers. At load, the values provided in this field are parsed into individual fields according to the following rules.

Integers are loaded as Number
Strings consisting on a single alpha character followed by a number (V12345) are split into Prefix and Number (V and 12345, respectively)
Strings consisting of a number and a single alpha character (12345a) are split, as above, into Number and Suffix
Strings containing one or two "separator characters" (| - . ;) are split at those characters.
The results of the above are checked to ensure that Number is an integer
Finally, the re-concatenated value is checked against the original. If they don't match, the original becomes Prefix.

Examples:

Input	Prefix	Number	Suffix	Display	Explanation
v12345	v	12345	NULL	v12345	One character plus number
v-12345	v-	12345	v-12345	v-12345	Split at a separator character
v-12345-1	v-	12345	-1	v-12345-1	Split at separator characters
1[12345]1	1[12345]1	NULL	NULL	1123451	Brackets are treated as characters.
1-abc-2	1-abc-2	NULL	NULL	1-abc-2	Number is not numeric
v-00001	v-00001	NULL	NULL	v-00001	Above rules would lead to dropped leading zeroes in Number

(Much of this procedure is included in Arctos Definitions and Standards as a broader description of Other Identifiers.)

Entering Citations

2007-11-06T22:25:00.001-09:00

[ https://arctosdb.wordpress.com/documentation/publications/#create_cite ]
Citations are a linkage between a cataloged item and a page in a publication. They contain little information, being essentially a connection between existing sets of information. Therefore in order to create citations, both the publication and the items must already be present in Arctos. The scientific name used by the authors must also be present. Most often this will be the same as the current identification of the specimen, but not always; that's why it's there.

Citations can be individually entered by finding the publication from the Publication/Project Search tab, clicking the Citation Button, and using the form (Citation.cfm) to enter the appropriate information. You will select the cited specimens by catalog number or an Other Identifier. And you will select the scientific name by which the item was cited.

In publications that cite numerous specimens, it is often possible and efficient to bulkload the citations, especially if they are in tabular form within an electronic copy of the document. This can be done by copying and pasting the table from the publication into a spreadsheet. It must then be formatted to exactly match the key fields in Arctos, and exported as a comma-delimited text file. The tool for uploading this file, and a detailed description of the file are found from Bulkload Citations on the Tool tab (BulkloadCitations.cfm).

Duplicate Agents

2007-10-22T10:20:00.002-08:00

[ moved to https://arctosdb.wordpress.com/documentation/agent/#duplicate ]

There are duplicate agents in Arctos. What am I supposed to do about that?

First, make sure that there are actually two separate records for the agents. Identical agent names, between and among agents, is another issue and not covered here. Duplicate agents are two or more agent records that mean the same physical entity (THAT PARTICULAR John Smith; US Fish and Wildlife Service). It is not necessary for duplicate agents to share a name; in fact, they are often introduced because of misspellings. The "Agent Activity" link is a good place to make sure you're dealing with real duplicates.

Once you're sure you have duplicate agents, simply flag one of them as a "bad duplicate of" the other in Agent Relations. Generally, you will want to flag the record with least complete information and/or the least activity. The application to actually make the deletion must then be run manually.

Once agents are flagged, the actual agent cleanup process (Manage Data/Agents/Merge Bad Dup Agent) often involves individual analysis of agents in roles. Arctos will not merge agents used in Publications, those with Addresses, or otherwise differentiated at the Agent Name level. You may have to address errors individually.

Bulk-loading, an Overview

2007-10-19T15:51:00.006-08:00

[ moved to https://arctosdb.wordpress.com/documentation/bulkloader/bulkloader-tutorial/#overview ]

New specimen records are created from a single "flat file, usually a text file in which all data for a single cataloged item are in a single row. This file can be created with any convenient client-side application (often Microsoft Access). The file is then loaded into a similarly structured table on the server, and a server-side application (the bulk-loader) parses each row into the relational structure of the database.

This approach makes keyboarding of data a client-side process, and thereby allows easy customization of data-entry applications. The process provides an independent layer of data checking before new information is incorporated into the database proper. Original data that are received in electronic format may require minimal manipulation; you can sometimes merely add the necessary columns to build a file in the bulk-loading format (download bulkloader templates or build your own with the Bulkloader Builder application).

What the bulk-loader does:

The bulk-loader expects to find pre-existing values in the database for
taxonomy, agent names, and higher geography.
Data of these types that are not already in the system must be added prior
to bulk-loading by a user who is priviliged to modify those tables.
The content of several data fields is controlled by "code tables"
which restrict the acceptable values for those fields.
(The values you see in dropdowns in the editting screens come from these code tables.)
The bulk-loader evaluates each row in the submitted table.
If the locality already exists in the database, then the bulk-loader
uses the existing locality.
If the locality does not exist, then (assuming that the row is otherwise acceptable)
the bulk-loader creates the new locality and parses the row into the appropriate
tables.
If no catalog number is provided by the submitted table, then bulkloader provides the next sequential catalog number from the indicated collection.

The template for this flat file handles the most common data but has limitations.
For example, if a specimen has five collectors, you could load the specimen and the
first three collectors with the bulk-loader, then add the other collectors by editting the online record. Or, you could request a change to the structure of the template.
(Ask Dusty nicely.)

Bulkloader Group Settings

2007-09-17T22:02:00.005-08:00

[ deprecated ]

Why do the data entry applications think I have group issues?

First, make sure the user has a privileged account.

Users with role DATA_ENTRY may enter records for those collections they have access to.
Users with role MANAGE_COLLECTION may modify records in the bulkloader.
Users may be in any number of collection groups.

More information about Arctos groups may be found here.

Loading Records

2007-09-17T21:57:00.001-08:00

[ moved to https://arctosdb.wordpress.com/documentation/bulkloader/bulkloader-tutorial/#loading ]

Records in the bulkloader are ready to go. Now what?

Ensure that you have no group issues.
NULLify LOADED using the Browse and Edit Bulkloader application under Tools.
Wait for them to load. The load process runs hourly, but your records may be in the queue for several hours or even days. Note that LOADED is a functionally binary field with the following values:
- NULL: The bulkloader may attempt to load this record
- NOT NULL: The bulkloader must ignore this record
Feel free to use it for comments. Enter DELETE in LOADED to get rid of a record.
Check progress under Tools ==> Bulkload Specimens ==> Bulkloader Status
Fix errors and NULLify LOADED as in 1).

Locality

2007-09-17T12:47:00.001-08:00

How do I update geospatial data?

Option One: Update data for a single specimen.

Simply click the Locality tab in SpecimenDetail and make any necessary changes. Your updates will affect only the specimen you are editing.

Option Two: Pick a new collecting event.

When a suitable collecting event (dates, locality, higher geography, georeferenceing, and collecting method) exists, click the Pick New Coll Event tab, find an appropriate collecting event, and save.

Option Three: Update the locality.

First, click the Locality tab under SpecimenDetail, then click the Edit Locality link (or, find a locality under Localities). You are potentially changing localities for multiple specimens in multiple collections. Be sure you know what you are doing! Edit the locality as appropriate and save.

Option Four: Move the collecting event to a new locality.

From SpecimenDetail, click the Locality tab. Then click Edit Locality. Then click Collecting Events to see a list of all events under that locality. Locate the one you wish to move, and click on the "Coll Evnt Id" link. Click the Change Locality For This Collecting Event button. You are potentially changing localities for multiple specimens in multiple collections. Be sure you know what you are doing!

Loans

2007-09-06T16:34:00.001-08:00

How do I create a loan?

Create (or find) the loan under the Transactions tab.
Add the loan to one or more Projects, if appropriate, under Edit Loan.
Click Add Items from Edit Loan to find specimens you want to include in the loan. This is the standard Specimen Search screen.
You should see an itemized list of available parts for each specimen in Specimen Results after a successful search. To add a part to the loan, simply fill in the Remark and Instructions boxes, check the Subsample box if you wish to create and loan a subsample, and click the appropriate Add button. Note that Remarks and Instructions apply to individual items; remarks and instructions for the entire loan may be entered under Edit Loan.
From Edit Loan, click the Review Items button to remove or edit loan items. Note that you cannot remove items with a disposition of "on loan."
Fill in Shipment information on the Edit Loan form. Add agent addresses under Agents if necessary.
Print forms using the Print tool.

Arctos allows transactions to have any number of Agents in various Roles. Some of those Roles have special significance to the application.

entered by: Populated with the person creating the loan's Login information.
in-house contact: Single person in the originating institution who should be contacted with questions about the loan.
outside contact: Single person in the receiving institution who should be contacted with questions about the loan.

All other roles may be populated as appropriate. See the code table for more specific documentation.

Reminders

2007-09-06T16:16:00.000-08:00

How do I get reminders?

Arctos will automatically send reminders when permits are expiring (365, 90, 30, and 0 days before permit expires_date) and loans are due (30 days before loan due_date). All contacts must have a valid email address. Simply enter a name in Contact Person under edit or create permits (access permits under Transactions). Loan reminders are sent to the Authorized By agent.

User setup

2007-09-06T14:34:00.006-08:00

[] moved to https://arctosdb.wordpress.com/home/administration/ ]

How do I allow a user to enter data or perform other internal Curatorial tasks?

New users must first create an account for themselves. Their account name must use only letters and numbers (ASCII characters A-Z, a-z, and 0-9) if they are to be operators. The name cannot begin with a number. (Public users can use any characters.) They must have an email address in their Profile.
Under the Agents tab, create them as a new agent or locate them if they are an existing agent. Make sure they have a name-type of "login," and that their login name matches their Arctos username. These are case sensitive.
From Management/Arctos/Arctos Users, click Invite to allow them to create an internal user account. They will have to ensure that their username is valid, pass certain password checks, etc. to become users.
After the user has completed Step 3, assign them appropriate data and collection roles. Include the COLDFUSION_USER and DATA_ENTRY roles to enable data entry.

Data Entry Accession Format

2007-09-06T12:32:00.004-08:00

[ moved to https://arctosdb.wordpress.com/documentation/accession/#dataentry ]

Why isn't my Accession Number accepted?

Collections own transactions by way of trans.collection_id. Collections own rows in the bulkloader/data entry application by way of collection_cde + institution_acronym. The default bulkloader behavior is to locate an accession based on the bulkloader data. Square brackets may be used to tell the bulkloader "ignore the collection in this row - go find an accession based on what's in the brackets."

Square brackets are required any time a record is to be attached to an accession belonging to another collection. Examples include.

A UAM Mammal Observation being entered into a UAM Mammal accession
An MVZ Bird being entered into an MVZ Mammal accession

Example Usage is follows. Collections are in italics.

Desired accession: UAM:Mamm 1234.123.Mamm
New Specimen: UAMObs:Mamm 9876
Default accession: UAMObs:Mamm 1234.123.Mamm (Does not and should not exist)
Value to enter for Accession: [UAM:Mamm]1234.123.Mamm

Desired accession: MVZ:Birds 14508
New Specimen: MVZ:Bird 183000 -Value to enter for Accession: 14508
New Specimen: MVZ:Mamm 250000 -Value to enter for Accession: [MVZ:Bird]14508
New Specimen: MVZObs:Bird 10 -Value to enter for Accession: [MVZ:Bird]14508

Encumbering Specimens

2007-09-06T12:18:00.000-08:00

How do I encumber specimens?

Find the specimens you want to encumber using SpecimenSearch.
From the Manage tool, choose Encumbrances and click Go. You should now see a summary of your specimens at the bottom of the page, and the encumbrance finder at the top.
Find the appropriate encumbrance by entering search criteria and clicking Find Encumbrance.
Under the appropriate encumbrance, click the Add All Items To This Encumbrance button.

When the screen refreshes, the specimens are encumbered. Double-check that no extraneous specimens have been encumbered.

Deleting Records

2007-09-06T11:27:00.000-08:00

How do I delete records from Arctos?

Encumber the record(s) to be deleted. Create an appropriate encumbrance first, if necessary. Records may be flagged from individual specimens, or en masse by using the Manage widget from SpecimenResults. Once records are flagged, they may be deleted by users with the appropriate privileges.
Find the encumbrance (under Tools). Click See Specimens and carefully review what you're about to delete.
From Manage Encumbrances, click Delete Encumbered Specimens. You'll again be asked to review your decision, and must click the proceed button at the bottom of the page to delete the records from the database.

Note that there may be reasons to keep masked records in the database instead of deleting them.