From e1e2894b3426f3f989eeed55ea690aee4b466fc5 Mon Sep 17 00:00:00 2001 From: Dan Scott Date: Sat, 8 Dec 2012 18:36:12 -0500 Subject: [PATCH] Roll in some Evergreen in Action chapters For the initial import we're keeping the formatting and words identical, so that we can manually sycnhronize changes as needed between the FLOSS Manuals version of this documentation and the AsciiDoc version. Signed-off-by: Dan Scott --- .../describing_your_organization.txt | 99 +++++ .../describing_your_people.txt | 321 ++++++++++++++++ .../migrating_your_data.txt | 349 ++++++++++++++++++ docs/root.txt | 12 + 4 files changed, 781 insertions(+) create mode 100644 docs/admin_initial_setup/describing_your_organization.txt create mode 100644 docs/admin_initial_setup/describing_your_people.txt create mode 100644 docs/admin_initial_setup/migrating_your_data.txt diff --git a/docs/admin_initial_setup/describing_your_organization.txt b/docs/admin_initial_setup/describing_your_organization.txt new file mode 100644 index 0000000000..e2b89a36ea --- /dev/null +++ b/docs/admin_initial_setup/describing_your_organization.txt @@ -0,0 +1,99 @@ +Describing your organization +============================ + +Your Evergreen system is almost ready to go. You'll need to add each of the +libraries that will be using your Evergreen system. If you're doing this for a +consortium, you'll have to add your consortium as a whole, and all the +libraries and branches that are members of the consortium. In this chapter, +we'll talk about how to get the Evergreen system to see all your libraries, how +to set each one up, and how to edit all the details of each one. + +Organization Unit Types +----------------------- +The term _Organization Unit Types_ refers to levels in the hierarchy of your +library system(s). Examples could include: All-Encompassing Consortium, Library +System, Branch, Bookmobile, Sub-Branch, etc. + +You can add or remove organizational unit types, and rename them as needed to +match the organizational hierarchy that matches the libraries using your +installation of Evergreen. Organizational unit types should never have proper +names since they are only generic types. + +When working with configuration, settings, and permissions, it is very +important to be careful of the Organization Unit *Context Location* - this is the +organizational unit to which the configuration settings are being applied. If, +for example, a setting is applied at the Consortium context location, all child +units will inherit that setting. If a specific branch location is selected, +only that branch and its child units will have the setting applied. The levels +of the hierarchy to which settings can be applied are often referred to in +terms of "depth" in various configuration interfaces. In a typical hierarchy, +the consortium has a depth of 0, the system is 1, the branch is 2, and any +bookmobiles or sub-branches is 3. + +Create and edit Organization Unit Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +. Open *Admin > Server Administration > Organization Types*. +. In the left panel, expand the *Organization Unit Types* hierarchy. +. Click on a organization type to edit the existing type or to add a new + organization unit. +. A form opens in the right panel, displaying the data for the selected + organization unit. +. Edit the fields as required and click *Save*. + +To create a new dependent organization unit, click *New Child*. The new child +organization unit will appear in the left panel list below the parent. +Highlight the new unit and edit the data as needed, click *Save* + +Organizational Units +-------------------- +'Organizational Units' are the specific instances of the organization unit types +that make up your library's hierarchy. These will have distinctive proper names +such as Main Street Branch or Townsville Campus. + +Remove or edit default Organizational Units +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +After installing the Evergreen software, the default CONS, SYS1, BR1, etc., +organizational units remain. These must be removed or edited to reflect actual +library entities. + +Create and edit Organizational Units +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +. Open *Admin > Server Administration > Organizational Units*. +. In the left panel, expand the the Organizational Units hierarchy, select a + unit. +. A form opens in the right panel, displaying the data for the selected + organizational unit. +. To edit the existing, default organizational unit, enter system or library + specific data in the form; complete all three tabs: Main Settings, Hours + of Operation, Addresses. +. Click *Save*. + +To create a new dependent organizational unit, click *New Child*. The new child +will appear in the hierarchy list below the parent unit. Click on the new unit +and edit the data, click *Save* + +Organizational Unit data +~~~~~~~~~~~~~~~~~~~~~~~~ +The *Addresses* tab allows you to enter library contact information. Library +Phone number, email address, and addresses are used in patron email +notifications, hold slips, and transit slips. The Library address tab is broken +out into four address types: Physical Address, Holds Address, Mailing Address, +ILL Address. + +The *Hours of Operation* tab is where you enter regular, weekly hours. Holiday +and other closures are set in the *Closed Dates Editor*. Hours of operation and +closed dates impact due dates and fine accrual. + +Set closed dates using the Closed Dates Editor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +. Open *Admin > Local Administration > Closed Dates Editor*. +. Select type of closure: typically Single Day or Multiple Day. +. Click the Calendar gadget to select the All Day date or starting and ending + dates. +. Enter a Reason for closure (optional). +. Click *Apply* to all of my libraries if your organizational unit has children + units that will also be closed. +. Click *Save*. + +Now that your organizational structure is established, you can begin +configuring permissions for the staff users of your Evergreen system. diff --git a/docs/admin_initial_setup/describing_your_people.txt b/docs/admin_initial_setup/describing_your_people.txt new file mode 100644 index 0000000000..7ed437167d --- /dev/null +++ b/docs/admin_initial_setup/describing_your_people.txt @@ -0,0 +1,321 @@ +Describing your people +====================== + +Many different members of your staff will use your Evergreen system to perform +the wide variety of tasks required of the library. + +When the Evergreen installation was completed, a number of permission groups +should have been automatically created. These permission groups are: + +* Users +* Patrons +* Staff +* Catalogers +* Circulators +* Acquisitions +* Acquisitions Administrator +* Cataloging Administrator +* Circulation Administrator +* Local Administrator +* Serials +* System Administrator +* Global Administrator +* Data Review +* Volunteers + +Each of these permission groups has a different set of permissions connected to +them that allow them to do different things with the Evergreen system. Some of +the permissions are the same between groups; some are different. These +permissions are typically tied to one or more working location (sometimes +referred to as a working organizational unit or work OU) which affects where a +particular user can exercise the permissions they have been granted. + +Setting the staff user's working location +----------------------------------------- +To grant a working location to a staff user in the staff client: + +. Search for the patron. Select *Search > Search for Patrons* from the top menu. +. When you retrieve the correct patron record, select *Other > User Permission + Editor* from the upper right corner. The permissions associated with this + account appear in the right side of the client, with the *Working Location* + list at the top of the screen. +. The *Working Location* list displays the Organizational Units in your + consortium. Select the check box for each Organization Unit where this user + needs working permissions. Clear any other check boxes for Organization Units + where the user no longer requires working permissions. +. Scroll all the way to the bottom of the page and click *Save*. This user + account is now ready to be used at your library. + +As you scroll down the page you will come to the *Permissions* list. These are +the permissions that are given through the *Permission Group* that you assigned +to this user. Depending on your own permissions, you may also have the ability +to grant individual permissions directly to this user. + +Comparing approaches for managing permissions +--------------------------------------------- +The Evergreen community uses two different approaches to deal with managing +permissions for users: + +* *Staff Client* ++ +Evergreen libraries that are most comfortable using the staff client tend to +manage permissions by creating different profiles for each type of user. When +you create a new user, the profile you assign to the user determines their +basic set of permissions. This approach requires many permission groups that +contain overlapping sets of permissions: for example, you might need to create +a _Student Circulator_ group and a _Student Cataloger_ group. Then if a new +employee needs to perform both of these roles, you need to create a third +_Student Cataloger / Circulator_ group representing the set of all of the +permissions of the first two groups. ++ +The advantage to this approach is that you can maintain the permissions +entirely within the staff client; a drawback to this approach is that it can be +challenging to remember to add a new permission to all of the groups. Another +drawback of this approach is that the user profile is also used to determine +circulation and hold rules, so the complexity of your circulation and hold +rules might increase significantly. ++ +* *Database Access* ++ +Evergreen libraries that are comfortable manipulating the database directly +tend to manage permissions by creating permission groups that reflect discrete +roles within a library. At the database level, you can make a user belong to +many different permission groups, and that can simplify your permission +management efforts. For example, if you create a _Student Circulator_ group and +a _Student Cataloger_ group, and a new employee needs to perform both of these +roles, you can simply assign them to both of the groups; you do not need to +create an entirely new permission group in this case. An advantage of this +approach is that the user profile can represent only the user's borrowing +category and requires only the basic _Patrons_ permissions, which can simplify +your circulation and hold rules. + +Permissions and profiles are not carved in stone. As the system administrator, +you can change them as needed. You may set and alter the permissions for each +permission group in line with what your library, or possibly your consortium, +defines as the appropriate needs for each function in the library. + +Managing permissions in the staff client +---------------------------------------- +In this section, we'll show you in the staff client: + +* where to find the available permissions +* where to find the existing permission groups +* how to see the permissions associated with each group +* how to add or remove permissions from a group + +We also provide an appendix with a listing of suggested minimum permissions for +some essential groups. You can compare the existing permissions with these +suggested permissions and, if any are missing, you will know how to add them. + +Where to find existing permissions and what they mean +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In the staff client, in the upper right corner of the screen, click on *Admin > +Server Administration > Permissions*. + +The list of available permissions will appear on screen and you can scroll down +through them to see permissions that are already available in your default +installation of Evergreen. + +There are over 500 permissions in the permission list. They appear in two +columns: *Code* and *Description*. Code is the name of the permission as it +appear in the Evergreen database. Description is a brief note on what the +permission allows. All of the most common permissions have easily +understandable descriptions. + +Where to find existing Permission Groups +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In the staff client, in the upper right corner of the screen, navigate to *Admin +> Server Administration > Permission Groups*. + +Two panes will open on your screen. The left pane provides a tree view of +existing Permission Groups. The right pane contains two tabs: Group +Configuration and Group Permissions. + +In the left pane, you will find a listing of the existing Permission Groups +which were installed by default. Click on the + sign next to any folder to +expand the tree and see the groups underneath it. You should see the Permission +Groups that were listed at the beginning of this chapter. If you do not and you +need them, you will have to create them. + +Adding or removing permissions from a Permission Group +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +First, we will remove a permission from the Staff group. + +. From the list of Permission Groups, click on *Staff*. +. In the right pane, click on the *Group Permissions* tab. You will now see a + list of permissions that this group has. +. From the list, choose *CREATE_CONTAINER*. This will now be highlighted. +. Click the *Delete Selected* button. CREATE_CONTAINER will be deleted from the + list. The system will not ask for a confirmation. If you delete something by + accident, you will have to add it back. +. Click the *Save Changes* button. + +You can select a group of individual items by holding down the _Ctrl_ key and +clicking on them. You can select a list of items by clicking on the first item, +holding down the _Shift_ key, and clicking on the last item in the list that +you want to select. + +Now, we will add the permission we just removed back to the Staff group. + +. From the list of Permission Groups, click on *Staff*. +. In the right pane, click on the *Group Permissions* tab. +. Click on the *New Mapping* button. The permission mapping dialog box will + appear. +. From the Permission drop down list, choose *CREATE_CONTAINER*. +. From the Depth drop down list, choose *Consortium*. +. Click the checkbox for *Grantable*. +. Click the *Add Mapping* button. The new permission will now appear in the + Group Permissions window. +. Click the *Save Changes* button. + +If you have saved your changes and you don't see them, you may have to click +the Reload button in the upper left side of the staff client screen. + +Managing role-based permission groups in the database +----------------------------------------------------- +While the ability to assign a user to multiple permission groups has existed in +Evergreen for years, a staff client interface is not currently available to +facilitate the work of the Evergreen administrator. However, if you or members +of your team are comfortable working directly with the Evergreen database, you +can use this approach to separate the borrowing profile of your users from the +permissions that you grant to staff, while minimizing the amount of overlapping +permissions that you need to manage for a set of permission groups that would +otherwise multiply exponentially to represent all possible combinations of +staff roles. + +In the following example, we create three new groups: + +* a _Student_ group used to determine borrowing privileges +* a _Student Cataloger_ group representing a limited set of cataloging + permissions appropriate for students +* a _Student Circulator_ group representing a limited set of circulation + permissions appropriate for students + +Then we add three new users to our system: one who needs to perform some +cataloging duties as a student; one who needs perform some circulation duties +as a student; and one who needs to perform both cataloging and circulation +duties. This section demonstrates how to add these permissions to the users at +the database level. + +To create the Student group, add a new row to the _permission.grp_tree_ table +as a child of the _Patrons_ group: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO permission.grp_tree (name, parent, usergroup, description, application_perm) +SELECT 'Students', pgt.id, TRUE, 'Student borrowers', 'group_application.user.patron.student' +FROM permission.grp_tree pgt + WHERE name = 'Patrons'; +------------------------------------------------------------------------------ + +To create the Student Cataloger group, add a new row to the +_permission.grp_tree_ table as a child of the _Staff_ group: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO permission.grp_tree (name, parent, usergroup, description, application_perm) +SELECT 'Student Catalogers', pgt.id, TRUE, 'Student catalogers', 'group_application.user.staff.student_cataloger' +FROM permission.grp_tree pgt +WHERE name = 'Staff'; +------------------------------------------------------------------------------ + +To create the Student Circulator group, add a new row to the +_permission.grp_tree_ table as a child of the _Staff_ group: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO permission.grp_tree (name, parent, usergroup, description, application_perm) +SELECT 'Student Circulators', pgt.id, TRUE, 'Student circulators', 'group_application.user.staff.student_circulator' +FROM permission.grp_tree pgt +WHERE name = 'Staff'; +------------------------------------------------------------------------------ + +We want to give the Student Catalogers group the ability to work with MARC +records at the consortial level, so we assign the UPDATE_MARC, CREATE_MARC, and +IMPORT_MARC permissions at depth 0: + +[source,sql] +------------------------------------------------------------------------------ +WITH pgt AS ( + SELECT id + FROM permission.grp_tree + WHERE name = 'Student Catalogers' +) +INSERT INTO permission.grp_perm_map (grp, perm, depth) +SELECT pgt.id, ppl.id, 0 +FROM permission.perm_list ppl, pgt +WHERE ppl.code IN ('UPDATE_MARC', 'CREATE_MARC', 'IMPORT_MARC'); +------------------------------------------------------------------------------ + +Similarly, we want to give the Student Circulators group the abillity to check +out copies and record in-house uses at the system level, so we assign the +COPY_CHECKOUT and CREATE_IN_HOUSE_USE permissions at depth 1 (overriding the +same _Staff_ permissions that were granted only at depth 2): + +[source,sql] +------------------------------------------------------------------------------ +WITH pgt AS ( + SELECT id + FROM permission.grp_tree + WHERE name = 'Student Circulators' +) INSERT INTO permission.grp_perm_map (grp, perm, depth) +SELECT pgt.id, ppl.id, 1 +FROM permission.perm_list ppl, pgt +WHERE ppl.code IN ('COPY_CHECKOUT', 'CREATE_IN_HOUSE_USE'); +------------------------------------------------------------------------------ + +Finally, we want to add our students to the groups. The request may arrive in +your inbox from the library along the lines of "Please add Mint Julep as a +Student Cataloger, Bloody Caesar as a Student Circulator, and Grass Hopper as a +Student Cataloguer / Circulator; I've already created their accounts and given +them a work organizational unit." You can translate that into the following SQL +to add the users to the pertinent permission groups, adjusting for the +inevitable typos in the names of the users. + +First, add our Student Cataloger: + +[source,sql] +------------------------------------------------------------------------------ +WITH pgt AS ( + SELECT id FROM permission.grp_tree + WHERE name = 'Student Catalogers' +) +INSERT INTO permission.usr_grp_map (usr, grp) +SELECT au.id, pgt.id +FROM actor.usr au, pgt +WHERE first_given_name = 'Mint' AND family_name = 'Julep'; +------------------------------------------------------------------------------ + +Next, add the Student Circulator: + +[source,sql] +------------------------------------------------------------------------------ +WITH pgt AS ( + SELECT id FROM permission.grp_tree + WHERE name = 'Student Circulators' +) +INSERT INTO permission.usr_grp_map (usr, grp) +SELECT au.id, pgt.id +FROM actor.usr au, pgt +WHERE first_given_name = 'Bloody' AND family_name = 'Caesar'; +------------------------------------------------------------------------------ + +Finally, add the all-powerful Student Cataloger / Student Circulator: + +[source,sql] +------------------------------------------------------------------------------ + WITH pgt AS ( + SELECT id FROM permission.grp_tree + WHERE name IN ('Student Catalogers', 'Student Circulators') +) +INSERT INTO permission.usr_grp_map (usr, grp) +SELECT au.id, pgt.id +FROM actor.usr au, pgt +WHERE first_given_name = 'Grass' AND family_name = 'Hopper'; +------------------------------------------------------------------------------ + +While adopting this role-based approach might seem labour-intensive when +applied to a handful of students in this example, over time it can help keep +the permission profiles of your system relatively simple in comparison to the +alternative approach of rapidly reproducing permission groups, overlapping +permissions, and permissions granted on a one-by-one basis to individual users. diff --git a/docs/admin_initial_setup/migrating_your_data.txt b/docs/admin_initial_setup/migrating_your_data.txt new file mode 100644 index 0000000000..4b0f85d8d9 --- /dev/null +++ b/docs/admin_initial_setup/migrating_your_data.txt @@ -0,0 +1,349 @@ +Migrating from a legacy system +============================== + +When you migrate to Evergreen, you generally want to migrate the bibliographic +records and copy information that existed in your previous library system. For +anything more than a few thousand records, you should import the data directly +into the database rather than use the tools in the staff client. While the data +that you can extract from your legacy system varies widely, this section +assumes that you or members of your team have the ability to write scripts and +are comfortable working with SQL to manipulate data within PostgreSQL. If so, +then the following section will guide you towards a method of generating common +data formats so that you can then load the data into the database in bulk. + +Making electronic resources visible in the catalog +-------------------------------------------------- +Electronic resources generally do not have any call number or copy information +associated with them, and Evergreen enables you to easily make bibliographic +records visible in the public catalog within sections of the organizational +unit hierarchy. For example, you can make a set of bibliographic records +visible only to specific branches that have purchased licenses for the +corresponding resources, or you can make records representing publicly +available electronic resources visible to the entire consortium. + +Therefore, to make a record visible in the public catalog, modify the records +using your preferred MARC editing approach to ensure the 856 field contains the +following information before loading records for electronic resources into +Evergreen: + +.856 field for electronic resources: indicators and subfields +[width="100%",options="header"] +|============================================================================= +|Attribute | Value | Note +|Indicator 1 |4 | +|Indicator 2 |0 or 1 | +|Subfield u |URL for the electronic resource | +|Subfield y |Text content of the link | +|Subfield z |Public note | Normally displayed after the link +|Subfield 9 |Organizational unit short name | The record will be visible when + a search is performed specifying this organizational unit or one of its + children. You can repeat this subfield as many times as you need. +|============================================================================= + +Once your electronic resource bibliographic records have the required +indicators and subfields for each 856 field in the record, you can proceed to +load the records using either the command-line bulk import method or the MARC +Batch Importer in the staff client. + +Migrating your bibliographic records +------------------------------------ +Convert your MARC21 binary records into the MARCXML format, with one record per +line. You can use the following Python script to achieve this goal; just +install the _pymarc_ library first, and adjust the values of the _input_ and +_output_ variables as needed. + +[source,python] +------------------------------------------------------------------------------ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +import codecs +import pymarc + +input = 'records_in.mrc' +output = 'records_out.xml' + +reader = pymarc.MARCReader(open(input, 'rb'), to_unicode=True) +writer = codecs.open(output, 'w', 'utf-8') +for record in reader: + record.leader = record.leader[:9] + 'a' + record.leader[10:] + writer.write(pymarc.record_to_xml(record) + "\n") +------------------------------------------------------------------------------ + +Once you have a MARCXML file with one record per line, you can load the records +into your Evergreen system via a staging table in your database. + +. Connect to the PostgreSQL database using the _psql_ command. For example: ++ +------------------------------------------------------------------------------ +psql -U -h -d +------------------------------------------------------------------------------ ++ +. Create a staging table in the database. The staging table is a temporary + location for the raw data that you will load into the production table or + tables. Issue the following SQL statement from the _psql_ command line, + adjusting the name of the table from _staging_records_import_, if desired: ++ +[source,sql] +------------------------------------------------------------------------------ +CREATE TABLE staging_records_import (id BIGSERIAL, dest BIGINT, marc TEXT); +------------------------------------------------------------------------------ ++ +. Create a function that will insert the new records into the production table + and update the _dest_ column of the staging table. Adjust + "staging_records_import" to match the name of the staging table that you plan + to create when you issue the following SQL statement: ++ +[source,sql] +------------------------------------------------------------------------------ +CREATE OR REPLACE FUNCTION staging_importer() RETURNS NULL AS $$ +DECLARE stage RECORD; +BEGIN +FOR stage IN SELECT * FROM staging_records_import ORDER BY id LOOP + INSERT INTO biblio.record_entry (marc, last_xact_id) VALUES (stage.marc, 'IMPORT'); + UPDATE staging_records_import SET dest = currval('biblio.record_entry_id_seq'); + END LOOP; + END; + $$ LANGUAGE plpgsql; +------------------------------------------------------------------------------ ++ +. Load the data from your MARCXML file into the staging table using the COPY + statement, adjusting for the name of the staging table and the location of + your MARCXML file: ++ +[source,sql] +------------------------------------------------------------------------------ +COPY staging_records_import (marc) FROM '/tmp/records_out.xml'; +------------------------------------------------------------------------------ ++ +. Load the data from your staging table into the production table by invoking + your staging function: ++ +[source,sql] +------------------------------------------------------------------------------ +SELECT staging_importer(); +------------------------------------------------------------------------------ + +When you leave out the _id_ value for a _BIGSERIAL_ column, the value in the +column automatically increments for each new record that you add to the table. + +Once you have loaded the records into your Evergreen system, you can search for +some known records using the staff client to confirm that the import was +successful. + +Migrating your call numbers, copies, and parts +---------------------------------------------- +'Holdings', comprised of call numbers, copies, and parts, are the set of +objects that enable users to locate and potentially acquire materials from your +library system. + +'Call numbers' connect libraries to bibliographic records. Each call number has a +'label' associated with a classification scheme such as a the Library of Congress +or Dewey Decimal systems, and can optionally have either or both a label prefix +and a label suffix. Label prefixes and suffixes do not affect the sort order of +the label. + +'Copies' connect call numbers to particular instances of that resource at a +particular library. Each copy has a barcode and must exist in a particular copy +location. Other optional attributes of copies include circulation modifier, +which may affect whether that copy can circulate or for how long it can +circulate, and OPAC visibility, which controls whether that particular copy +should be visible in the public catalog. + +'Parts' provide more granularity for copies, primarily to enable patrons to +place holds on individual parts of a set of items. For example, an encyclopedia +might be represented by a single bibliographic record, with a single call +number representing the label for that encyclopedia at a given library, with 26 +copies representing each letter of the alphabet, with each copy mapped to a +different part such as _A, B, C, ... Z_. + +To migrate this data into your Evergreen system, you will create another +staging table in the database to hold the raw data for your materials from +which the actual call numbers, copies, and parts will be generated. + +Begin by connecting to the PostgreSQL database using the _psql_ command. For +example: + +------------------------------------------------------------------------------ +psql -U -h -d +------------------------------------------------------------------------------ + +Create the staging materials table by issuing the following SQL statement: + +[source,sql] +------------------------------------------------------------------------------ +CREATE TABLE staging_materials ( + bibkey BIGINT, -- biblio.record_entry_id + callnum TEXT, -- call number label + callnum_prefix TEXT, -- call number prefix + callnum_suffix TEXT, -- call number suffix + callnum_class TEXT, -- classification scheme + create_date DATE, + location TEXT, -- shelving location code + item_type TEXT, -- circulation modifier code + owning_lib TEXT, -- org unit code + barcode TEXT, -- copy barcode + part TEXT +); +------------------------------------------------------------------------------ + +For the purposes of this example migration of call numbers, copies, and parts, +we assume that you are able to create a tab-delimited file containing values +that map to the staging table properties, with one copy per line. For example, +the following 5 lines demonstrate how the file could look for 5 different +copies, with non-applicable attribute values represented by _\N_, and 3 of the +copies connected to a single call number and bibliographic record via parts: + +------------------------------------------------------------------------------ +1 QA 76.76 A3 \N \N LC 2012-12-05 STACKS BOOK BR1 30007001122620 \N +2 GV 161 V8 Ref. Juv. LC 2010-11-11 KIDS DVD BR2 30007005197073 \N +3 AE 5 E363 1984 \N \N LC 1984-01-10 REFERENCE BOOK BR1 30007006853385 A +3 AE 5 E363 1984 \N \N LC 1984-01-10 REFERENCE BOOK BR1 30007006853393 B +3 AE 5 E363 1984 \N \N LC 1984-01-10 REFERENCE BOOK BR1 30007006853344 C +------------------------------------------------------------------------------ + +Once your holdings are in a tab-delimited format--which, for the purposes of +this example, we will name _holdings.tsv_--you can import the holdings file +into your staging table. Copy the contents of the holdings file into the +staging table using the _COPY_ SQL statement: + +[source,sql] +------------------------------------------------------------------------------ +COPY staging_items (bibkey, callnum, callnum_prefix, + callnum_suffix, callnum_class, create_date, location, + item_type, owning_lib, barcode, part) FROM 'holdings.tsv'; +------------------------------------------------------------------------------ + +Generate the copy locations you need to represent your holdings: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO asset.copy_location (name, owning_lib) + SELECT DISTINCT location, 1 FROM staging_materials + WHERE NOT EXISTS ( + SELECT 1 FROM asset.copy_location + WHERE name = location + ); +------------------------------------------------------------------------------ + +Generate the circulation modifiers you need to represent your holdings: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO config.circ_modifier (code, name, description, sip2_media_type) + SELECT DISTINCT circmod, circmod, circmod, '001' + FROM staging_materials + WHERE NOT EXISTS ( + SELECT 1 FROM config.circ_modifier + WHERE circmod = code + ); +------------------------------------------------------------------------------ + +Generate the call number prefixes and suffixes you need to represent your +holdings: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO asset.call_number_prefix (owning_lib, label) + SELECT DISTINCT aou.id, callnum_prefix + FROM staging_materials sm + INNER JOIN actor.org_unit aou + ON aou.shortname = sm.owning_lib + WHERE NOT EXISTS ( + SELECT 1 FROM asset.call_number_prefix acnp + WHERE callnum_prefix = acnp.label + AND aou.id = acnp.owning_lib + ) AND callnum_prefix IS NOT NULL; + +INSERT INTO asset.call_number_suffix (owning_lib, label) + SELECT DISTINCT aou.id, callnum_suffix + FROM staging_materials sm + INNER JOIN actor.org_unit aou + ON aou.shortname = sm.owning_lib + WHERE NOT EXISTS ( + SELECT 1 FROM asset.call_number_suffix acns + WHERE callnum_suffix = acns.label + AND aou.id = acns.owning_lib + ) AND callnum_suffix IS NOT NULL; +------------------------------------------------------------------------------ + +Generate the call numbers for your holdings: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO asset.call_number ( + creator, editor, record, owning_lib, label, prefix, suffix, label_class +) + SELECT DISTINCT 1, 1, bibkey, aou.id, callnum, acnp.id, acns.id, + CASE WHEN callnum_class = 'LC' THEN 1 + WHEN callnum_class = 'DEWEY' THEN 2 + END + FROM staging_materials sm + INNER JOIN actor.org_unit aou + ON aou.shortname = owning_lib + INNER JOIN asset.call_number_prefix acnp + ON COALESCE(acnp.label, '') = COALESCE(callnum_prefix, '') + INNER JOIN asset.call_number_suffix acns + ON COALESCE(acns.label, '') = COALESCE(callnum_suffix, '') +; +------------------------------------------------------------------------------ + +Generate the copies for your holdings: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO asset.copy ( + circ_lib, creator, editor, call_number, location, + loan_duration, fine_level, barcode +) + SELECT DISTINCT aou.id, 1, 1, acn.id, acl.id, 2, 2, barcode + FROM staging_materials sm + INNER JOIN actor.org_unit aou + ON aou.shortname = sm.owning_lib + INNER JOIN asset.copy_location acl + ON acl.name = sm.location + INNER JOIN asset.call_number acn + ON acn.label = sm.callnum + WHERE acn.deleted IS FALSE +; +------------------------------------------------------------------------------ + +Generate the parts for your holdings. First, create the set of parts that are +required for each record based on your staging materials table: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO biblio.monograph_part (record, label) + SELECT DISTINCT bibkey, part + FROM staging_materials sm + WHERE part IS NOT NULL AND NOT EXISTS ( + SELECT 1 FROM biblio.monograph_part bmp + WHERE sm.part = bmp.label + AND sm.bibkey = bmp.record + ); +------------------------------------------------------------------------------ + +Now map the parts for each record to the specific copies that you added: + +[source,sql] +------------------------------------------------------------------------------ +INSERT INTO asset.copy_part_map (target_copy, part) + SELECT DISTINCT acp.id, bmp.id + FROM staging_materials sm + INNER JOIN asset.copy acp + ON acp.barcode = sm.barcode + INNER JOIN biblio.monograph_part bmp + ON bmp.record = sm.bibkey + WHERE part IS NOT NULL + AND part = bmp.label + AND acp.deleted IS FALSE + AND NOT EXISTS ( + SELECT 1 FROM asset.copy_part_map + WHERE target_copy = acp.id + AND part = bmp.id + ); +------------------------------------------------------------------------------ + +At this point, you have loaded your bibliographic records, call numbers, call +number prefixes and suffixes, copies, and parts, and your records should be +visible to searches in the public catalog within the appropriate organization +unit scope. diff --git a/docs/root.txt b/docs/root.txt index 4c2a66c8da..30f2ad5436 100644 --- a/docs/root.txt +++ b/docs/root.txt @@ -103,6 +103,18 @@ The Evergreen system allows a free range of customizations to every aspect of the system. Use this part of the documentation to become familiar with the tools for configuring the system as well as customizing the catalog and staff client. +// Push titles down one level. +:leveloffset: 1 + +include::admin_initial_setup/describing_your_organization.txt[] + +include::admin_initial_setup/describing_your_people.txt[] + +include::admin_initial_setup/migrating_your_data.txt[] + +// Return to normal title levels. +:leveloffset: 0 + include::admin/template_toolkit.txt[] // Push titles down one level. -- 2.43.2