Re: [ubl-dev] UBL Newbie -- invoices

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

At 2006-01-14 15:50 +0100, Manuzhai wrote:
>I am a small business owner from the Netherlands. I am in the web
>development business (mostly selling services instead of products --
>I'll get back to that), and I like (XML) standards, so I decided that
>I wanted to rewrite my *very* simple invoicing system to produce UBL
>Invoices and render them to PDF and/or XHTML.

There are freely downloadable stylesheets for producing PDF and HTML 
... just follow the "Free resources" hyperlink at the right edge of 
our home page linked in my trailer below.

>In doing this, I've got
>some questions, though, and as I haven't been able to find much
>documentation about using the format, I decided to ask my questions on
>this list. Consider these newbie implementation questions.

You've found the right place to ask!  I can answer some questions, 
and others can address the other questions or disagree with mine.

>1. Is there an easy-to-read list of available elements that I can use
>in cac:Party, or maybe in cac:Party/cac:Address? In addition to the
>default elements listed in the example documents in the UBL package, I
>already found cbc:Telephone and cbc:ElectronicMail. Should these be
>put into cac:Address, or one level up in cac:Party?

This kind of information can be found from the schemas, but W3C 
Schema expressions (for any model) are notoriously difficult to 
read.  One available resource that may help you find such things is 
the list of valid XPath addresses for the information items described 
by the W3C Schema expressions:

   http://lists.oasis-open.org/archives/ubl/200410/msg00002.html

In there you will find complete enumerations of the information items 
possible in a UBL instance, indicated by their respective XPath address.

>Also, in the
>Netherlands it is required to put a VAT number and a Chamber of
>Commerce ID for the seller in the invoice.

I'll let someone else address this as I don't know if you can use an 
existing information item or if you will need to add a new 
information item.  I'm curious myself.

>Finally, I would like to
>advertise my website on the invoices. Is there a default element I can
>use for this? I've looked through the .xsd's for cac and cbc, but I
>wasn't able to find any elements.

I see this (and saw this when I wrote the stylesheets available on 
our web site) as a presentation issue and not an information 
issue.  Thus, I see this as an issue of the way the information is 
presented to users, not in the way information is coded for users.

Looking at the sample PDF files in the stylesheet delivery, look at 
the vertically-oriented text starting at the bottom left of the 
page.  Hover over this and you'll see that it is hyperlinked, such 
that clicking on it opens a web screen.  Not only can you add your 
web site to the invoice but XSL-FO allows you to hyperlink it in the 
PDF file for your users.

So, I think you should not put such information in an element.  If 
you want it actually *in* the instance, then the correct construct 
would be an XML comment, as this is the kind of an annotation to use 
for the human reader (the other kind of XML annotation, the 
processing instruction, is targeted to an application acting on the XML).

>2. Since I may have multiple projects for one client, is there a way I
>can reference the project the current invoice is concerned with? I
>used to display this with the BuyerParty information, but I'm not sure
>where to put it now (or how I can describe it).

I'll defer to the business subject matter experts (I'm just an XML 
geek) but my guess would be to use the generic cbc:Note element to 
carry supplemental information such as this.

>3. What are options for the cbc:InvoicedQuantity/@quantityUnitCode?
>The example uses PKG; since I'm often talking about hours of
>development, I have a few examples of 1.5 hours and I'm not sure
>whether this is a valid use for this element.

Ahhhhhhhhh ... code lists ... another religious topic ... looking at 
the XSD declaration of @quantityUnitCode you'll see that there is no 
specification of a value to use.  You get to make up your own!  But, 
that doesn't sound very portable, does it?  So, when two trading 
partners need to agree on codes to use where codes are not specified, 
they need a formal way of declaring the codes upon which they agree, 
and the places where they can be used.  The UBL team is reviewing a 
candidate OASIS standard to do this, and comments from UBL-Dev 
members are *most* welcome:

   http://www.oasis-open.org/archives/ubl-dev/200512/msg00034.html

For now, make up your own code and I think you are going to have to 
pull something out of the air on your own.  I think XSD durations are 
inappropriate as the value incorporates the units of measure, though 
there are cases where this can be useful.  So are iCal 
http://www.ietf.org/rfc/rfc2445.txt durations.  Given that UBL uses 
CCTS which uses only a decimal value and a single coded unit of 
measure, I'm not sure which you could use, but probably just "H" and 
a value of 1.5 would do.

If the CCTS had allowed a string value and a coded unit of measure, 
then one could have used the encoded string as the value and the unit 
of measure as  "xsd:duration" or "ical".  But, we are committed to 
using CCTS so this is not available.  And, from what I can tell, 
neither system allows for decimal points in the values so I'm not 
sure how you would say "P1.5H" in either specification other than 
"P1H30M".  But that's moot since CCTS doesn't allow such a string value.

>4. In the InvoiceLines, Tax:Scheme/cac:TaxTypeCode is used. What are
>valid values for this? Should I use my national translation for VAT,
>"BTW", or stick to VAT? What are good values for cac:ID in
>cac:TaxCategory.

Same answer as above, though in this case the value is a normalized 
string and not a decimal number.  UBL does not provide for values, so 
you get to pick your own.  Two trading partners can agree on picks by 
formalizing a declaration of allowed values for the given context.

>5. In cac:PaymentTerms/cac:ReferenceEventCode, what are valid values,
>and what does the "!" value used in the examples mean?

Same answer once again ... no prescribed values according to the XSD 
expressions.

BTW, which example has an exclamation mark for such a value?

>Now, all of this might be documented somewhere, but I wasn't able to
>find it in the standard package and a quick Google search didn't
>reveal many other resources. Any pointers to more human-readable docs
>are appreciated.

Works are in progress ... stay tuned ...

>All in all, this seems a very nice, workable standard
>(even for the non-standard use I'm putting it to).

Who is to say what you're doing is non-standard?  This is wonderful 
to see you trying to apply the standard to your own situation.

Please keep us all informed of your progress ... good luck!

I hope this helps.

. . . . . . . . . . . . Ken

--
Upcoming XSLT/XSL-FO hands-on courses:  Denver,CO March 13-17,2006
World-wide on-site corporate, govt. & user group XML/XSL training.
G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/u/
Box 266, Kars, Ontario CANADA K0A-2E0    +1(613)489-0999 (F:-0995)
Male Cancer Awareness Aug'05  http://www.CraneSoftwrights.com/u/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal