Crane's OASIS UBL customization in OpenOffice 3

This web-site copy of the readme.html file is posted to provide information regarding the scope and use of this software.

1. Introduction

This environment supports the customization of subsets of OASIS [OASIS] Universal Business Language (UBL) 2.0 [UBL 2.0] schemas using OpenOffice 3 [OOo]. The complete specification is maintained by the OASIS Universal Business Language Technical Committee [UBLTC]. The environment is delivered as two Open Office XML filter packages.

Installing these two packages as XML Filters in OpenOffice 3 enables the user to specify subsets of the UBL 2.0 specification and create developer resources reflecting the specified subset. These resources include human-readable HTML reports, XSD schemas, XSLT and Python filter programs and XML support documents.

The primary file format for storage of profile specifications is a standard Open Document Spreadsheet file, created by the supplied profile customization template. Alternatively, and required for some of the available functionality, an XML vocabulary describing a collection of UBL profiles is included in this package. Such XML documents are termed "Profile XML files" in this guide.

1.1. Restrictions of use

There is no charge for the purchase of this code but the use of this code, unless specifically permitted in writing by Crane Softwrights Ltd., is restricted to bona-fide users of Crane Softwrights Ltd. book: Practical Universal Business Language Deployment [Crane Books].

THE AUTHOR MAKES NO REPRESENTATION ABOUT THE SUITABILITY OF THIS CODE FOR ANY PURPOSE. THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

2. Installation and configuration

The specification in Section 2.3, “Java parameters” need only be done once and need not be refreshed when installing a new version of these filters.

2.1. Uninstalling the installed version of these filters

At this time of writing there are problems sometimes exhibited in OpenOffice 3 when trying to install a new version of one of these filters on top of an old version of the same filter. It is recommended that you first uninstall an old version of the filter before installing a new one. If you choose to simply install the new filter, you will know this is successful if opening a Profile XML file presents the Crane interface. If you attempt to open a Profile XML file and you end up with an empty spreadsheet instead of the Crane interface, this is evidence of the new filter having been corrupted during installation over top of the old filter.

To confirm this is the cause of the problem, inspect the transformation log file configured as described in Section 2.3, “Java parameters” and you should see something along the lines of:

To completely uninstall the filters, start OpenOffice 3 and open a new document or spreadsheet. Click the menu item "Tools" / "XML Filter Settings...", select (for example) the "Profile Filter 1 of 2 by Crane Softwrights Ltd" filter and press the button "Edit...":

Figure 1. Editing the package for deleting the package contents

Select the "Transformation" tab and press the "Browse..." button for the "XSLT for export" selection:

Figure 2. Browsing the export directory

Right click on the stylesheet name and delete the stylesheet (note that if you hold down the shift key this will permanently delete the file rather than sending it to the recycle bin):

Figure 3. Deleting the old filter file

Press the "Cancel" button to return to the Transformation tab and repeat for the "Template for import" entry (note that it is not necessary to do this for the "XSLT for import" entry):

Figure 4. Browsing the template directory

Press the "Cancel" button to return to the "Transformation" tab, and then press "Cancel to return to the "XML Filter Settings" dialogue box. Press the "Delete..." key to delete the filter:

Figure 5. Deleting the package itself

Don’t forget to do the same steps for the second of the two filters, in this example that would be the "Profile Filter 2 of 2 by Crane Softwrights Ltd" filter.

Note at this point it is often true that the filter entries still show in the "XML Filter Settings" dialogue box even though you have requested they be deleted. Pressing "Close" and reopening the dialogue box using the menu item "Tools" / "XML Filter Settings..." will show the list without the deleted entries.

2.2. Installing the two filters

Start OpenOffice 3 and open a new document or spreadsheet. Click the menu item "Tools" / "XML Filter Settings..." to get to the filter dialogue.

Each filter is installed separately using the following procedure (illustrated for the "Profile Filter 1 of 2 by Crane Softwrights Ltd" filter but the same steps are taken for the "Profile Filter 2 of 2 by Crane Softwrights Ltd" filter). Press the button "Open Package..." without regard for any existing filter that may happen to be selected:

