Auto-Generating Location Codes and Location Display Format

Please note: This post highlights our current thinking on this feature. Please help us improve it — share your questions, constructive feedback and ideas in the comments below.

We’ve gotten some user feedback on our Location CRUD (create, read, update and delete) design. Location CRUD is done in Settings > Organization > Location setup. This user feedback has resulted in some proposed modifications we’d like to get broader input on.

Summary of proposed changes:

1. Names and codes should only need to be unique within the context of their hierarchy
   Story added: UIORG-95, With this change, you could reuse the location name “Reference” in different libraries or have a “Main library” on two different campuses, for example.
2. Configuration of Location display format. Since location names and codes won’t always be unique, FOLIO needs to support the inclusion of hierarchy elements (e.g. Institution, Campus and Library) in the location display so that the necessary context is apparent. To this end, we have designed a feature that allows tenant configuration of location display. See the “FOLIO location display name configuration” on this mockup
3. Auto-generation of Location hierarchy codes (based on manually entered location component codes) is essential to the usability of this feature. See “Location hierarchy code configuration” field on this mockup

Details on auto-generation of location hierarchy codes:
A. When configuring location hierarchy codes, where do the component codes (e.g. for Campus and Library) come from? Are they auto-generated based on the first 3 letters of the name?
— The component codes are not auto-generated. They are manually added as part of the Institution, Campus and Library CRUD. See this screenshot for how this is done. These codes can be whatever you want; two letters, three letters, capitals, lowercase, numbers…
B. Where does the location hierarchy code display?
— On the location record in Settings (read-only display) (see mockup)
— In the location selection menu on the holding and item records
— Anywhere that location displays (e.g. Loans, Check in, Requests) IF you make Location hierarchy code part of the FOLIO location display name (see item #2 above)
C. Are component codes required when creating location hierarchy components?
— They are not currently, but we would make them required when implementing this change
D. Do the component codes need to be unique?
— Yes, just like component names, they need to be unique within their own hierarchy
E. When creating a location hierarchy code format, what flexibility do I have?
— I can include the component codes in whatever order I want them and I can use whatever separators I want (dashes, slashes etc) but I must include all elements of the hierarchy

What do you think of these changes? Any questions or concerns? Let us know in the comments.

For reporting purposes, it would be most efficient to require location codes to be unique across the entire tenant. Otherwise, reports including location codes will need to include additional data elements associated with a particular context. Also, managing location codes (CRUD) should be restricted to a small number of users per institution via security roles.

Thanks, @Sharon! The auto-generated Location hierarchy code would definitely need to be unique across the entire tenant (and would be if each of the component codes that comprise it are unique within their own hierarchy).

I think the component codes (e.g. campus code, library code) need only need to be unique within their own hierarchy. Do you agree? If not, could you supply some examples where this might be problematic? Thanks!

I’d like to input an example to see if I’m understanding the proposal correctly. As an example of a possible hierarchy in our institution:
institution: Texas A&M University code: am
campus: College Station code: cs
library: Medical Sciences Library code: msl
location code: BookStacks_msl_cs_am

is this basically correct or have I missed a level in the hierarchy?

the fact that I’m putting the codes in reverse order is something I can do based on the fact that the interface would allow the individual tenant to configure the order of elements in the hierarchy code, correct?

(Sharon forwarded your “convenors” email to the Reporting sig. and in the email you mention auto generation of location display name. Is that also implied by this post? Because I don’t see a reference to location display name in the post itself, but maybe I’m missing something.)

Hi @hismith! You are missing one level.

Manually entered component codes:

• institution: Texas A&M University code: am
• campus: College Station code: cs
• library: Medical Sciences Library code: msl
• location: Book stacks code: BookStacks

Auto-generated Location hierarchy code: BookStacks_msl_cs_am

the fact that I’m putting the codes in reverse order is something I can do based on the fact that the interface would allow the individual tenant to configure the order of elements in the hierarchy code, correct?

Correct!

(Sharon forwarded your “convenors” email to the Reporting sig. and in the email you mention auto generation of location display name. Is that also implied by this post? Because I don’t see a reference to location display name in the post itself, but maybe I’m missing something.)

Location display format is mentioned in #2 above, but by a slightly different name (“FOLIO location display name configuration”). I’ll edit the post to clarify that’s what I mean.

@cateboerema, does the option for FOLIO location display name configuration include the ability to control or choose to show “friendly” names in the interface instead? (E.g., “Medical Sciences BookStacks” rather than BookStacks_msl_cs_am.)

I could see some end users preferring to report via friendly names rather than heirarchy codes, especially if we are writing or providing canned reports for staff to run as needed.

Thanks @enettifee! Yes, it does. There are 4 component parts to the location hierarchy: Institution, Campus, Library and Location. Each component part has a Name and a Code. These are all manually entered (they can be whatever you want). “Name” is where you’d capture the user-friendly name.

When configuring the Location display format , you will be provided with tokens for data that can be included. The tokens offered are: {Institution Name}, {Campus Name}, {Library Name}, {Location Name} and {Location Hierarchy Code}. You can use as many or as few or these as you want. For example, if your tenant only has one institution, you will probably not include the Institution Name (as it has no distinguishing value). Or, if you have created Location Names that are unique, you need not include Campus and Library Name. You don’t need to use the Location hierarchy code in the Location display name, but you might want to, as it includes a lot of information in a condensed format.

When specifying the Location hierarchy code, you will also be given tokens, but this time only for the component codes (i.e. {Institution Code}, {Campus Code}, {Library Code} and {Location Code}). You can assemble them in whatever order you want with whatever separator you want, but you do need to include them all.

I should also point out that, in the location record, we have a field for “Discovery display name”. This is what would display to patrons in discovery and other external systems.

Something that we’ll need to be really clear on - if I need tell FOLIO to do something to a location, how do I indicate that location? Two examples: 1) often external vendors are sending data in MARC records or APIs to create or update holdings or items. 2) when creating an order, the final location where that thing will live is often assigned at point of order.

