1. Overview

Crane Softwrights Ltd. is usually contracted on an hourly basis to fulfill a customer’s needs including specifying and performing the work customized to the customer’s requirements.

Certain tasks, however, are well-defined and subject to such little variation that Crane can offer to provide popular such services for a fixed number of hours at our short-term consulting hourly rate. If you wish to know more of our hourly rates, please contact Ken at gkholman@CraneSoftwrights.com for access to the private password-protected rate sheet.

2. UBL CCTS subset validation artefact creation

The UBL document model based on the Core Components Technical Specification (CCTS) Version 2.01 is very large. UBL 2.1 - ISO/IEC 19845 has 65 Document ABIES, 293 Library ABIEs, 2242 BBIEs and 1577 ASBIEs. These can all be seen in the 66 worksheets of the UBL committee’s Google spreadsheet.

The tools used by the UBL committee to create XSD schema and CVA code list validation artefacts for distribution are freely available to be used by anyone. These tools, written and published by Crane Softwrights Ltd., also support creating subset XSD schemas. The committee process and subset process are outlined here. Anyone is welcome to download and use the tools to create their own subset schemas, as the invocation arguments for each tool are documented. Training in these tools is part of the afternoon hands-on full-day version of Practical Universal Business Language Deployment.

Subset schemas are important to users of software that does not have the capacity to accommodate the very large UBL 2.1 models. By trimming down the XSD expression of only that subset of the large common library that is used by the document type, some software will work more quickly or even will work at all.

It is a general rule of thumb to validate a UBL document with the complete UBL XSD schemas, in order to confirm conformance to the OASIS Standard. Generating a UBL document from a software tool, however, rarely (if ever) requires the complete XSD. It is more typical to engage tools with the subset of UBL known to be created by the tool.

A typical data flow, then, would have the sender use the subset schema to generate a UBL instance to be sent, validate that instance with the complete schema before sending to a recipient, and then the recipient would use the complete schema to confirm the information is correctly structured.

2.1. Generating validation artefacts service

Crane offers a commercial service of using its own free tools to generate the XSD, CVA and HTML expressions of a customer’s customized UBL subset. The customer works with their copies of the committee’s Google spreadsheet to express their needs. The customer then mocks up one (or more) example XML instances they are expecting the subset to validate, validates them according to the committee schemas, and forwards them to Crane.

When the customer is ready, they ask Crane to produce the artefacts and we create a ZIP of the HTML reports, XSD files, CVA files (if required), customer example XML instances and XSD validation software demonstrating the examples being validated with the XSD files.

The initial setup and production of the first set of artefacts incurs a charge of 3 hours of consulting.

Each subsequent request for a new set of artefacts incurs a charge of 1 hour of consulting. This is requested after the customer has finished modifying the shared Google spreadsheet that has the revised cardinalities of the subset. On its best effort (in light of travel and training obligations) Crane will download the spreadsheet, run the process and deliver a revised ZIP of validation artefacts as quickly as practical. If the stars align and Crane resources are immediately available when the request is received, the artefacts may be returned completed within the hour.

When considering the costs, consider the experience of one user running the same subset creation tools themselves on their Windows10 computer with 4Gb of memory. For them each run of the process takes over seven hours of dedicated time to create the artefacts before they can be tested.

2.2. Leading up to the spreadsheet preparation

There are a number of steps left up to the customer in order to prepare their spreadsheet information for Crane to engage the service of generating validation artefacts:

• documenting the overall objectives of the information exchange and the roles of the parties involved
• documenting the exchange choreography between parties (e.g. by swim-lane diagrams)
• documenting the information bundles that participate in each exchange of the overall process
• documenting which UBL documents and BIEs satisfy the members of the information bundles
• documenting which documents and members of the information bundles need to be expressed as new
• expressing in spreadsheets the cardinality of BIEs as a subset of UBL documents or as new documents

Should the customer need assistance in any of these spreadsheet preparation tasks, Crane can be contracted on an hourly basis according to the normal terms and conditions of hourly service. Additionally, Crane can be hired as a facilitator to walk through the spreadsheet preparation process advising on appropriate rules of structuring CCTS content. The caveat with facilitation, however, is that the customer cannot expect Crane to be fully conversant with the subject matter, only with the CCTS expression of information, and so the responsibility of the integrity of the semantic information is still with the customer. Crane will produce the validation artefacts according to the semantic information described by the customer.

2.3. Spreadsheet preparation

Users have the responsibility to express in a copy of the UBL spreadsheet which members of the documents and libraries participate in the subset and which others are to be omitted from the spreadsheet. Concepts of the UN/CEFACT Core Components Technical Specification V2.01 as described in the Business Document Naming and Design Rules Version 1.0 are used in the spreadsheet, such as BIE (Business Information Entity), ABIE (Aggregate Business Information Entity), ASBIE (Association Business Information Entity) and BBIE (Basic Business Information Entity). Participation is indicated by specifying the new cardinality of a ASBIE or BBIE in place of the original cardinality for that BIE.

The user must decide first on one of two editing conventions for the rows of the subset column of the spreadsheet: is a cell that is empty to be regarded as omitting the row from the subset, or preserving the row for the subset? If the subset is a small portion of the whole, then the user should regard the empty cells as being omitted and make the effort to indicate the minimum suite of BIEs for each ABIE. If the subset is a large portion of the whole, then the user should regard the empty cells as being preserved and only make the effort to indicate which cardinality values are different. Alternatively to both approaches, the user could simply copy the entire column of existing cardinality values over as the initial subset cardinality values and then make changes, but this makes the changes harder to find or see in quick review.

More advanced users may be creating new spreadsheets from scratch to augment the UBL document suite with their own documents using their own common library in conjunction with the UBL common library. This can be done by starting with the empty Google spreadsheet for CCTS model specification and creating tabs as necessary, perhaps copying tabs from the UBL spreadsheet as a starting point.