Figure 6. XML Filter Settings Dialogue

Navigate to the directory in which you unzipped the distribution file and select Crane-profile2ods-1-of-2.jar (for this example) to add the "Profile Filter 1 of 2 by Crane Softwrights Ltd" filter to your installation and report successful operation:

Figure 7. XML Filter Successful Installation Dialogue

Repeat this "Open Package..." step using Crane-profile2ods-2-of-2.jar for the "Profile Filter 2 of 2 by Crane Softwrights Ltd" filter.

2.3. Java parameters

It is necessary to configure two or three Java parameters before successfully working with the Profile XML formats. To specify these parameters, use "Tools" / "Options..." to get to the "Java Start Parameters" dialogue box:

Figure 8. Specification of Java Parameters

Java parameters for memory options for startup and maximum heap space must be specified (and larger values than the examples below may be used) to override the default values. The default values have proven to be insufficient for the number of sheets and rows in the spreadsheets.

The parameter named "XSLTransformer.statsfile" is useful should there be any import or export problems related to these filters. With each open and close of a Profile XML file the file you specify here will be refreshed with the results of the behind-the-scenes XSLT transformation process log. When problems are encountered, inspecting this log may indicate the nature of the problem you are experiencing. Sending this log to Crane will help greatly in diagnosing what may have happened in the transformation. See Section 9.2, “Memory problems” for an excerpt of the log file.

The summary of parameters would look something like the following, though of course you can use any file name you wish for the log file:

Interestingly, the redundant settings for memory appear to be necessary as not all installations of OpenOffice support all ways of expressing the values. Expressing them both ways appears to work in some versions of OpenOffice. If you continually get "out of Java heap space" errors, try setting the memory values using only one of the two syntaxes, and then the other. If anyone can shed light on why some settings do not work on some installations, please let us know so we can share with others.

The dialogue box will look like this (the order of the parameters is not important):

Figure 9. XML Filter Successful Installation Dialogue

You will need to exit and restart OpenOffice in order to engage the changed values.

Note again that larger values for the memory specifications may be used, but Crane has only tested this environment successfully with the values above, so smaller values should be avoided.

3. Creating a new profile document from scratch

Selecting the menu item "File" / "New" / "Templates and Documents" brings up the "Templates and Documents - Templates" dialogue. Double-click on the "Profile Filter 1 of 2 by Crane Softwrights Ltd" entry to bring up the "Templates and Documents - Profile Filter 1 of 2 by Crane Softwrights Ltd" dialogue. Double-click on the "profileCustomization" entry to bring up a copy of the profile template.

Figure 10. New profile document from scratch

4. Saving and opening the profile document as a spreadsheet file

The typical format to save a profile document is an OpenOffice spreadsheet file with the ".ods" extension, because of the performance of closing and opening such files. The save action takes less than a minute for the spreadsheet file. Opening the spreadsheet file takes less than a minute.

5. The typical customization process

This tool was designed to support a particular approach towards the specification of a subset schema customization. The decision making process of what goes in and what stays out of a subset is independent of using this approach towards codifying the decisions made. Decisions are reflected in the user interface of this environment and then the artefacts that implement the decisions are exported. One can then test those artefacts and consider what other decisions need to be made.

5.1. Overview

In the UBL document model there are many Business Information Entities (BIEs). An aggregate BIE (ABIE) is a container of basic BIE (BBIE) and associate BIE (ASBIE) constructs. A BBIE is an atomic value. An ASBIE is a pointer to an ABIE. Specifying the subset document model involves deciding the customization cardinality of the BBIE and ASBIE constructs in the ABIE constructs.

There are five cardinalities supported for a customization: "1..n" is mandatory and repeatable, "1" is mandatory and not repeatable, "0..n" is optional and repeatable, "0..1" is optional and not repeatable, and "0" is excluded and not used. Which cardinality is available for a customization depends on the original cardinality designed for the construct by the UBL committee: in a customization the minimums can be increased and the maximums can be decreased, but no other changes can be made.

