Argus

Argus is a pull-slip manager for special collections. Library staff and researchers can create lists of bibliographic (bib) records from a connected Ex Libris Alma/Primo catalog to look up items by call number, barcode, or Alma's mms_id. 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 content
    • "Editor" role can create their own projects or serve as a co-editor for someone else's project to which they've been added
    • "Admin" role can change user permissions; and view, search or edit other user's projects
• 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.
  • 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.

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.

NEXT_PUBLIC_APP_BASEPATH=/argus. # or whatever path you want to use; skip this to use /
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_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
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_IS_DEV_ENV=false #when true, will display some ugly-useful JSON data on some results pages
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_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"]'
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

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.

   • 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. 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.

7. Add optional local customizations to the .env file.

   • 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_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.

8. 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.

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.