Multipart id numbering.conf

From CollectiveAccess Documentation
Revision as of 13:03, 1 November 2013 by Julia (talk | contribs) (The multipart_id_numbering.conf Configuration File)
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
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

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.

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: objects, lots, entities, place_names, voc_terms
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.
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.
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.

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.
Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools