Argus

Argus is a project manager for library special collections and archives. Library staff and researchers can create lists of bibliographic (bib) records imported from a connected Ex Libris Alma/Primo catalog and/or from ArchivesSpace. Item records (for individual volumes) associate with each bib record can also be specified. Once lists are created, a user can generate pull slips for use in special collections.

User-created lists can be used to help researchers remember items of interest, and can help library workers easily re-use or update course-related items from one class/semester/year to the next, streamlining workflows and reducing duplicated effort.

Features

• Users
  • Any user may have the "canPrint" option set by an admin; users with the canPrint option set may print slips
  • Supports four user roles: user, editor, admin, superadmin
    • "User" role can view public projects.
    • "Editor" role can create their own projects or serve as a co-editor for someone else's project to which they've been added. This is the most typical role.
    • "Admin" role can change user permissions; and view, search or edit other user's projects. This role is typically reserved for special collections staff.
    • "Superadmin" role can only be edited by another superadmin. This role is usually reserved for a systems administrator.
• Entries
  • An entry is a bibliographic record, typically part of a larger Project.
  • An entry is a record generate either by connecting with the Alma catalog to retrieve relevant bibliographic details or by entering custom information not drawn from Alma.
  • Entries can be added or removed from a project.
  • For entries drawn from Alma, the entry record also includes a link back to the Alma record.
• Projects
  • A project is a collection bibliographic entries for items of interest. A project is owned and controlled by an Editor-level user or above; they can add other "Editor"-level users as co-editors on a project. A user may have many projects.
  • A project can generate "pull slips" with information about each item, including item, bibliographic, and project/user information on each slip. Slips are half-page sheets printable two to a page.
  • A project may have its ownership reassigned to another user (Editor-level or higher) by the owner or by an administrator.
  • All of a user's projects may be reassigned en masse to another user (Editor-level or higher) by an administrator in the "Users" tab.
  • Projects may be archived (hidden) or deleted. Users may view or unarchive their archived projects.
  • Projects may be duplicated (with all entries) -- this is of use when two users may want to start from a similar point but go in different directions (such as a class with sections taught by two different librarians or faculty members).
• Quick Slips
  • For items that are needed in the moment but are not part of an ongoing project, a user with the canPrint permission can generate a pull slip for an item from the Alma catalog or for a Custom entry. This one-time slip is not tracked in the system, only generated by it.
• Search
  • A search function allows users to search across their own projects as well as any public projects.
  • Admin users can search for records across all projects.

Architecture

This is a Next.js project bootstrapped with create-next-app.

It uses Google-based authentication, managed through Clerk. User permissions are managed by the application.

Databases are managed through Prisma on a hosted database.

Connects with Ex Libris's Alma API; to allow call-number lookups, the Ex Libris Primo API is required as well.

Connects with ArchivesSpace's API to allow lookups by URL; URLs can come from the public or staff web interfaces or be direct API endpoints.

Configuration

Set up a .env file in the root directory of the project. You can copy and paste the following template and edit it as appropriate. You can reorganize or comment out lines from the file with a hash-tag as needed.

# Installation config
NEXT_PUBLIC_APP_BASEPATH=/argus. # or whatever path you want to use; skip this to use /
NEXT_PUBLIC_CATALOGS='[{"slug":"ALMA","label":"Alma"},{"slug":"ASPACE", "label": "ArchivesSpace"}]' #remove any not in use, or change the label if you want it referred to differently
NEXT_PUBLIC_IS_DEV_ENV=false #when true, will display some ugly-useful JSON data on some results pages
PORT=3333 # or whatever port you want to use
NODE_ENV=development #or production -- note: production required to 'npm run build'; doesn't build under developement

# External Services and APIs
DATABASE_URL=postgresql://... # database connection string; I use Neon
SHADOW_DATABASE_URL=postgresql://... # if hosting locally, you may need to specify a shadowdb for handling migrations
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=

