TOC | Previous | Next | Documentation Home

Creating custom (locally-defined) metadata fields

Site administrators can define additional metadata fields that are attached to samples.  Some labs find these fields convenient for storing information such as billing account numbers, requested completion dates, extra tracking information.  Custom metadata fields are defined on a per-lab basis their visibility is configurable.  They are not searchable and they are not replicated to other sites in the Reciprocal Net Site Network.

Each custom metadata field can store textual data up to 128 characters in length.  Metadata contained within custom fields is visible in the recipnet web application on the Sample Details and Edit sample pages, and can be edited on most of the workflow action pages.  Each site may define at most 1000 custom fields, with each field being used by a single lab.

Custom metadata fields are defined in recipnetd.conf by using the SitLocalFieldxxx directive, one metadata field per directive and one directive per line.  The line in recipnetd.conf should look something like

SitLocalField000=12345,”Field name”,65535

where 000 is any three-digit number uniquely identifying the field, 12345 is the numeric id of the lab that will use this custom field, and Field name is the human-readable name for the metadata field.  The number 65535 is a bit mask that controls which web pages display the field (see below).  There should be no spaces between the three directive parameters, and the field name should be enclosed in quotation marks. You may choose any three-digit decimal number for the directive, as long as each SitLocalFieldxxx directive in recipnetd.conf has a distinct number.  The numeric lab id required by the directive can be found by using the recipnet web app, logging on as a site administrator, going to Administrative Tools, and going to the Edit Lab page for the desired lab.

In addition to identifying specific fields, the three-digit field numbers establish the relative order in which they are displayed by the recipnet web application: lower-numbered custom metadata fields are displayed before (higher on the page than) higher-numbered fields.  Order of the directives in recipnetd.conf is not significant.

The visibility number is a bit mask that specifies which pages in the site software web application should expose the custom field.  The minimum value is 0, which means that the field is not exposed anywhere, and the maximum value is 65535, which means that the field is exposed in all possible places.  Other values require doing some binary math.  The bits of the visibility number are defined as follows:

 Bit number

Custom field exposed where?

(least significant)  0



Submit page


Collect Preliminary Data page


Refine Structure page


Release to Public page


Modify Custom Fields page


Suspend page


Resume page


Declare Incomplete page


Failed to Collect page


Declare Non-SCS page


Retract page


Withdraw page


Sample Details page, visible to any authenticated lab user


Sample Details page, visible to any authenticated provider user

(most significant)  15

Sample Details page, visible to any unauthenticated user

After making changes to recipnetd.conf, you should restart recipnetd so that the changes will take effect.  httpd and tomcat5 should be restarted at the same time, as usual.

If you decide ever to stop using a custom metadata field, you may delete the appropriate SitLocalFieldxxx directive from recipnetd.conf.  Keep in mind that this will not delete the actual metadata from the database, however, and therefore you should avoid using the same three-digit number on other custom fields in the future.  A superior alternative might be to change the visibility number to 0, which will cause the web application to not display the field on any page.

TOC | Previous | Next | Documentation Home