Feature #12365

Allow more customization options for reference code separator settings

Added by Dan Gillean over 3 years ago. Updated over 3 years ago.

Status:NewStart date:08/03/2018
Priority:MediumDue date:
Assignee:-% Done:


Target version:-
Sponsored:No Tested version:


Currently (in 2.4 and earlier), users can set a reference code separator in Admin > Settings > Global, which is used between identifiers when the Reference code inheritance setting is turned on.

Recently in the AtoM forum (2018-07-22, thread here ), a user from Portugal pointed out that in Portugal and France, best practice is to also use a slash separator between the country code and repository code as well. The user developed his own solution, but this also prompted discussions around implementing a better feature that would accommodate different use cases.

The following feature proposal documents a potential solution that should be flexible enough to meet many different use cases.

Similar to how the Accession mask and Identifier mask work, a single setting that accepts a reference code mask would be implemented, so users can customize how the reference code is rendered, and different separators could potentially be used between certain elements as needed. Set values could be entered to indicate each element of the reference code, with users adding spaces, special characters, or even alpha/numeric characters to be used as part of the separators.

We would add a default mask value that would replicate the current functionality, so that current users who upgrade will not experience unexpected changes to reference code inheritance.

The following values could be used to represent the reference code mask values:

  • %C = Country code
  • %R = Repository code
  • %P = Parent identifiers (i.e. the identifiers of all the ancestors of the current unit of description)
  • %I = Identifier of current unit of description


Overview and default mask value

Given a description with:

  • A country code of CA
  • A repository code of REPO
  • A collection-level identifier of C1
  • A series-level identifier of S1
  • A file-level identifier of F1
  • An item-level identifier of IT1

The current implementation gives an inherited reference code at the item level of: CA REPO C1-S1-F1-IT1

The default mask value that would produce this would be: %C %R %P-%I

Example 1

  • Reference code mask: %C-%R/%P-%I
  • Example value: CA-REPO/C1-S1-F1-IT1

Example 2

  • Reference code mask: %C-%R: %P/%I
  • Example value: CA-REPO: C1/S1/F1/IT1

Example 3

  • Reference code mask: %C:%R(%P.%I)
  • Example value: CA:REPO

Example 4

  • Reference code mask: %C/%R RECORD-SET: %P_%I
  • Example value: CA/REPO RECORD-SET: C1_S1_F1_IT1


#1 Updated by Dan Gillean over 3 years ago

NOTE: while the proposed default value would work for new users, things get trickier for upgrading users who have changed the default dash value to something else (like a slash).

Would it be possible to have a migration script check the current separator value, and then use that to update the new mask value? I.E:

If the new default mask is: %C %R %P-%I

And a user has changed the default separator value to /

Then post migration script, the default value in this upgraded instance would be: %C %R %P/%I


Also available in: Atom PDF