The format of order files
This information has been obsoleted by
OrderFileFormat (as of June 2018)
This page describes the fields used in an order file. It describes
their current use (as of 2015), and tries to point out various uses which do or do
not work. It does not attempt to be definitive or
prescriptive. Although it may now be irrelevant the translation to the
XML order file format is mentioned for each field. For the definitive
story on the translation to XML see the inforder DTD
(
/usr/lib/orders/xml/inforder.dtd
on
ordershost and
customtoxml
in the
dice-orders
package).
Fields which appear only once, at the beginning of the file
These fields appear once only in an order file, at the top.
date
This field stores the date on which the order was created.
It appears only once in the order file.
It is compulsory to have a date in the order.
Takes a numerical date of the form
dd/mm/yyyy
Single 'd' or 'm' figures are OK. A leading zero is accepted but not
required.
A few orders had a two figure
yy
field instead of four
figures. The results of that are not as intended - for instance year
10
when entered into the database became the year
0010
when
returned in a query.
Also one or two had incorrect years -
inf0364:date:31/03/209
inf1142:date:8/2/1011
uoe100491:date:25/2/2105
uoe20324:date:9/12/201
uoe98963:date:03/02/2105
uoe98986:date:03/02/215
These incorrect years were accepted uncritically and made it
into the database intact (albeit with leading zeroes to make them up
to 4 numerals). They have now been corrected.
Interestingly the 'date' field appears in database queries in the
format
yyyy-mm-dd
but the related 'delivered' field, which is also a date,
appears as
dd/mm/yyyy
.
In the transformation to XML,
date:17/02/2015
becomes
<order_date year="2015" month="02" day="17" />
One order uses dots instead of slashes for the date:
uoe888942:date:31.7.2014
The date of this order does appear correctly in the database:
2014-07-31
However it's not clear whether dots are accepted properly or
whether this one-off was manually corrected in the database but not in
the orders file.
supplier
This is a free format text field, one line, denoting the supplier of
whatever's being ordered.
It appears only once in the order file. It is a compulsory field.
Most of our popular suppliers have multiple forms of their name in the
database. For example, Dell appears in these forms:
Dell
Dell
Dell
Dell (Clodagh Higgins)
Dell Computer Corporation
Dell Corporation Ltd
Dell Corporation Lts
Dell Corproration
Dell (John David)
Dell (John David - 01344 723941)
Dell Online
Dell parts
Dell Parts
Dell (Paul McGeoch)
The first three forms differ in the amount of white space after the
word 'Dell' - so white space is significant and is carried over into
the database. Would it be useful to add a 'contact' field?

ascobie - good idea!
In the transformation to XML,
supplier:Dell Corproration
becomes
<supplier_name>Dell Corproration</supplier_name>
ticket
A free form text field, used to record the RT ticket that was used to
raise the order. This field is recorded in the orderstable on ordershost, but is not
supported by the 2008 Inventory system.
note
A free form note that applies to the whole order.
Fields appearing once per unique item
Many of the fields in an order file are used once 'per
unique item' rather than once per order file. Each unique item must
have an item number and a dot in front of every line associated only
with that item. By convention the first unique item in each order is
numbered '1', the second '2', and so on. For instance an order for
fruit might include these lines:
1.item:banana
1.quantity:3
1.delivered:
2.item:orange
2.quantity:5
2.delivered:
3.item:mango
3.quantity:2
3.delivered:
item
This denotes the name and description of a particular thing being ordered.
It can appear multiple times in an order file, once for each unique
item description. It contains free arbitrary text, and this goes straight into the
database - unaltered except that commas in the order file seem to be
transformed into semi-colons in the corresponding database entry.
The value is added when the order is created.
In the transformation to XML,
1.item:Dell XPS Laptop
becomes
<order_line number="1">
<item_maker>Dell</item_maker>
<item_description>XPS Laptop</item_description>
This exposes a flaw in the XML definition: it assumes that the 'item' value will start with
the 'maker' of the item. (There is a list of official 'makers' which
can be edited and added to.

- cc -
rfe makers
gives access to the
file, which is
/var/rfedata/orders/makers
on
ordershost. - ascobie - looks like bin/customtoxml processes this file) However, many "item" values do not start
with the name of a maker. If an item's value does not start with a
recognised maker then the item_maker field in XML is left empty, so
for instance:
uoe93093:1.item:Earmuffs & Ear Plugs
becomes
<item_maker></item_maker>
<item_description>Earmuffs & Ear Plugs</item_description>
warranty
This (per unique item) field records warranty details, if any. It
always appears in the order but can be left blank when not
applicable. The corresponding field in the orders database gets the
value unaltered, except that (in the web query output) commas in the
order file are transformed into semi-colons.

