CAM and UBL Implementers' Package Release: freeb-ubl

SourceForge freeb-ubl Project Announces Release of Version 1.0 Software

2007-01-30.

Project administrators from the SourceForge freeb-ubl project have announced the first release of software (Version 1.0) supporting the UBL, ebXML, and CAM specifications. The software is freely available for download and use under the freebXML License Version 2.0:

http://downloads.sourceforge.net/freeb-ubl/freeb-ubl-kit-v1-0.zip

The 'freeb-ubl' project is a new royalty-free, open source project from the freebXML Software Foundation.

'freeb-ubl' is published as an opensource implementers' package for UBL and ebXML. It provides royalty-free, out-of-the-box tools to aid with use of the Universal Business Language (UBL) and the standard framework for electronic business with XML, ebXML. The package is intended to grow over time but this version provides:

stylesheets for transforming UBL 1.0 Small Business Subset (SBS) compliant instances (electronic invoices, orders and the like) to their UBL 2.0 equivalents
CAM templates samples for contextual content validation and subset business rules (for illustration)
XForms for simple input, editing and viewing with an XForms reader of various UBL and ebXML-BP documents (Note: this version focuses on the UBL procurement documents)
generator (XSLT) to allow self-build creation of XForms additional to those ready-made (can be combined with jCAM engine)
UBL 1.0 and UBL 2.0 customizations (subsets) for general use with schema files provided (procurement documents) and matching CAM templates
atomic, modular ebXML Business Process (ebXML-BP 2.0) definitions for these documents

About freeb-ubl

Free opensource software for the Universal Business Language and the ebXML framework including XSLT stylesheets to generate XForms for creating, editing and viewing UBL and ebXML documents.

Contact

Stephen Green <stephengreenubl@gmail.com>
David RR Webber <david@drrw.info>
Farrukh Najmi <farrukh@wellfleetsoftware.com>

References

Release Notes 1.0

Implementers' Kit For UBL ('freeb-ubl')
Source: http://sourceforge.net/project/shownotes.php?group_id=186271&release_id=482510

Project Owner: The freebXML Software Foundation
Package Version: 1.0
Creation Date: 2007-01-17
Latest Update: 2007-01-29
Originator:  Stephen Green, SystML 
Authors: Stephen Green, David R.R. Webber

Legal Notices

 Copyright 2006-2007 The freebXML Foundation 
 
 Licensed under the freebXML License, Version 2.0 (the "License"); 
 you may not use this file except in compliance with the License. 
 You may obtain a copy of the License at 
  
 	http://www.freebXML.org/licenses/LICENSE-2.0 
  
 Unless required by applicable law or agreed to in writing, software 
 distributed under the License is distributed on an "AS IS" BASIS, 
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 See the License for the specific language governing permissions and 
 limitations under the License.

 Copyright (c) SystML, 2006-2007, All Rights Reserved.

* stylesheets for transforming UBL 1.0 Small Business Subset (SBS) compliant 
  instances (electronic invoices, orders and the like) to their UBL 2.0 
  equivalents 
* CAM templates samples for contextual content validation and subset business
  rules (for illustration)
* XForms for simple input, editing and viewing with an XForms reader of various 
  UBL and ebXML-BP documents (Note: this version focuses on the UBL procurement 
  documents)
* generator (XSLT) to allow self-build creation of XForms additional to those 
  ready-made (can be combined with jCAM engine)
* UBL 1.0 and UBL 2.0 customizations (subsets) for general use with schema 
  files provided (procurement documents) and matching CAM templates
* atomic, modular ebXML Business Process (ebXML-BP 2.0) definitions for 
  these documents

Glossary

XML - extensible markup language, a standard format for many kinds of machine processible data, content and publication, widely favoured since 2000

XSLT - extensible stylesheet transformation language, a standard for transforming to and from XML and between formats of XML, widely favoured since 2000

HTML - markup language used for content presentation, particularly for the Worldwide Web

XHTML - revision of HTML to comply with requirements of XML and XML processors

XForms - revision of forms provisions of HTML to allow particularly for XML input and output, typically but not exclusively used together with XHTML

CSS - cascading stylesheets, used to guide content processors in their presentation of HTML, XHTML, XForms, etc

UBL - Universal Business Language, a set of standards for XML commonly used business documents (invoices, orders, waybills, etc)

ebXML - electronic business using XML, a set of modules providing a standard framework for the provision of electronic business solutions using XML, standardised as ISO 15000

XForms Kit (v1.0) (subdirectory 'XForms/')

