Multipart id numbering.conf

From CollectiveAccess Documentation
Jump to: navigation, search

The MultiPartIDNumber ID Numbering plug-in

The MultiPartIDNumber plug-in provides a flexible means to generate structured numbering systems such as accession numbers within CollectiveAccess. For most numbering schemes employed by museums and archives it should be possible to configure a convenient user interface and adequate validation rules using only the plug-in and without any custom programming.

The MultiPartIDNumber plug-in requires an ID number "format" for each data item in CollectiveAccess that supports ID numbers. A format is composed of "elements" joined together by a "separator." Each element in a format has parameters specified that determine what input is valid for it and how it will behave in the user interface. An ID number is constructed by stringing together the individual elements using separators. By combining various types of elements you can create arbitrarily complex numbering systems.

The multipart_id_numbering.conf Configuration File

The id_numbering.conf file defines the formats used by the MultiPartIDNumber plug-in. It is a standard CollectiveAccess configuration file using the common configuration syntax.

CollectiveAccess supports ID numbers for the following data items:

  1. objects ("ca_objects")
  2. lots ("ca_object_lots")
  3. entity authority items ("ca_entities")
  4. place name authority items ("ca_places")
  5. collection authority items ("ca_collections")
  6. items in user-defined authorities (aka "occurrences") ("ca_occurrences")
  7. loans ("ca_loans")
  8. movements ("ca_movements")
  9. tours ("ca_tours")
  10. tour stops ("ca_tour_stops")

You must specify a format for each type of data item listed above in id_numbering.conf. The format name for each must be identical to the data item name (quoted in the list above). CollectiveAccess will use the format to generate an ID number entry interface and validate input for the ID number field of the respective data item. For objects, this is the 'idno' field; for lots this is the 'idno_stub' field; for the authorities and for vocabularies it is the 'idno' field.

The following sample id_numbering.conf configuration is for an organization employing a lot numbering scheme based upon the year of acquisition and an automatically assigned incrementing lot number. Object numbers are based upon the lot number format but with an additional automatically assigned incrementing item number. In both number formats, elements are separated with periods ("."). The file specifies a two part number for entities: the first element is a code taken from a drop-down list of three allowable values and the second element is an automatically assigned incrementing number. For both place names and vocabulary terms an automatically assigned incrementing number is specified.

formats = {
	ca_objects = {
# This is a default numbering format for object type for which a format has not been explicitly specified
		__default__ = {
			separator = .,
# sorting of id numbers will be in reverse of display order (eg. if display is 2011.52.1, sort will be on 1.52.2001); remove sort_order altogether if you want sort to consider elements in display order

			sort_order = [item_num, lot_num, acc_year], 

			elements = {
				acc_year = {
					type = YEAR,
					width = 6,
					description = Year,
				
					editable = 1
				},
				lot_num = {
					type = NUMERIC,
					width = 6,
					description = Lot number,
				
					editable = 1		
				},
				item_num = {
					type = SERIAL,
					width = 6,
					description = Item number,
				
					editable = 1,
					
					table = ca_objects,
					field = idno,
					sort_field = idno_sort,
				}
			}
		},
# Here's a specialized number format for objects of type "video" (where "video" is the idno of the object_type)
		video = {
			separator = .,
			
			elements = {
				acc_year = {
					type = YEAR,
					width = 6,
					description = Year,
				
					editable = 1
				},
				typecode = {
					type = LIST,
					values = [8MM, DV, BETASP],
					default = ORG,
					width = 6,
					description = Type code,
					editable = 1	
				},
				item_num = {
					type = SERIAL,
					width = 6,
					description = Item number,
				
					editable = 1,
					
					table = ca_objects,
					field = idno,
					sort_field = idno_sort,
				}
			}
		}
	},
	
	ca_object_lots = {
		__default__ = {
			separator = .,
			
			elements = {
				acc_year = {
					type = YEAR,
					width = 6,
					description = Year,
				
					editable = 1
				},
				lot_num = {
					type = SERIAL,
					width = 6,
					description = Lot number,
				
					editable = 1,
					
					table = ca_object_lots,
					field = idno_stub,
					sort_field = idno_stub_sort
				}
			}
		}
	},
	
	ca_entities = {
		__default__ = {
			separator = .,
			
			elements = {
				code = {
					type = LIST,
					values = [PER, ORG, GRP],
					default = ORG,
					width = 6,
					description = Entity code,
					editable = 1	
				},
				num = {
					type = SERIAL,
					width = 8,
					description = Entity number,
					editable = 1,
					
					table = ca_entities,
					field = idno,
					sort_field = idno_sort
				}
			}
		}
	},
	ca_places = {
		__default__ = {
# Note the blank separator -- the comma is part of the config file, not the separator value
			separator = ,
			
			elements = {
				num = {
					type = SERIAL,
					width = 8,
					description = Place number,
					editable = 0,
					
					table = ca_places,
					field = idno,
					sort_field = idno_sort
				}
			}
		}
	},
	
	ca_collections = {
		__default__ = {
# Note the blank separator -- the comma is part of the config file, not the separator value
			separator = ,
		
			elements = {
				num = {
					type = SERIAL,
					width = 8,
					description = Collection number,
					editable = 0,
				
					table = ca_collections,
					field = idno,
					sort_field = idno_sort
				}
			}
		}
	},
	
	ca_occurrences = {
		__default__ = {
# Note the blank separator -- the comma is part of the config file, not the separator value
			separator = ,
		
			elements = {
				num = {
					type = SERIAL,
					width = 8,
					description = ID number,
					editable = 0,
				
					table = ca_occurrences,
					field = idno,
					sort_field = idno_sort
				}
			}
		}
	}
}

