UBL INPUT SHELL REQUIREMENTS
Preliminary Draft –
Table Of Contents
1. Introduction
2. A model for UBL Data for Forms Development
3. Handling of UBL specific datatypes (an overview)
a. Tokenized Strings
b. Numbers
c. Strings
d. Dates
e. Currencies
f. Lists
4. Form Logic Gates
5. Static Form Regions and Fields
6. Dates – calculations required
7. Currencies – calculation required
a. Calculation models
8. XML Elements of Output Specifications and Mappings
9. Index
Introduction
This document gives the input requirements which an Application developer can use in constructing an Input
form for user input to generate an UBL document instance.
An input specification attempts to collect, distill and publish enough information about the expected output
so that an implementer can satisfy a requirement to accept input from human interaction with forms to create
a document instance without having to have a deep technical knowledge of the target output.
There are already output specifications defined, the input specifications will define basic requirements to
match the output specifications but can go over these requirements to discuss the input requirements for
elements the outputs of which have not as yet been defined.
The expected output formats for which this document will be concerned are as follows:
UBL Small Business Subset Invoice
UBL Small Business Subset Order
As a best practice it should be held that any implementation that has both an
output and an input component the presentation of the input should match as
closely as possible the expected output so that the user will not become
confused.
A model for UBL data for forms development
In discussing a model for representation of UBL data in a form we will start from the Xforms model of how
data is bound to form elements, and how these form elements result in XML output.
Xforms identifies various properties of data that is bound to a form element, these values are ReadOnly,
Required, Relevant, Calculate, and Constraint. We will define the state of our form elements dependent on
these same property terms