5.2. Initial steps

For collaboration and verification purposes, one typically then only exports the HTML human-readable reports (see Section 7.2, “Human-readable HTML report”) during the initial specification process. The very first step is to select the document types in the profile and to export only the HTML report. This report reveals only those ABIE constructs in play by the selection of document types.

By focusing on only the ABIE constructs in play, one doesn't waste time trying to prune irrelevant constructs. Making the changes to each of the ABIE constructs can be done randomly across the various sheets of the spreadsheet. At any time one can create and review a revised HTML report.

Walking through this HTML report gives one the assurance of the changes reflected in the user interface of the tool showing the pruning decisions that were made. The report will also flag a particular error situation where one has inadvertently specified an empty ABIE that is being referenced somewhere by an in-use ASBIE. Such an error creates an inconsistent and incomplete schema artefact that cannot be used in deployment.

5.3. Final steps

Once one is comfortable with the information exposed by the HTML report, one would then activate the other export artefacts for the exportation process and regenerate the HTML and generate the corresponding XSD schemas, XSLT or Python filters, or any of the XPath reports.

The combination of the profile version and the date and time stamp embedded in each generated file is used to correlate a suite of exported artefacts.

Each OpenOffice spreadsheet file or Profile XML file describes a project with a collection of profiles. Each profile contains one or more document types. Each document type as the BIE constructs needed to represent the information conveyed in a particular set of transactions.

6. The sheets of the profile customization user interface

There are configuration, profile, document type and support sheets when managing a suite of profiles.

6.1. The Configuration sheet

The Configuration sheet directs the dynamic properties of interacting with this environment: control over user interface components and specification of export behaviors:

Figure 11. The Configuration sheet

The "Input schema parent directory" points to the parent directory of the two XSD subdirectories named "/xsd/" and "/xsdrt/". If you have installed UBL 2.0 into a local location, or you use the online OASIS artefacts, then that parent directory is named "/os-UBL-2.0/". In the example above the directory is in the local file system, thus the specification begins with "file:///" (note the three oblique characters), as in "file:///c:/path/to/local/copy/os-UBL-2.0". In the UBLProfiles.xml suite of profiles the directory points to the OASIS web site with "http://docs.oasis-open.org/ubl/os-UBL-2.0/" (note the two oblique characters after the colon). The schema pruning process will fail if the environment cannot locate the two XSD directories.

The "Export version profile suffix" is added to the end of each profile short name when exporting artefacts. Ostensibly, this is for version control as profiles evolve, but unfortunately there is an unresolved issue in OpenOffice 3 that prevents the same set of artefacts being written twice during one execution of OpenOffice. Until this issue is resolved (and it has been reported for OpenOffice 3.1), you can only export a set of artefacts a second time if you restart OpenOffice or if you change this export version profile suffix.

The "Export nature" distinguishes between two kinds of profile customization from the annotations you make in the models. A "permitted" customization includes all constructs both with and without cardinality annotations in the document type sheets. A "strict" customization includes only those constructs with cardinality annotations in the document type sheets. You choose which value to use based on your approach towards customization: use "permitted" to start with the maximum set of constructs and pare down those items you do not want, or use "strict" to start with the minimum set of constructs and build up those items you do want.

The various "base" and "parent" directories are the locations where export artefacts are written. Typically, the same path would be used for all directories, but you have the flexibility to specify different directories. See Section 7, “Exporting the deployment artefacts for a profile” for details on each artefact.

To the right of each of these locations is a checkbox used to indicate which of the artefacts are to be generated during the next exportation process. If none of the boxes are checked, the exportation report will indicate that no artefacts are created.

The next section governs which profiles are exported during the exportation process. Each row reflects one of the profiles specified on the Profiles sheet (see Section 6.2, “The Profiles sheet ”).