All formats in the configuration file are located in an associative list named 'formats' The keys of this list are table names for which format are specified. Each table name key has as its value an associative list keyed on type (you should use the idno of types for the table, not numeric type_ids). If you want to specify a format valid for all types, a common case, use __default__ instead of a valid type code.

Each type key has as its value an associative list specifying the format. The following keys may be placed in the list:

Key Description Example value Mandatory?
separator The value of the 'separator' key will be displayed between elements in the user interface for the format. If you want your elements to be merged end to end with no space or separator character(s) then leave this blank.
separator = ,
Yes
dont_inherit_from_parent_collection In some archival configurations of CollectiveAccess a cross-table hierarchy is used to link object-level records to the collections they are a part of. By default these child records inherit their parent's id number. Often this is the desired behavior but other times, for example when a SERIAL configuration is set for object idnos, it's not because it has the potential to create duplicate id numbers in the object table. In this case dont_inherit_from_parent_collection can be used to prevent object children from inheriting collection idnos that are duplicative. Note this only impacts cross-table hierarchies (doesn't impact other relationships or hierarchies within a single table).
dont_inherit_from_parent_collection = 1
No
elements The value of the 'elements' key is an associative list containing a list of elements and the parameters for each. Elements will be output when constructing an ID number or user interface in the same order they appear in the list.
elements = {
				code = {
					type = LIST,
					values = [PER, ORG, GRP],
					default = ORG,
					width = 6,
					description = Entity code,
					editable = 1	
				},
				num = {
					type = SERIAL,
					width = 8,
					description = Entity number,
					editable = 1,
					
					table = ca_entities,
					field = idno,
					sort_field = idno_sort
				}
			}
Yes
sort_order By default an ID number will sort on its constituent elements in the order they are defined in the elements list. If you need to have the elements of an ID number display in one order but sort in another, you can set the order used for sorting here. The value should be a simple non-associative list with the element keys in the order to use for sorting. If you want sorting to use the same order as display, you should simply omit sort_order
sort_order = [num, code]
No
allow_extra_elements An existing ID number value may include more parts than are currently configured. This can happen when configuration is changed, invalidating numbers created under earlier configurations, or if values are imported from other data sources that don't conform to current standards. For these numbers CollectiveAccess can either (a) ignore the additional parts, truncating the number at the configured number of parts or (b) add "extra" elements for these numbers, preserving the additional parts. No matter which option is chosen the a number with extra parts is still considered invalid. To tolerate numbers with extra parts set this option to a non-zero, non-blank value. To truncate set this option to 0. If omitted the default is to allow extra elements. (Available from version 1.6)
allow_extra_elements = 1
No
extra_element_width Width of any "extra" elements in editing forms, in characters. Defaults to 10 if not set. (Available from version 1.6)
extra_element_width = 4
No

The keys of the element associative list are element names. These names are only used for reference during configuration and to name HTML form elements and are never output to the user. They should use only alphanumeric characters and underscores. Do not put spaces or punctuation in the names.

The value for each element name in the elements list is yet another associative list, this one containing a list of parameters defining the characteristics of the element. The most important parameter to set for an element is its type which defines the general range of allowable values and user interface behaviors. The plug-in supports the following types:

Type Description
LIST Element value must be taken from a predefined list. User interface is drop-down list containing allowable values.
SERIAL If element value is not set, it will be set to a value one greater than the greatest existing value of the ID number as formed from the element and all preceeding elements in the format. For example, if for the three element format with last last element set to SERIAL 2006 001 001 exists and you enter 2006 4, the last element will be set to 5. It is also possible to set the element value manually, but only letters and numbers are allowed.
CONSTANT Element is always set to a constant alphanumeric value and cannot be changed.
FREE Any input is allowed.
NUMERIC Only numbers are allowed.
ALPHANUMERIC Only numbers and letters are allowed.
YEAR Only valid four digit years are allowed, and if empty the element will default to the current year. This is useful when your numbering system includes the current year.
MONTH Only valid month numbers (between 1 and 12) are allowed, and if empty the element will default to the current month.
DAY Only valid day numbers (between 1 and 31) are allowed, and if empty the element will default to the current day.
PARENT Automatically set to the identifier value for the parent when a new record is create. This element is primarily useful when implementing "agglutinative" numbering systems which each level in a hierarchy incorporates the numbers of its parents. When used this must be the first element in the element list for a format type. Expected behaviors may occur if placed in other locations in the element list.

Besides type, there are a number of other parameters that can be set for an element. Some are common to all element types and others are specific to certain types.

Parameters applicable to all types of elements are:

Parameter Description
description A short description of the element, suitable for display in error messages. You must set this for each element.
editable Valid values are 0 (false) or 1 (true). If true, element is presented in the user interface as editable (except for elements of type CONSTANT which are never editable). If false, then elements are only editable when empty in the case of user-entered element types (LIST, FREE, NUMERIC, ALPHANUMERIC) and never editable in auto-filled element types (SERIAL, CONSTANT, YEAR, MONTH and DAY)
width Display width, in characters, of entry field in user interface

Type-specific parameters are:

Type Parameter Description
LIST values List of allowable values for the element. Used to validate input and generate a drop-down list in the user interface. Note that the value for this parameter is a simple list, not an associative list. Ex. values = [eins, zwei, drei, vier]
default Default value for element
SERIAL table database table name to use for lookup when determining next number in sequence. Should be one of the primary types (Ex. ca_objects, ca_object_lots, ca_entities, ca_places, ca_list_items)
field database field to use for lookup when determining next number in sequence. Should be idno for objects, idno_stub for object lots and idno for entities, places, occurrences and collections.
sort_field database field to use for sorting lookup when determining next number in sequence
child_only child records to automatically generate id numbers in an ascending order based on the idno of the parent record
zeropad_to_length if set to a non-zero value, the sequence number is left-padded with zeros until its length is equal to the value. For example, if set to 4, the sequence number 17 would be output as 0017. The zero padding length does not affect sequence numbers longer in length than the specified value. Thus, for example, if zeropad_to_length is set to 3, the sequence value 7114 would be output as-is.
sequence_by_type if set to a non-zero value sequences are calculated by type. That is, each individual record type within the table gets its own number sequence. By default the numbering sequence is shared amongst all types. For most primary types (objects for example) you'll generally want a single set of numbers for all types. Sometimes, most commonly for occurrences, you may prefer that each type have its own sequence. (available from v1.5)
minimum_value a non-zero number to use as the initial value for the sequence. Ex. if set to 20000 then the first record created with be numbered 20000, the second 20001 and so on. (available from v1.7)
CONSTANT value Value of constant. This must be specified.
FREE minimum_length Minimum allowable length, in characters, of element value.
maximum_length Maximum allowable length, in characters, of element value.
zeropad_to_length if set to a non-zero value, the sequence number is left-padded with zeros until its length is equal to the value. For example, if set to 4, the sequence number 17 would be output as 0017. The zero padding length does not affect sequence numbers longer in length than the specified value. Thus, for example, if zeropad_to_length is set to 3, the sequence value 7114 would be output as-is.
NUMERIC minimum_length Minimum allowable length, in characters, of element value.
maximum_length Maximum allowable length, in characters, of element value.
minimum_value Minimum allowable numeric value of element value.
maximum_value Maximum allowable numeric value of element value.
ALPHANUMERIC minimum_length Minimum allowable length, in characters, of element value.
maximum_length Maximum allowable length, in characters, of element value.
YEAR force_derived_values_to_current_year When deriving an identifier from an existing value (typically when duplicating a record, or creating a child record), force the new value to the current year no matter the existing value.
MONTH force_derived_values_to_current_month When deriving an identifier from an existing value (typically when duplicating a record, or creating a child record), force the new value to the current month no matter the existing value.
DAY force_derived_values_to_current_day When deriving an identifier from an existing value (typically when duplicating a record, or creating a child record), force the new value to the current day no matter the existing value.

Problems with SERIAL elements

To generate unique values for SERIAL elements the plug-in must query your CollectiveAccess database. If the database operation fails you may see the word 'ERR' instead of the expected numeric value. If you get an ERR value, verify that the table, field and sort_field element parameters are correct.

The automatically issued SERIAL values should always be one more than the largest extant value in your database. If you are getting values that are less than the maximum check that the sort_field element parameter is correct. The plug-in relies upon this field to properly sort the existing numbers in order to choose the largest existing value.

See also
Cookbook_Chapter_5:_Configuration_Files#Configuring_a_Numbering_System for details on how to get child records to automatically generate id numbers in an ascending order based on the idno of the parent record.

sphinx_moved

Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools