Aliases, Permalinks, Redirects, and Human-Readable URLs

Summary and Disambiguation

There are few separate things we’re talking about here:

1. Aliases: The ability to redirect whatever past or preferable urls to the “core” URL for a given work or collection

2. Slugs (a vanity url or display url): The ability to format the URL structure for works and collections

   1. This would be the “active” URL to which all other permalinks redirect.

3. UUIDs: the ability to set the core ID of a given work or collection, and potentially use that in the permalink.

4. Permalinks:

   1. DOI - Proprietary, standard permalink service + identifier for published works. Linking service will serve the active link for the repository in which a given work is stored.

   2. Handle - Proprietary, standard permalink service. Linking service will serve the active link for the repository in which a given work is stored.

   3. Hyku - native URL with UUID for a given work that won’t change, even if a given work is edited, and the parent collection is modified.

   4. ARK links - ARK Alliance - Popular in Europe and other places in the US

User Stories

1. As a user who is migrating works to Hyku, I want all past URLs from my previous repository to continue to function. The past URLs will be redirected and continue to function.

   1. Pitt Examples

      1. Collections: legacy URLs: “/view/centers/cen=5Fother=5Finstpolitics/“

      2. Works: legacy URLs like: “/37684/”, “/eprints/id

         /37684/” (many to one)

      3. Filesets: legacy URLs like: “/37684/1/IOP%20-%20Lead%20Safe%20Demolition%20Report.pdf”

      4. The Works/Filesets hierarchy means that it would be ideal to 404 a missing Fileset level URI back to the Work level. (n.b. this is out of scope for current funding)

2. As a Hyku user, I want URLs for collections and works to contain elements such as the identifier or title or author of it, rather than a string of random numbers and letters.

   1. This will make it easier to work with researchers and for them to accurately cite the materials they find online. [University of Louisville]

3. As a researcher, I want to click a button to copy a permalink to a work or collection, and know that it will not change amidst other updates to the work or collection aliased URLs, or any updates for that matter.

   1. Dovetails into Handle system support

4. As an institution that has already implemented a custom version, I want the structure of the new code to be easily mappable to what I already have.

   1. We used source_identifier in our URLs, and want to retain that. If some other portions of the string (e.g. concern and worktype) are changing, fixing links would be less cumbersome if the key unique part (source_identifier) remained stable. [University of Louisville]

5. As a collection curator, I want to easily access and link to all works in a collection through a human-readable URL. [University of Louisville]

   1. The approach could be the same as for works or, since there are much fewer collections than works, could be selectable (as is done for other systems such as ArchivesSpace, LibGuides, etc.)

6. As a repository administrator, I want to be able to audit my aliases in bulk, in order to verify aliases, identify orphaned aliases, and spot conflicts. I would like to be able to export aliases as part of a metadata export. From NDSR..

7. Patrick’s Scenario (for consideration) - I would like the system to automatically generate an alias using the existing metadata that appears. An example, since all our work types are additive we have required fields that will be present and unique across the board, such as title or identifier. Allow me to select which field to use for this operation. When when I upload files via bulkrax create a hash of that value using some algorithm and place it an alias.

Funded work by UPitt

Scope and Deliverables

This module enables institutions to define custom vanity URLs for works and preserve legacy URLs from previous repository systems. Requirements were refined during a March 12, 2026 discussion between Clinton Graham, Kirk Wang, LaRita Robinson, Shana Moore, and Nick Steinwachs. A detailed technical approach document accompanies this SOW.

Problem

Institutions need two things from their repository URLs: human-readable vanity URLs for public-facing content (e.g., /robs-cat-study instead of /concern/generic_works/abc-123-uuid), and preservation of legacy URLs from previous systems so that existing links, citations, and search engine rankings remain intact. These are distinct from persistent identifiers (DOIs, Handles), which are managed by external services.

Approach

The feature is built in two phases within the module:

Phase 1: Research Spike (3-4 days, 1 developer)

