Aspen Discovery + Koha

Data Interactions between Koha and Aspen Discovery

In this blog post, we discuss how Aspen Discovery interprets the data from the Koha ILS and how you can map and customize this data.

Bib Records and Record Grouping

A unique feature in Aspen is that it uses a process called FRBRization where Aspen tries to automatically group same title, same author, same language and same expression of the work all within one grouped work display.

What MARC data does Aspen use to group records?

  • Title - Aspen will first look for 130 (Uniform Title) subfields a, b, m, n, p and s and then 245 a, b, f, n and p.
  • Author - 100 a,d
  • Language - 008 position 35-37

Note: The data that Aspen uses for grouping is slightly different than what data Aspen uses for display within the grouped work in search results. For grouped work title display, Aspen will use 245 subfields a, b, f, m, o, p, s. Aspen prefers the information in the Book bibliographic record and then looks at the information in the eBook bibliographic record (if it exists) and prefers to display the longest title. Aspen automatically adds a : (colon) to separate out main title and subtitle. For Author, Aspen will use 100 a and d but it will display the normalized value from all the included records.

Aspen also groups multiple editions/versions of the same format together. Aspen takes each of these bib records and combines them under one format. This way, if a user hits Place Hold at the top, they will get the first available version. If they want a specific version (exp: hardback, paperback, specific print) they can still hit the Place Hold next to that record.

Mapping Item Data from Koha to Aspen

Aspen maps the item data coming in from Koha in Aspen Administration > ILS Integration > Indexing Profiles > click into the ILS Indexing Information.

In the Item Information menu, this is where Aspen learns which subfield in Koha should map to where.

For example, we tell Aspen that subfield 8 is Collection Code and subfield c is Shelving Location.

Translating Data Coming in From Koha

Once Aspen knows what fields to look at from the ILS Indexing mapping, Aspen will start pulling in the data from those fields.

To see what data Aspen is pulling in, you can look at Aspen Administration > ILS Integration > Translation Maps

Here's an example from the shelf_location map.

On the left side of these maps, these are the values that Aspen is pulling in from Koha. Do not modify this column in Aspen (any changes will be overridden).

You can modify the right hand column. The right hand column is how the value will display to users within Aspen. In this case, the Shelf Location that shows in the Shelf Location facet, the Where is it? copy summary and the Copies menu in the detailed record display.

Changes made here will only affect the display in Aspen and not push these changes to Koha. This way, you can have this information display one way to staff in Koha and a different way in more patron-friendly terms to users within Aspen if you wish.


Aspen has around 40 facets to choose from to help users filter searches. Most of these facets are directly pulling in information from Koha. Here are some common facets and the data points they are using:

  • Added in the Last - Date added is item subfield d - date acquired in Koha. On order is pulling from status 952, subfield 7. On order is not accounted for in the other added in the last facets. On order would move to added in the last when status changes.
  • Author - 100 a,b,c,d,q or 110ab
  • Collection - 952, subfield 8. Values for these are in Aspen Administration > ILS Integration > Translation Maps > collection that pull from Koha's Authorized Values > CCODE
  • Item Type - 952, subfield y. Values for these are in Aspen Administration > ILS Integration > Translation Maps > itype that pull from Koha's Item Types chart.
  • Publication Year: 264 subfield c or the 260 c or 008 position 7-10
  • Series - MARC 830anp 830v, 800pqt. If not found in the 830 or 800 fields, look at the 490. Note: Information might also come in from paid enrichment like Novelist and/or API information from econtent providers such as OverDrive and Hoopla.
  • Shelf Location - 952, subfield c. Values for these are in Aspen Administration > ILS Integration > Translation Maps > shelf_location that pull from Koha's Authorized Values > LOC

Find more information on all Facet definitions here.

Format Information

Aspen relies heavily on formats in the grouped work display to quickly show users what is available for a specific title.

Aspen can use a variety of data points to map format. You can find the Format map in Aspen Administration > ILS Integration > Indexing Profiles > click into the ILS Indexing Information > Format Information.

First, we try to use item type to map formats. Examples of this would be if you had an item type of BOOK14 and BOOK21, we would map both of those to show in Aspen as a format of Book. Or, an item type value of AUDIO, we would map as a format of Audiobook in Aspen.

If your item types don't clearly map to specific formats, you can also use CCODE and/or Shelving Location values to map formats.

Example: Use a Collection Code of Graphic Novel to map to a format of Book or Graphic Novel if you don't have a specific item type for this format.

To do this, add the Value from Koha in Value column and the Format that should display in Aspen in the Format column.

Many different Values can map to the same Format. We try to consolidate formats down to as few as possible to make searching more user friendly for users.

This can be more complicated if you group multiple formats in one item type, collection code and/or shelving location, for example, a value of GAMES but this includes Wii, Playstation and Nintendo formats. In this case, you can put the Value of GAME in and then leave the Format category blank. Then, Aspen will know to look at the bib record information to make a bib level determination for that format.

Find more information on what data Aspen uses to make a Bib Level Determination here.


Aspen uses a combination of the following Authorized Values tables related to status:

  • LOST

By default, Aspen will pull in these status values:

  • Checked Out
  • Claims Returned
  • Damaged
  • Discard
  • In Processing
  • In Transit
  • Library Use Only
  • Long Overdue (Lost)
  • Lost
  • Lost and Paid For
  • Lost Claim
  • Missing
  • On Hold Shelf
  • On Order
  • On Shelf
  • Withdrawn

This status chart can be found in Aspen Administration > ILS Integration > Indexing Profiles > click into the ILS Indexing Information > Status Mappings.

Many of these are suppressed by default in Aspen, but from this chart, libraries can decide which statuses should/should not be suppressed from the Aspen catalog and make other customizations to the statuses.

Additional custom statuses can be added and these statuses can be edited by adding the text found in the status Description field in Koha, not the Authorized Value code, to this map.

Because of the way that Aspen groups works, the status that Aspen shows in the grouped work display is often not literal. Aspen will look at the individual statuses of the items on the record and try to make a simplified status to show to patrons.

For example, Aspen might be displaying a status of Checked Out in the Grouped Work display for a Book but the individual statuses of the items might be Checked Out (to a user), In Transit, On Hold Shelf and Missing. To a user, we want to simply show them if it is available or not.

Individual item statuses can be found within the grouped work display > Copies information.

Find more information about statuses in Aspen here.

We hope this provides a good overview of how Koha and Aspen work together to interpret your data and show it to patrons in a user friendly way!

Throughout implementation and beyond, we're always here to help answer any questions that you may have.