## ALMA/PRIMO CONFIG
ALMA_BASEURL=https://api-na.hosted.exlibrisgroup.com #or whichever server is best for you
ALMA_API_KEY= #your alma api key
ALMA_PERMALINK_BASEURL= # your local alma permalink base url, e.g. https://ohiolink-mu.primo.exlibrisgroup.com/permalink/01OHIOLINK_MU/i4qs0/alma
NEXT_PUBLIC_USE_PRIMO=true
PRIMO_API_KEY=
PRIMO_QUERYSTRING=tab=Everything&scope=MyInst_and_CI&vid=01OHIOLINK_MU:MU #use your tab, scope, and vid
NEXT_PUBLIC_BARCODE_PREFIX=12345
NEXT_PUBLIC_INST_CODE=4321

## ARCHIVES SPACE CONFIG
ASPACE_API_BASE_URL=
ASPACE_PUBLIC_BASE_URL=
ASPACE_USER=
ASPACE_PASSWORD=


# Local UI Customizations
NEXT_PUBLIC_NAV_COLOR=primary #suggested: primary, dark, success (bootstrap theme colors suitable for light text)
NEXT_PUBLIC_NAV_LABEL= #This text will be appended to the Argus logo text
NEXT_PUBLIC_CONTACT_DEPT= #used in About & Guest page
NEXT_PUBLIC_CONTACT_EMAIL= #used in About & Guest page
NEXT_PUBLIC_CONTACT_PHONE= #used in About & Guest page
NEXT_PUBLIC_SLIP_HEADER= #header on pull slips, e.g. Miami University Libraries
NEXT_PUBLIC_SLIP_SUBHEAD= #subhead, e.g. Special Collections & Archives Request Slip
NEXT_PUBLIC_LOCATION_CODES_JSON='[{"code":"arcli","name":"Archives"},{"code":"mss","name":"Manuscript Collection","unofficial":true},{"code":"spcfo","name":"Folios"}]' #this is a JSON string with an array of locations as [{code, name}] -- optionally, you can also add "unofficial:true" for entries that are not official locations in Alma; these locations are used only for Custom Entries. It does not need to be an exhaustive list of every location used in Alma, just the ones you want to be able to use for custom entries.
NEXT_PUBLIC_PROJECT_PURPOSES='["Class","Conservation","Digitization","Event","Exhibit","Reference"]'
NEXT_PUBLIC_USER_AFFILIATIONS='["Miami","Other"]'
NEXT_PUBLIC_USER_STATUSES='["Undergrad","Graduate","Faculty","Staff","Alumni","Other"]'
NEXT_PUBLIC_SUBJECT_LIST='["Anthropology","Art and Architecture","Biology","Business","Chemistry and Biochemistry","Disability Studies","Economics","English","Environmental Sciences","History","Latin American Studies","Mathematics","Music","Political Science","Spanish and Portuguese","Theatre","Womens Gender and Sexuality Studies"]'

Optionally include minimum level of logging:

LOG_LEVEL=info #info is the default, choose from: error,warn,info,verbose,debug,silly

Configuration steps

1. Clone the git repository and run npm install.
2. Using the template provided above, create a .env configuration file (which is a text file).
   • copy and paste the text above.
   • set the NEXT_PUBLIC_APP_BASEPATH, which will set the URL where the app appears. The most likely values are / and /argus depending on your preferences and server configuration.
3. Create a PostGreSQL database (could be hosted locally or on a hosting service like Neon) and get the authentication url and add it to the .env file.
   • If using Neon or another commercial product, set the connection string they provide as the DATABASE_URL
   • If hosting the database locally, you may need to set up a shadow database as well to manage database migrations. Use the SHADOW_DATABASE_URL for that connection string.
   • Run npx prisma generate to create prisma's database structure locally.
   • Then run npx prisma migrate dev to update the remote database to match the required data format.