To the right of each of these profiles is a checkbox used to indicate which of the profiles are to have their artefacts generated during the next exportation process. If none of the boxes are checked, the exportation report will indicate that no artefacts are created.

For navigation between sheets, the ">" arrows are hyperlinks. Click on the respective arrow to jump directly to the profiles sheet or the document types sheet.

The "Definitions/terms language" radio buttons are used to pick the display language for UBL definitions and alternative business terms. This language is used on the individual document type sheets as well as in the exported artefacts.

In the example above, only the HTML artefacts of only the Complex Procurement profile would be generated and the English language would be used for definitions and alternative business terms.

6.2. The Profiles sheet

The Profiles sheet defines the properties of each profile in the suite of profiles. Each profile is a collection of document types that share the same customizations of the common library of constructs. Consider that there may be for one user community two profiles for procurement: a simple profile that has only an invoice document type, and a complex profile that has both an invoice document type and an order document type. In each profile there may be different definitions for invoice constructs and for common library constructs.

Figure 12. The Profiles sheet

The "<" and ">" arrows are hyperlinks. Click on the respective arrow to jump directly to the configuration sheet or the document types sheet.

The "Indicate column save action" control is used to change the number of profiles in the OpenOffice sheets. There are no macros available to engage this change, so the change must be effected by saving and reloading the Profile XML file representation of the profiles (which does not preserve any entered user meta data). The minimum number of profile columns in a project is three, and you can leave any of them empty.

The "Profile Short Name" value is the only mandatory description field. Be careful to ensure this value starts with a letter and has only letters and numbers, as the environment cannot verify this before trying to use the value. The artefacts are created using this value as a basis for distinguishing one set of files from another set of files.

The "CustomizationID string" and "ProfileID string" values document what user instances should have in the <CustomizationID> and <ProfileID> elements to assert an instance conforms to this particular profile. The ProfileID value should be unique for all profiles, while the CustomizationID value should be the same for all profiles in a given customization. The CustomizationID value can, however, be different when maintaining more than one customization profile collection in a single spreadsheet.

The "Domain" value categories some overarching domain in which the profile has a role. It would make sense to be the same value for all profiles in a project, though this is not obligatory. Consider that both simple and complex procurement might be profiles used within an overarching domain of "Post award procurement".

The "Process" value further categorizes a collection of profiles within the overarching domain. Consider that both simple and complex procurement might be profiles used within an "Ordering - Fulfillment - Billing - Payment" process in the domain, but that transportation documents would be used in a different "Shipping" process within the domain.

The "Title" value is used for documentary purposes and is reflected near the top of all of the generated artefacts.

The "Document reference" value is used within the artefacts to point outside of the artefacts to some supplemental documentation regarding the profile.

The "Description" value is available for documentary purposes and conveys information beyond the title to further help the user understand the purpose of the profile.

The "Commentary" value is available for supplementary documentation purposes. This is not meant to be used for descriptive prose, as the Description value would be more appropriate for that. This is more for development or reminder purposes, keeping notes that are relevant to the task of specifying the profile, but not distinguishing properties of the profile as in the description.

Note how the pale yellow color of the unused column indicates that any values entered in that column will not be relevant until a profile is defined for that column. When using the spreadsheet format for saving profile information, such intermediate work can be saved without losing it. When using the Profile XML format, such intermediate work is lost.

6.3. The Document Types sheet

Figure 13. The Document Types sheet

Using any non-blank value, one indicates which document types are in each profile.

6.4. The individual document type sheets

There is an individual document type sheet for the common library and each of the 31 UBL documents. On these sheets one specifies under each profile's column the new cardinality of the BIE indicated on the row.

Figure 14. The individual document type sheets

The distinction between a "permitted" customization and a "strict" customization governs whether you will be populating the new cardinality cells with values for each row. Recall that a strict customization includes only those BIE items with a specified new cardinality (even when it is the same value as the old cardinality), and that a permitted customization only excludes those BIE items with a specified new cardinality of "0". Your iterative approach is therefore building up a strict customization or paring down a permitted customization. Of course mandatory and non-repeatable items (that is, items with a cardinality of "1") cannot have a different cardinality specified and are in all customizations, so those cells are read-only.