Provided is a set of XForms for UBL and ebXML and a set of XSLT stylesheets which can be used to generate the XForms. They are specifically designed for the UBL and ebXML business document types but they may or may not work with other XML models depending on the schema design conventions used in the XML. XForms typically allow input of data and output of XML either in a suitably enabled browser or other devices. This version is provided as a starting point which may be adapted for production use.

The XForms-generating stylesheets cater for repeatable elements by generating these for elements which have successive multiple occurances in the XML fed to the XSLT stylesheet. This means that instances fed to the stylesheet in a transformation (with an XSLT processor) may be tailored to match the XForms requirements.

The following are types of such tailored XForms which come ready made with this package (others can be generated with different editing of the XML and XSLT as required, though this requires some knowledge of these technologies).

'New-Standalone.xhtml' This form initialises using an internal instance copied from the transformation template and outputs to an external file (using HTTP Put). The CSS stylesheet is internal in the form. The initialization instance is copied in from a separate file as it is better if it doesn't include the repeated elements needed in the main transformation instance.

'Edit.xhtml' This form takes for initial values the output file from the 'New-' forms and writes output to the same file, effectively editing the content.

'Viewer-Verbose.xhtml' This form presents a view of the output file from the other forms and, to provide full support for the subset, is generated a template file with all elements and attributes present and two or more of every repeatable element (named 'TemplateVerbose.xml' in this package).

Ready built XSLT transformation stylesheets are provided in directory 'XForms/XFormsGenerators/'. A large part of the stylesheet functionality is common to the various types of XForms and is the same irrespective of the XML being processed (except for mixed content). This has been separated into a common set of importable stylesheets - placed in subdirectory 'common/'. These two broader types of common stylesheet are one for output (read only) and one for input (with input xforms controls for creating and updating XML). These are imported into the other stylesheets as required. Several varieties of stylesheets which import one or more of these common stylesheets are where namespaces and other details are made specific to the type of XForms and the XML format as required.

Suggested Methodology

* Step 1 : Create or generate sample instances a) with two occurances for every element of multiple occurance and b) with sample content - one with attributes (TemplateVerbose.xml) and one without (Template.xml). (Suggestion: a combination of fairly powerful text editor and a specialist XML editor may prove useful here and in all the following steps.)

* Step 2 : Create or generate sample instances with a) one occurance for every element of single or multiple occurance and b) with sample content - one with attributes (InitialVerbose.xml) and one without (Initial.xml). There may be further editing necessary to provide for usability requirements.

* Step 3 : Remove the content values from the instances from Step 2, except where the schema requires values, editing the latter values to what is deemed appropriate for the initialization values to be displayed in the XForms (although these can be modified in Step 7).

* Step 4 : Edit XForms-generating stylesheets to the appropriate namespaces and edit other values where necessary.

* Step 5 : Generate XForms using the appropriate XForms-generating stylesheets with the appropriate template instances (TemplateVerbose.xml or Template.xml - see various XForms descriptions above).

* Step 6 : Test resulting XForms with an XForms processor (such as an appropriate browser with an plug-in or extension where necessary).

* Step 7 : It is expected that in most cases the resulting XForms (and those ready-made XForms included here) should just be taken as a starting point for further development rather than their being used as- is. However, this could be weighed against advantages which may be found in being able to regenerate XForms by this method when a customization or version change is made to the schemata so an alternative to refinement of the XForms might be to refine the stylesheets which generate them to avoid having to repeat Step 7. Another option might be to create further stylesheets (or other mechanism) to automate Step 7. A combination of these is anticipated for the further development of this resource and its implementations. (Suggestion: a book on XForms may prove useful here.)

For example it may be necessary to add selection of code values for codelists and better validation to improve the use of these XForms. Other features abound in the XForms standard to improve these forms - features such as allowing a switch between localized versions of control labels and business rules and the keeping of label values in external files, referenced by urls. Advantage might be taken of such potential in future work on this project as well as by individual implementations. Essential to further development would be to provide a mechanism for suppressing any optional elements and attributes without data from being included in the output and for allowing the person inputting data to remove optional data completely from the output instance. There should be no empty elements in the final document and there may be business reasons for not allowing default values in most cases.

Schemata (subdirectory 'Schemata/')

Customizations (v1.0)