4. Create a Clerk account; create a new Clerk application using Google authentication. See video demo (timestamp: 25:47-27:17) save the NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY provided in the setup process in the .env file.
5. Add Alma / Primo details (if using Alma/Primo).
   • Using the ExLibris Developer network, create API keys for Alma and Primo and add them to the .env file as ALMA_API_KEY and PRIMO_API_KEY.
   • Set your ALMA_PERMALINK_BASEURL in .env. To find this, identify an item in Primo that has a permalink that ends with 'alma' and a string of numbers (e.g., "https://ohiolink-mu.primo.exlibrisgroup.com/permalink/01OHIOLINK_MU/1bhrr0p/alma991013473189708518"). To get the base URL, just remove the numbers after "alma" -- this will be the consistent base URL for Alma/Primo items in your catalog.
   • Set your PRIMO_QUERYSTRING in .env. To find this, do a search in Primo and copy the URL. You only need the "tab", "scope", and "vid" paramters from the url, e.g. ("tab=Everything&scope=MyInst*and_CI&vid=01OHIOLINK_MU:MU"). Include these paramters and leave out any others in the URL.
   • Set NEXT_PUBLIC_BARCODE_PREFIX with the first few numbers of your local Alma barcodes.
   • Set NEXT_PUBLIC_INST_CODE -- these will be the last four digits of your institution's Alma MMS IDs. For example, if an item has an MMS ID of 991017357419708518, the institution code is 8518. Learn more about the "anatomy" of Alma record numbers. To find an example MMS ID, find a permalink as in step 5b -- the number after the "alma..." at the end of the permalink is an MMS ID; the last four digits become are institution code.
6. Add ArchivesSpace details (if using ArchivesSpace).
   • Create an ArchivesSpace API user for Argus with "viewer" or "read-only" permissions to all repositories; include the credentials for that user as ASPACE_API_USER, ASPACE_API_PASSWORD.
   • The lookup function can take ArchivesSpaces URLs from either the API or from the public catalog. Set the base URLs for each of those: ASPACE_API_BASE_URL -- the API base url may look like 'https://aspace.your.org:8089' or 'https://aspace.your.org/api' -- do not include a trailing slash. ASPACE_PUBLIC_BASE_URL is likely to be simpler, like 'https://publicaspace.your.org'.
   • There is an additional, more complex ArchivesSpace setup step that will require more involved work and which probably cannot be done at setup time. See "ArchivesSpace call-number and title customization" below for details on adding custom scripts that can more accurately pull your title and call-number information from ArchivesSpace metadata.
7. Host the configured project on a server (could be hosted locally or on a third-party site like Heroku).
   • Note: for testing things out initially, you can skip this step and host the project on a personal computer.
8. Add optional local customizations to the .env file.
   • Set any or all local contact info settings: NEXT_PUBLIC_CONTACT_DEPT, NEXT_PUBLIC_CONTACT_EMAIL, NEXT_PUBLIC_CONTACT_PHONE. If used, these settings will add contact information to the About page and the Guest (unlogged-in user) page.
   • Set the NEXT_PUBLIC_LOCATION_CODES_JSON -- this is a JSON array (as a string) listing the in-house special collections locations used in the Alma catalog. Each array entry should be an object with the location code as "code" and the location name as "name". Optionally, you can also add "unofficial":true for entries that are not official locations in Alma. Example: [{"code":"arcli","name":"Archives"},{"code":"mss","name":"Manuscript Collection"},{"code":"spcfo","name":"Folios"}]. The locations listed here will be shown as options when creating a Custom Entry, and items from these locations will be sorted above other locations when looking up an item -- so if an item exists both in Special Collections and in the Main Stacks, the Special Collections item will appear higher in the display than the Main Stacks item. Unofficial locations are listed only when creating custom enties.
   • Edit NEXT_PUBLIC_PROJECT_PURPOSES. A project has a "purpose" associated with it, such as "class", "reference", etc. You can edit the list of purposes available based on the values defined in this array.
   • Edit NEXT_PUBLIC_USER_AFFILIATIONS. This is the list of affiliations available for a user or a project's patron, such as your institution's name and "Other". You can list as many affiliations as your institution needs (not just a single "us / other" split); order is preserved as given, so list your institution's own name(s) first.
   • Edit NEXT_PUBLIC_SUBJECT_LIST. This is an array of subject areas; you will want to adapt the list in the template to subjects used at your institution. Subjects are optional for a project.
   • Set the NEXT_PUBLIC_NAV_COLOR. This defines the color of the header. You can use any Bootstrap color suitable for pairing with light-colored text. Suggested values are: "primary" (blue), "dark" (dark grey), "success" (green). If you will maintain separate instances of Argus (such as one for testing, one for production) it can be helpful to choose different colors to quickly tell the user which instance they're using.
   • Set the NEXT_PUBLIC_NAV_LABEL. This text will be appended to the Argus logo text; so if you have a test instance, you might set the value to " -- TEST", and the header text with real "Argus -- TEST".
   • Set NEXT_PUBLIC_IS_DEV_ENV. Should be false for production; when true, will display some ugly/useful JSON data on some results pages.