If this is the structure:
Manually entered component codes:

• institution: Texas A&M University code: am
• campus: College Station code: cs
• library: Medical Sciences Library code: msl
• location: Book stacks code: BookStacks

Auto-generated Location hierarchy code: BookStacks_msl_cs_am

And I’m a vendor sending a cataloging record with holdings/item information to create/update a holdings/item for TAMU Medical Book Stacks, would I send BookStacks_msl_cs_am to represent the location in the MARC record/API data?

Similarly, if I am creating an order in FOLIO and want to designate that book as one that will end up being shelved in TAMU Medical Book Stacks, would I be selecting BookStacks_msl_cs_am from a list of possible locations in the order record?

And a couple more quick questions:

• You mention 2 or 3 character codes, anything you want. Could they be single character codes, to keep the combined code as short as possible?

• You mention upper and lower-case are permitted. Would FOLIO allow 3 different codes of MAIN, Main, and main at the same level in the same tenant, or would that be disallowed? It could be really confusing it it were allowed. I once worked with a vendor that argued that usd and USD were different currency codes based on the case used. That caused big problems when we were trying to transfer data from one system to another, since we could not just assume the proper ISO currency code and case.

• If I am a library with only 1 institution, campus, library, location, and my only location is circulating stacks, I still must fill in all 4 levels of location hierarchy, correct? But I could just use codes m-m-m-m for InstitutionM-CampusM-LibraryM-CircStacks, correct?

If that’s the case, then it’s probably a good idea in any documentation to clarify if there is a recommended best practice for libraries who may only need 2 or 3 layers of what is currently 4 layers in the hierarchy.