Validate the technical implementation path before committing to full development. Specifically:

• Prototype the Rack middleware approach for canonical URL rendering (alias path displayed in the browser, work rendered normally)

• Confirm Bulkrax field-mapping bridge works with the current knapsack Bulkrax version

• Identify any Hyrax/Hyku edge cases with path rewriting (breadcrumbs, canonical meta tags, caching)

Notch8 will share spike findings with Clinton before proceeding to Phase 2. If the spike reveals that the middleware approach isn't viable, we'll propose an alternative approach and revised estimate before continuing.

Phase 2: Core Development (~2.5 weeks, 2 developers)

Build the full feature based on spike findings.

Deliverables

1. Alias model and database schema — Dedicated work_aliases table with indexed path lookups, canonical flag, and ordering. Tenant-scoped via Apartment.

2. Canonical URL rendering — When a work has a canonical alias, visiting that alias path shows the work directly (the alias IS the URL in the browser). Visiting the standard Hyku URL (/concern/type/uuid) returns a 301 redirect to the canonical alias.

3. Non-canonical alias redirects — Secondary aliases (e.g., legacy paths from a previous repository) return a 301 redirect to the canonical alias.

4. Admin UI for alias management — Add, edit, and remove aliases per work. Mark one alias as canonical. When changing an alias, option to keep the old path as a redirect (Drupal-style lifecycle).

5. Bulkrax integration — Aliases as a multi-value metadata field in Bulkrax imports and exports. First value is canonical by default. Supports bulk migration of legacy URL mappings.

6. Validation — Uniqueness across all works in the tenant. Soft warning for paths that match known Hyku system routes (e.g., /catalog, /dashboard). Hyku system routes always take precedence — documented, not dynamically enforced.

7.  

Out of Scope

• Wildcard or pattern-based redirects

• Query parameter-based redirect rules

• External URL redirects (aliases are paths within the repository domain)

• Auto-generated URL slugs from metadata (separate feature — Custom URL Slugs)

• Dynamic validation against all Hyku routes (documented behavior only)

•  

Designs

Aliases / Redirects

field design:

Open

Tab design:

Open

Open

Open

Open

Open

Discussion Jan 9, 2026

This could be a workaround for slugs.  The custom slug feature just builds it automatically.  Users can do that using excel.

👆not true - deciding what shows up in the browser URL as the “final destination” is a key capability tied into custom slugs.  Aliases always forward to whatever your choice is: Slug or Hyku Permalink

Previous slugs would get stored as aliases to redirect to the new one

Initial design here, but there are other implications, especially the ability to specify them via bulkrax, handling duplicates, etc.

Option: when changing a slug / URL, prompt the user, “Do you want to add the previous URL as an alias for this work?” -> “Yes” would add an alias

Need to enable export / import of aliases using Bulkrax

Technical / Implementation details

Aliases / Redirects

Clients have requested an ability to specify previous UUIDs on works and collections that are migrated to a new Hyku instance. We’re seeking input from folks on whether they care if these UUIDs are added as aliases for a work or collection, or if there is a reason they’d need to be the true “permalink” UUID.

On the data side, this can be handled with the metadata on works and collections. We may want to add a new “standard” metadata field apart from identifiers (naming TBD, but could be “redirects” or “aliases”).

When a URL is entered, at the end of the route stack, it may be directed to try the redirect controller, which would search through the other identifiers on works, and direct the user accordingly.

Of note, uniqueness of the identifier / URL should be validated on input, so that we don’t end up with ambiguous routes.

Human-readable URLs (Slugs)

This needs to be a separate feature from the Aliasing feature.

There needs to be a feature switch that allows administrators to turn the primary URL for works and collections to be either a UUID (i.e. permalink), or a human-readable alias that is generated and persisted based on a configurable URL structure.

Would need a rake task that generates any that are missing. Needs to be tenant-aware (not global) (maybe?).

All past slugs / aliases that are generated would need to persist through changes, and continue to work.