ReadOnly data – the data can only be read by a form element, for example in the case of a select
box we will want to read the list of values allowed to be placed in the select box, and then choose
one of this list for our output.
Required data – data must be supplied for this to be considered valid.
Relevant data – Certain parts of the form will be accessible to the user dependent on values placed
from various other parts of the form. This is addressed further in the part of the document entitled
Form Logic Gates.
Calculate – the value of this form field will be filled by a calculation undertaken by the
implementation. A calculated field should be ReadOnly.
Constraint –
And to this we will add the concept of form regions, a form region represents a number of form fields that
when completed will map to the individual textnode holding elements of a complex element structure.
As UBL is defined using W3C XML Schema it would follow that UBL makes use of the standard XML
Schema datatypes as well as types defined specifically for UBL.
For the purpose of handling of input fields the following datatypes are important:
1.
2.
3.
4.
5.
6.
Tokenized strings, based on xsd:token
Numbers, derived from various XML Schema numeric datatypes.
Strings, derived from xsd:string
Dates
Currencies
Lists, represented in W3C XML Schema as enumerations, documenedt in UBL via the genericode
Codelist standard
Handling of UBL specific datatypes
Tokenized Strings: When dealing with a tokenized string in a user input situation the form implementer
should remember that an xsd:token cannot have any leading or trailing whitespace, and that there must not be
more than one whitespace character in a row within the output XML element. Expecting a user in a
production system to follow this rule when entering input into a form field would not be a good idea
therefore the implementer should when possible implement an algorithm to strip whitespace in the manner
described.
Numbers: For the shell input forms there will not be any numbers used that will require standard numerical
operations (addition, subtraction, multiplication, etc.) other than currencies, operations specific to currencies
Strings: There is no specific requirement for how strings are handled, however in fields where the element
output is required and is a string it should be noted that the W3C Schema String datatype allows for zerolength strings. Thus an element that can be important for implementing a business rule could conceivably
come to be valid by the Schema rules for validation, but not hold any actual meaningful content. An
implementer should take this into consideration, and where necessary implement specific business rules
requiring actual content be placed into form fields. For the purpose of this document any form field that is
described as needing to be filled must result in an output xml field that is non-empty (following the XML
specification's definition of an empty element.)
Dates: Dates in XML Schema are represented in the Gregorian manner, with the year first, the month
second, and the date third – for example the following date: 2003-11-12. Users entering information will
often not conform to the Gregorian date format, and the values they enter will need to be changed to the
Gregorian. This is dependent on the implementation.
DateTimes are represented as a combination of the Gregorian date and time values, for example:
2003-11-12T18:20:00+01:00 would refer to the Year 2003, Month 11, Day 12 T for Time Hours 18 Minutes
20 Seconds 0, time zone Central European Time, +1 from GMT.
Aside from this there are in the context of user interaction with forms two commonly important
classifications of dates, these being dates that occur before or on the date of data entry, and dates that occur
after the date of data entry. For example it would be assumed that a date of payment being required should
come some time after the date of the document requesting the payment. There are of course aside from this
all sorts of other date relations that are important, for example the relations of order dates to invoice dates.
Currencies: Currencies can be divided into two parts, there is the definition of what currency is used, which
is defined via a List, and the currency amount. A currency amount is of course especially meaningful in a
business document. For the purposes of the input it shall be assumed that users are only dealing with one
currency throughout the document.
.
FORM LOGIC Gates
In the definition of Relevant areas of a form, relevance can be defined by entry of data into
form fields which will map to output elements, but it can also be mapped to entry of data into form fields that
will not map to output elements. These elements function as logic gates, allowing one to turn on/turn off
various parts of the form dependent on user input.
List of Logic gates:
1. In UBL there are various informational items that can be represented either on the header
level or on the line level, overriding the header level. A user may want to fill out all line
elements, and not fill out the header, thus the form should provide for the user being able to
switch off the header level form fields and require the line level form fields be filled out.
Static Form Regions and Fields
In a form input for a smaller organization certain form fields and regions will not need to be filled out in
every form, but rather the information should be stored as static xml content and merged into the output
document. An obvious such region would be the part mapping to the CreditorSupplierParty of an Invoice
document.
Each document has particular elements that it might make more sense than others to have statically stored
and to merge at the point of document generation time, these sections represented per document type are as
follows:
INVOICE
CREDITORNOTE
ORDER
Dates
Calculations Required:
Currencies
For each Message Type in UBL there are certain elements that have a currency data-type that will be
relevant for processing of the message, each of these elements can be referred to by a shorter name: these
are, by message type:
Invoice:
Xpath: /in:Invoice/cac:TaxTotal/cbc:TotalTaxAmount
Shorter name: InvoiceTotalTax
Xpath: /in:Invoice/cac:LegalTotal/cbc:LineExtensionTotalAmount
Shorter Name: InvoiceLineTotal
Xpath: /in:Invoice/cac:LegalTotal/cbc:TaxInclusiveTotalAmount
Shorter Name: InvoiceTaxAndTotal
Xpath: /in:Invoice/cac:InvoiceLine/cbc:LineExtensionAmount
Shorter Name: InvoiceLineAmount
Xpath: /in:Invoice/cac:InvoiceLine/cac:LineItem/cac:BasePrice/cbc:PriceAmount
Shorter Name: InvoiceBasePrice
Order:
Xpath: /po:Order/cbc:LineExtensionTotalAmount
Shorter Name: OrderLineTotal
Xpath: /po:Order/cac:OrderLine/cac:LineItem/cbc:LineExtensionAmount
Shorter Name: OrderLineAmount
Xpath: /po:Order/cac:OrderLine/cac:LineItem/cac:BasePrice/cbc:PriceAmount
Shorter Name: OrderBasePrice
Calculations Required:
An implementation may, for usability purposes, need to allow users to make human readable currency
amounts (for example in Danish currency amounts as an human readable output 1,500.05 would be written
as 1.500,05 while as a decimal in XML Schema it would be represented as 1500.05). An application for a
human entering currency amounts should probably, in order to minimize errors, allow the human to enter the
amount of the currency in the way they are accustomed to representing currencies in their normal cultural
context, and convert the amount to the properly formatted XML Schema amount.
Aside from this there are of the course the calculation model of a document. For example a hypothetical
calculation model for an order might be that the total amount paid must equal the total of all lines of the
order, multiplied by the tax rate (the actual calculation model for an UBL Order is somewhat more
complicated than this.)
A UBL document declares these amounts, when receiving a document the calculation should determine if
any individually declared amount matches the other declarations, but when generating the document Rules
should be used to calculate the values of fields without user inputs. In the example stated above it would not
be necessary for a user to enter the total cost, because that total cost should be calculated from the other
values the user has entered.
The Calculation model for an Invoice is thus:
(BasePrice * (InvoiceQuantity div BaseQuantity))