6.4.1. Customizing user meta data

The sheets for each document type are delivered with three columns of user meta data that can be altered in a limited extent to support one's own values associated with each item. Users have found this very useful in tracking their changes, capturing supplemental data, and recording rationale for the decisions made.

These values are only maintained in the spreadsheets and reported in the HTML reports, but are not preserved when exported to XML, nor is the information realized anywhere in any other exported artefacts.

Note

In the current version of this software, user meta data is not preserved when saving and opening the information in the profile XML vocabulary. Be aware of losing your work when you change the number of profiles. You can save the "old" spreadsheet in ODS format and copy the columns to the "new" spreadsheet created from XML to preserve this information.

The user meta data columns are labeled "U1", "U2" and "U3". Alternations can only be made after turning off sheet protection, and sheet protection should be turned back on when done to avoid any inadvertent overwriting of important spreadsheet contents.

6.4.2. Detailed steps with a document type sheet

Using menu "Tools / Protect Document / Sheet..." to unprotect the sheet (there is no password to enter). This will reveal a red warning "SHEET NOT PROTECTED AS RECOMMENDED".

The column headings and widths may be anything you wish, though the HTML browser will make its own determination of column widths when presenting the data.

To add a new column, select any of the existing user columns except for first one and use the right-click menu "Insert / Columns". If you use the first column it will look correct but the style names in the cells will be wrong. The style for the heading cell must be "CraneUserHeading". The upper cell of each pair of stylesheet rows must have the style named either "UserABIE", "UserBBIE" or "UserASBIE", and you are welcome to modify these styles as you wish without changing the base style "CraneUser". These style names are critically important and must not be changed.

Using menu "Tools / Protect Document / Sheet...", protect the sheet (typically without a password). This will then hide the red warning "SHEET NOT PROTECTED AS RECOMMENDED".

The cells in the columns can now be freely edited, and the values will be seen in the HTML reports.

6.5. The Help sheet

Each "??" hyperlink on other pages points to the specific help item on this help sheet. The "<<" back-links on the help sheet jump to the sheet of the item being documented. Note in OpenOffice there is no "go back" when traversing a hyperlink as there is when traversing a hyperlink in HTML browsers or PDF readers.

6.6. The Support sheet

7. Exporting the deployment artefacts for a profile

The export facility is engaged by invoking "File / Export..." and empirically this does not appear to work correctly for a new suite of profiles until the suite of profiles has been saved at least once in either spreadsheet or XML format.

Until a problem is addressed in OpenOffice, you will get errors when you export the deployment artefacts twice for the same profile without restarting OpenOffice or twice without changing the "Export version profile suffix" on the configuration sheet. Hopefully this will be addressed in OpenOffice 3.1. This error is confirmed when the stylesheet log file reads along the lines of the following:

7.1. Primary export log

This is the only file guaranteed to be created is the plain text file you name in the "Export" dialogue box as a "Profile Export Report (.txt)" file. This file is a log of all of the processes engaged during the export process. The following is an abbreviated excerpt of the UBLProfiles.txt file in the "/samples/" directory:

Note how the first section summaries the properties of the project. The remaining sections convey the activity engaged for each of the profiles listed in the summary.

7.2. Human-readable HTML report

Figure 15. Crane's HTML report of a customization

The first section is an alphabetized index of all BIE items, grouped by the first two characters of the UBL name of the BIE, followed by links to the common library and each of the document types in the profile.

The third section only appears in the report when there are ABIE items in the profile where every member of the ABIE is not included in the profile. An ABIE is in the profile when it is pointed to by an ASBIE in the profile, so there are two ways to remove the problem: add one or more items to the ABIE, or remove all ASBIE references to the ABIE.

The fifth section is an alphabetical listing of all BIE items ordered by the UBL name for each item. The hyperlinked numbers take you to the corresponding row in the tabular section of the HTML page. The hyperlinked UBL names take you to the corresponding definition within the summary section. Note the summary section does not have any UBL BIE items that are not included in the profile.