- ascobie - wasn't aware of this
For the XML translation,
1.warranty: 1 year next day on site
becomes
<item_warranty duration="1" time_unit="years">
<warranty_details>next day on site</warranty_details>
</item_warranty>
If the warranty value starts with a number followed by months or years, they are fed into the
'duration' and 'time_unit' fields of the warranty
declaration. Any free text is fed into the 'warranty_details' value,
except for the following terms which go instead into the warranty's
"type" field if they occur after the time period: rtm, Onsite, nbd,
educational, other.
1.warranty:3yr nbd
becomes this:
<item_warranty duration="3" time_unit="years" type="nbd">
</item_warranty>
quantity
The quantity of a particular item being ordered.
This is a per-item field and is compulsory.
The value is added when the order is created.
The value is almost always an integer but a few instances exist of
the value being given to two places after the decimal point,
e.g. "250.00". The orders database seems to cope with this.
A web query on the orders database returns as many lines as the value of
the 'quantity' field - for instance 30 lines of results for a quantity
of 30.
In XML,
1.quantity:1
becomes
<item_quantity>1</item_quantity>
price
The price of an item. This is another per-item field (rather than
per-order).
It should consist of an integer or real value representing the
per-item price in pounds.
The value is added when the order is created.
In a few order files (inf5079, uoe101395, uoe98963, uoe98964,
uoe98986, uoe99891) the 'price' value started with a £ symbol. This was
translated successfully to XML but a web query on the database shows a
blank 'price' field for these orders. These orders have now had the £
symbol removed.
(Question: how would one enter a price which was expressed in another
currency? Or is it not possible to place such orders anyway? Is there
any possibility that orders in another currency will one day become
possible? -

- ascobie - Do you mean if UK adopt the euro? We
already do occasionally order in euros, but prices are always
normalised to pounds in the orders db.

- cc - I was
curious about what happened when we
ordered in any other currency, for instance US$. But a currency change
of some kind no longer seems unthinkable. A minor/distant worry perhaps.)
In XML,
1.price:1030.02
becomes
<item_price>1030.02</item_price>
delivered
Records the date on which the items were delivered.
One line per unique item is required. It seems to be assumed that the entire
quantity of each unique item will be delivered simultaneously (

- ascobie - too complicated (and too much data replication) to do otherwise - though I guess there could be a default value and then some means of overriding for certain (late?) items)
Until the items have been delivered, the '.delivered.' line is left
with a blank value (

- ascobie - previous practice was to set this to NOTYET by default. This was set as a default value in the template - now removed)
In XML,
1.delivered:04/02/2015
becomes
<item_delivery_date year="2015" month="02" day="04"/>
budget
This records the code of the budget to which the items being ordered
are to be charged. There should be a budget code given for each unique
item in the order. This field should be added and filled in at order
creation time.
In the translation to XML,
1.budget:747CIS/3152/RE7588
becomes
<item_budget>747CIS/3152/RE7588</item_budget>

