How to add a new number pattern

CollectionSpace can automatically generate various types of identification numbers for your cataloging and procedural records. Examples include object numbers, acquisition reference numbers, and loan out numbers.

You can use some or all the predefined number patterns that come with a CollectionSpace system. You can also create new, custom number patterns to automatically generate the types of record numbers specific to your institution.

Task Description

This document describes how to add a new number pattern to CollectionSpace.

Prerequisites

A system administrator with experience editing XML markup and running command line utilities can perform all of the tasks described in this document.

Procedure

To create a new number pattern, follow the next steps:

Create the new number pattern in a SQL load file

1. Make a new directory.
2. Change into that directory.
3. Download the Services source code tree into that directory. See How to check out the Services layer source code for details.
4. Within that source code tree, find the .SQL import file for the ID service ; e.g.:

   services/id/service/src/main/resources/db/mysql/load_id_generators.sql

   (You can also view and copy an example of this file online.)
5. Copy the file and rename it. You might name it something like my_custom_number_pattern.sql.
6. Open your new SQL load file, my_custom_number_pattern.sql, in a text editor.
7. Delete all but one of the INSERT statements for existing number patterns. (You'll use the one remaining INSERT statement as a template that you can modify.)
   These INSERT statements all begin with INSERT INTO, contain many lines of text, and end in a semicolon (;). They follow this general pattern:

   INSERT INTO `id_generators`... VALUES (...);

8. Create your new, custom number pattern by editing the one remaining INSERT statement, changing several of its values as follows:
   1. Change the first value ('csid') to a new 36-character unique ID. (To generate this ID, see the Generating section of /wiki/spaces/collectionspace/pages/666274321.)
   2. Change the second value ('displayname') to a human-readable name for the number pattern.
   3. Change the third value ('description') to a description of the number pattern, such as a summary of its purpose and any other relevant information.
   4. If the fifth value ('last_generated_id') contains a value, remove that value (the quantity between the single quotes). The empty value should simply look like this: ''
   5. Change the last value ('id_generator_state') to XML markup that reflects the number pattern you'd like to generate. Specifically, within the existing <parts> element in this XML markup, you'll add or edit a set of "parts," such as the StringIDGeneratorPart and YearIDGeneratorPart. Some of these parts insert static strings, while others insert dynamic numbers, dates, alphabetic values, etc. You'll add one of these parts for each of the distinct portions of your number pattern that is to be generated, from left to right. Each part has initial and/or current values that you may wish to customize as well.
      
      The following example shows a number pattern consisting of four parts, all added as children of the existing <parts> element: a string part, a current year part, another string part, and an auto-generating numeric part. This pattern will generate numbers like PR2011.1, PR2011.2, and PR2011.3 ... if the current year is 2011; numbers like PR2012.2, PR2012.2, PR2012.3 ... if the current year is 2012, and so on:

      <!-- Always begin numbers with the string "PR" -->
      <org.collectionspace.services.id.StringIDGeneratorPart>
        <initialValue>PR</initialValue>
        <currentValue>PR</currentValue>
      </org.collectionspace.services.id.StringIDGeneratorPart>
      <!-- Insert the current, four-digit year; currentValue should be empty -->
      <org.collectionspace.services.id.YearIDGeneratorPart>
        <currentValue></currentValue>
      </org.collectionspace.services.id.YearIDGeneratorPart>
      <!-- Insert a string consisting of just a period/full stop (".") -->
      <org.collectionspace.services.id.StringIDGeneratorPart>
        <initialValue>.</initialValue>
        <currentValue>.</currentValue>
      </org.collectionspace.services.id.StringIDGeneratorPart>
      <!-- Insert an autogenerated number, starting at 1 and ending at 999999 -->
      <org.collectionspace.services.id.NumericIDGeneratorPart>
        <maxLength>6</maxLength>
        <initialValue>1</initialValue>
        <!-- currentValue should be set to -1 if the first value to be generated is the initial value, shown above -->
        <currentValue>-1</currentValue>
      </org.collectionspace.services.id.NumericIDGeneratorPart>
      

      In addition to the parts shown in the example above, which you can mix and match as you wish, there is also an additional part you can include in your custom number pattern that can generate alphabetic sequences; e.g."a, b, c ... z, aa, ab ..." or "Y, Z, AA. ..." as illustrated next:

      <org.collectionspace.services.id.AlphabeticIDGeneratorPart>
        <startChar>a</startChar>
        <!-- When the end character in the sequence, below, is reached, this part -->
        <!-- will add an additional character at left and roll over to a new sequence; -->
        <!-- for example, from "zx", "zy", "zz" to "aaa", "aab", etc. -->
        <endChar>z</endChar>
      </org.collectionspace.services.id.AlphabeticIDGeneratorPart>
      

Import the new pattern into the database

1. Import the new number pattern into the MySQL database.
   1. On a computer that has the mysql command line client installed, log into a MySQL user account by typing:

      mysql -u username -p

      where 'username' is the name of a MySQL user that can write to tables in the 'cspace' database.
   2. At the password prompt, enter the password of that MySQL user.
   3. To import the new number pattern(s), at the mysql> prompt, type:

      source pathto/my_custom_number_pattern.sql

      where pathto is the filesystem path to the SQL load file containing your custom number pattern(s), if that file is not in your current directory.
   4. To exit MySQL, at the mysql> prompt, type:

      quit

Modify the main CollectionSpace configuration file to reflect your new number pattern

Reference your newly-created number pattern by editing the main CollectionSpace configuration file, by following the next steps:

1. Find this configuration file. You will find it in the following locations:
   (Under Linux and other Unix-like systems)

   $JBOSS_HOME/server/cspace/conf/cspace-config.xml

   (Under Windows)

   %JBOSS_HOME%\server\cspace\conf\cspace-config.xml

2. Edit this configuration file in a text editor.
3. Within this configuration file, find the record block for the ID service. This will start with <record id="id" ...>; e.g.:

   "Note"

   The ellipses ("...") in the examples below indicate additional markup that isn't displayed, to keep examples brief and uncluttered. They are not literally present in this markup, and you should not add them.

   <record id="id" type="id">
   ...
     <section>
       <field id="accession"><selector>9dd92952-c384-44dc-a736-95e435c1759c</selector></field>
       <field id="archive"><selector>70586d30-9dca-4a07-a3a2-1976fe898028</selector></field>
       ...
     </section>
   

4. For each new number pattern you added to the services, above, add one new field element within the section block shown above; e.g.

     <section>
       <field id="accession"><selector>9dd92952-c384-44dc-a736-95e435c1759c</selector></field>
       <field id="archive"><selector>70586d30-9dca-4a07-a3a2-1976fe898028</selector></field>
       ...
       <field id="mynewnumbertype"><selector>9dd92952-c384-44dc-a736-95e435c1759c</selector></field>
     </section>
   

   1. For the first value ('id'), enter a short name for the type of your new number pattern.
   2. For the second value ('selector'), enter the 36-character unique ID that you created earlier for your new number pattern in the SQL load file, above.
5. Next, within this configuration file, find the block for the record type to which you wish to add this number pattern. It will start with <record id="..."> and will look something like the following (in the example of an acquisition record):

   <record id="acquisition" in-findedit="yes" type="record,procedure">
   

6. Find the field element within that record that configures which number patterns are presented to the user, via a Number Pattern Chooser widget. It will have a chooser="yes" attribute, as in this example:

   <record id="acquisition" in-findedit="yes" type="record,procedure">
     ...
     <field id="acquisitionReferenceNumber" in-title="yes" chooser="yes" mini="number,search,list,relate,terms" seperate_ui_container="true">
       ...
       <options>
         <option id="accession" sample="2009.1">Accession</option>
         <option id="archive" sample="AR2009.42">Archives</option>
         <option id="library" sample="LIB2009.1">Library</option>
         ...
       </options>
   

7. Within that field's options block, add a new option element for your new number pattern:

       <options>
         <option id="accession" sample="2009.1">Accession</option>
         <option id="archive" sample="AR2009.42">Archives</option>
         <option id="library" sample="LIB2009.1">Library</option>
         ...
         <option id="mynewnumbertype" sample="MYN.1.9">My New Number Type Here</option>
       </options>
   

   1. For the first value ('id'), enter the same name (e.g. mynewnumbertype) you entered previously, when adding your new number pattern to the record block for the ID service.
   2. For the second value ('sample'), enter a representative sample of an ID number that matches your pattern.
   3. For the third value, enter a display name for your new type of number. This is the name that will be displayed to the user, in the Number Pattern Chooser widget.

Restart the CSpace server

1. Shut down the 'cspace' server (only - not the Nuxeo server) by following the instructions in the reference document: Shutting Down the CollectionSpace Server.
2. Start the 'cspace' server by following the instructions in the reference document: Starting Up the CollectionSpace Server.

Test

To verify that you have successfully added your new number pattern in the database:

1. Make a services call to verify that your new number pattern is now available. In a browser, type:

   http://myserverhostname:myport/cspace-services/idgenerators?format=full

   where 'myserverhostname:myport' is the hostname and port of your CollectionSpace server.
   Example: http://demo.collectionspace.org:8180/cspace-services/idgenerators?format=full
2. When prompted, authenticate with a username and password for a valid user of the CollectionSpace system.
   
   You should see XML markup displayed in your browser's window that includes an entry for your new number pattern.

To verify that you have successfully added your new number pattern to CollectionSpace's main configuration file:

1. Log into the CollectionSpace system.
2. Click the Create New tab.
3. Click the button next to the record type to which you've added your new number pattern.
4. Click Create.
5. On the data entry screen for your record type, find the field next to a Select number pattern button.
6. Click that button.
   
   A Number Pattern Chooser widget should pop up. This widget will display a list of various types of numbers you can add. You should see your new number pattern in that list.
   
   
7. Select your new number pattern from that list.
   
   A automatically generated number, following your new number pattern, should appear in the text field next to that button.

Summary

The above procedure describes how to add a new number pattern to CollectionSpace by:

• Creating a custom number pattern in the a SQL load file.
• Importing that number pattern into the CSpace database via the database client's command line utility.
• Editing the main CollectionSpace configuration file in two places:
  • Adding an entry for that number pattern.
  • Referencing that number pattern within the entry for the appropriate record type and field into which you'll be entering these numbers.
• Shutting down the CSpace server.
• Restarting the CSpace server.

See Also

The following documents can provide additional information on configuring CollectionSpace.

• A set of example number patterns provided 'out of the box' with a new CollectionSpace deployment are listed in the Notes near the bottom of many of the Schemae pages. See Schema.
• See ID Service Contract for information on how to programmatically invoke CollectionSpace's ID service to auto-generate numbers from number patterns.