The remaining sections are the tabular reports of information associated with each BIE item. Note the tables section does not have any table for any UBL documents that are not included in the profile. Each table that is presented does not have any UBL BIE items that are not included in the profile. The hyperlinked numbers take you to the corresponding definition within the summary section. The hyperlinked UBL names take you to the corresponding definition within the tabular section.

The rule of thumb is that hyperlinked numbers change the presentation between summary and tabular forms, while hyperlinked UBL names keep the presentation within the respective summary and tabular forms.

On review if you need to make any changes to the profile, these changes are reflected in the individual document type sheets and the export process is triggered again to recreate the artefacts for review. Remember again that a temporary problem with OpenOffice requires you to either restart OpenOffice or change the "Export profile version suffix" on the configuration sheet before attempting to recreate the results.

7.3. XSD schema pruning

A pruned XSD schema is a processed copy of a published UBL schema fragment where your choices of customization within a profile are reflected inside the processed results. This approach promoted by Crane Softwrights Ltd. preserves in the customization schema fragment the original OASIS schema fragment content, so that users can be assured the customization is properly reflected in the revised declarations. By inspecting the declarations, one can see which were removed and which were modified and how they were modified.

Where a profile is removing a BIE, the declaration and use of the BIE is preserved inside of an XML comment annotation in the pruned result. An XSD processor does not inspect comments for any information, thus ignoring the original UBL information being commented out. The comments remain, however, to give the human reader the bread crumbs tracking down what was in UBL before being pruned by the process. Any and all comments can be removed from a schema fragment, however, when distributing the schema fragment the copyright comments of both Crane and OASIS must be preserved.

An ABIE definition in error, that is it has no child constructs, will reliably produce a schema fragment with the ABIE declaration absent. Such a schema is incomplete and inconsistent and will not be processed by any conforming XSD schema validation tool. This ensures the schema will not be inadvertently used when instances of such a schema would be invalid according to the normative document constraints for UBL 2.0. Review the HTML report for all ABIE definitions in error, as these are prominently flagged at the beginning of the report.

Having created the schema fragments, these are overlaid on top of a copy of the xsd/ and/or xsdrt/ subdirectories from the UBL 2.0 package. Figure 16, “The overlaying of customization schema fragments” depicts how only the schema fragments describing the customization replace the original schema fragments, thus preserving all of the schema fragment linkages for those fragments that remain unchanged.

Figure 16. The overlaying of customization schema fragments

7.3.1. Extending UBL

To complete the customization picture, it is sometimes necessary to add new non-UBL business objects to UBL documents. The book associated with this tool, "Practical Universal Business Language Deployment" [Crane Books], includes examples extending UBL. This OpenOffice environment is not designed to support the specification of non-UBL business objects or non-UBL documents, only the specification of subsets of UBL business objects and UBL documents.

Use typical W3C Schema development practices to create the required fragments as illustrated in Crane's training material. It is recommended to follow the UBL Naming and Design Rules such that any new business objects would be structured in the same style as UBL. This may also support a submission to the UBL Technical Committee for consideration in a future version of UBL.

7.3.1.1. Adding non-UBL objects to UBL documents

Figure 17, “The extension of non-UBL business objects” illustrates an approach to specifying extension schema fragments defining the UBL extension point for non-UBL business objects in a particular customization. Note the suggested use of aggregate and component extension fragments correspondent to the like UBL fragments. The suggested apex fragment has no corollary in UBL and would be abandoned should the extension business objects migrate to a future version of the UBL common library.

Figure 17. The extension of non-UBL business objects

7.3.1.2. Using the UBL library for non-UBL documents

Figure 18, “Extending UBL to include non-UBL documents” illustrates an approach to specifying the schema fragments defining a non-UBL document using both UBL and non-UBL business objects. Note the suggested use of aggregate and component extension fragments correspondent to the like UBL fragments. The suggested apex fragment has no corollary in UBL and would be abandoned should the extension business objects migrate to a future version of the UBL common library with the document element getting an "official" UBL namespace as a future UBL document.

