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.