- ascobie - might be worth looking at whether can validate this in some way
category
To record the classification of the things being ordered - 'tablet',
'printing', 'cables', and so on. There have been 47 different values
used in the order files to date. There seems to have been some attempt
at consistency in the use of this field (

- ascobie - I tidied things up last year but
it looks like things have drifted - need validation) but there are quite a number
of inconsistencies in its use (e.g. printer toner cartridges sometimes
have a blank category and are sometimes 'consumables'; laptops have
been classified 'portable', 'portable ', 'Portable', 'laptop',
'portable als', 'Laptop'; etc.).
One 'category' line appears per unique item in the order.
The 'category' field is not translated to the XML format.
requestor
This records the person (or function) asking for the purchase (rather than the one
recording it). Many people have been recorded as their UUN, but there
are also quite a few real names used in this field, and some other types of data too, for instance RT ticket numbers. The most popular
value for this field is 'support' (165 occurrences).
One 'requestor' line appears per unique item in the order.
The 'requestor' line does not become part of the XML order.
note
A free form field for making a note specific to a line item
Fields which appear for each instance of each item
Some information is unique for each instance of each item
ordered - for instance the serial number. To continue the example
above, if fruit were expected to come already marked with unique
serial numbers, the order file might contain:
1.item:banana
1.quantity:3
1.delivered:
1.sno:
1.sno:
1.sno:
2.item:orange
2.quantity:5
2.delivered:
2.sno:
2.sno:
2.sno:
2.sno:
2.sno:
3.item:mango
3.quantity:2
3.delivered:
3.sno:
3.sno:
sno
This is used to record the serial numbers, if any, of the goods being
ordered.
The serial numbers can obviously not be known at the time the order is
placed; so at this time the order file contains a blank 'sno'
line for every instance of each item. Once the items have been delivered, and if they have serial
numbers, these are added to the order file.
Each 'sno' line contains at most one serial number.
This field appears once for each instance of each item which has a
serial number. For instance, if one order was for ten servers and five
laptops, and all had serial numbers, the order file would eventually
contain fifteen 'sno' lines recording those serial numbers.
If an item does not have a serial number then the line should be left
with a blank value. In this case, and in the case of items not yet
having been delivered, it is sufficient to have one 'sno' line in the
orders file for each numbered unique item being ordered, regardless of quantity.
In XML,
1.sno:G8GPL32
becomes
<item_serial_numbers>
<serial_number>G8GPL32</serial_number>
</item_serial_numbers>
barcode (to be deprecated)
This field will soon be deprecated, because the syntax used means that when a
quantity of identical items greater than 1 is ordered it is not
possible to associate each particular item with its own serial number and
barcode.
Some order files contain this field, but by no means all.
The purpose was to record the number of the barcode sticker which was
added to a (relevant) item after delivery. Only some items would carry
barcodes - computers, for instance. Other less long-lived items such
as network cables or printer cartridges would not.
One 'barcode' line would be used per individual item which had a
barcode added to it.
Fields appearing once, at the end of the file (
ascobie - actually none of these need be at the bottom)
vat
This records the rate of VAT chargeable on the items being ordered.
It appears only once in each order file.
The rate is expressed as the number which should be multiplied with
the pre-VAT price to get the post-VAT price - for instance a VAT rate
of 20% would be expressed as 1.2 (or as 1.20).
One order (uoe59331) has a VAT rate of 1.2000229.
When translating to XML,
vat:1.20
becomes
<inforder vat = "1.20" >
procurement contract (desired) -
- ascobie
It would be good to have a field that recorded under which procurement contract the goods were ordered - eg selectPC, selectserver, NSSA, off-contract, etc. Would probably have to be free-text
comment
I wonder if we could do with a 'comment' field? To capture random extra bits of data as necessary. Free text, to appear as many or as few times as desired, and usable both per-item and per-file. (If we did add this, we could also accept synonyms such as 'note'? Or would that confuse people...). There is - it's the 'note' field that can be used both per-item and per-file.