Figure 18. Extending UBL to include non-UBL documents

7.4. XSLT and Python instance filters

Note

In the current version of this software, creation of this export artefact cannot be engaged.

An instance filter plays an important role in preprocessing a UBL XML document in advance of application processing. Consider the following processing model for UBL XML documents:

Figure 19. The processing model using customization filters

In the diagram, the structure constraints XSD labeled (1) is the pruned customization schema produced by the export processes described in Section 7.3, “XSD schema pruning”.

When this validation process finds no violations to the structure constraints, the instance is passed to the second pass value constraints XSLT labeled (2). When the instance is eventually given to the application, the application is informed that the initial validation process passed.

When this validation process finds violations to the structure constraints, the instance is then pruned using the customization filter XSLT labeled (F) and described in this section. Alternatively the (F) artefact could be a Python application, also produced in this process.

The resulting pruned instance is then validated once again by the same pruned structure constraints XSD labeled (1).

When this validation process finds violations to the structure constraints, the UBL XML instance is rejected and it is up to out-of-band processes (including human intervention) to handle the document as an exception.

7.5. XPath full text report

Note

In the current version of this software, creation of this export artefact cannot be engaged.

This artefact is useful in reviewing all contexts of all BIE items in the customized profile's model. It is a simple text file enumerating every BIE in every context.

The list of items found in this report reflects a maximal document (without recursive repetition).

7.6. XPath minimal text report

Note

In the current version of this software, creation of this export artefact cannot be engaged.

This artefact is useful in reviewing all contexts of all BIE items in the customized profile's model. It is a simple text file enumerating only the mandatory BIE items that are found in mandatory ABIE and ASBIE contexts.

The list of items found in this report reflects a minimal document containing the absolute fewest number of constructs to validate with the pruned schema.

7.7. XPath XML report

Note

In the current version of this software, creation of this export artefact cannot be engaged.

This artefact is a useful developer tool suitable for analyzing all of the BIE items in all document contexts. It has a very small vocabulary and the information can be processed with XML-based tools.

7.8. XPath instance report

Note

In the current version of this software, creation of this export artefact cannot be engaged.

This artefact is a useful developer tool suitable for analyzing the kinds of instances produced by all of the BIE items in all document contexts. Such an instance cannot be validated by a schema because the contents of the elements and attributes are filled with the reference numbers of the enumeration found in the text reports.

8. Saving the profile document as a Profile XML file

The two limited situations where one would use the Profile XML file format is to save the profile information in an accessible format for other applications, and to engage changes in the number of profiles being maintained in the spreadsheet.

This save process can take as long as six to ten minutes, so it isn't something you want to do very often.

Note

In the current version of this software, user meta data is not preserved in a Profile XML file and will need to be copied from a saved spreadsheet file to the newly-created spreadsheet file.

The minimum number of profiles that can be specified in the spreadsheet is three. When you need more than three profiles, you can either create your own Profile XML file and open it (see Section 8.1, “Opening an existing Profile XML file”) or you can use the "Column save action" values to insert new columns adjacent to existing columns. These new columns are only realized when the file is saved and reloaded, as described in Section 8.2, “Saving and reloading the file to effect changes”.

Use "File" / "Save As..." and select the file type as "Profile (.xml)". Note that the list of file types is very long and the quickest way to find this file type is to repeatedly press "P" until you find it. When using the drop-down list, this entry is found in the long section of spreadsheet file types beginning with "ODF Spreadsheet (*.ods)".

Figure 20. Save a set of profiles as XML

8.1. Opening an existing Profile XML file

Open an existing Profile XML file from within OpenOffice using the "File / Open..." menu item and selecting files of type "Profile (*.xml)". This file type entry is sometimes difficult to find in the very long list of document types, but can quickly be selected by pressing the "P" key until the type is given. When using the drop-down list, this entry is found in the long section of spreadsheet file types beginning with "ODF Spreadsheet (*.ods)".

