luxe-tooling and methodology manual
TRANSCRIPT
2013, Groningen Page 1 of 37
Author
S. Huizinga
Date, version
Januari 13, 2013 v1.6
Status
Final
LUXE-Tooling and methodology manual
Designing information exchange using a CIM
From
S.Huizinga
LUXE-Tooling and methodology manual
2013, Groningen Page 2 of 37
Contents
1 Introduction ............................................................................................................ 4
1.1 Methodology ..................................................................................................... 4
1.2 Required design tool and experience ................................................................... 4
1.3 General tooling behaviour .................................................................................. 5
1.4 Acronyms ......................................................................................................... 5
2 Designing a CIM in a Logical Object Model ................................................................... 6
2.1 Creating a Logical Data Type .............................................................................. 7
2.2 Wizard: Validate Logical Object Model .................................................................. 8
2.3 Wizard: Manage Semantic Annotations ................................................................ 9
2.4 Wizard: ‘Where used’ Wizard .............................................................................10
2.5 Adding SequencingKey to connector ends ...........................................................11
2.6 Adding mapping between Logical Object Models ...................................................12
3 Designing a Message ...............................................................................................13
3.1 Wizard: Message Assembly Wizard .....................................................................13
3.2 Wizard: Change Information Entity .....................................................................15
3.3 Wizard: Update Core Components Message Assembly ...........................................16
3.4 Wizard: Validate Core Component Message Assembly ...........................................16
3.5 Wizard: Re-create blueprint ...............................................................................17
3.6 Wizard: Manage CCMA Action Code ....................................................................18
3.7 Creating a Business Document Header ................................................................19
3.8 Creating a derived Logical Data Type ..................................................................19
3.9 Using choiceGroup for choices ...........................................................................20
3.10 Changing a SequencingKey..............................................................................20
3.11 Providing an alternative complexType name ......................................................21
4 Designing a Service .................................................................................................22
4.1 Wizard: Validate Service(s) ...............................................................................23
4.2 Using fault messages in a Service ......................................................................23
4.3 Using header messages in a Service ...................................................................24
4.4 Providing an alternative operation name .............................................................24
5 Generating a implementation ....................................................................................25
5.1 Wizard: (Batch) Generate CCMA to XML-Schema .................................................25
5.2 Wizard: (Batch) Generate Web Service ...............................................................26
5.3 Technical notes on implementation .....................................................................27
5.3.1 UN/CEFACT NDR 3.0 .................................................................................28
5.3.2 WSI-Basic Profile ......................................................................................28
6 General modelling approach and tips .........................................................................29
6.1 Define information domains ...............................................................................29
6.2 Define the information that you communicate and not the data you have ................30
6.3 Use iteration to create consistent designs............................................................31
6.4 Go ‘top-bottom’ and ‘bottom-up’ to validate designs .............................................31
6.5 Be aware of basic rules of normalizing objects, messages and services ...................32
6.6 Break through the reuse XML-Schema fundamentalism .........................................33
LUXE-Tooling and methodology manual
2013, Groningen Page 3 of 37
Appendix ..................................................................................................................36
1 Validation Rules ..................................................................................................37
LUXE-Tooling and methodology manual
2013, Groningen Page 4 of 37
1 Introduction LUXE was initially an acronym for Logical modelling, UN/CEFACT Core Components Message
Assembly, XML implementation and Extensions.
The LUXE-Tooling is part of a methodology for designing inter- and intra-organizational
information exchange with use of a Common Information Model (CIM). A CIM contains the
definitions of the information exchanged.
1.1 Methodology
The methodology is based on 3
layers. The first layer contains a
Common Information Model
(CIM) which includes the
definitions of information
exchanged. The second layer
contains the messages and
services that are created from the
CIM. The last layer contains the
technical implementation.
The methodology is using basic
UML design language and
translates the technical output
into standardized
implementations (with use of
UN/CEFACT and WSI-Basic Profile specifications). It tackles the issues encountered in complex
and high dynamic environments:
• It can design hundreds of messages and services consistently without losing context
sensitivity.
• It can specialize CIMs for both inter and intra-regional/business purposes.
• It can link and/or combine different originating CIMs down to the implementation.
• It enforces linkages between model and implementation for tracing the impact of changes.
• It produces discrete packages for large scale side-by-side deployments for phased
transitions.
• It enables the automation of mappings between messages and IT system data models.
• It can transparently be used for the intra-organizational design and implementation
process.
The approach and general tips for using the methodology is explained in chapter 6.
1.2 Required design tool and experience
The required design tool is Sparx Enterprise Architect (EA). The LUXE-Tooling is installed as an
add-in and automates the transformations, validations and generation of implementations.
Basic UML knowledge of class models and sequence diagrams is required.
Messages and Services
Measurement serviceRequest
Response
Technical implementation
Common Information Model
Contract
- Identifie r: Identifie r
- Val idFrom: DateTime
- Val idTo: DateT ime
Measurement
- Val idFrom: DateTime
- Val idTo: DateT ime
- Quantity: Quanti tyT ype
- Version: Numeric
Connection
- Identi fier: Identi fier
- T ype: ConnectionT ype
Supplier
- Identi fier: Identi fier
- Name: Text
- Address: AddressT ype
Client
- Identi fier: Identi fier
- Name: Text
- Address: AddressT ype
Inv oice
- Identi fier: Identi fier
- CreationDate: Date
- Quanti ty: Quanti ty
0..*
0..*
0..*
1 ..*
10..*1 0..*
0 ..*
0..*
LUXE-Tooling and methodology manual
2013, Groningen Page 5 of 37
1.3 General tooling behaviour
The LUXE-tooling is context sensitive. When,
for instance a package with a LOM stereotype
is selected (with a right mouse click), a popup
menu appears with ‘Add-in’ � ‘LUXE-tooling’
� presenting the options that are possible
(picture). This routine is used for all of the
automated functions of the LUXE-tooling.
1.4 Acronyms
This document contains various acronyms. A list of the acronyms including the descriptions is
stated in this paragraph.
Acronym Description
ABIE Aggregated Business Information Entity
ASBIE Associated Business Information Entity
ASMA Associated Message Assembly
BBIE Basic Business Information Entity
CC Core Components
CCMA Core Components Message Assembly
CDT Composition Data Type
CIM Common Information Model
EA Sparx Enterprise Architect
EAP Enterprise Architect Project
EDT Enumeration Data Type
IT Information Technology
LDM Logical Data Model
LDT Logical Data Type
LOM Logical Object Model
LUXE Logical modelling, UN/CEFACT Core Components Message Assembly, XML implementation and Extensions
MA Message Assembly
NDR Naming and Design Rules
OWL Web Ontology Language
PRIM Primitive
RDF Resource Definition File
SBDH Standard Business Document Header
SOAP Simple Object Access Protocol
UML Unified Modelling Language
UN/CEFACT United Nation Centre for Trade Facilitation and E-business
W3C World Wide Web Consortium
WSDL Web Service Description Language
WSI Web Service Interoperability organization
XML eXtensible Markup Language
LUXE-Tooling and methodology manual
2013, Groningen Page 6 of 37
2 Designing a CIM in a Logical Object Model The Common Information Model (CIM) is modelled in a Logical Object Model (LOM). A
characteristic of a CIM is that it only describes the information that is communicated between
parties. It does not contain the data that parties have traditionally defined in a Logical Data
Model (LDM).
Logical Object Model (LOM)
Common Information Model (CIM)
Describes the information that is communicated between parties
Modelled in aModelled in a
Objects are observed from at least two positions (relative)
Logical Data Model (LDM)
Describes the data someone haves
Objects are observed at one position (absolute)
The methodology is focused on the creation of a CIM in a Logical Object Model although the
LUXE-Tooling can be used for a LDM as well.
A Logical Object Model is created with basic UML classes, in a package with a LOM stereotype.
Some restrictions, conditions and options are applicable:
• Only unidirectional associations (connections between objects) are allowed.
• Generalization/Specializations are allowed.
• ‘Dependency’ connections can be used to link with other (types of) models.
• Names of objects and attributes always start with a capital character.
• ‘Alias’ field can be used for assigning a reading name to an object and attribute name.
• ‘Notes’ field of object and attribute can be used for describing the definition.
• Attribute data type must be a Logical Data Type.
• Cardinality can be used for determining the maximum range of an association or attribute.
• A ‘Role’ name can be added to an association-end for defining an alternate name to a
connected object.
• By using specializations a more ‘general’ model like a cross-border or intra-regional model
can be tailored to regional specific conditions.
LUXE-Tooling and methodology manual
2013, Groningen Page 7 of 37
2.1 Creating a Logical Data Type
A Logical Data Type (LDT) is a data type used by attributes. All LDTs are specialized from a
primitive. A primitive is the most basic form of a Logical Data Type.
«PRIM»
composition
«PRIM»
enumeration
tags
implementation = true
«PRIM»
string
tags
length =
maxLength =
minLength =
pattern =
totalDigits =
whiteSpace =
«LDT»
AddressType
- StreetName: Text
- HouseNumber: Numeric
- PostalCode: PostalCodeType «LDT»
PostalCodeType
tags
length = 6
«LDT»
ConnectionType
- Gas
- Electric
There are three groups of primitives. The ‘composition’ primitive is used when creating a data
type that exists out of a composition of two or more attributes. The ‘enumeration’ primitive is
used for creating enumerative data types. The last one contains all the other possible
primitives which are equal to the XML-Schema primitives1, where the Tagged Values
represents the constraining facets. The Tagged Values content should not be changed on the
primitive level, only altered at the LDT level. One ‘special’ primitive exists which is ‘xml’ that
represents a data type that result into an xml data type. A enumeration has a special Tagged
Value ‘implementation’ which can be used to specify if the enumeration values of the Logical
Data Type must be used in the implementation or not. All the Logical Data Types can be
stereotyped with LDT, although optionally an enumeration can be stereotyped with EDT
(Enumeration Data Type) and a composition with CDT (Composite Data Type). These
alternative stereotypes can be used for discriminative purposes required by documentation
tooling.
The name of a primitive may collide with other classes with the same name. To solve this issue
an alternative name can be provided in a Tagged Value ‘XSDAlternativeName’. The tooling will
use this value during the generation of the implementation.
«PRIM»
_string
tags
length =
maxLength =
minLength =
pattern =
totalDigits =
whiteSpace =
XSDAlternativeName = string
PRIM class is renamed to _string.
The name used in the XML-
Schema is placed in the tagged
value XSDAlternativeName.
1 http://www.w3.org/TR/xmlschema-2/#built-in-datatypes
LUXE-Tooling and methodology manual
2013, Groningen Page 8 of 37
2.2 Wizard: Validate Logical Object Model
The wizard validates a LOM. It will be available for all packages that are stereotyped LOM
and LDT. This wizard is useful for creating a consistent LOM during design.
LUXE-Tooling and methodology manual
2013, Groningen Page 9 of 37
2.3 Wizard: Manage Semantic Annotations
Semantic annotations are unique ID’s for each object and attribute in a LOM. It creates the
opportunity to automate mappings and to link with other LOMs without having to consume it.
The Wizard will create unique IDs and places it as a ‘modelReference’ Tagged Value to the
objects/attributes. You can also attach your own modelReference tags to each object and
attribute if desired. These modelReference tags will be copied to the message objects and
attributes during the creation of a message, and will be placed in the XML-Schema2 during the
generation of the implementation. The modelReference tags can be added later to a LOM as
well. The Update Core Components Message Assembly wizard will update the modelReference
tags to the messages.
The semantic annotations provide the opportunity to trace from which CIM objects the
message elements are derived from and to automate the mappings between the (hundreds) of
messages and a (company) logical data model, or an IT system object model.
Common Information Model (Company)Logical Data Model
One mapping
Messages will receive the modelReference ∞
All possible mappings are automated
∞
Messages
Contract
- Identifier: Identifier
- ValidFrom: DateT ime
- ValidT o: DateTime
Measurement
- ValidFrom: DateTime
- ValidTo: DateT ime
- Quantity: QuantityType
- Version: Numeric
Connection
- Identifier: Identifier
- Type: ConnectionType
Supplier
- Identifier: Identifier
- Name: Text
- Address: AddressType
Client
- Identifier: Identifier
- Name: T ext
- Address: AddressType
Invoice
- Identifier: Identifier
- CreationDate: Date
- Quantity: Quantity
0..*
0..*
0..*
1..*
10..*1 0..*
0..*
0..*
«ABIE»Invoice
«BBIE»
+ Ident if ier: Ident if ier+ Creati onDate: Date
+ Quanti ty: Q uanti ty
«ABIE»
Connection
«BBIE»
+ Ident if ier: Ident if ier
+ T ype: Connecti onType
«ABIE»
Contract
«BBIE»
+ Ident i fi er: Ident if i er
+ Val idF rom : DateT i me+ Val idT o: DateTi m e
«ABIE»
Client
«BBIE»
+ Iden ti fi er: Ident i fi er
+ Nam e: Text+ Add ress: AddressT ype
«SBDH»
DocumentHeader
«BBIE»
+ Docum ent Ident if ier: Ident if ier+ Creat io nDateTi mestam p: DateT i me
+ Correla ti onIdent if ier: Ident if ier
«M A»
Clie ntContracts
«ASBIE»
0.. *
«ASBIE»
0. .*
«ASBIE» 0.. *
«ASM A»
1
«ASM A» 1
«ABIE»Invoice
«BBIE»
+ Ident if ier: Ident if ier+ Cre ati onDate: Date
+ Qua nti ty: Qu anti ty
«ABIE»
Connection
«BBIE»
+ Ident i fi er: Ident i fi er
+ Type: Connecti onT ype
«ABIE»
Contract
«BBIE»
+ Ident if ier: Ident if ier
+ Vali dFrom: Da teT im e+ Vali dT o: Date Ti me
«ABIE»
Client
«BBIE»
+ Id enti fi er: Id enti fi er
+ Na me: Text+ Ad dress: Ad dressT ype
«SBDH»
DocumentHeader
«BBIE»
+ Docum entIdenti f ier: Ident if ier+ Creati onDateT im estamp: DateT im e
+ Correl at ionIdent if ier: Ident if ier
«M A»
ClientContr acts
«ASBIE»
0. . *
«ASBIE»
0.. *
«ASBIE» 0. . *
«ASM A»
1
«ASM A» 1
«ABIE»Inv oice
«BBIE»+ Id enti fi er: Identi f ier
+ Creat ionDate: Date+ Quant ity: Quant i ty
«ABIE»
Connection
«BBIE»
+ Identi f ier: Ident if ier+ T ype: Connecti onType
«ABIE»Contra ct
«BBIE»
+ Ident if ier: Ident if ie r
+ Val idFrom: DateT i me+ Val idT o: DateTi m e
«ABIE»Client
«BBIE»
+ Identi fi er: Ident if ier
+ Name: T ext+ Address: Addre ssType
«SBDH»Docu mentHeader
« BBIE»
+ Docum entIdent if ier: Ident i fi er
+ Creat ionDateTi mestam p: DateTi m e+ Corre lat ionIdent if ie r: Ident i fi er
« MA»
ClientContracts
«ASBIE»
0. .*
«ASBIE»
0. . *
« ASBIE» 0. .*
«ASMA»
1
«ASM A» 1
«ABIE»
Inv oice
«BBIE»
+ Id enti fi er: Identi f ier+ Creat ionDate: Date
+ Quant ity: Quant i ty
«ABIE»Connection
«BBIE»+ Identi f ier: Ident if ier
+ T ype: Connecti onType
«ABIE»Contra ct
«BBIE»+ Ident if ier: Ident if ie r
+ Val idFrom: DateT i me
+ Val idT o: DateTi m e
«ABIE»Client
«BBIE»+ Identi fi er: Ident if ier
+ Name: T ext
+ Address: Addre ssType
«SBDH»Docu mentHeader
« BBIE»+ Docum entIdent if ier: Ident i fi er
+ Creat ionDateTi mestam p: DateTi m e
+ Corre lat ionIdent if ie r: Ident i fi er
« MA»
ClientContracts
«ASBIE»
0. .*
«ASBIE»
0. . *
« ASBIE» 0. .*
«ASMA»
1
«ASM A» 1
«ABIE»Inv oice
«BBIE»+ Id enti fi er: Identi f ier
+ Creat ionDate: Date+ Quant ity: Quant i ty
«ABIE»
Connection
«BBIE»
+ Identi f ier: Ident if ier+ T ype: Connecti onType
«ABIE»Contra ct
«BBIE»
+ Ident if ier: Ident if ie r
+ Val idFrom: DateT i me+ Val idT o: DateTi m e
«ABIE»Client
«BBIE»
+ Identi fi er: Ident if ier
+ Name: T ext+ Address: Addre ssType
«SBDH»Docu mentHeader
« BBIE»
+ Docum entIdent if ier: Ident i fi er
+ Creat ionDateTi mestam p: DateTi m e+ Corre lat ionIdent if ie r: Ident i fi er
« MA»
ClientContracts
«ASBIE»
0. .*
«ASBIE»
0. . *
« ASBIE» 0. .*
«ASMA»
1
«ASM A» 1
«ABIE»Invoice
«BBIE»
+ Ident if ier: Ident if ier+ Creati onDate: Date
+ Quanti ty: Q uanti ty
«ABIE»
Connection
«BBIE»
+ Ident if ier: Ident if ier
+ T ype: Connecti onType
«ABIE»
Contract
«BBIE»
+ Ident i fi er: Ident if i er
+ Val idF rom : DateT i me+ Val idT o: DateTi m e
«ABIE»
Client
«BBIE»
+ Iden ti fi er: Ident i fi er
+ Nam e: Text+ Add ress: AddressT ype
«SBDH»
DocumentHeader
«BBIE»
+ Docum ent Ident if ier: Ident if ier+ Creat io nDateTi mestam p: DateT i me
+ Correla ti onIdent if ier: Ident if ier
«M A»
Clie ntContracts
«ASBIE»
0.. *
«ASBIE»
0. .*
«ASBIE» 0.. *
«ASM A»
1
«ASM A» 1
Portfolio
- Identifier: Identifier
- ValidFrom: DateTime
- ValidT o: DateTime
Consumption
- Val idFrom: DateTime
- Val idTo: DateTime
- Quantity: QuantityType
MeteringPoint
- Identifier: Identifier
- Type: ConnectionType
BusinessPartner
- Identi fier: Identi fier
- Name: T ext
- Address: AddressType
Invoice
- Identifier: Identifier
- CreationDate: Date
- Quantity: Quantity
The wizard request meta data for creating the scheme of the unique ID conform the
UN/CEFACT NDR 3.03 for namespaces.
The scheme can be a URN (NDR 3.0 preferred option)
or URL. Next to the generation of the model
references a resource file can be created in
RDF/OWL4 format or CSV5. This resource file is a
‘dictionary-like’ file containing all the definitions,
which can be loaded into automated environments.
This can be used for creating mappings and semantic
linkages between models/dictionaries, and to
automate mappings between XML-Schemas and
system data models.
2 W3C Semantic Annotations for WSDL and XML-Schema
3 UN/CEFACT Naming and Design Rules 3.0 4 W3C OWL Web Ontology Language 5 Comma separated values
LUXE-Tooling and methodology manual
2013, Groningen Page 10 of 37
The ‘Annotations’ field can be used to place identifying parameters ($ID$) or other meta data
to the resource file for source save/versioning systems.
2.4 Wizard: ‘Where used’ Wizard
The ‘Where used’ wizard shows to which message objects a LOM object is derived to, and
presents where a LDT is used. This wizard will be available on all packages with a LOM or LDT
stereotype.
In the ‘Select object’ field the object can be selected to search with. In the ‘Used In’ field the
objects + attributes are presented where a selected LDT is used. In the ‘Derived to’ field the
objects are placed to which the selected LOM object is derived to.
In the Attributes field the attributes are presented of the selected object with filter options.
‘Local defined’ are only the attributes that are present in the selected object. “+Inherited” are
the local defined including those which are inherited from the (grand) parents. “+Childs”
includes all the local, (grand) parents and from all the (grand) childs (specialized) of the
selected element. “+ All Usages” includes all the attributes that are available of the (grand)
parents, local defined, (grand) childs, and cousins.
LUXE-Tooling and methodology manual
2013, Groningen Page 11 of 37
2.5 Adding SequencingKey to connector ends
Optionally, when an association is made, a ‘SequencingKey’ can be added to the target and
source end of the connector. This is used to define the sequence of each association when
used in a message, instead of determining each sequence in the hundreds of messages
manually.
The SequencingKey will be placed in the message during the creation of a message with the
Message Assembly Wizard, or when using the Update Core Components Assembly Wizard.
LUXE-Tooling and methodology manual
2013, Groningen Page 12 of 37
2.6 Adding mapping between Logical Object Models
As noted in paragraph 2.3, semantic annotations can be used to create mappings between
models. With the semantic annotations wizard each objects/attribute gets a modelReference
as a unique global identifier. When these identifiers are in place a mapping can be created
between objects/attributes.
A mapping between objects is indicated with a dependency stereotyped ‘mapsTo’ placed
between the two objects. Multiple mapsTo dependencies are allowed.
Client
- Identifier: Identifier
- Name: Text
- Address: AddressType
Customer
- Identifier: Identifier
- Name: Text
- Address: AddressType
LOM example Second LOM
«mapsTo»
An attribute of an object can be individually mapped by using the modelReference as a value
of a mapsTo[..] tag. An example can be found in the following figure.
In this example the Address attribute of the Client object has a ‘mapsTo[1]’ tag with
modelReference of the related object. Multiple mapsTo tagged values are allowed, each with
an unique number (mapsTo[1], mapsTo[2], mapsTo[..] and so on). The mappings are also
allowed between Logical Data Types.
To export the mappings use the CSV export option in the Manage Semantic Annotations
wizard.
LUXE-Tooling and methodology manual
2013, Groningen Page 13 of 37
3 Designing a Message An infinite amount of messages can be created from a Common Information Model (CIM).
A message is a subset of
a derivative CIM (∆CIM).
A ∆CIM spans an infinite
amount of (contextual)
space providing an
infinite amount of
possibilities for creating
a message. The limited
context of an exchange
determines the limited
subset taken from a
∆CIM.
This differentiation
process is automated
with the Message
Assembly Wizard.
3.1 Wizard: Message Assembly Wizard
This wizard will be available on packages stereotyped CCMA or Service.
When the wizard is started the first
element(s) of a message can be
selected from a CIM. A tip is to first
start with a ‘document header’
object. After this the objects can be
selected like for instance the Client
object. The selected objects will be
shown as a message element in the
Message Assembly tree view.
In the Message Assembly tree view
you can select the attributes you
want to have in the message, and
select the ‘following’ associations,
for instance Contracts, and repeat
the previous steps until you are
satisfied with the content of the
message. Then you can select
‘Generate Diagram’ for
automatically creating a diagram,
and ‘Simplified Diagram’ if you need
an overview without any CCMA
stereotyping.
∆CIM
CIM
Limited context of exchange
Message
∞
Message
Exchange
S.Huizinga, 2011
Contract
- Identi fier: Identi fier
- Val idFrom: DateT im e
- Val idTo: DateT ime
Measurement
- ValidFrom: DateTime
- ValidTo: DateT ime
- Quanti ty: Quanti tyType
- Version: Numeric
Connection
- Identifier: Identifier
- Type: ConnectionType
Supplier
- Identi fier: Identi fier
- Name: Text
- Address: AddressType
Client
- Identi fier: Identi fier
- Name: Text
- Address: AddressType
Inv oice
- Identi fier: Identi fier
- CreationDate: Date
- Quanti ty: Quantity
0..*
0..*
0..*
1..*
10..*1 0..*
0..*
0..*
LUXE-Tooling and methodology manual
2013, Groningen Page 14 of 37
Provide a name for the message and press ‘Create Message Assembly’. This methodology uses
the UN/CEFACT Core Components Message Assembly as its meta-model for message designs.
This will create a similar message like the following picture.
«ABIE»
Inv oice
«BBIE»
+ Identi fier: Identifier
+ CreationDate: Date
+ Quantity: Quanti ty
«ABIE»
Connection
«BBIE»
+ Identifier: Identi fier
+ Type: ConnectionType
«ABIE»
Contract
«BBIE»
+ Identi fier: Identifier
+ ValidFrom: DateTime
+ ValidTo: DateTime
«ABIE»
Client
«BBIE»
+ Identifier: Identi fier
+ Name: Text
+ Address: AddressType
«SBDH»
DocumentHeader
«BBIE»
+ DocumentIdentifier: Identi fier
+ CreationDateTimestamp: DateTime
+ CorrelationIdenti fier: Identifier
«MA»
ClientContracts
«ASBIE»
0..*
«ASBIE»
0..*
«ASBIE» 0..*
«ASMA»
1
«ASMA» 1
When you want to extend the current message you can use the Message Assembly Wizard
again on the same message to make the extending adjustments. The deriving steps from a CIM
to a Message is presented in the following overview.
Common Information Model (Modeled in a LOM)
Message
«ABIE»
Supplier
«BBIE»
+ Identifier: Identifier
+ Name: Text
+ Address: AddressType
«ABIE»
Invoice
«BBIE»
+ Identi fier: Identifier
+ CreationDate: Date
+ Quantity: Quantity
«ABIE»
Contract
«BBIE»
+ Identifier: Identifier
+ ValidFrom: DateTime
+ ValidTo: DateTime
«MA»
ContractDetails
Contract
- Identifier: Identifier
- ValidFrom: DateTime
- ValidTo: DateTime
Inv oice
- Identi fier: Identifier
- CreationDate: Date
- Quantity: Quantity
Supplier
- Identifier: Identifier
- Name: Text
- Address: AddressType
Client
- Identifier: Identifier
- Name: Text
- Address: AddressType
Connection
- Identifier: Identifier
- Type: ConnectionType
Measurement
- ValidFrom: DateTime
- ValidTo: DateTime
- Quantity: QuantityType
- Version: Numeric
A Common Information Model (CIM) can be used
to derive an infinite amount of messages from
A message is derived subset. Only the objects and attributes are
selected that are required in a certain exchange.
UN/CEFACT Core Components Message Assembly (CCMA)
Definitions
MA: Message Assembly (Root element)
ASMA: Associated Message Assembly (Connects ABIE to MA)
ABIE: Aggregated Business Information Entity
ASBIE: L Associated Business Information Entity
BBIE: Basic Information Entity
«derivedFrom»
«ASBIE»1
«derivedFrom»
«ASBIE» 0..*
«derivedFrom»
«ASMA»
1
10..*1 0..*
0..*
0..*
0..*
0..*
0..*
1..*
LUXE-Tooling and methodology manual
2013, Groningen Page 15 of 37
3.2 Wizard: Change Information Entity
This wizard is available by right clicking on a class stereotyped ABIE. With this wizard you can
change the attributes of a message element to the original derived from LOM object, or vice
versa. This is useful when adding a separate message to a LOM and pulling it’s attributes to the
LOM level or to adapt a message element with new attributes available in the LOM.
LUXE-Tooling and methodology manual
2013, Groningen Page 16 of 37
3.3 Wizard: Update Core Components Message Assembly
This wizard is available on all packages stereotyped CCMA, Service or Services. It will update all
the meta-data from the LOM to a Message Assembly. This will keep the LOM synchronized
with the (hundreds of) messages created.
3.4 Wizard: Validate Core Component Message Assembly
The validate wizard will be available on packages which are stereotyped ‘CCMA’ (for one
message) or ‘Services’ and ‘CCMA’ for multiple validations at once. It will help find errors and
mistakes in the created messages.
LUXE-Tooling and methodology manual
2013, Groningen Page 17 of 37
3.5 Wizard: Re-create blueprint
This wizard is available on a message assembly package with the stereotype CCMA. It will copy
the original message, discard al the localized changes, and re-create the message to its original
‘blueprint’ derived from a Logical Object Model. In practice this is used when ‘functional’
readable messages where created from the LOM, and the technical detailed messages are
created using the functional messages as input.
LUXE-Tooling and methodology manual
2013, Groningen Page 18 of 37
3.6 Wizard: Manage CCMA Action Code
This wizard is available on a message package stereotyped CCMA. CCMA Action Code is an
alternative method for specifying the action that should be taken with the communicated
information, in contrary to implicitly defining the action in the service or message definition.
Actions may be determined by a system at runtime (Dynamic), or may be specified at design
time (Fixed value). The Action Code can be defined for each element individually.
LUXE-Tooling and methodology manual
2013, Groningen Page 19 of 37
3.7 Creating a Business Document Header
This (optional) header is normally modelled as a separate LOM, with the first element
stereotyped SBDH. The first element can be selected in the Message Assembly wizard during
the creation of a message.
«SBDH»
DocumentHeader
+ DocumentIdentifier: Identifier
+ CreationDateTimestamp: DateTime
+ CorrelationIdentifier: Identifier
Notice
+ Code: Code
+ Description: Text
0..*
3.8 Creating a derived Logical Data Type
In regular cases a Logical Data Type (LDT) must be specialized at the message level. This is
useful when for instance a QuantityUnitType contains too many values for a specific message.
To create a specialized LDT a copy of the original element must be made with a derivedFrom
dependency between them.
In the new element the restrictions can be added. The validation wizard will detect that in the
message a different LDT is used than in the LOM but allows this difference if the new LDT is
derived from the original one.
Message
Logical Object Model
composition
«LDT»
QuantityType
- Value: Quantity
- Unit: QuantityUnitType
enumeration
«LDT»
QuantityUnitType
- kWh
- m³
string
«LDT»
Text
tags
minLength = 1
composition
«LDT»
QuantityType
- Value: Quantity
enumeration
«LDT»
QuantityUnitType
- kWh
string
«LDT»
Text
tags
maxLength = 10
minLength = 1
«derivedFrom» «derivedFrom» «derivedFrom»
LUXE-Tooling and methodology manual
2013, Groningen Page 20 of 37
3.9 Using choiceGroup for choices
In the case there are excluding interdependencies between objects a choiceGroup can be
used. The objects that are mutely exclusive can be grouped together by adding a Tagged Value
‘choiceGroup’ to the objects with a unique name as value. In the following picture Client or
Invoice will be available in the message and not both. The same applies to choiceGroup ‘B’ in
which Supplier or Connection will be present in the message. A choiceGroup can be used with
attributes as well.
«ABIE»
Supplier
«BBIE»
+ Identifier: Identifier
+ Name: Text
tags
choiceGroup = B
«ABIE»
Inv oice
«BBIE»
+ Identifier: Identifier
+ CreationDate: Date
tags
choiceGroup = A«ABIE»
Connection
«BBIE»
+ Identifier: Identifier
+ Type: ConnectionType
tags
choiceGroup = B
«ABIE»
Client
«BBIE»
+ Identifier: Identifier
+ Name: Text
tags
choiceGroup = A
«ABIE»
Contract
«BBIE»
+ Identifier: Identifier
+ ValidFrom: DateTime
+ ValidTo: DateTime
«SBDH»
DocumentHeader
«BBIE»
+ DocumentIdentifier: Identifier
+ CreationDateTimestamp: DateTime
+ CorrelationIdentifier: Identifier
«MA»
Contracts
«ASBIE»
1
«ASBIE» 0..*
«ASBIE»
0..*
«ASBIE» 1
«ASMA»
0..*
«ASMA» 1
3.10 Changing a SequencingKey
As explained in paragraph 2.5 the sequence of associations of all the messages elements can
be determined at the LOM level. However, when the SequencingKey is not defined at the
LOM level a default SequencingKey will be created by the Message Assembly Wizard. This
can be changed by selecting the association and change the SequencingKey Tagged Value
manually.
LUXE-Tooling and methodology manual
2013, Groningen Page 21 of 37
3.11 Providing an alternative complexType name
The Core Components Message Assemblies can be generated into a XML-Schema
implementation with the CCMA to XML-Schema wizard. Each Aggregated Business
Information Entity is generated into an ‘complexType’ in the XML-Schema.
In some implementations the complexType name requires an alternative name or the name
must be shorter. Changing the complexType names does not alter the functional content of
the message. The messages exchanged are interoperable between the XML-Schemas
without alternative names. However it may formally result into less compliant
implementations according to the NDR 3.0.
To alter the default name of a complexType a tagged value ‘XSDAlternativeName’ can be
added to a ABIE with the value as the alternative name. The behaviour of the alternative
name can be manipulated via the ‘XSDAlternativeNameType’ tag.
The value of the XSDAlternativeNameType can be ‘Synonym’ (default) or ‘Short’. ‘Synonym’
replaces the ABIE part of the generated complexType name with the alternative, while
‘Short’ removes all the auto-generated parts and keeps only the (short) alternative name.
To ensure that the tag is used check the option ‘Use Alternative Names...’ when generating a
XML-Schema with the CCMA to XML-Schema wizard. This option can be found in the
Extension tab of CCMA to XML-Schema wizard.
LUXE-Tooling and methodology manual
2013, Groningen Page 22 of 37
4 Designing a Service A service is modelled as a sequence of messages between a sender and a receiver. It’s starts
with the creation of a package stereotyped with ‘Service’ containing a Sequence diagram.
In the Sequence Diagram one Actor must
be placed, and one lifeline stereotyped
‘Service’ with the service name. The
messages can be added to the diagram
by drawing the arrows and giving the
arrows the name of the messages root
element. By double-clicking on the
arrows the ‘Synch’ can be changed from
Synchronous to Asynchronous if desired.
A more complex sequence with longer
durations can be designed as well
(picture on the left).
Inside the service package the message packages (stereotyped CCMA) can be placed that are
exchanged in this service, or the message packages can be ‘imported’ by using the UML
‘import’ statement. A service itself can inherit its content from another service by using a UML
‘use’ statement, which is useful to create an alternative sequence of a existing service with the
same messages.
«Service»
PublishConnectionMeasurement
«CCMA»
PublishConnectionMeasurementRequest
«CCMA»
PublishConnectionMeasurementResponse
«import» «import»
Requester
«Service»
CreateContract
CreateContractRequest
AcknowledgmentOfReceipt
{1 hours}
AcknowledgmentOfAcceptance
{24 hours}
CreateContractResponse
AcknowledgmentOfReceipt
«Service»
PublishConnectionMeasurement
«Service»
PublishConnectionMeasurementAlternativ e
«use»
LUXE-Tooling and methodology manual
2013, Groningen Page 23 of 37
4.1 Wizard: Validate Service(s)
The validate service wizard will be available on packages which are stereotyped ‘Service’ (for
one service) or ‘Services’ (for multiple validations at once of services). It will help find errors
and (minor but not blocking) mistakes in the created services.
4.2 Using fault messages in a Service
Fault messages are used to return (predefined) errors that occur during the execution of a
service. Multiple fault messages can be defined for one service. At paragraph 5.1 is explained
how to mark a message as a fault message (Extensions tab in CCMA to XML-schema wizard).
During the generation of an implementation the fault messages are transformed into SOAP
fault messages.
Two options are possible. The first option is to place the fault message package (stereotyped
CCMA) into the Service package. The second option is to import the fault message with a
UML ‘import’ statement to the Service.
«Service»
PublishConnectionMeasurement
«CCMA»
Fault
«import»
The second option is preferred because fault messages are normally placed centrally and
reused across different services. Multiple fault messages can be imported in one service,
each with a unique name.
LUXE-Tooling and methodology manual
2013, Groningen Page 24 of 37
4.3 Using header messages in a Service
Header messages are used to send information separate from the main body of a service.
Typically this is used for transactional information like session identifiers or authentication
and authorisation codes.
Multiple header messages can be defined for one service. At paragraph 5.1 is explained how
to mark a message as a header message (Extensions tab in CCMA to XML-schema wizard).
During the generation of a web service implementation the header messages are
transformed into SOAP headers.
Two options are possible. The first option is to place the header message package
(stereotyped CCMA) into the Service package. The second option is to import the header
message with a UML ‘import’ statement to the Service.
«Service»
PublishConnectionMeasurement
«CCMA»
Header
«import»
The second option is preferred because header messages are normally placed centrally and
reused across different services. Multiple header messages can be imported in one service,
each with a unique name.
4.4 Providing an alternative operation name
During the generation of a WSDL the operation names are created with the initiating
message name as the operation name. An alternative name can be provided by adding a
tagged value ‘operationName’ with the alternative name as value.
LUXE-Tooling and methodology manual
2013, Groningen Page 25 of 37
5 Generating a implementation
The designed Messages and Services can be generated into implementations. The
implementation technology supported are XML-Schema and Web Services.
The messages implementations are generated with the ‘Generate CCMA to XML-Schema’
wizard and ‘Batch Generate CCMA to XML-Schema’ wizard. The services are created with the
‘Generate Web Service’ and ‘Batch Generate Web Service’ wizards.
5.1 Wizard: (Batch) Generate CCMA to XML-Schema
The normal wizard is available for a message
assembly stereotyped CCMA. The batch wizard
will be available on all packages with CCMA and
Service or Services stereotype containing
multiple messages.
On the general tab the first area contains several
mandatory meta-data fields, including the
creation of the namespace (unique ID) of a
message. The URN is the preferred scheme of
the UN/CEFACT NDR 3.0. In the Semantic
Annotations area the option can be selected to
include the modelReference6 to the XML-
Schema, originally derived from the LOM
elements, as explained in paragraph 2.6).
The Core Components Documentation area provides the option to add the CCMA annotations
as specified in the UN/CEFACT NDR 3.0 to the XML-Schema.
In the Customize area the inclusion of the enumeration values can be overridden, the schema
modularity and versioning can be changed. The Functional modularity is the preferred method
although not 100% NDR 3.0 compliant. Functional modularity has the lowest maintenance
time and impact during changes. The NDR 3.0 Modularity option can be selected with the
drawback that it will fragment the implementation over several different XML-Schemas. The
default option for versioning the files is the Major/Minor structure (NDR 3.0 compliant). Two
alternative options exists to suit alternative implementations.
Due the model driven approach of this methodology in which the relations and reuse of
objects are managed at the model level, the NDR 3.0 Modularity on the implementation level
is redundant. This issue is discussed in depth in paragraph 5.3.1.
The ‘Annotations’ field can be used to place identifying parameters ($ID$) or other meta data
to the schema files for source save/versioning systems.
6 W3C Semantic Annotations for WSDL and XML-Schema
LUXE-Tooling and methodology manual
2013, Groningen Page 26 of 37
At the extension tab the option to mark the
message as a fault or header message is available.
When one of these options are checked the
message cannot be used as a ‘normal’ message in a
service. The use of fault or header messages in a
service is further described in paragraph 4.1 and
4.2.
Another group of options is the XML-Schema
Customization. These options changes the internal
structure of the XML-Schemas. These options
accommodate different practices (other than NDR
3.0) and should be used with caution. Use of
these options result into less compliant
implementations and should only be used for
backwards compatibility reasons. The Batch wizard has the same options as the general tab
plus overwrite options to change the meta data and options of several messages at once.
5.2 Wizard: (Batch) Generate Web Service
The generation of the Web Service is done via two
wizards. The ‘normal’ wizard will be available on
packages that are stereotyped ‘Service.’ The
‘batch’ wizard provides the ability to generate a
complete batch of services at once. The batch
wizard will be available on packages which are
stereotyped ‘Services’.
The wizards will produce a package including a
WSDL and XML-Schemas for the messages.
The first ‘General’ tab contains several mandatory
meta-data fields, including the creation of the
unique ID (namespace) of this service. The
URN is the preferred scheme of the
UN/CEFACT NDR 3.0. If required, the exact
service address at which the service will be
available can be entered.
In the Customize area the inclusion of the
enumeration values can be overridden,
and the schema modularity and versioning
can be changed. The ‘Annotations’ field
can be used to place identifying
parameters ($ID$) or other meta data to
the schema files for source
save/versioning systems.
In the extension tab more options are
available. The SOAP version can be
switched between 1.1 and 1.2. The SOAP
protocol includes transport information in
the messages used by brokers and service
LUXE-Tooling and methodology manual
2013, Groningen Page 27 of 37
bus systems. Interdependencies exists between the options. When for instance SOAP 1.2 is
selected the options WS-Addressing and WS-SecurityPolicy are possible. Addressing gives the
ability to dynamically specify the return address for asynchronous response(s). Secondly it
provides the requester with the (optional) ability to dynamically specify a return address for
fault messages.
The second option applies a security policy to the web service. First a security policy specifies
the (optional/ mandatory) use of a certificate for identifying the client.
Third it specifies the algorithm used for encrypting the transport. Which options are required is
depending on the technical requirements and maturity level of the communicating parties. If
dynamic relocations of systems can occur the service can benefit of Addressing options. If a
high level of security is required the Security options should be considered. However, the
addressing and security options may not be technical feasible due restrictions of (less mature)
parties.
The Batch generate service wizard has the same options but with extra overwrite options to
change the meta data and options of several services at once. One extra option is available and
that is the creation of a ‘menu file’ which is a WSDL file containing a ‘menu’ with references to
all the services.
5.3 Technical notes on implementation
For easy maintenance of the implementations the methodology produces self-contained
packages. This provides the ability:
• for parallel development, test and implementation phases;
• to do side-by-side deployments of different versions;
• to minimize faults and interdependencies between (dozens of) separate designs and
implementations.
LUXE-Tooling and methodology manual
2013, Groningen Page 28 of 37
5.3.1 UN/CEFACT NDR 3.0
UN/CEFACT NDR 3.0 is used as the main formatting for the XML-Schema with one
exemption. The exemption is the “1 Message Assembly = 1 XML-Schema” principle
(Functional modularity) instead of the Modular framework of NDR 3.0.
Due the model driven approach of this methodology in which the relations and reuse of
objects are managed at the model level, the NDR 3.0 Modularity on the implementation level
is redundant.
A practical but blocking issue was experienced with even a minor set of messages. When
trying to implement the ‘spirit’ of the NDR 3.0 modular framework, reusing message
elements across messages creates a complex set of interdependencies between dozens of
unrelated messages over time, resulting in a very sluggish and difficult design- and
implementation process. Each minor change to a CIM object or message element in the
design phase have to be scrutinized and have (unintended) consequences for (hundreds of)
unrelated but technical intertwined implementations.
This situation was noted in the NDR 3.0 (page 44 and 61) as well. It even mentions on page
61 that: “linking of BIEs across packages is strongly discouraged”. The NDR 3.0 modularity
option is available in the tooling but has taken the notes into consideration to limited the
linkages to within the scope of a single message. This makes the NDR 3.0 modularity
interchangeable with the Functional modularity option. This however does not provide any
more added-value other than a ‘more’ standard compliant implementation with the drawback
of a more fragmented and error prone implementation.
Although not explained in the NDR 3.0 itself, it seems that a balancing act between using
XML-Schema for message validation and using XML-Schema for (semantic) model validation
is causing the difficulties.
However, W3C itself have already created a solution. The solution is to use W3C Semantic
Annotations for WSDL and XML-Schema. This diminishes the requirement for using XML-
Schemas for both message validation and semantic model validation. Instead of using a
modular catalogue of reusable XML-Schemas and XML-Schema parts, the individual message
schemas will be self-contained and only point by reference to a centralized definition. The
LUXE-Tooling provides the option to create the model references on the Logical Object Model
and to implement them into the XML-Schemas. This can also be used to automate the
mappings of dozens of messages at once as stated in paragraph 2.3. More on the self-
containment issue is discussed at paragraph 6.6.
5.3.2 WSI-Basic Profile
The WSDL generated is compliant to WSI Basic Profile 1.1 or 2.0 (depending on selected
options). However, Basic Profile also prohibits functionally the use of asynchronous ‘Solicit-
Response’ and ‘Notification’ transaction patterns. When designing a service with these
transaction patterns it will result into non-compliant implementation.
LUXE-Tooling and methodology manual
2013, Groningen Page 29 of 37
6 General modelling approach and tips
This chapter will discuss briefly the modelling approach and tips. You should have some basic
experience with modelling. The following tips are based on experience during the PhD.
6.1 Define information domains
Information is communicated between information domains. Unintended design behaviours
have the tendency to define process domains instead. However, different processes uses the
same information. The same information placed into several process domains means a
fragmented information landscape; information needs to be exchanged continuously to keep
all the different domains synchronised.
Information domains are grouped by the cohesion of the information like a supermarket has
grouped his floor by the cohesion of its products (vegetable area, meat area) and not to its
1000+ suppliers (Uni-lever area, Nestlé area, etc).
Information domains are not bound to IT-application boundaries. One (large) application can
be supplying for different information domains, and one information domain can be supplied
by more than one application.
It’s a matter of being aware of these characteristics to create a maintainable landscape. In
practicing the methodology the domains act as the grouping of the services catalogue.
In some IT-driven companies it will grow naturally that (large) groups of information is
centralized. Some companies that are heavily depended on information processing tend to
change the processes orientation to an information orientation to cut down dependencies and
to increase the flexibility of their company.
When defining information domains for complete industries, a role model may act as a
equivalent of a information domain model with the requirement that the roles represents
information producing and/or consuming responsibilities.
When designing the domains there are two different types you should detect: transformative
and distributive. A transformative domain is for example a Production domain that
transforms information input into new output. Distributive domains centralizes shared output
and presents it as shared input. Such a domain could contain for example a centralized
business partner register.
Transformative domains Distributive domains
Transforms input into new output Centralizes shared output for use as shared input
Redundant transformations are grouped together
until no redundant transformations exists
Shared input and output is grouped together until
no redundant shared input and output exists
What can ‘I’ transform without redundantly
compete with others in the group?
Who can ‘I’ help with shared output without
redundantly compete with others in the group?
By using these two types and their characteristics you can optimize a landscape during the
design process.
LUXE-Tooling and methodology manual
2013, Groningen Page 30 of 37
6.2 Define the information that you communicate and not the data you have
A Common Information Model (CIM) is fundamentally different than a Logical Data Model
(LDM). Many ICT-professionals are not used to the idea of defining a CIM that is not build
upon their own data model. The biggest difference is that a LDM contains the data you have
and a CIM contains the information you communicate.
Company
Logical Data Model
Client
Logical Data Model
Supplier
Logical Data Model
Company ClientCommon
Information Model
SupplierCommon
Information Model
Data you have
Information you communicate
This principle also applies to information exchange within a company. Generally it’s easier to
create a CIM within a company than trying to create a very large LDM. CIMs that are
correctly created are in some cases 1% as large as the data oriented ones, because instead
of focusing on the data of all the domains, they only contain the (minimal) information the
domains require or produce.
Two issues are most common (and often happens simultaneously);
• A too detailed CIM because it’s a composition of all the LDMs,
• A too generalized CIM because it’s a generalization of all the CIMs.
The relationship between the communicating domains determines the context of a CIM.
These relationships create different contexts, so CIM models (as with all models) can’t be
stacked up or generalized indefinitely without losing context sensitivity; There cannot be ‘one
CIM to rule them all’. By definition a CIM must be able to link with other CIM’s without
consuming it. To create linkages semantic annotations are required (see paragraph 2.3).
In practice some basic questions help to sometimes remove 4 out of 5 definitions out of a
CIM without hurting the integrity. 1) Is the definition you purpose communicated? 2) Is this
definition data you have or is it information that you require/produce?
LUXE-Tooling and methodology manual
2013, Groningen Page 31 of 37
6.3 Use iteration to create consistent designs
Information is unlocked by a service and is always required and provided by a domain. When
the design meets these conditions it’s a valid design. These conditions can be achieved using
the following iterations during the thinking process:
You start thinking; “Domains provide Services unlocking Information required by (other)
Domains”. The reverse iteration must be used as well: “Domains require Information
unlocked by Services provided by (other) Domains”. When you can iterate through both
cycles the design is consistent.
6.4 Go ‘top-bottom’ and ‘bottom-up’ to validate designs
The combination of the methodology
and the LUXE-Tooling provides the
ability to develop draft versions of
designs and implementations in
minutes. Use this advantage to
feedback issues during the design
phase.
Use the validation wizards to detect
inconsistencies and use the update
wizards to drill down new additions.
No one can create a correct design in
its first go. It’s normal to move up
and down.
When a draft XML-Schema and/or WSDL is entered into a system a ‘real-life’ check can be
done if all the elements and/or definitions are in place. This greatly reduce the testing and
retesting time during the implementation phase.
Messages and Services
Measurement serviceRequest
Response
Technical implementation
Common Information Model
Contract
- Identif ier: Identif ier
- Vali dFrom: DateTime
- Vali dTo: DateTime
Measurement
- Vali dFrom: DateTime
- Vali dTo: DateTime
- Quantity: QuantityType
- Version: Numeri c
Connection
- Identifi er: Identi fier
- Type: ConnectionType
Supplier
- Identif ier: Identif ier
- Name: Text
- Address: AddressType
Client
- Identif ier: Identif ier
- Name: Text
- Address: AddressType
Inv oice
- Identifi er: Identifi er
- CreationDate: Date
- Quanti ty: Quantity
0..*
0..*
0..*
1..*
10..*1 0..*
0..*
0..*
LUXE-Tooling and methodology manual
2013, Groningen Page 32 of 37
Allocation
- ValidFrom: DateTime
- ValidTo: DateTime
- Status: AllocationStatusType
- Version: Numeric
- Energy: EnergyType
6.5 Be aware of basic rules of normalizing objects, messages and services
Basic rules of normalization do apply when creating a CIM, messages and services. Basic
rules of normalization are derived from Codd (Codd, 1970). To explain them an Allocation
example is drawn from the PhD.
ValidFrom ValidTo Status Version Energy
2010-03-31 10:55Z 2010-03-31 11:00Z Prognosis 10000 kWh
2010-03-31 09:00Z 2010-03-31 10:00Z Preliminary 10000 kWh
2010-03-31 08:00Z 2010-03-31 09:00Z Preliminary 10000 kWh
2010-03-31 07:00Z 2010-03-31 08:00Z Preliminary 10000 kWh
2010-03-31 06:00Z 2010-03-31 07:00Z Preliminary 10000 kWh
2010-03-30 05:00Z 2010-03-31 06:00Z Accountable 1 10000 kWh
2010-03-30 05:00Z 2010-03-31 06:00Z Accountable 2 10000 kWh
Allocation
Functional width
Vo
lum
e/C
ap
acity
1
2
3
4
5
6
7
An object must be composed independent of period, time, granularity, status, version,
source(system), unit or process owner. As you can see they are simply attributes of an
object and represents different records in a table. Therefore they should not be arguments to
split-up an Allocation into a PrognosisAllocation and PreliminaryAllocation object.
These rules do apply for services and messages as well. Take a look to the following example
in which 4 services where created to retrieve different types of allocations.
FuturePresent
PrognosisPreliminary
Past
Accountable
Online allocation processOffline allocation process
>36 hour (Application B) < 36 hour (Application A)
Version 1Version 2Version n*
Publish operational prognosis allocation
Publish operational preliminary allocation
Publish analyses preliminary allocation
Publish analyses accountable allocation
Allocation life cycle
Services
During a life-cycle a Allocation can be produced by multiple IT-applications within different
processes. It can be created at different moments in time and can have multiple statuses,
granularity and versions. Arguments like 'it’s a different application' or 'we see two different
types: 5 minute allocations an 1 hour allocations' are not valid reasons to split-up a message
or service.
This does not mean they are not valid arguments at all. They are good arguments to solve IT
technical issues like scalability, availability, reliability and infrastructure.
LUXE-Tooling and methodology manual
2013, Groningen Page 33 of 37
In this case it should only be one service with parameters to filter the return. An example of
a good service could be answering the following question: "Give me the Allocation within a
specified period (ValidFrom,ValidTo), with a particular energy unit (kWh or MJ), with a
specific status (Prognosis, Preliminary, Accountable) and in a specific granularity (5 minutes,
1 hour)".
6.6 Break through the reuse XML-Schema fundamentalism
Due the model driven approach of the methodology in which the relations and reuse of
objects are managed at the model level, XML-Schema modularity on the implementation
level is redundant, and even threatening.
While message elements of different messages are maybe derived from the same
centralized definition, message elements of different messages are not equal to each other.
Common Information Model (Modelled in a LOM)
«ABIE»
Connection
«BBIE»
+ Identifier: Identifier
«ABIE»
Connection
«BBIE»
+ Type: ConnectionType
Message 1 Message 2
Connection
- Identifier: Identifier
- Type: ConnectionType
tags
modelReference = urn:luxe:1:#Connection
«derivedFrom»«derivedFrom»
≠
Even if the structure of derived elements looks the same still semantically it’s not equal to
each other because they are derived with different motivations (= a different context). This
also applies to LDTs. LDTs are also centrally defined and then derived to each message. In
many cases LDTs must be specialized even further at the message level as well, as explained
in paragraph 3.8.
Reusing message elements across messages creates a complex set of interdependencies
between dozens of unrelated messages and implementations over time, resulting in a very
sluggish and difficult design- and implementation process. Each minor change to a CIM
object or message element in the design phase have to be scrutinized and have (unintended)
consequences for (hundreds of) unrelated but technical intertwined implementations.
LUXE-Tooling and methodology manual
2013, Groningen Page 34 of 37
This does not mean that the initial responses of developers and others are unfounded; this
reaction must be taken serious. The initial consequence of the self-contained messages is the
increase of repetitive manual activities on the implementation level.
First of all, modelling means that the output will contain a far more consistent set of
implementations and therefore it will create by definition a larger number of ‘stupid’
repetitive activities. Secondly, this situation should be a motivator (instead of a roadblock) to
automate the manual repetitive activities.
One of the repetitive activities are the mappings between the message elements and an
object of a IT-system. This mapping can be automated by using the Semantic Annotation
option of paragraph 2.3 recommended by the designers of XML-Schema (W3C).
Semantic annotations are unique identifiers for each object and attribute in a LOM from which
the message elements are derived from. A ‘modelReference’ tag containing this unique code
will be placed for each message element in the XML-Schema7.
A message element containing a modelReference tag which refers to the original LOM object <xsd:complexType name="PublishConnectionReponse_Connection" sawsdl:modelReference=”urn:luxe:1#Connection”>
<xsd:sequence>
<xsd:element name="Identifier" type="ccma:Identifier“ sawsdl:modelReference=”urn:luxe:1#Connection.Identifier” />
</xsd:sequence>
</xsd:complexType>
In the following mapping table the modelReference tags are linked to the object used by a
IT-System.
Mapping table
modelReference Maps to object:
urn:luxe:1#Connection Application.OwnDataModel.NetworkPoint
urn:luxe:1#Connection.Identifier Application.OwnDataModel. NetworkPoint.Id
These modelReference tags can be used to automate repetitive mappings. This requires a few
lines of automation code in a mapping tool. First the modelReference tags are loaded from the
XML-Schema. Each modelReference is looked-up in a mapping table in which is stated to which
object a modelReference is mapped to. When the modelReference is present, the mapping
tool will be configured to create a mapping between the message element and the related
object.
The following step is to add manually the mappings that where left. When the mapping is
completed the new mappings are added to the mapping table. With this approach the
mapping tool will learn after a view messages to automate most of the mappings based on
the same semantic model.
Next to automating the mapping, the structure of messages can be different without having
to create a different mapping as well. In the following example you will see two separate
messages elements. Both are derived from the same LOM object but have different
structured names and namespaces. However, they both have modelReference tags attached
to it.
7 W3C Semantic Annotations for WSDL and XML-Schema
LUXE-Tooling and methodology manual
2013, Groningen Page 35 of 37
A message element from message 1: <xsd:complexType name="GetMeteringPointReponse_MeteringPoint" sawsdl:modelReference=”urn:luxe:1#Connection”>
<xsd:sequence>
<xsd:element name="Identifier" type="ccma:Identifier“ sawsdl:modelReference=”urn:luxe:1#Connection.Identifier” />
</xsd:sequence>
</xsd:complexType> A message element from XML-Schema 2:
<xsd:complexType name=“NWP" sawsdl:modelReference=”urn:luxe:1#Connection”>
<xsd:sequence>
<xsd:element name=“Id" type="ccma:Identifier“ sawsdl:modelReference=”urn:luxe:1#Connection.Identifier” />
</xsd:sequence>
</xsd:complexType>
Mapping table
modelReference Maps to object:
urn:luxe:1#Connection Application.OwnDataModel.NetworkPoint
urn:luxe:1#Connection.Identifier Application.OwnDataModel. NetworkPoint.Id
If the mapping is created for the first element, the same mapping can be used for the second
element. This will allow a larger degree of freedom for structuring messages and even ‘old’
messages can be reused with semantic models and vice-versa.
LUXE-Tooling and methodology manual
2013, Groningen Page 36 of 37
Appendix
LUXE-Tooling and methodology manual
2013, Groningen Page 37 of 37
1 Validation Rules
The validation rules are used by the validation wizards of the LOM (paragraph 2.2),
messages (paragraph 3.4) and services (paragraph 4.1).
Validation Rule Level
LOM Object
LOM Attribute
LOM Connector
Logical Data Type
Primitive
Message Object
Message Root Object
Message Attribute
Message Connector
Service Sequence
Name only contains a to z characters and 0 to 9 numerics 1: Error x x x x x x x xName must start with a capital a to z character 1: Error x x x x x x xCan only be of UML class type 1: Error x xCan only be specialized from one parent object 1: Error xDatatype must be a Logical Data Type 1: Error x xDependency, Generalization and Association are the only connector types 1: Error xMust be of unidirectional (bidirectional) type 1: Error xNo duplicate SequencingKey is allowed in a group of Connectors 1: Error xMust be specialized from one Primitive 1: Error xSpecialized from a Primitive ‘composition’ must be stereotyped with LDT or CDT 1: Error xSpecialized from a Primitive ‘composition’ must contain at least one Attribute 1: Error xSpecialized from a Primitive ‘enumeration’ must be stereotyped with LDT or EDT 1: Error xSpecialized from a Primitive ‘enumeration’ must contain at least one Attribute 1: Error xSpecialized from a Primitive other than ‘composition’ and ‘enumeration’ must be stereotyped LDT 1: Error xMust only be specialized to a Logical Data Type 1: Error xMust start with a lower a to z character 1: Error xHave only directed Association with a Aggregation at Source End 1: Error x xMust be derived from a LOM Object indicated with a dependency stereotyped ‘derivedFrom’ 1: Error xMust be stereotyped ‘ABIE’ 1: Error xMust be stereotyped ‘MA’ 1: Error xOnly one Object stereotyped with ‘MA’ is allowed in the same package 1: Error xMultiplicity must be equal or higher to lower bound specified in related LOM element 1: Error x xMultiplicity must be equal or lower to higher bound specified in related LOM element 1: Error x xData type must equal to Data type specified in related LOM element 1: Error xMust be stereotyped 'BBIE' 1: Error xMust be derived from a Connector in related LOM element 1: Error xOnly one Sequence object stereotyped 'Service' is allowed in the same package 1: Error xMust have transactions with only one Actor 1: Error xNames of transactions are equal to message root object name of messages imported/used 1: Error xRelated connectors with this element at Source End must be stereotyped 'ASBIE' 1: Error xRelated connectors with this element at Source End must be stereotyped 'ASMA' 1: Error xSequencingKey must be equal to SequencingKey of related LOM element 1: Error xShould contain a description in the notes field 2: Warning x x x x x x xMay contain a SequencingKey Tagged Value on connector source and/or target 2: Warning xMay contain SequencingKey Tagged Value 2: Warning xMay use ‘Alias’ field for assigning a reading name 3: None x x x x x x x x x xMay contain a modelReference Tagged Value 3: None x x x x x xMay be specialized from another object 3: None xMay use a ‘Role’ name for defining an alternate name to a connected object 3: None xSpecialized from a Primitive ‘enumeration’ the attributes represents the enumeration values 3: None xMay contain a choiceGroup Tagged Value 3: None x