Two customizations of UBL which are used as the basis for the XForms in this package are provided here, one for UBL 1.0 and one for UBL 2.0. These follow the same principles as UBL 1.0 Small Business Subset 1.0 (http://docs.oasis-open.org/ubl/cs-UBL-1.0-SBS-1.0).

Schemata/UBL1-0/SystML1/

This set of files defines a customization (subset) of UBL 1.0, applying formally defined constraints to allow use of UBL in an implementation such as can be achieved with these relatively simple XForms and with software capable of reading the UBL documents so produced. These must all be regarded as secondary to the original UBL 2.0 standard schemata in validations. The copyright of the original schemata belongs to the OASIS organization (http://www.oasis-open.org).

Schemata/UBL2-0/SystML2/

This set of files defines a customization (subset) of UBL 2.0, along the same lines as systml1, above. It is regarded as secondary to the original UBL 2.0 standard schemata in validations. The copyright of the original schemata belongs solely to the OASIS organization (http://www.oasis-open.org).

Use of the above customizations must be in accordance with the UBL 1.0 Small Business Subset cs-UBL-1.0-SBS-1.0 which state:

"2.1 Normative Business Rules - Unless otherwise specified in a trading partner agreement, the default use of a UBL 1.0 Small Business Subset MUST be in accordance with the following two business rules:

2.1.1 UBL 1.0 SBS Business Rule 1. Parties sending UBL documents to parties specified as receivers of a UBL 1.0 Small Business Subset (SBS) document or documents SHOULD NOT require the same receiving party to process any part of the UBL document which is external to the specified SBS.

This does not mean that business data external to the subset cannot be included in a message. It does mean that business data external to the subset MAY be ignored by the party receiving the document.

2.1.2 UBL 1.0 SBS Business Rule 2. Parties specified as receivers of a UBL 1.0 Small Business Subset (SBS) document or documents SHOULD ensure that their systems appropriately process at least every document part that is specified in the SBS.

Extensions to these default rules MAY be made and specified in trading partner agreements. For example it might be that in a particular collaboration certain business components should be processed in addition to those identified in the SBS."

In practise this means that applications which fulfill the role of receiving UBL messages in a process requiring compliance with this customization should cater for every element and attribute in the above Schemata unless there is reason not to, to avoid there being information sent in these which is overlooked. There is on the other hand no requirement to cater for information in other elements and attributes and applications of the sending role need to be cautious in this regard.

Schemata/ebxml-bp/

These are version 2.0.4 (OASIS Standard) schema files for ebXML-BP with minor modification of the url for the imported xml.xsd schema which is local in the same directory. The copyright of the original schemata belongs solely to the OASIS organization (http://www.oasis-open.org).

UBL Version Transformations (subdirectory 'VersionToVersion/')

'UBL1SBStoUBL2' (v1.0)

This is a set of XSLT stylesheets to convert instances between UBL 1.0 SBS and UBL 2.0. SBS is the UBL Small Business Subset, a customization of UBL for general use. It is similar to and a precursor to the subsets included with this release, SystML1 and SystML2. Use SystML1 can be said to compliant with the UBL 1.0 SBS committee specification if the documents sent with it to another party do not require that more than the elements in the SBS be properly processed by the receiving system.

Please note that although the syntax is converted between UBL 1 and UBL 2 with these transformations, values are not converted and some which were valid in UBL 1.0 might not be valid in UBL 2.0. In particular indicator values and certain code values are more constrained in UBL 2.0 than in UBL 1.0. Indicators in UBL 1.0 allow values 'true'/'false' or '1'/'0' while in UBL 2 only 'true' and 'false' are allowed. Units of measure attributes in UBL 1.0 are not constrained as a codelist by the schema but there is constraint with a schema codelist of the units of measure attributes of UBL 2. Quantity and Measure have a units of measure using this codelist in UBL 2.

Business Process Profiles (subdirectory 'Profiles/')

There are profiles for ready-to-use business processes related to the UBL documents provided as a set of ebXML Business Process Specification (2.0) definition instances. The universally unique identifiers (uuid attribute in the top element) they contain may be used as value for the ProfileID element in a UBL 2 instance (with UBLVersionID set to the version of UBL, e.g., '2.0' for UBL 2.0 or the SystML2 customization and the CustomizationID set, for SystML2, to the identifier in the SystML2 customization schema). Also, when used with ebXML message handlers which use ebXML CPPA (collaboration Protocol Profiles and Agreements), the uuid attribute value can be used in a CPP and/or CPA instance to enable proper processing of the UBL message. For example, the profile identifier provided for the UBL 2 SystML 2 invoice being sent as a notification is 'www-systml-co-uk-xml-profiles-ubl-2- systml2-invoice- notification' and this is found in the profile file 'ubl-2-systml2- invoice-notification.xml'. The value for UBLVersionID in a UBL 2.0, customization 'SystML2' Invoice sent according to this process profile will be '2.0'. The customization identifier, found in the SystML2 schema (<!-- id="... at the top of the schema) of the Invoice is "www- systml-co-uk-xml-systml2-maindoc-Invoice-2" and this is the value to be used as the content of the UBL 2 CustomizationID. The profiles are atomic and can be further combined into more complex definitions where appropriate using XInclude references.

Sample Collaboration Protocol Agreements (subdirectory 'Agreements/')

Here are provided sample agreement files for trading partner collaborations which conform to the ebXML standard CPPA 2.0a. The files are samples corresponding to the above business process definitions which can be modified to include appropriate trading partner party names and details and electronic certificates. The examples depict, as providing necessary placeholders, collaborations using the real business processes between ficticious trading partners 'Coronation' and 'Gnaraloo'. One way to use these instances might be to merely substitute proper values, certificates, endpoints, etc for the ficticious placeholders for the appropriate business processes and business documents for the trading partner collaboration concerned. A set of forms, say, could be designed to facilitate this and output proper collaboration protocol agreements (CPAs) for storage as required. Likewise it should be possible to either use these CPAs with ebXML compliant messaging handling systems or use transformations or other software to create message headers for transporting the UBL documents such as those conforming to the ebXML Messaging Services standard (ebMS). Some means may then need to be provided for directing a message handler in how to match the UBL document to a corresponding CPA and then determine how and where to send the document as a message. Special regard also needs to be given to the need for response signals.

For a fuller understanding of the UBL documents and the ebXML processes there are specifications and other documents available on the OASIS website http://www.oasis-open.org.

Content Assembly Mechanism (CAM) Templates (subdirectory 'CAM/')

PLEASE NOTE: These files are for illustration and not intended for actual use as provided

Introduction

The CAM templates here are for use together with the jCAM toolset to perform business rule validation of UBL documents and optionally transform them also. You can produce user documentation pages of the rules and structure items that apply to the UBL XML transactions.

The CAM toolset consists of two components - the CAM development editor, and the jCAM deployment engine. The development editor allows you to run and test the supplied UBL CAM templates interactively on your desktop system. Instructions are provided next below for this.

Installation/Getting Started

* download the zipped CAM Editor from sourceForge.net - this can be found by 
  navigating to http://jcam.org.uk/ then selecting Download from the menu and 
  following the link to the sourceForge site for the jCAM project. You will see 
  the editor resource link there.
* ensure Jave JRE 5.0 is installed on the machine which will run the editor 
  (available from http://java.sun.com )
* unzip the CAM Editor to a suitable folder location (such as c:\jCAM\ )
* Inside the CAMed directory this creates, run the Editor, by clicking on the 
  icon for the CAMed.exe file itself.
* in the running editor select menu items 'File' then 'Open' and select one of 
  the CAM templates from this UBL package, (such as the Order subset)
* from the 'Run' menu select 'Run CAM'
* select when prompted a UBL XML instance of the same document type as the 
  template (such as Order subset or Order sparse example)
* click 'Finish'
* view results displayed by the editor user interface

Editing and Developing

Once you have a base template working, you can review the rules and extend these as needed. There are screencast tutorial resources available from http://www.jcam.org to assis you in learining how to use the jCAM development editor. You can make changes and run and test them interactively in the editor. You can also read more about the CAM specification from the OASIS TC site, and access presentation materials describing use case there as well.

CAM Engine Deployment Notes

The jCAM package is currently found on the same sourceForge project as the editor and contains an API ofr use with Java and standalone jCAM engine for integration use. After completing your CAM templates you can deploy then using the jCAM engine.

CAM standard and specification

CAM, the XML language for specifying content constraints for specific contexts, is currently a committee approved specification in OASIS (see http://www.oasis-open.org/committees/cam/). Tutorials are available on the http://jcam.org.uk/ website.

Summary and Role

CAM is designed to allow for the types of contextual constraints required in business to business collaborations such as with UBL, that are not currently catered for in W3C XML Schema UBL structure definitions alone. Exmples are included in this package with particular regard to the requirements for subsetting of UBL. Each industry has its own rules and definitions and the CAM toolset is designed to allow these rules to be overlaid on the base UBL foundation structures and formally shared across the community of users and partners systems.

Prepared by Robin Cover for The XML Cover Pages archive. See also "Universal Business Language (UBL)."