Artbox Custom Data Definition

Disclaimer: Proximity Corporation provided the information in this article and it was deemed accurate as of 30 May 2007. Apple Inc. is not responsible for the article's content. This article is provided as is and may or may not be updated in the future.

The scripts which artbox uses to configure the data as shipped can also be used to set up data required specifically for a particular customer.

The basic procedure is to create a new file in CSV (comma-separated value) format, which can be maintained by most spreadsheet programs, and create a new initdata.conf file. Details vary depending on what sort of data requires the customisation. These files must be located in:

/usr/artbox/sql/custom

Once you have the data set up, you can get your changes into the database by running:

/usr/artbox/sbin/ab_initdb

Depending on the type of data, you can get updates propagated to the database by running that script again after editing the data files. Just be aware that in most cases, we don't attempt to capture changes to user-modifiable data, as we want to avoid clobbering anything someone may have done using the artbox ui itself. However we do capture additions of new fields etc.

Configuring an initdata.conf file

The initdata.conf file can normally be found in /usr/artbox/sql on a production artbox system. It provides instructions as to which data files should be processed using which scripts. An example of what a current (at time of writing) one looks like is:

# $Id: initdata.conf,v 1.5 2004/10/21 06:55:41 ben Exp $
#
# Config file for initdata.rb. The first column is the table name, the
# second is a list single character flags and the third is an optional
# ruby sub-script. Flags are:
#
# g - .dat file must be generated from a .def file
# d - a .dat file is processed directly by the ruby script
# r - use script in 3rd colum to insert data rather than a direct copy
# 
# The r flag takes precedence over c and only works if a script is
# specified. If the r flag is specified on its own, then the .def file
# is read directly by the .rb script
#
# Columns must be tab separated

# <table name>		<flags>		[script]
pxtraitclass		gr		insTraitClass.rb
pxuser			rd		insUser.rb
pxgroup			rd		insGroup.rb
pxgrouphasuser		rd		insGroupHasUser.rb
pxschema		gr		insSchema.rb
pxentitylinktype	gr		insEntityLinkType.rb
pxenum			r		insEnum.rb
pxenumentry		r		insEnumEntry.rb
pxmdfield		r		insMdField.rb
pxtrait			gr		insTrait.rb
pxmdgroup		r		insMdGroup.rb
pxmdgrouphasfield	r		insMdGroupHasField.rb
pxmdmap			r		insMdMap.rb
pxeventstatus		gr		insEventStatus.rb

The comments at the top explain the flag codes reasonably well. For each sort of data file, you could create a new data file of the appropriate type, and add a line to this file, using the script appropriate to the type of data.

You will need to create your own initdata.conf file inside the custom directory. The database update script will detect this file and execute it's contents.

Metadata Fields

The script which processes metadata fields is insMdField.rb. The data file needs to have fourteen columns, interpreted as follows:

• ;fieldid: a unique concise text name for the field id, must be unique among all metadata fields
• ;name: a name for the field
• ;datatype: the data type, the name of a Kt-type, examples are KtInt, KtString, KtString32, KtDateTime, KtIntXY, PxTimecode, KtBool
• ;description: a description for the field, this is used in roll-over text
• ;rangemin: if the field is of a numeric type, and the values are to have a lower limit, enter the value, otherwise enter null
• ;rangemax: for numeric fields, the upper limit, if any, otherwise null
• ;suffix: a text suffix to appear after the value in the user interface, eg units for a measurement
• ;removable: t for true, f for false, whether or not it should be possible for the admin to remove this field definition in artbox, usually t
• ;definable: t/f, whether or not to allow editing of the definition of this field in artbox, usually t for a custom field
• ;enumid: if the values of this field are to be taken from an enum (aka look-up), the text id of the enum, otherwise null
• ;defaultvalue: the default value for the field, if any, otherwise null
• ;fieldcategory: a flag to indicate whether the field has any special meaning, usually 0 for custom fields
• ;mdgroupcategoryid: for custom metadata, this should always be custom
• ;hints: display hints to the user interface, see other fields for examples, leaving this blank is a good default

Metadata Group

Metadata groups are inserted with the insMdGroup.rb script. The data file has nine columns, as follows:

• ;mdgroupid: a concise text id for the md group, unique among all metadata groups
• ;name: the name of the md group
• ;trait: which trait this md group corresponds to. For asset metadata, this will usually be either "asset", if the field should apply to all assets, or the specific name of the trait for an asset type (eg asset_graphic, asset_animation)
• ;removable:t/f, whether this md group should be removable in artbox, usually t
• ;definable:t/f, whether the configuration of this md group should be modifiable in artbox, usually t
• ;action: a comma-delimited list of actions where this md group will apply, for example view details,edit details,create
• ;mdgroupcategoryid: the category of md group, usually custom for custom md
• ;priority: a number that determines the order of appearance of the tab for this md group, a higher number means it appears further to the right, ie after other fields. In practice 10 is about the highest number you'd want to use here.
• ;hints: a set of values giving hints to the user interface about how to display this md group, blank is a good default

Metadata Map

Metadata maps are inserted with the insMdMap.rb script. The data file has three columns, as follows:

• ;fieldid1: field ID of the source field to be mapped from
• ;fieldid2: field ID of the destination field to be mapped to
• ;priority: map priority. if more than one field id maps to the same field id, the map with the highest priority will take precedence. the higher the priority number, the higher the map priority.

Setup

Once you have a correctly formatted CSV document, the following preparations should be completed when importing data:

1. Copy the CSV document to /usr/artbox/sql/custom
2. Convert the line endings of the CSV document to Unix-style endings ('\\n'), if required
3. Remove any blank rows
4. Ensure that certain characters are correctly escaped for the database, single quote entries ' should be escaped to \\'
5. Add an entry to /usr/artbox/sql/custom/initdata.conf to reference the customer specific metadata.

   For example, if you have custom field metadata in a CSV document named "/usr/artbox/sql/custom/mystation-md.csv", then run the following command:

   mystation-md
   r
   insMdField.rb
6. Ensure that artbox is not running by running artbox stop
7. Run the update script and check to see if there are any error messages
   /usr/artbox/sbin/ab_initdb
8. Restart artbox by running artbox start