The file extension of the Profile XML file does not have to be ".xml" but can be any file extension.

Figure 21. Open an existing Profile XML document

This open process can take as long as 30 minutes (!!), so it really isn't something you want to do very often.

The two sample files are very different. The "test.xml" file has two bogus profiles used for testing the insertion of two columns between two profiles.

The "UBLProfiles.xml" file is a suite of 31 profiles, one for each UBL document type, and with no modifications indicated to change the original UBL definitions.

8.2. Saving and reloading the file to effect changes

Changing the number of profiles in a suite is engaged when the file being edited is reloaded after a save operation. This technique avoids the need to install macros in the template, as some users of OpenOffice are expressly prohibited from engaging macros.

Be careful to save first before attempting a reload, as if you cancel your changes during a reload process you will lose your work.

To save the document use the "Save" or "Save as..." entry in the "File" menu, avoiding at this time the use of the "Reload" entry:

Figure 22. Saving the current work

To engage the changes after saving, use the "Reload" entry in the "File" menu:

Figure 23. Reloading the current work to engage the changes

Remember that the opening of a Profile XML file is a very long process. This is because the process is creating 37 sheets with over 51,000 cells.

8.3. Validating Profile XML files

For those who are working with the Profile XML files, there is a document model in the support directory in the file named Crane-UBLProfile.rnc. The syntax used for this model is ISO/IEC 19757-2 RELAX-NG [RELAX-NG] and one tool available for validation is named Jing [Jing]

9. Help, future plans and other documentation

If you should encounter any problems within the document areas of functionality, we welcome your feedback to improve the application for you and other users. Please contact us at info@CraneSoftwrights.com with your information.

9.1. Configuration problems

The cryptic error message citing a "defective JRE" in the error message has in the past been primarily associated with problems specifying the Java parameters described in Section 2.3, “Java parameters”. If you should trigger this error, it would help us to know what was wrong whether or not you were able to fix it.

9.2. Memory problems

The size of the UBL spreadsheets necessitates there being sufficient memory allocated with which to transform the document. If there isn't enough memory, the typical error message for this condition reads as follows in the XSLT transformation log file:

Both the memory allocations and the XSLT transformation log are specified using the process described in Section 2.3, “Java parameters”.

9.3. Execution problems

Two significant problems in OpenOffice 3 are triggered by normal operation of this environment. When the problems are fixed in a future version of Open Office, Crane's environment should work without changing the Crane deliverables.

Getting an empty spreadsheet when trying to open a Profile XML file in OpenOffice is evidence of an installation problem triggering a transformation error. This has been reported here: http://www.openoffice.org/issues/show_bug.cgi?id=97170. Please review Section 2, “Installation and configuration” for details regarding uninstalling the old filter and reinstalling a new filter. The typical transformation log will include an error along the lines of:

Getting an export error worded "Error saving the document xxxxxxxxx: Write Error. The file could not be written." is typically the result of already having created the exported files during any given session of running OpenOffice 3. This has been reported here: http://www.openoffice.org/issues/show_bug.cgi?id=97173. The two ways around this are to save the content as an ODS file then exit and restart, or to alter the "Export version profile suffix" field in order to write the results to a new directory location. The hassle with the first is the delay in exiting and restarting OpenOffice. The hassle with the second is the proliferation of files and having to find your results in a new directory with every export. The typical transformation log will include an error along the lines of:

9.4. User-triggered error messages

Getting an export error worded "URI has an authority component" can be the result of having specified a file-based URI incorrectly. For example, "file:///t:/report.txt" (three slashes after the first ":") is valid while "file://t:/report.txt" (two slashes after the first ":") triggers the authority component error message.

9.5. Reporting problems to Crane

10. Bibliography

[Crane Books] Crane Softwrights Ltd. Crane's book sales page

[UBLTC] Jon Bosak, Tim McGrath OASIS UBL Technical Committee 2001