9. When the site is ready to go into production (i.e., after testing), use the Google Developer Console to create a project to handle authentication. Provide the Google project configuration to Clerk to let Google handle the authentication and have Clerk manage users. Refer to Clerk's documentation on Deploying to production for and this video tutorial guidance.

Additional customizations using a fork of the GitHub repo (recommended)

The configuration steps above allow an institution to connect to their own catalog and create some display and permissions settings in Argus. You can do all of that without forking the GitHub repo.

There are additional customizations possible, but they require that you create a local fork of the main argus4archives/Argus repo (e.g. your-org/Argus) on GitHub; this is especially important if you are connecting to ArchivesSpace. This will allow you to customize:

• The format of printable request slips.
• How Argus identifies a call number/shelfmark for ArchivesSpace items.
• How Argus identifies the title of ArchivesSpace items.

To create these customization:

1. Fork the repo to your own user or organization in GitHub.
2. Set the argus4archives/Argus as the "upstream" branch and your own fok as the "origin" branch.

git remote add upstream https://github.com/argus4archives/Argus.git
git remote add origin https://github.com/<your-org>/Argus.git

3. Configure the "ours" merge driver locally on the command line: git config merge.ours.driver true. This only needs doing once per machine/clone. Because the local customization files are meant to diverge per installation, this command sets it up once so future git pulls from upstream don't create merge conflicts on your local edits. This tells git to keep your local version of any file matching a merge=ours rule in .gitattributes (e.g. callNumberOverrides.ts) whenever you merge or pull changes from upstream, instead of trying to merge the two versions. Upstream Argus development should never need to edit this file's contents again after it's created, so in practice this means your customization simply persists across updates.
4. Edit the local Overrides files described in the following sections.
5. Once customization has been added, do not use GitHub's "sync fork" button to update the software, since it can't apply the merge=ours behavior and will offer to discard the customization commit instead of merging around it.Instead, fetch and merge upstream/dev locally:

git fetch upstream
git checkout main
git merge upstream/main

With the driver configured, git pulls in the new upstream commits (new version release) normally, and for the three merge=ours files it keeps the local version untouched — no conflict markers, no manual resolution. 6. Push the merged result to origin:

git push origin main

This is the actual "sync" — origin/main now has upstream's changes plus the preserved override customizations, and the local commit is never discarded.

ArchivesSpace call-number and title customization

Different institutions structure their ArchivesSpace id_0/id_1/id_2/indicator/display_string fields differently, so call-number parsing is a designated per-installation extension point rather than a one-size-fits-all default.

lib/catalogs/aspace/callNumberOverrides.ts ships with empty defaults (today's built-in parsing behavior). To customize call-number parsing for your installation, edit that file directly and implement whichever of the resources, topContainer, or archivalObject bib/item functions you need — anything left unimplemented falls back to the built-in logic. The function signatures are fully typed against the ArchivesSpace client's response types, so your editor will show you exactly what data is available.

Structured like the callNumberOverrides.ts file, lib/catalogs/aspace/titleOverrides.ts allows for local customizations of how titles are extracted from ArchivesSpace data.

Request slip customization

Similar to to the ArchivesSpace title and call number customizations above, the /components/Request Slips/BibSectionOverrides.tsx file will let you make a custom local layout for the top portion of the request slip. Using the same variables available in the BibSection-aspace.tsx and BibSection-default.tsx files, you can provide an alternate layout for that section of the printable request slips.

As with the title and call number customizations, the BibSectionsOverrides.tsx file is managed by the .gitattributes file so that your changes to the overrides file will no be overwritten by future software updates.

Getting Started (Boilerplate NextJs stuff)

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3333 (or use whatever port is set in the .env file) with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.