[Accessibility conventions are described at the bottom of the page]

9. UBL customization
[> 10.][< 8.1.4][^^^]
9.0 When to customize UBL
[> 9.1][> 10.][< 9.][^^][^^^]
Many criteria are considered when determining when and how to customize UBL
[[1] - the use of UBL
[[2] - stakeholders
 [2] - profiles of deployment
 [2] - business vs. technical
][1] - the scope of UBL
[[2] - more documents in UBL than needed
 [2] - fewer documents in UBL than needed
][1] - the size of UBL
[[2] - more information items in UBL than needed
 [2] - fewer information items in UBL than needed
][1] - the perspective of UBL
[[2] - closed environment or open environment?
[[3] - compatible or conformant?
][2] - taking advantage of existing UBL-based resources
]]
The UBL committee is not a certification authority
[[1] - it is not in the OASIS UBL Technical Committee charter to review, comment, measure or certify a UBL customization
[[2] - responsible only for "Standard UBL" and associated publications
 [2] - responsible to define conformance and compatibility but not enforce it or measure it
 [2] - committees can claim conformance or compatibility of their customization, but it is up to users to measure or confirm such is true
][1] - however a community defines a customization is up to the community
[[2] - following TC guidelines may help in identifying and meeting objectives
 [2] - one is not obliged to follow TC guidelines
]]
There are common basic steps in the process of creating a UBL customization
[[1] - define the profile
[[2] - what business function is being satisfied by the customization?
][1] - define the processes
[[2] - which transactions are needed to enact the business function?
][1] - determine the documents
[[2] - which documents are used in the transactions?
][1] - determine the document contents
[[2] - what information items are in the documents?
][1] - specify the restrictions and extensions
[[2] - which existing constructs are not needed and therefore are pruned
 [2] - which non-existent constructs must be added to the existing constructs
][1] - emit the other artefacts
[[2] - what support will the user community need?
]]
9.1 Customization considerations
[> 10.][< 9.0][^^][^^^]
9.1.1 Out-of-the-box UBL
[> 9.1.2][> 10.][< 9.0][^^][^^^]
Standardized UBL is defined to accommodate general accounting principles for business documents
[[1] - committee of experts included constructs necessary to communicate the essence of the business documents
 [1] - the documentary scenarios frame the choices made in the semantic concepts and expression of granularity and labels for markup
]
If all e-commerce systems implemented full UBL and UBL met everyone's requirements then there would be no need for customizations
[[1] - but UBL only implements 80%-90%of a general-purpose scenario
 [1] - the general-purpose solution may be so large as to be too costly to implement all of UBL
 [1] - special requirements and legacy needs may dictate going beyond UBL
]
UBL 2.0 defines 31 different document types
[[1] - no formal profiles in UBL 2.0
 [1] - the purpose and use of documents is illustrated using only representative workflows
]
UBL 2.0 defines 1972 different elements in parent/child contexts
[[1] - children are themselves parents of other elements in the nested nature of XML
 [1] - tens to hundreds of thousands of elements in full path document contexts
]
9.1.2 Customization stakeholders
[> 9.1.3][> 10.][< 9.1.1][^][^^][^^^]
A UBL customization is an implementation of UBL tailored for a user community
[[1] - UBL defines a baseline implementation without extensions or business rules
[[2] - needs to be tailored in a particular context to meet the objectives defined by the context
][1] - build on UBL
[[2] - build on top of UBL to create a customized environment for a closed set of users
][1] - scale down UBL
[[2] - "which of the existing UBL constructs makes sense for our user community?"
][1] - augment UBL
[[2] - the user community defines an extension of custom constructs on top of the UBL subset
]]
A business has both an internal user community and an external user community
[[1] - how will a customization meet internal business requirements?
 [1] - how will a customization meet partner business requirements?
]
A community could be an entire industry
[[1] - a specialized industry (e.g. aerospace) may need semantic augmentations to accommodate unique meta data
[[2] - e.g. augmented line items in invoices
]]
A community could be only customers or suppliers of a company
[[1] - streamlining internal processes by mandating external interfaces
 [1] - a large company may be homogenizing its interfaces
 [1] - a small company may be stepping out into standardization for internal benefits
]
A community could be defined by geo-political properties
[[1] - e.g. Denmark legislation for OIOXML (UBL 0.7) and OIOUBL (UBL 2.0)
 [1] - e.g. PEPPOL deployment of pan-European BII requirements (UBL 2.1)
]
A community could be participants in common process
[[1] - aggregating common information from multiple sources by using a single standardized format
 [1] - e.g. US Department of Transport Electronic Freight Management
[[2] - parties from all over the world participating in the shipment of goods
]]
A community could be customers of a particular software vendor
[[1] - offering an electronic version of a business document produced by the vendor's software
]
How are members of the community of users identified?
[[1] - for legal purposes
[[2] - e.g. having the responsibility of payment
][1] - for communication purposes
[[2] - e.g. successfully getting information from point A to point B
]]
Denmark's OIOSI project for OIOUBL purchased a million EAN numbers to use as endpoints
[[1] - used as an electronic delivery address only, not a legal entity identification
 [1] - available and searchable in a public UDDI register
[[2] - open-source software made available implementers to promote deployment
][1] - published guidelines
[[2] - [http://www.oioubl.info/guidelines/en/OIOUBL_GUIDE_ENDPOINT.pdf]
]]
Existing business practices within an organization already have processes to identify and authorize legal transactions
[[1] - one of UBL's primary goals is the elimination of rekeying of information, not the retooling of business practices
 [1] - e.g. shipments and payments would be authorized in a UBL-based environment no differently than in an existing environment
[[2] - UBL is only playing a role in getting the information between parties successfully
 [2] - existing environments probably already have concepts of customer numbers and supplier numbers
]]
Should the endpoint identifier be mandatory?
[[1] - using a single identifier to an internal definition of party address and contact information
[[2] - updated using an independent change-of-information business process
][1] - if so, are other party identification methods used for verification?
[[2] - allow users to enter their contact information used as a backup or for verification if the endpoint identifier is entered incorrectly or other problems are experienced using it
 [2] - should probably not be the method by which a change-of-information request is made
]]
9.1.3 Refining the business process models
[> 9.1.4][> 10.][< 9.1.2][^][^^][^^^]
Profiles of diverse business processes
[[1] - different profiles engage the use of different sets of documents
[[2] - e.g. the same document type can be used in different profiles of message choreography
][1] - may require multiple customizations of one document model
 [1] - e.g. an invoice used in "simple procurement" may require far less detail than an invoice used in "advanced procurement"
[[2] - when an invoice is raised without a formal purchase order, the simple invoice document model has no order reference information
 [2] - when an invoice is raised with a formal purchase order, the complex invoice document model mandates order reference information
]]
Three of the many draft BII profiles utilizing the Invoice document are as follows:
[[1] - BII04 - Basic Invoice Only
]
[Figure 9.1: Example BII profile: "Basic Invoice Only"
The ??
]
[[1] - BII05 - Basic Billing
]
[Figure 9.2: Example BII profile: "Basic Billing"
The ??
]
[[1] - BII06 - Basic Procurement
]
[Figure 9.3: Example BII profile: "Basic Procurement"
The ??
]
The above figures are excerpted from the CEN WS-BII-WG1 phase 2 report - Report 1, Version 2.0 (undated).
9.1.4 Technical considerations
[> 9.1.5][> 10.][< 9.1.3][^][^^][^^^]
Starting with UBL means not having to conceive of everything
[[1] - business experts participated in the UBL process
 [1] - avoiding a colloquial vocabulary avoids the problems of gaining acceptance
 [1] - can take advantage of existing processes or tools tailored to UBL
[[2] - won't have to implement parallel processes that are already implemented for UBL
][1] - opportunity for interoperability with other UBL deployments
[[2] - not guaranteed to be fully interoperable because of differing customizations
 [2] - high chance for sufficient interoperability to not inhibit accomplishing business
]]
Business and technical reasons to not support everything
[[1] - not all constructs available are relevant to the nature of the business
[[2] - irrelevant items can be distracting from those that are relevant
 [2] - users may feel it necessary to populate items that end up not being used in business processes
][1] - supporting everything in a single implementation would be a challenge
[[2] - application development to accommodate every construct
 [2] - testing of the support of every construct
 [2] - rendering of every construct
]]
Choosing to create a conformant customization can leverage standard UBL artefacts
[[1] - compatible schemas need to be created from scratch
[[2] - tools exist for creating schema expressions based on abstract definitions
][1] - conformant schema subsets can be mechanically derived from standard schemas
[[2] - see [Chapter A.]
]]
9.1.5 Expanding the scope of coverage
[> 9.1.6][> 10.][< 9.1.4][^][^^][^^^]
To support an existing business process, a new non-UBL document might be needed
[[1] - a customization is welcome to use its own document types not already included in the UBL document suite
[[2] - with the thought that such a document is probably a good candidate to add to a future revision of UBL
][1] - create a new document schema in a non-UBL namespace
[[2] - as with other UBL documents, only the document element is in the document namespace
 [2] - all other business objects in the document schema are from a library module
][1] - share the UBL common library
[[2] - wherever possible use the existing business objects to promote interoperability
 [2] - these business objects may be customized or not
][1] - create an add-on library of business objects not already in UBL
[[2] - use another non-UBL namespace so that the add-on library can be shared with multiple non-UBL document schemas
]]
Requirements to the UBL committee for future consideration
[[1] - dozens of documents are already in consideration for new minor versions of UBL 2
[[2] - identify the need for a new document type
 [2] - contribute the add-on business objects for inclusion in the common library
][1] - participate in the work to reduce the migration effort from the non-UBL addition to the future UBL-included specification
]
9.1.6 Refining the business document models
[> 9.1.7][> 10.][< 9.1.5][^][^^][^^^]
Profiles may affect both the common library and the document models
[[1] - may share a modified common library across different profile's customizations
 [1] - may require each profile's customization to have a different common library
]
Different versions of a given schema could share or distinguish common fragments
[[1] - on the left three profiles of the invoice document schema are sharing a common set of customizations of the common library
[[2] - not expected to be very common situation
 [2] - only "top level" constructs are defined in the document schema, thus not enough opportunity for customization
][1] - on the right three profiles of the invoice document schema are using different customizations of the common library
[[2] - expected to be very common situation
]]
[Figure 9.4: Possible XSD structure differences between profiles
The diagram shows the OASIS Standard UBL schemas in the middle, with a set of schemas defined to the left and another set of schemas defined to the right as described in the prose.
]
Recall [Figure 2.3]
[[1] - one customized common library is used for all document customizations
 [1] - the responsibility for process-specific variations is borne by supplemental validation using Schematron
]
Different document schemas in a given profile would share the same customization of the common library
[[1] - the customizations of the common library are different for each profile
 [1] - all documents within any given profile are using the same common library
 [1] - the business objects are shared within a profile and different between profiles
]
[Figure 9.5: Possible XSD structure differences between profiles
The diagram shows the OASIS standard UBL schemas to the left and three profiles to the right. Each profile has a different number of documents. Each profile has its own version of the common schemas, and all documents within that profile use that profile's common schemas.
]
9.1.7 Steps refining the document model
[> 9.1.8][> 10.][< 9.1.6][^][^^][^^^]
The information model is first refined based on user requirements
[[1] - the information model is abstract and based on the business requirements
 [1] - the document model is a concrete syntactic expression of the information model
 [1] - irrespective of the document model, new information items may have an association with existing items
 [1] - e.g. an extended line item description augments the existing line item
]
Remove document model components not used in the information model
[[1] - only optional document model constructs can be removed
]
Revise document model component cardinality based on the information model
[[1] - minimums can be increased
[[2] - e.g. an optional construct can be made mandatory in a customization
][1] - maximums can be decreased
[[2] - e.g. a repeated construct can be constrained to be a singleton
]]
Realize the information model augmentations in the document model
[[1] - compatible additions can be added anywhere in the document model
[[2] - there is no requirement for validating the instance with the standard UBL document models
][1] - conformant additions must utilize the extension point
[[2] - prevents rejection of the document instance triggered by constraint violations of the standard UBL document models
 [2] - put only the augmentations under the extension point
 [2] - replicate the standardized information under the extension point with augmentations in context
 [2] - utilize the extension point as an inboard repository
[[3] - e.g. scanned images, legacy format file content, etc.
 [3] - note: should utilize AttachedDocument when using outboard association of such entities with a document
]]]
9.1.8 Using UBL instances as a model for customization
[> 9.1.9][> 10.][< 9.1.7][^][^^][^^^]
Rather than working from the model to the instance, work from the instance to determine the model
[[1] - create a UBL instance with the required information
[[2] - work iteratively until all the information needed is expressed
][1] - validate the instance with the full UBL document model
[[2] - this confirms the content is acceptable
][1] - use the instance to walk through the customization process
[[2] - assume nothing but mandatory constructs are in the customization
 [2] - walk through the model adding those elements found in the instance
[[3] - which will likely reveal other important optional elements
][2] - probably (but not required to) preserve the modeled cardinality for each added construct
]]
9.1.9 Code list conformance
[> 9.1.10][> 10.][< 9.1.8][^][^^][^^^]
UBL document conformance does not include coded values
[[1] - except for a limited number of UN/CEFACT data types where coded values are embedded in the schemas
[[2] - such exceptions are being removed from UBL 2.1
][1] - recall [UBL documents - Section 5.2.2]
[[2] - no reference in normative validation definition to code values
]]
The community must decide to which code lists must the document values conform
[[1] - which information items in the document are constrained by controlled vocabularies?
 [1] - which controlled vocabularies are going to be used for those items?
 [1] - recall the list created and supplied by the TC for UBL ([UBL validation of controlled vocabularies - Section 8.1.2 UBL validation of controlled vocabularies])
]
Restricting and extending code lists must be considered
[[1] - masquerading a subset of a list as if it were the entire list
[[2] - promotes interoperability of the coded values
 [2] - uses best practices regarding list-level meta data
]]
Trading partners can further restrict and extend lists for private needs
[[1] - trading relationships can change over time
 [1] - the UBL committee and the customization community cannot anticipate private trading relationship requirements
]
Can choose to constrain code lists to a subset of lists provided by UBL TC
[[1] - if it is important for interoperability at the value level with a UBL 2.0 implementation using defaultCodeList.xsl then all values in the constrained list must also be values in the UBL published list
]
Can choose one's own selection of code lists for value conformance
[[1] - UBL conformance is measured at the schema level only
 [1] - defaultCodeList.xsl is part of an informative annex only
[[2] - provided only as a convenience to users
]]
In UBL 2.0 the UN/CEFACT schemas prevent extension of values for supplemental components
[[1] - currencyID= attribute for amount currency
 [1] - mimeCode= attribute for MIME type
 [1] - unitCode= attribute for unit of measure
 [1] - subsets of these values do not cause problems
[[2] - no need to change the schemas
 [2] - second-pass value validation can confirm the values used are within the subset of chosen values
][1] - any extensions to these values will prevent an instance using such values to validate against the UBL 2.0 schemas
 [1] - in UBL 2.1 this constraint is being removed
]
9.1.10 Identifying the customization
[> 9.1.11][> 10.][< 9.1.9][^][^^][^^^]
cbc:CustomizationID value
[[1] - identifies the customization as a whole
 [1] - any string can be used but a URI is recommended
]
cbc:ProfileID value
[[1] - identifies the profile within the customization
 [1] - any string can be used but a URI is recommended
 [1] - not necessary to include reference to the customization
[[2] - the string shouldn't be used in isolation without consideration of the customization identifier
]]
URI string can be discoverable or not
[[1] - a discoverable URI is a URL that can be accessed with HTTP without further dereferencing
[[2] - e.g. http://www.CraneSoftwrights.com/ns/CraneUBL
[[3] - points to a directory in which an index.html file is returned
 [3] - the file is in XHTML with RDDL attributes
][2] - e.g. urn:x-Crane:CraneUBL:InvoiceOnly
[[3] - this URI cannot be resolved to a URL without some kind of redirection lookup
 [3] - the lookup could very well return a URL as in the earlier example
]]]
Use of Resource Directory Description Language (RDDL)
[[1] - [http://www.rddl.org]
 [1] - a micro-vocabulary of attributes to add to the XHTML anchor element <a>
 [1] - formally identifies resources by their nature, purpose and format
 [1] - allows a program mining the document to find other related resources and documents
]
9.1.11 Announcing the customization
[> 10.][< 9.1.10][^][^^][^^^]
How will you get word out regarding the customization you've created?
[[1] - announce on [http://ubl.xml.org]
 [1] - announce and discuss on UBL-Dev
[[2] - [http://lists.oasis-open.org/archives/ubl-dev/]
 [2] - [http://www.oasis-open.org/mlmanage/]
]]


This is an accessible version of Crane's commercial training material. The content has been specifically designed to assist screen reader software in viewing the entire textual content. Figures are replaced with text narratives.

Navigation hints are in square brackets:
[Tx.x] and [Fx.x] are textual representations of the applicability icons;
[digit] indicates list depth for nested lists;
[link [URL]] indicates the URL of a hyperlink if different than link;
[EXAMPLE] indicates an example listing of code;
[FIGURE] indicates the presence of a figure replaced by its description;
[>] jumps forward;
[<] jumps backward;
[^] jumps to start of the section;
[^^] jumps to the start of the chapter;
[^^^] jumps to the table of contents.
Suggestions for improvement are welcome: [info@CraneSoftwrights.com]
Book sales: [http://www.CraneSoftwrights.com/links/trn-acc.htm]
Information: [http://www.CraneSoftwrights.com/links/info-acc.htm]
This content is protected by copyright and, as there are no means to protect this accessible version from plagiarism, please do not make any commercial edition available to others.

+//ISBN 1-894049::CSL::Presentation::UBL//DOCUMENT Practical Universal Business Language Deployment 2009-02-12 13:50UTC//EN
Practical Universal Business Language Deployment
Third Edition - 2009-02-12
ISBN 978-1-894049-23-8
Copyright © Crane Softwrights Ltd.