I talked with @UschiKlute and @janaagne today and we developed and rehearsed the scenario mentioned above. Due to our union catalogue data structure we only need a permanent location at the item level. However, it should not cause any problems if there are other options as described here (https://wiki.folio.org/display/RA/Effective+Location+Logic), for example. We will not use the additional fields then.

A simple example from ZBW, the library I work at, would be:
institution: ZBW code: 0206
campus: Hamburg code: H
library: - code: -
location: Stacks code: Mag
Auto-generated Location hierarchy code: Mag_?_H_0206
=> As you can see, we wouldn’t have 4 levels of granularity as there is no ‘library’ assigned. Or would “Hamburg” be the library instead of the campus?

A second example without a library + location code:
institution: ZBW code: 0206
campus: Hamburg code: H
library: - code: -
location: - code: -
Auto-generated Location hierarchy code: ?_?_H_0206
=> In this case there should be a fallback to a default location value. Let’s say, if location = empty, default location = reading room.

So we would like to propose to add a new label (field/element) in the settings under Settings / Organization / Location Setup / Locations: One should be able to define a location as “default location”. In case the location is not specified during import, the fallback should take effect. For each combination consisting of institution, campus and library it must be ensured that only one default location can be defined.

And I’m a vendor sending a cataloging record with holdings/item information to create/update a holdings/item for TAMU Medical Book Stacks, would I send BookStacks_msl_cs_am to represent the location in the MARC record/API data?

Yes

Similarly, if I am creating an order in FOLIO and want to designate that book as one that will end up being shelved in TAMU Medical Book Stacks, would I be selecting BookStacks_msl_cs_am from a list of possible locations in the order record?

Yes

You mention 2 or 3 character codes, anything you want. Could they be single character codes, to keep the combined code as short as possible?

Yes

You mention upper and lower-case are permitted. Would FOLIO allow 3 different codes of MAIN, Main, and main at the same level in the same tenant, or would that be disallowed? It could be really confusing it it were allowed. I once worked with a vendor that argued that usd and USD were different currency codes based on the case used. That caused big problems when we were trying to transfer data from one system to another, since we could not just assume the proper ISO currency code and case.

There can be multiple “Main” campuses (or one “main” and another “Main”) in a single tenant but there cannot be more than one “Main” or “main” campus within a given institution. So, basically, we will enforce uniqueness (case insensitive) within the hierarchy.

If I am a library with only 1 institution, campus, library, location, and my only location is circulating stacks, I still must fill in all 4 levels of location hierarchy, correct? But I could just use codes m-m-m-m for InstitutionM-CampusM-LibraryM-CircStacks, correct?

Correct

A simple example from ZBW, the library I work at, would be:
institution: ZBW code: 0206
campus: Hamburg code: H
library: - code: -
location: Stacks code: Mag
Auto-generated Location hierarchy code: Mag_?_H_0206
=> As you can see, we wouldn’t have 4 levels of granularity as there is no ‘library’ assigned. Or would “Hamburg” be the library instead of the campus?

Our current model does assume that Institution, Campus and Library are all populated. Is there no library name you can use in this case?

A second example without a library + location code:
institution: ZBW code: 0206
campus: Hamburg code: H
library: - code: -
location: - code: -
Auto-generated Location hierarchy code: ?_?_H_0206
=> In this case there should be a fallback to a default location value. Let’s say, if location = empty, default location = reading room.

Hmmm. Are you saying you describe items as being located at the Hamburg campus? Isn’t that too vague?

no;-)

Use case for a large amount of our libraries: They have only one library building. Within the stock, a distinction is then made, for example, between closed stacks, free accessible stock (borrowable) and reference stock, whereby no separate location is specified for the open access stock.
Keep in mind that we usually have individual signatures. That means, there are different call numbers for the items, e.g. for a book with 5 copies:
2 copies at closed stacks with location MAG and the call numbers
A 2018/1234
A 2018/1235
1 reference copy with location HAM and call number
HH 2039/116
2 copies (free access and loanable) without location but call numbers
GEO 14/345
GEO 14/345a

Institution: University Library XY-Town, Code: 22
Campus: University Library XY-Town, Code: 22
Library: University Library XY-Town, Code: 22
Locations: MAG, HAM and nothing

This is not a real example, but represents the GBV situation.

Of course there are libraries with two or more sites (like Felix’ Library in two cities). In each city there is one library building, so there is no distinction between Campus and Library. The names and codes for Campus level and Library level must therefore be identical. Or one of the levels has to be omitted.