version 1.1 May 24, 2006
Modelling
Methodology
Status: Approved
Version/release: 1.1
Revision:
Date:
-
May 24 th , 2006
C O N T E N T
Milestone 5: Business information model and translation guides approved ................ 18
6 TRANSITION, MODEL TO TECHNICAL/PROCEDURAL DOCUMENTS..................... 33
ebIX Modelling Methodology 2
T RANSLATION GUIDE , FROM UML CLASS DIAGRAMS TO EDIFACT .................................... 33
Steps in making the translation guide (To be further elaborated)................................. 33
T RANSLATION GUIDE FROM UML CLASS DIAGRAMS TO XML ............................................. 34
APPENDIX A USECASE DESCRIPTION TEMPLATE......................................................... 41
APPENDIX B ISO/IEC 14662, OPEN-EDI REFERENCE MODEL ...................................... 42
APPENDIX C EXAMPLE OF NATIONAL DOCUMENTATION ........................................ 44
APPENDIX F BUSINESS DOCUMENT SETS IN EDIFACT ................................................ 50
ebIX Modelling Methodology 3
ebIX Modelling Methodology 4
1 Introduction
1.1
About this document
The ebIX methodology is written mainly as a guide for ebIX projects and working groups, to help them in their work. The methodology describes items such as how to create ebIX projects, how to do modelling according to ebIX rules, how to make changes to models and business documents, etc.
1.2
Objective
A deregulated European energy market consists of several different business process areas operated by a number of parties with different roles. Each of these business process areas has their own business experts with an in-depth knowledge of the business process within their area. Making common electronic data exchange standards for these different business process areas, involving different business experts, requires a common methodology to assure that standards are made in a harmonised way. The objective of ebIX is to model precisely these different business process areas and to define appropriate electronic data interchange standards for the different business process areas. Accordingly, this has led to the development of a methodology, which defines the rules for how to make ebIX business information models and related technical documents for specification of the exchange of electronic documents.
The objective of this document is to describe a methodology for running ebIX modelling projects and to produce an ebIX business information model for a defined business process area, or part of a business process area, within the energy market. The aim is to enable the ebIX project groups, with different participants and different business experience, to produce harmonised descriptions for the implementation of information exchanges . Having a common methodology as the basis for the ebIX projects will make it possible to implement different business process areas in a harmonised way.
The first part of the methodology describes an ebIX project outline. It is an 9-step process, which concludes with a business information model, a set of translation guides and eventual changes to the ebIX Core Components, code lists or other registries/repositories maintained by ebIX. The business information model will be approved by the ebIX Forum and posted on the ebIX web site for implementation.
The second part of the ebIX methodology introduces the UN/CEFACT Modelling Methodology
(UMM) and shows the artefacts and main terms used within UMM. This part is meant as an introduction to UMM for business experts from the energy market, participating in ebIX projects, without a profound knowledge of UMM. Note that this part of the document not is a complete description of UMM and it is expected that business modellers with a deeper foundation in UMM will be responsible for the layout of the business information models.
The later parts of the ebIX methodology provide rules for the layout of the documents made in ebIX projects and more detailed technical rules for document content.
1.3
ETC, ebIX Technical Committee
The ebIX methodology is maintained by ETC. If there is comments or suggestions to the methodology please contact any member of ebIX/ETC.
Current members of ETC are:
Name Company Country Telephone/Mobile E-mail
Carl Major
Christian Odgaard
Hans Montelius
Hugo Dekeyser
E.ON Netz
Eltra
SvK
Electrabel
Jon-Egil Nordvik (Convenor) Statnett
Kees Sparreboom TenneT
DE
DK
SE
BE
NO
NL
+49 5132 88 2179 Carl.Major@eon-energie.com
+45 76 22 44 63 Christian.odgaard@eltra.dk
+32 4 77 5580 03 hans.montelius@svk.se
hugo.dekeyser@electrabel.be
+47 975 36 303
+31 622 66 7911 jon-egil.nordvik@statnett.no
kees.sparreboom@cgey.nl
ebIX Modelling Methodology 5
Matti Vasara (Observer)
Ove Nesvik (Secretary)
Terje Nilsen (Observer)
Fingrid
EdiSys
Nord Pool
FI
NO
NO
+358 405 19 50 17 Matti.Vasara@fingrid.fi
+47 928 22 908
+47 930 34 100 ove.nesvik@edisys.no
terje.nilsen@nordpool.com
1.4
References
[1] UN/CEFACT Unified Modelling Methodology, see http://www.unece.org/cefact/umm/umm_index.htm
[2] UN/CEFACT Core Component Technical Specification, see http://teheran.mminf.univie.ac.at/untng_mambo/
[3] ebIX model for customer switching, see http://www.ebix.org/
[4] The Harmonised Role Model – ETSO, ebIX and EFET, see www.edi.etso-net.org
Note:
The Role model describes a model identifying all the roles that can be played for given domains within the electricity market. The roles are of a logical nature (such as a trade responsible party), which act within a given domain (such as a balance area) and shall always define specific responsibility. A prerequisite for the identified roles is that the responsibilities of the roles must be mutually exclusive in the model. The document covers the roles as identified in current development being carried out in information exchange. It will naturally grow or evolve as this work progresses.
[5] ebIX Common rules and recommendations, see http://www.ebix.org/
[6] ebIX Domain model, see http://www.ebix.org/
Note:
The purpose of the Business Domain Model is to show the structure and dynamics of the
European energy industry. It ensures that all users, standards developers and software providers have a common understanding of the business domain with no special focus on an electronic commerce solution. The domain is divided into sub domains showing UseCase analysis on each sub domain. All modelling done within ebIX will be carried out on a part of the business domain model. The Business Domain Model shows the scope of the business domain, business domain
UseCase diagram and description and business domain activity diagram.
[7] ebIX Core Components (CC), see http://www.ebix.org/
[8] Unified Modeling Language™ (UML®), version 2.0, see http://www.omg.org/technology/documents/modeling_spec_catalog.htm
1.5
Change log
Ver. Rel. Rev. Date
1
1
1
0
-
-
January 2006
Changes
Restructured version
March 31 st , 2004 First version ebIX Modelling Methodology 6
2 Brief methodology description
As a basic principle the ebIX methodology shall be used for all ebIX projects. This methodology is based on the standard UMM methodology using the UML modelling language. In the ebIX methodology we use at the moment up to a maximum of four elements of UML:
Use case diagrams
Sequence diagrams
Activity diagrams
Class diagrams.
2.1
UseCase
In a UseCase stylised descriptions of the working fields in the sector are presented. This is done in a hierarchy of linked UseCases. Each working field specifies the roles active in this field. As an example you find below the top-level ebIX UseCase for the energy sector (this is only a preliminary version!).
Figure 1 UseCase example (Business domain)
For a certain project not all elements in this UseCase are relevant. Pick the relevant element with its relation out of the overall UseCase and start detailing the UseCase for the current project. As can be seen in the diagram below (for metered data). ebIX Modelling Methodology 7
Figure 2 UseCase example (Business process area)
And continue detailing if needed. ebIX Modelling Methodology 8
2.2
Sequence diagrams
The next step is to define the information exchange relations in the lower level UseCase diagrams. In this step we have to define the business documents to be exchanged between roles. The business documents and roles are only identified, but not specified. An example is given below.
Figure 3 Sequence diagram example
This sequence diagram describes (part of) the information exchange between the role metered data collector and the role metered data aggregator regarding metered time series. ebIX Modelling Methodology 9
2.3
Activity diagram
The next step is to describe how the roles act in the sequence diagram. Naturally, the description of the activities shall be limited to the handling of the information exchange, since the main objective of standardising the interface between parties or roles is not to interfere with the processes “inside the party”.
The example given below is drawn from the ebIX Customer Switch project.
Figure 4 Activity diagram example
Each sequence diagram shall be accompanied by one or more activity diagrams.
2.4
Class diagram
The last step in modelling according to the present ebIX methodology is the specification of the class diagram for each business document exchanged in the sequence diagrams. In more familiar terms this means a data model for each business document type exchanged. ebIX Modelling Methodology 10
The example you find below is also drawn from the ebIX Customer Switch project (Class diagram:
392 Request for change of metering point master data). ebIX Modelling Methodology
Figure 5 Class diagram example
11
2.5
Complete model: more than pictures alone
The complete model is more than just pictures. The pictures that are the result of the formal modelling are described in accompanying text. The combination constitutes the complete model.
2.6
Cascade or iteration?
In modelling one can distinguish two basic principles: cascading and iteration. Cascading means that you start one phase and complete it before you move on to the next phase. Iteration means that you go back and forth between two (or even more) phases until each phase is completed. In UMM you start with a cascade and iterate when needed. There shall always be scope for going back one or more steps if we find an error or omission in previous phases.
2.7
From model to business document
Once we have completed the model, we have not yet finished, as the ultimate objective of the project is to specify the actual exchange of information.
This means that finally we have to:
translate the class diagrams into EDIFACT messages and/or into XML-schemas;
translate activity diagrams into procedures.
2.8
Combining common elements
Once we have started the modelling we will find that there are some elements that appear time and time again in most diagrams. In ebIX it is the task of the ETC to define those common elements for all ebIX projects, for example confirmation and rejection procedures plus business documents. And, we have the Functional Description to define basic principles for all business documents (how to define date/time, how to use UTC, etc.).
2.9
Room for national standards
In doing this we shall always have to bear in mind that we are specifying the common elements for all participants in the European energy market. There are, however, differences between national markets and national procedures. So one might expect that we have to leave room for national detailing.
Nevertheless it should be our aim to harmonise as much as possible, since each national specialty means an obstacle for a truly open European market. ebIX Modelling Methodology 12
3 ebIX projects
The ebIX modelling methodology is a further development of the methodology agreed between ebIX,
ETSO and EFET and includes further artefacts from the UMM to produce a comprehensive methodology for the market or sector. It is aimed at the production of an ebIX business information model for a defined business process area, or part of a business process area, within the energy market.
It is an 9-step process with 5 key milestones that concludes with a business information model and a set of translation guides, approved and posted to the ebIX web site for implementation. ebIX Modelling Methodology 13
3.1
The ebIX Methodology outline ebIX Modelling Methodology
Figure 6 ebIX methodology outline
14
The outline respects the essential of the UN/CEFACT methodology. However since the key deliverable is not the same, the methodology cannot also be the same. In the UN/CEFACT methodology the key deliverables are a library of business objects and business processes, whereas the key ebIX deliverable is a business information model that can be put into operation by the parties to satisfy a given business need. The five key milestones have been provided in order to facilitate project management. Each of the milestones identifies a significant and measurable point in the project. Each of the 9 steps can be resumed as follows:
1.
Prior to any project development a business process area, or part of a business process area, for development has to be identified and approved. Any ebIX participating member may submit a development area for consideration. The submission method or content has not been formalised. It is the knowledge within the evaluation team of business practises covering several countries that will determine the validity or not of setting up a project.
2.
Once the development area is approved a project team is set up to prepare a detailed project plan .
This plan once approved will form the basis of all future development work. It provides a perspective of the area that is to be covered and the expected deliverables. Once the project plan has been approved the first milestone of development has been reached.
3.
Project development then begins and UseCase diagrams are produced which detail the project requirements.
4.
The UseCase diagram from step 3 must be compared with the relevant part of the ebIX Domain
to see if the two UseCase diagrams are aligned. In the case where the ebIX Domain
does not cover all the processes defined within the project a modification request is initialised in order to adjust the
5.
The requirements having been described, the
is aligned with the projects scope and the scope of the project is outlined within the Harmonised role model,
the case where the role model does not cover all the roles or domains necessary to satisfy the project requirements a modification request is initialised in order to adjust the role model once the business process development has confirmed their use. Once the project requirements have been scoped within the role model the second milestone of development has been reached.
6.
The business processes are then developed using sequence diagrams and activity diagrams .
Through these diagrams the workflow of the business processes in question is developed. This process refines the project’s scope and if the maintenance request for new roles or domains identified in the preceding step is confirmed or additional roles or domains are identified the maintenance request is submitted to the
Harmonised role model, [4] , maintenance group (
To be defined) . The role model adjustment may be an iterative process and will continue until the project’s scope has been successfully integrated into it. This process may additionally require modifications to the project requirements. The approval of the business processes signifies that the third milestone of development has been reached.
7.
From the business processes and workflow diagrams the required set of information requirements can be identified. Each business document identified between two roles that are determined as being a candidate for automation is modelled through the use of class diagrams . The ebIX core components are interrogated to make use of existing objects or core components. New core components are added to the repository if necessary (this process has not yet been completely mapped out). The approval of the information model signifies that the fourth milestone of the development has been reached.
8.
From the class diagrams translation guides are generated respecting the generation rules that have been defined for this transformation process.
9.
The business information model is written up in compliance with the layout key for ebIX documents. The approval of the business information model signifies that the fifth and final milestone of development has been reached. The approved business information model is then inserted in the ebIX web site for implementation.
The requirements necessary to satisfy each of the milestones will be covered in more detail in the next chapters of this document. In relation to the UMM one can easily see that the inception phase which addresses the workflows of business modelling and requirements are covered by the first three ebIX Modelling Methodology 15
milestones, and the elaboration phase which addresses the workflows of analysis and design are covered with the fourth milestone. The fifth milestone is not addressed within the UMM.
3.2
Milestone requirements
3.2.1
Milestone 1. Project approved for development
The initial phase of starting up an ebIX process is to prepare a project plan . A project plan can only be developed against an approved development area.
The project plan will contain the following:
1. Presentation of the project,
2. Outline of the goals and benefits
3. Explanation of how it is going to be organised,
4. Description of the deliverables,
5. Establishment of the initial timetable,
6. Declaration of needed resources,
7. Presentation of the development costs.
The presentation of the project will describe a single and complete business process area, or part of a business process area. It will provide the framework for the future development.
The goals must be clearly stated and measurable.
The organisation of the project will identify a project leader and the team that is going to work on the project. The members of the team must have a commitment from their organisation that they, or their replacement, will follow the project through to completion.
The deliverables, which are generally one business information model and a set of translation guides, will define what is to be expected when the project has been terminated.
The initial timetable will be built identifying the key development milestones. For example, the four milestones of development could be used as the principal milestones for the development of the deliverables. The milestones are not necessarily limited to those outlined in this methodology.
However, the basic milestones must be outlined as a minimum.
If external consulting resources are to be used these should be identified here along with any travel costs that may be required. ebIX members finance the project through their time, where their expected contribution is over and above the normal time necessary for meeting preparation and meeting time then this should be identified.
The key deliverable of this milestone is the project plan, which has to receive official ebIX approval before the project itself can be launched. It is recommended that the approval process in question be identified in the project plan.
3.2.2
Milestone 2: Scope defined
The initial task of the project is to situate it within its general context and in more detail. Once the context has been defined through the development of a UseCase , all the roles necessary to complete the task will have been identified. ebIX has together with ETSO/TF-14 and other organisations developed the Harmonised role model ,
This role model is a living model that outlines all the roles and domains with their principal interactions within the industry. It is consequently not necessary in the preparatory stages to spend a ebIX Modelling Methodology 16
significant amount of time working on the overall business domain. This task is already catered for within the role model.
However, during the development of the project requirements it may happen that roles that have not previously been identified may appear. The project should prepare a maintenance request to change the role model. This request will be confirmed during the next development phase.
The key deliverables at this milestone is as follows:
An eventual revised version of the role model along with the maintenance requests outlining the revisions;
An outline of the project scope identifying all the roles and domains in the role model that will come into play in the project;
The initial version UseCases describing the requirements and their explanatory text.
3.2.3
Milestone 3: Business process defined
The business process analysis stage builds on the UseCases that have been developed during the project requirements stage. It introduces activity and sequence diagrams that show the interactions between the various roles. These are placed in the context of the UseCases previously defined.
The UseCases may be refined at this milestone, as more information becomes available. This provides clarification to more detailed points that are not necessary during a requirements development process.
For example more detailed UseCases may de developed to show up particular contexts that are necessary in order to describe completely the business process in question.
However, if a UseCase described during the requirements step is completely put into question then it may be necessary to reiterate the requirements phase completely.
This stage of the methodology will also identify the workflow requirements for the business process. It will identify all the information flows (business documents) between the different roles that are necessary to satisfy the requirements. The relationships between the information flows will also be developed.
The need for any new roles or domains is confirmed and appropriate maintenance requests are submitted to the role model maintenance group. The role model maintenance process may immediately approve the new role or they may require clarification or suggest the use of another role.
This is an iterative process that shall continue until the project has a satisfactory solution to the roles that it wishes to present in its project requirement and business information models.
The key deliverables at this milestone are as follows:
The finalised version of the business process UseCases and the associated explanatory test.
The activity, sequence diagrams and associated text describing the interactions between the roles. This includes workflow requirements for the business process and business documents between roles necessary to satisfy the business requirements.
If any, the finalised role model maintenance requests.
During this activity the first versions of the Class diagrams should be made. Knowing the rough content of the business documents makes it easier for the project group to discuss the sequence and activity diagrams.
3.2.4
Milestone 4: Information requirements defined
All the business documents that have been identified will be further analysed to identify their content.
Class diagrams will be used for this purpose. If an attribute within a given class is conditional then a dependency matrix identifying the conditional where the attribute must figure must be provided. ebIX Modelling Methodology 17
During this analysis the ebIX core components will be examined in order to determine whether or not existing objects or components will satisfy the requirements. If so, they will be introduced into the model.
If a core component could satisfy the requirement with the adjustment of the definition then a maintenance request should be placed against the ebIX core components repository. The use of subtyping (or generalisations) is encouraged at this stage.
Ask ETC for a new core component if an equivalent core component cannot be found.
For certain core components there are associated code lists. Ask ETC for a code if a new code is required.
If the contents of an new object are identical to an existing core component and there is only a difference of object name then the initial object should be used and a the new object shall be added as a synonym to the initial object in the CC registry.
The key deliverable at this milestone are a set of class diagrams, their associated definitions along with, if necessary the dependency matrices that qualify the mandatory use of conditional class attributes and the codes that are intended to be used.
3.2.5
Milestone 5: Business information model and translation guides approved
The ebIX project chooses which syntax to be used, either XML and/or EDIFACT. For each syntax a translation guide has to be generated.
Generate XML translation guide
The XML translation guide has to be generated from the UML class diagram for each information flow (business document) that is a part of the business information model. The generation process
UML class diagrams to XML]. These rules enable the production of an XML DTD.
From the DTD in question an XML Schema is produced making use of core components. The ebIX core component repository will be updated with any new core components or context specific core components as needed.
The DTD and the Schema form the basis of the XML translation guide.
Generate EDIFACT translation guide
The EDIFACT translation guide has to be generated from the UML class diagram for each business document that is a part of the business model. The generation process must respect the rules as defined
in the basic rules for EDIFACT generation [see 6.2.1 Translation guide, from UML class diagrams to
EDIFACT]. These rules enable the production of a subset of an EDIFACT message.
The production of the EDIFACT translation guide makes use of core components. The ebIX core component repository will be updated with any new core components or context specific core components as needed. ebIX Modelling Methodology 18
4 Modelling within ebIX
The basis for all modelling within ebIX is the UN/CEFACT Modelling Methodology (UMM). The
UMM employs a “step by step” approach to capture the business knowledge from business analysts in non-technical terms, independent of any specific modelling tool. The energy business environment is large and complex. Any basic understanding of this environment begins with information and documentation. The UMM is an incremental business process and information model construction methodology that provides levels of specification granularity suitable for communicating the model to business practitioners, business application integrators, and network application solution providers.
The UMM provides the conceptual framework to communicate common concepts.
The UMM is targeted to the modellers and facilitators working with the business experts to extract their business knowledge. They need a high-level understanding of the concepts behind OO modelling, business process modelling, and some rudimentary knowledge of UML in order to utilize the UMM. ebIX business information models will always reflect the core business need for a majority of the countries participating in the ebIX project. National exceptions and additions will not be a part of a core ebIX business information model.
In this chapter the modelling principles used within ebIX is detailed. Chapter 4.1 describes the
structure of the ebIX business information model to be developed. The rest of chapter 4 describes rules for how to deal with other subjects, such as core components, dependency matrices and acknowledgments.
4.1
The structure of a business information model
An ebIX business information model shall be structured according to the different levels defined in
UMM. The business information model will consist of several modelling business objects documented in a hierarchy. On the bottom of this hierarch are the ebIX and UN/CEFACT core components, which is the building blocs of the ebIX business documents. The flow of the business documents is shown in business transactions, business process etc., according to the following structure:
The following modelling business objects are identified, described and maintained by ETC:
Business domain : The business domain is the highest level of modelling of the
Business area : energy industry and describes all relevant business areas identified in the European energy marked.
The business domain is split into several business areas.
In the energy market the business areas are defined as phases in the
Business process area : market, such as the planning-, trading- and settlement phase. The
UseCase models of the business areas are included in the ebIX business domain model.
A business process area is another first level decomposition of the business domain model , in a manner that is orthogonal to the categories chosen for the business areas . For example, the metering business process area is used in several of the other business areas in the business domain model, such as in structuring, settlement and reconciliation.
One reason for identifying both the Business area and the Business process area is to be able to separate between development and maintenance. Often the development will be assigned to projects describing a Business process area, while maintenance probably will be done for one Business area at the time. ebIX Modelling Methodology 19
The following modelling business objects are identified and described in ebIX projects:
Business process : A business processes is the means by which one or more activities are accomplished in operating business practices. It is conducted between two or more parties.
Business transaction : A business transaction is a set of business information and business signal exchanges between two business partners that must occur in an agreed format, sequence and time period. The ebIX models shall be based on the pre-specified business transaction patterns from
UMM, i.e. Commercial Transaction, Request/Confirm,
Query/Response, Request/Response, Notification or Information
Distribution.
Business document : A business document is a set of information components that are interchanged as part of a business transaction , such as a request or a notification. It will be shown as an arrow in a sequence diagram and will be described as a class diagram.
Other modelling business objects terms used in the ebIX methodology:
Core components (CC): The lowest level in a business information model and the building blocks of the ebIX business documents.
The class diagram below shows the relationship between the different levels of the modelling business objects and the documents produced in an ebIX modelling project.
Figure 7 Documents produces in an ebIX modelling project
An ebIX business information model will describe a part of, or the whole of, a business process area or a business area: ebIX Modelling Methodology 20
Figure 8 Business areas and business process areas
The business information model will describe the business objects using UML artefacts according to the UMM. In this chapter the content and items to be aware of in each level of the ebIX business information model is described.
The main document made in an ebIX modelling project is the Business information model document.
This document describes the business processes, transactions and business documents using the UML artefacts UseCase diagrams with connected UseCase descriptions, sequence diagrams, activity diagrams and class diagrams, as shown below:
Figure 9 The structure of a business information model document ebIX Modelling Methodology 21
4.1.1
Business area
The first level of decomposition of the energy market business domain model is the business areas. A business area consists of a series of business processes. One or more ebIX business information models, such as the ebIX business information model for customer switching, will describe each business area. The upper level of an ebIX business information model will always refer to the ebIX business domain model and describe the business area(s) where it belongs.
The business areas are documented in the ebIX business domain model by a business area UseCase diagram and a connected UseCase description.
4.1.2
Business process area
An ebIX business information model will describe a business process area or a business area. A
UseCase diagram and its related UseCase description are used to document the business process area.
At this level of the ebIX business information model all the general descriptions are placed, such as the objectives and scope of the business information model and the relevant subset of the Harmonised role model
, [4], showing the roles and domains relevant for the business information model.
Business process areas show the first level of decomposition of the business domain model, in a manner that is orthogonal to the categories chosen for the Business Areas. This is shown in the
UseCase diagram below, which shows the business process area of Read meter as an extension from the business area customer switching.
Figure 10 Business process area
The first version of the model of the business area or business process area is made during step 3, 4 and 5 of an ebIX project. During the later steps of the modelling project the business process area is reviewed and changed if needed.
4.1.3
Business process
A business process is documented by the following artefacts:
UseCase diagram
UseCase description (including related business processes)
Sequence diagram
Activity diagram.
(Experiences from the ebIX project groups will at a later stage be used for making additional rules for the number of artefacts and relations between the different types of artefacts).
The sequence diagram will show the business documents needed to carry out the full business process. ebIX Modelling Methodology 22
If a business process triggers another business process, this shall be shown in the activity diagram as a sub-activity.
For the ebIX projects developing a business processes, the UseCase description is the primary vehicle for gathering detailed requirements. The requirements are specified as single concept sentences in the following categories:
1) Static relationships that must exist between entities, e.g. Business agreements have been made between the relevant roles and parties must be able to communicate electronically with each other.
2) Normal dynamic relationships that must exist between activities, e.g. a meter stand man need to validated before responding to a request.
3)
“Exception” conditions, e.g. in some countries, when customer moves out, the old Consumer may contact the Grid access provider instead of the Balance supplier.
4.1.4
Business transaction
A business transaction is a set of business documents exchanges between two business partners that must occur in an agreed format, sequence and time period. A business transaction has a defined start and end. In other words if you are still 'waiting' for your business partner's response or reaction, the business transaction has not been completed.
A business transaction can be used in several business processes, which make the documentation and implementation easier. If a business document is used in several business processes, the business transactions must have different “Reasons for transaction”.
The actual information content of the business document to be transmitted in the different business processes is documented in class diagrams.
All business transactions will be described in activity diagrams, which show the business documents to be used.
There are 6 pre-specified business transaction patterns from UMM that can be used to specify the core characteristics of a transaction, some of which can include two business documents:
# UMM transaction pattern Examples of ebIX usage
1.
Commercial Transaction Not used within ebIX
2.
Request/Confirm
3.
Query/Response
For the moment not used within ebIX
E10/E07, E39/E37
4.
Request/Response
5.
Notification
6.
Information Distribution
392/414
E44, E07, E30, E08, E11, E13, E37, …..
Not used within ebIX
The following figure is taken from the UMM and provides a set of decision criteria for selection of business transaction patterns. The validity of this figure for use within the ebIX methodology has to be proven yet. ebIX Modelling Methodology 23
Is there a response required?
Yes
No
No
Is this a formal nonreputable notification?
Yes
Does the responder already have the information?
No
Is context validation required before processing by the receiver?
Yes
No
Yes
Select
Query/
Response
Select
Information
Distribution
Select
Notification
Is there a residual obligation between roles to fulfil terms of the contract?
No
Select
Request/
Confirm
Yes
Select
Request/
Response
Select
Commercial
Transaction
Figure 11 Decision criteria for selection of business transaction patterns
The business transactions are made during step 6 and 7 of an ebIX project. During this step previous modelled objects are reviewed and changed if needed.
4.1.5
Business documents
A business document is defined by its:
Business document type
Reason for transaction
Sector
Ancillary-role (sender or receiver)
Business document function code.
Notice that it may be different reasons for transactions and/or Business document function codes within a business document, dependent on the requirements given in the class diagram for the business document. The responsible role (sender or receiver) is implicit given by the business document type.
Each business document is specified using a UML class diagram. The class diagram shall describe the classification of the attributes as required (1) or dependent (0..1). A general rule within ebIX is to see all optional elements as dependent and describe the dependency in a dependency matrix associated with the business document. If an element is dependent on national rules the attribute must be specified in national user guides. This shall be stated in the ebIX business information model.
A business document can be implemented using different syntax types (i.e. XML or EDIFACT syntax). ebIX Modelling Methodology 24
Note that a business document may be seen as orthogonal to the business transactions. An instance of a business document may consist of several instances of business transactions and a business transaction pattern may include two business documents (e.g. request/confirm). The actual business transactions in an instance of a requesting business document do not have to correspond to the actual instances of transactions in an instance of the responding business document.
The class diagrams describing the business documents are made during step 7 of an ebIX project. Also during this step previous modelled objects are reviewed and changed if needed.
4.2
ebIX process patterns
This chapter shows a generic way of making UseCase diagrams. In ebIX business information models the “Responsible role” should always be expressed as a real role (e.g. the Balance responsible party or
Metering point administrator). The “Initiating role” and “Linked role” may have specialisations showing the actual roles or may be expressed as the actual role itself.
Figure 12 ebIX process patterns (UseCase diagram)
Using this principle the actual roles involved can be shown in the UseCase diagram as specialisations, while the detailed diagrams, such as sequence and activity diagrams, may use the generic terms;
“Initiating role” and “Linked role”. This will make the detailed diagrams easier to read, since the number of roles in the sequence diagrams and the number of swim lanes (columns in the activity diagram) can be reduced.
Figure 13 ebIX process patterns (Sequence diagram) ebIX Modelling Methodology 25
Remark: An example of requirements for generic roles related to supporting procedures will be made when needed in ebIX projects, such as description of how to handle the billing process and related roles as buyer, supplier invoicee, invoice issuer, billing agent etc in the models.
4.3
ebIX Core components
4.3.1
Definitions
The following definitions of Core Components are taken from the UN/CEFACT CCTS, see [2].
[Definition] Core Component (CC)
A building block for the creation of a semantically correct and meaningful information exchange package. It contains only the information pieces necessary to describe a specific concept.
There are four different categories of Core Components : Basic Core Component , Association Core
Component , Core Component Type and Aggregate Core Component . The following definitions explain each of these:
[Definition] Basic Core Component (BCC)
A Core Component which constitutes a singular business characteristic of a specific Aggregate
Core Component that represents an Object Class . It has a unique Business Semantic definition. A
Basic Core Component represents a Basic Core Component Property and is therefore of a Data
Type , which defines its set of values. Basic Core Components function as the Properties of
Aggregate Core Components .
[Definition] Association Core Component (ASCC)
A Core Component which constitutes a complex business characteristic of a specific Aggregate
Core Component that represents an Object Class . It has a unique Business Semantic definition. An
Association Core Component represents an Association Core Component Property and is associated to an Aggregate Core Component , which describes its structure.
[Definition] Core Component Type (CCT)
A Core Component , which consists of one and only one Content Component , that carries the actual content plus one or more Supplementary Components giving an essential extra definition to the
Content Component . Core Component Types do not have Business Semantics .
[Definition] Aggregate Core Component (ACC)
A collection of related pieces of business information that together convey a distinct business meaning, independent of any specific Business Context . Expressed in modelling terms, it is the representation of an Object Class , independent of any specific Business Context .
4.3.2
BIE (Business Information Entity)
When CCs are used in a business context they are called BIEs. The BIEs will be a restricted subset of the CCs:
The ABIEs (Aggregate Business Information Entities) will be classes in the class diagrams.
The BBIEs (Basic Business Information Entities) will be attributes in the classes.
The ASBIEs (Associated Business Information Entities) will be associations in the class diagrams.
All BBIEs will either be of type UDT (Unqualified Data Type), which are identical to the CCTs, or of type QDT (Qualified Data Type), which are restricted subsets of the CCTs.
The QDTs may have associated code lists, specified as enumeration classes.
A QDT has one or more attributes. These attributes shall either be of a basic type (char, string…) or of the type enumeration (specific code list). ebIX Modelling Methodology 26
4.4
General rules for UML artefacts
4.4.1
UseCase diagrams
There is one UseCase diagram for each Business process.
All UseCases names shall be in imperative tense.
4.4.2
Sequence diagrams
There is normally one sequence diagram for each Business process, but if needed for presentation or clarification purposes, it can be split into more.
4.4.3
Activity diagrams
There shall only be one activity diagram for each Business process.
4.4.4
Special rules related to MagicDraw
The Business domain, Business areas, Business processes, and class diagrams are shown as UML packages in a hierarchy:
The Business areas are shown as packages within the Business domain package
The Business processes within a Business area are shown as packages within the Business area.
The Class diagrams within a Business process are shown as packages within the Business process. ebIX Modelling Methodology 27
5 ebIX principles
5.1
Business document type
A business document is a set of information components exchanged between two or more roles. An occurrence of a business document may contain several business transactions of the same kind.
A business document has a business document type that is defined by:
the nature of the business transaction where it is being used,
the role responsible for the information in the business transaction and
the direction of the information flow.
A business document has a certain structure that is determined by:
the Business document type,
the Business sector (e.g. electricity or gas),
the Ancillary-role (the role explicitly included in the header part of the business document),
the “Reason for transaction” (i.e. in which business process the business transaction is used) and
the Business document function code (e.g. add, change or delete).
The following rules apply for the business document type:
There can only be one responsible role for the information components in a business document type.
The actual information content of a business document may be a subset of the total information components structure of a certain business document type, dependent on the business sector, the “non-responsible” role, the attribute “Reason for transaction” and the
Business document function code.
The “responsible” role in the business transaction is implicit given by the business document type.
The “non-responsible” role is explicitly specified in the header section of the business document.
A business document may contain several instances of transactions, of the same type.
Transaction pattern
Responsible role included in the document type
Ancillary-role (explicit given in the business document header)
Commercial
Transaction
Request/Confirm
Query/Response The “Responsible role” is the role receiving the initiating document.
Request/Response See above
Notification The “Responsible role” is the role sending the document.
Sender role in the initiating document
Receiver role in the responding document
Sender role in the initiating document
Receiver role in the responding document
Receiver role
Information
Distribution ebIX Modelling Methodology 28
5.2
Dependency matrix
Given the principles specified in 5.1, Business document type it is possible to use dependency
matrices for specifying how to reuse business documents. A specific business document, identified by a business document name, can be used in different business processes. A dependency matrix is set up to show the dependency for different usage. The attribute “Reason for transaction” will specify in which business process the business document is used. Different usage of attributes or classes will often be related to the relevant “Reason for transaction”.
Dependency matrices are typically used for simplifying business information models and may be used for specifying the usage of attributes dependent on other attributes in the business documents, such as national dependencies.
Note: The use of dependency matrices will be reviewed after more experiences from ebIX projects are available. The use of dependency matrices shall not in any way replace the use of class diagrams.
5.3
Basic principles for making Business Document Set
In the present ebIX models we find Business Documents being specified in the Class Diagrams. For efficiency reasons we may still want to be able to combine Business Documents in a set for the exchange with another party. So in the models, the information to be exchanged could be regarded as bottom-up defined, since the business defines the information, which is only later combined in a set.
Several Business Documents may be combined in one Business Document Set:
BusinessDocumentSet
+identifier : BusinessD ocumentSet_ID
...
1..* xxx_BusinessDocum ent
1
Type
1
Data
Figure 14 Business Document Set (overview)
There are conditions that have to be met in order to combine Business Documents in one set. Business
Documents may only be combined in one Business Document Set if they have the information the two upper Classes in the Class Diagram (the Class “xxx_BusinessDocument” and the Class
“BusinessDocumentType”) in common. Additionally there may be special conditions related to the chosen syntax. ebIX Modelling Methodology 29
392_BusinessDocument
+@m arketDom ain : ebIX 01C::QDT::MarketDom ain_Code = E01{frozen , SG=0}
+m es s ageDateTim e : ebIX 01C::QDT::DateTim e{SG=0, Qualifier=DTM- C507.2005=137}
+receiverID : ebIX 01C::QDT::Party_ID{SG=2, Qualifier=NAD-3035=MR}
+reques tForAcknowledgem entOf Acceptance : ebIX 01C::QDT::Res pon s eType_Code = AB{SG=0}
+s enderID : ebIX 01C::QDT::Party_ID{SG=2, Qualifier=NAD-3035=MS}
+tim eZone : ebIX 01C::QDT::Tim eZone{SG=0}
1
1
BusinessDocumentType
+@type : ebIX 01C::QDT::Bus ines s Docum entType_Code = 392{frozen, SG=0}
+@bus ines s Sector : ebIX 01C::QDT::Bus ines s Sector_Code = 23{frozen , SG=0}
+@reas onForTrans action : ebIX 01C::QDT::Reas onForTrans action_Co de = E56{frozen, SG=4}
+@ancillaryRole : ebIX 01C::QDT::Role_Code = DDQ{frozen, SG=2}
+@function : ebIX 01C::QDT::Bus ines s Docum entFunction_Code = 9{fro zen, SG=0}
+@clas s Diagram Vers ion : UDT::Identifier [0]{frozen} vers ion: not yet us ed
BusinessDocumentData
+identifier : ebIX 01C::QDT::Bus ines s Docum ent_ID{SG=4}
...
MeteringPoint
+m eterReadingIns truction : ebIX 01C::QDT::Ins truction_Code [0..1]{SG= 4}
+identifier : ebIX 01C::QDT::Dom ain_ID{SG=4, Qualifier=LOC-3227=172 }
1
MP_Address
+pos tCode : ebIX 01C::QDT::Pos tal_Code{SG=11}
+buildingNum ber : char{Data=NAD-C059.3042, SG=11}
0..1
{Qualifier=NAD-3035=IT,
SG=11}
Party
+identifier : ebIX 01C::QDT::Party_ID{SG=11}
1
1
{Qualifier=NAD-3035=DDK,
SG=11}
New balance Res pons ible
Contract
+s tartDate : ebIX 01C::QDT::DateTim e{SG=4, Qualifier=DTM-C507.2005 =92}
...
Author
Creation date ks parreb
2/7/05 6:19 PM
Modification date 2/9/05 5:22 PM
Structure Edifact , UTILMD , 01C
<<enum eration>>
Instruction_Code
(CodeLis t ebIX)
E01 (No m eter reading available)
Diagram nam e
Docum entation
392, 23, E56, DDQ, 9
CD Des cription Reques t change Balance Res pons ible
Figure 15 Business Document Set (details)
This condition is represented in the model below. As you see:
a set may only contain one instance of the class Exx_BusinessDocument
a set may only contain one instance of the class BusinessDocumentType
the only information the BusinessDocumentSet adds to the combination of BusinessDocuments is the ID for the BusinessDocumentSet.
This enables us to combine several sets of “data” in one BusinessDocumentSet, as long as they have the two classes that describe the information in common. ebIX Modelling Methodology 30
BusinessDocumentSet
+identifier : Bus ines s Docum entSet_ID
...
1
SyntaxSpecificInformation
...
1 xxx_BusinessDocument
1
Type
Data
1..*
Figure 16 Business Document Set (mapped to syntax) ebIX Modelling Methodology 31
5.4
Relations between versioned modelling elements ebIX model versions are determined by the versions of the components used in the model. The figure below shows the relations between the various elements used in the modelling.
Role model ebIX model national model
+version [1] +version [1] +version [1] role model role
+version [1] domain
+version [1] installation
+version [1]
1..* ebIX domain
+version [1]
1..* national domain
+version [1] ebIX EFET ETSO UCTE IEC model ebIX
UseCase
+version [1]
Sequence
+version [1]
Class
+version [1]
Activity
+version [1]
0..*
SyntaxMappedClass
Core Components
+version [1]
CC ebIX
SyntaxMappedCC
+version [1]
Syntax
+version [1]
CC UN/CEFACT
BCC
+version [1]
ACC
+version [1]
UDT
+version [1]
UN/Cefact
+version [1] codelists UN/CEFACT codelist
+version [1] ebIX
+version [1]
BBIE
+version [1]
ABIE
+version [1]
QDT
+version [1] documents UN/CEFACT
XML
+version [1]
0..1
0..1
Edifact
+version [1]
UN/Cefact naming and design rules
+version [1] codelists ebIX codelist
+version [1] documents ebIX ebIX methodology
+version [1] ebIX acknowledgement and error report
+version [1] ebIX rules and recommendations
+version [1] ebIX recommendations for cancellation
+version [1]
Figure 17 Relations between versioned modelling elements ebIX Modelling Methodology 32
6 Transition, model to technical/procedural documents
6.1
Development of translation guides
The ebIX business information models will be made independent of syntax. This shall ensure that the models can be implemented in whichever syntax necessary, such as EDIFACT or XML. When a business information model has been completed the translation guide for the chosen syntax will be made.
Each business transaction is documented in its own translation guide with its own version and revision. The name of the initial document will identify the business transaction.
6.2
Translation guide, from UML class diagrams to EDIFACT
6.2.1
Basic rules
This chapter contains intermediate rules for how to make EDIFACT translation guides from class diagrams for business documents. The chapter will be reviewed when UN/CEFACT publishes specifications of how to go from class diagrams to EDIFACT messages, expected published during the year 2004.
The current solution for mapping between a UML Class diagram and EDIFACT requires the following steps:
1) Find a suitable EDIFACT message: a) Compare the functional definition of the process and business document with the definitions of EDIFACT messages, preferably EDIFACT messages made for the energy industry, such as
UTILMD or UTILTS. If a definition matches or matches satisfactorily, take the EDIFACT message as a basis and request extension of the EDIFACT functional definition with the missing functions. Otherwise, request a new EDIFACT message. b) For each class and attribute within this class, find segment groups and segments of which the definition matches, possibly at a more generic level of abstraction. If no segment matches, request a new (generic) segment. c) Ensure that the segments used within the EDIFACT structure are in the same level as in the
Class diagram. If the level within the EDIFACT message not matches the levels in the class diagram request an EDIFACT message structure change. d) If the segment found is qualified, look in the segment’s qualifier code list for a qualifier that matches the specific definition of the attribute. If none is found, request a new one. If the definition of an existing qualifier may be slightly adapted, request a change. e) Check the structure of the segment. In many cases the structure will not match the structure of the class/attribute. If the element and sub-element structure of the segment match the attribute, and if the definitions also match, use the elements. Request changes and additions to the segment structure where appropriate.
2) Document the relationship between the Class diagram (ABIE/BBIE) and the EDIFACT message: a) Add the appropriate EDIFACT elements; Segment group, Segment, Composite element, Data element, and Qualifier, to the Class diagram.
6.2.2
Steps in making the translation guide (To be further elaborated).
1.
Copy the relevant class diagram from the Business information model, inclusive enumerations describing the relevant codes used.
2.
Add the attributes UNSM_Version, RequestForAcknowledgement and BusinessProcess.
3.
Add constraints to specify the EDIFACT structure. ebIX Modelling Methodology 33
6.3
Development of implementation guides ebIX implementation guides (IG) describe EDIFACT message in detail. Since there is no parallel to the semantics in the UNSMs (UN Standard Messages) for XML there is no parallel to the implementation guides either.
There will be one IG for each EDIFACT message type and version of the EDIFACT message type used within ebIX. The implementation guides defines a framework for how to use EDIFACT messages in general terms, i.e. a subset of the generic EDIFACT message, inclusive general requirements to be used within ebIX. The ebIX EDIFACT translation guides will be based on a subset of the implementation guide and show the specific use of the IG for a business document as documented in the class diagrams in an ebIX business information model.
6.4
Translation guide from UML class diagrams to XML ebIX XML translation guides will be based on UN/CEFACT specifications. These are currently under development and this chapter will be reviewed and updated according to the UN/CEFACT developments. ebIX Modelling Methodology 34
7 Layout/design of ebIX documents
7.1
ebIX business information models
The ebIX business information models describe a part of, or the whole of, a business area or a business process area, based on UN/CEFACT Modelling Methodology (UMM). All ebIX business information models should be constructed respecting the same basic structure and layout.
The document produced shall as a minimum contain the following parts:
1) Description of the project requirements:
Objective, scope, process overview, participants and references.
2) Reference to the ebIX business domain model:
Placement of the business area in the overall model of the energy industry and in the Harmonised role model.
3) Description of the business processes:
UseCase diagrams, UseCase descriptions, sequence diagrams, activity diagrams and general ground rules describing the business processes.
4) Description of each business document:
Class diagrams and related core component specifications.
5) Requirements and rules
Requirement for acknowledgements, rejection procedures and cancellation principles.
6) Appendices:
E.g. objects that only are used by a single country.
There may be other chapters containing information that is necessary to ensure the complete comprehension of the ebIX business information models.
7.1.1
The first part of the ebIX business information model
This part of the business information model will contain information prepared during the first and second stages of the development process. This shall include, but shall not be restricted to, the objective and scope of the project, the overview of the process, participants in the project developing the model, references to the relevant documentation and its version, and a change log for updates of the document.
7.1.2
The second part of the ebIX business information model
The second part of an ebIX business information models will reference the ebIX business domain model
, [6], and describe where in the overall model of the energy industry this business process area
fits in. The UseCases developed during the course of the project and their explanatory documentation shall be included in this part of the guide. This part of the ebIX business information model will also show the part of the Harmonised role model
7.1.3
The third part of the ebIX business information model
This part of the business information model will contain all the information prepared during the third of the development process. This shall include, but not be restricted to, the sequence diagrams and activity diagrams depicting the information flows (business documents) between the different roles that participate within the scope of the project. Finally, any general ground rules that need to de defined in order to ensure that the business processes could be correctly interpreted.
The information in this part of the ebIX business information model will be documented and presented in a hierarchy of UseCases, UseCase descriptions, sequence diagrams and activity diagrams, according to the detail levels described in UMM. ebIX Modelling Methodology 35
7.1.4
The fourth part of the ebIX business information model
This part of the business information model will describe the various business documents with their class diagrams and core component specifications that were established during the fourth step of the development process. It will only be the ebIX core components that have special requirements or dependencies that will be listed in the information model. Other core components will be referenced in the ebIX core components repository.
There will be as many repetitions of this fourth part as there are distinct business documents necessary to ensure the execution of the business process that the project is implementing.
The rules governing the overall business document implementation and the aggregate elements should contain a dependency matrix wherever there are conditional elements. The dependency matrix shall define the conditions where a conditional element is used and where it is not.
The rules governing the basic elements shall be made up according to the specification in 4.3 ebIX
7.1.5
The fifth part of the ebIX business information model
As the fifth and last part of ebIX business information models the requirement and rules governing the overall business document implementation will be documented. This include:
Requirement for acknowledgements
Rejection procedures
Cancellation principles
7.1.6
Appendices of the ebIX business information model
If it during the modelling project has been found business objects that only are used by one country, these business objects will be kept in a separate model in an appendix, for possible future implementation by more countries
7.2
ebIX XML and EDIFACT Translation guides
This chapter will be made after examples have been made in the ebIX CuS and/or EMD projects.
7.3
ebIX EDIFACT Implementation Guides
The ebIX implementation guides will have the following content:
Introduction: This part will describe the area where the EDIFACT message may be used, give references to other documents of interest, specify special conditions or requirements and change log for the IG.
Message overview: In this part of the ebIX IG there shall be given an overview of the business objects that can be sent in this EDIFACT message, EDIFACT message it self and the mapping between business objects/attributes the EDIFACT message itself:
A class diagram of all business objects and attributes covered by the IG.
A cue list mapping the attributes to the EDIFACT structure.
A message diagram where the structure of the EDIFACT segments used in the IG are shown.
A segment table with the description of the EDIFACT segments used.
Detailed description: This is the main part of the IG. It shows all segments and segment groups, specified in detail. All elements of the segments used are shown with its classification (Mandatory, Required, Dependent, Advised, Optional or Not ebIX Modelling Methodology 36
used), format and reference to the attributes in the class diagram. In addition an example of the use of the segment shall be stated. ebIX Modelling Methodology 37
8 Maintenance procedure
This chapter gives an overview of the rules that apply for all technical documents maintained by ETC, such as ebIX business information models, XML and EDIFACT Translation Guides and EDIFACT
Implementation Guides.
8.1
Introduction
All ebIX documents are maintained on a regular basis. This is to ensure that they reflect the energy market information interchanges as they currently stand and that they take into account any intended evolutions. In such a fast moving market this is essential to the success of the seamless operation of electronic data interchange systems.
At the same time there is a recognised need for a certain form of stability between the market players.
The users of the documentation (market players and software providers) need to know when a new version is scheduled to appear with added functionality. They need to be able to determine how long a given development may remain operational before necessary changes are required. In an environment where there is little or no change this is not such a problem, but in fast moving environments it is essential to know the frequency of change.
The objective of the ebIX maintenance procedures is to ensure that the user community as a whole is perfectly aware of the periodicity of change and the potential modifications that can take place.
8.2
Responsibility for maintenance
The table below shows an overview of the different ebIX documents and the body responsible for maintenance of it.
Energy domain
Harmonised role model
Business domain model
UN-CEFACT
ETC
X 5)
X ebIX
Work groups
National groups
Business area
Business Information models
Procedures
Registry/repository
CCs
Code lists
Templates
(X 3) ) X 1) X 2)
X
X
X
3)
3)
X 4)
X 4)
X
Technical documents
XML Translation Guides
EDIFACT Translation Guides
EDIFACT IGs X 3)
X
X
X 4)
X 2)
X 2)
X 2)
1) If the working groups finish, ETC will act as the working group for maintenance of smaller changes.
2)
Responsible for national adjustments, such as extensions and restrictions, see Appendix C for an
example.
3) Global business information models, CCs, Code lists and UNSMs (UN Standard Messages)
4) Energy domain CCs, Code lists and UNSM subsets (IGs)
5) In co-operation with ETSO ebIX Modelling Methodology 38
8.3
Rules for versioning of ebIX technical documents
All technical documents will have 2 levels of version numbering. This will be Version and Release. In addition there will be a Revision number. Change is not systematic nor does a change always have the same significance. For this reason ebIX has introduced a version/release process to manage document changes. The distinction between these three notions is as follows:
A version changes only whenever there is a modification to the document that entails a functional change in any supporting softwar e. For example a change to the data model,
DTD, process flow, functional processes, etc, that impacts in one way or another the operational system.
A release changes only whenever there is a modification to the document that does not require a change to supporting software. For example a correction of documentation errors, additional reason codes, coding schemes, etc, that does not impact the operational system.
A revision letter will be updated when there have been minor changes, like correction of spelling or improvements to provide better clarification.
With this process users can immediately determine if there have been only release changes and that their software implementations not will require modification. The version/release indicators are represented by numeric values. A version value of “0” represents a document in development. In this case the release number is used to identify different editions of the development document. The first official version of a document is assigned the number of "1". With each version change the release indication is reinitialised to 0. ebIX Modelling Methodology 39
9 Table of figures
Figure 15 BusinessDocumentSet, header information mapped to EDIFACT version 01C ................. 50
Figure 16 BusinessDocumentSet, header information mapped to EDIFACT version 02B ................. 50
ebIX Modelling Methodology 40
Appendix A UseCase description template
The following UseCase description template shall be used together with all UseCases shown in ebIX business information models:
UseCase Name A short name for this UseCase. The name shall connect the UseCase to the process it defines.
Traceability Identifier
UseCase Description
Roles
Performance Goals
Preconditions
Post conditions
Identifies the hierarchical position of the UseCase within the business information model.
A set of simple sentences that state the actions that may be performed as part of the business process. The description should briefly convey the role and purpose of the
UseCase. A single paragraph should suffice for this description.
List the roles involved in this UseCase or reference the relevant UseCase diagram.
A specification of the metrics relevant to the UseCase and a definition of their goals.
Non-functional requirements may be a source of performance goals. For each performance goal, provide a name of the performance goal and a brief description of the performance goal
Preconditions are the rules defining the conditions that must be true for the context that this process is conducted within. These rules are constraints that must be satisfied before instantiating or initialising the business process thus ensuring that the proper context for the process has been established.
Post-conditions are the rules defining the conditions that must be true for the localized context that exists after the business process completes. These rules are constraints that must be satisfied after the business process thus ensuring that the proper update to context of the parent process has been occurred.
Scenario
Alternative Scenario
Special Requirements
Extension Points
A textual description of the scenario the use case represents. The scenario should describe what the business does to deliver value to a business role, not how the business solves its problems.
Name of step in Scenario
A brief description of the step.
Name of next step in the scenario
A brief description of the step. Etc
Describe any alternatives to the above scenario .
The special requirements of the use case are included here. These are requirements not covered by the scenario as it has been described in the sections above.
Name of special requirement
A brief description of the special requirement
Extension points of the use case.
Name of extension point
Definition of the location of the extension point in the flow of events ebIX Modelling Methodology 41
Appendix B ISO/IEC 14662, Open-edi Reference Model
The UMM is organised into 4 views so that each business process and information model can be viewed from a number of perspectives, all of which are contained within the Business Operational
View (BOV) from the ISO/IEC 14662, Open-edi Reference Model. Each view is briefly described as follows:
The Business Domain View (BDV) - the partitioning of business domain into business areas, business process areas, and business processes. This view establishes the business context of the process which is a precursor to evaluating the likelihood of finding reusable, previously defined, process descriptions or terminology in the UMM libraries. ebIX project: The BDV is developed and maintained by ebIX forum and ETC.
Artefacts: UseCase diagram, Role model
Example: ebIX business domain model
The Business Requirements View (BRV) - the view of a business process model that captures the business scenarios, inputs, outputs, constraints and boundaries for business processes and their interrelationships within business processes. This view is how the business domain expert sees and describes the process to be modelled. The BRV is expressed in the language and concepts of the business domain expert. ebIX project: Corresponds to ebIX project step 3, 4 and 5, and ends with milestone 2.
Artefacts: UseCase diagram and updates of Role model
Example: CuS: UseCase diagram Structuring and CuS part of the Role model
The Business Transaction View (BTV) - the view of a business process model that captures the semantics of business information entities and their flow of exchange between roles as they perform business activities. This view is an elaboration on the business requirements view by the business analyst and is how the business analyst sees the process to be modelled.
This view uses the language and concepts of the business analyst to convey requirements to the software designer and the business domain expert. ebIX project: Corresponds to ebIX project step 6 and 7 , and ends with milestone 4.
Artefacts: UseCase diagrams, sequence diagrams, activity diagrams and Core
Components, including relevant procedural descriptions.
Example: CuS Business process Change balance supplier
The Business Service View (BSV) - the view of a business process model that specifies the component services and agents and their business document (information) exchange as interactions necessary to execute and validate a business process. The BSV is expressed in the language and technical concepts of the software developer. ebIX project: Corresponds to ebIX project step 8 and 9, and ends with milestone 5.
Artefacts: Class diagrams and translation guides
Example: CuS Class diagrams and translation guides
The modeller sees all the views and is responsible for documenting each view in UML and preparing the output from one view for input to the next. Each UMM view produces a set of UMM models
(deliverables) that are used as input to subsequent workflows.
The participants in the four UMM views are identified in the following. Depending upon the view, the roles could be played by different participants
1.
Business Domain View (BDV) Modelling: ebIX Modelling Methodology 42
a.
Business stakeholders : Executive Management, Business Owners b.
UMM modellers : Business Analysts, Business Architects
2.
Business Requirements View (BRV) Modelling: a.
Business stakeholders : Executive Management, Business Owners, Information
Modellers, Process Modellers b.
UMM modellers : Business Analysts, Business Modellers
3.
Business Transaction View (BTV) Modelling: a.
Business stakeholders : Business Analysts, Systems Architects, Implementers b.
UMM modellers : Information Modellers, Process Modellers
4.
Business Service View (BSV) Modelling: a.
UMM modellers: derived from BTV UMM models ebIX Modelling Methodology 43
Appendix C Example of national documentation
This chapter is copied from the Danish national ebIX documentation. ebIX expects the need for national documentations based on ebIX standards to remain. This example shows how it can be done. ebIX plan to come up with recommendations in the foreseeable future.
C.1
Overview of technical documents
FSV
Functional
Service View
BOV
Business
Operational View
UN/CEFACT
EDIFACT/ ebXML
Document
Spec
Subset ebIX/Europe ebIX
Functional
Description ebIX
Document
IG
Subset
Uses
Business
Scenario and
Transaction
Inspires
Market
Rules
Detailed
User Guide
National authority ebIX/National
National
General
Guide
National
Dokument
IG
Uses
National
Business
Transaction
Belongs to
Uses
National
Business
Scenario ebIX/National
National
Application
(OBPI)
National
Code
List
Figure 18 Example of national documentation
The Danish ebIX documentation is based on the structure showed in Figure 18 .
C.2
UN/CEFACT
The UN/CEFACT organisation defines the EDIFACT documents that are used by ebIX. Standard
EDIFACT converters will therefore have definitions of the different EDIFACT documents.
C.3
ebIX/Europe
The ebIX organisation covering Europe has defined a standard for data interchange. It consists of a
Functional Description with all general rules for data interchange, implementation guides for the
EDIFACT documents used and proposal for business scenarios and transactions that use the documents.
The ebIX implementation guide for EDIFACT documents are based on the standard EDIFACT document specification with the following:
Exclusion of data elements not used in ebIX data interchange
List of allowed codes for certain data elements ebIX Modelling Methodology 44
In that way ebIX documents are subsets of the UN/CEFACT EDIFACT documents, ebIX are also describing business scenarios and business transactions that describe the recommended usage of the ebIX documents
C.4
ebIX/National
The National ebIX group uses the ebIX documents with input from the different authorities and user groups.
C.5
National General Guide
ebIX National General Guide describes within the framework of the ebIX Functional Description how ebIX data interchange is carried out nationally.
C.6
National Document Implementation Guide
For each ebIX EDIFACT document used nationally there is a national implementation guide that describes which attributes that are used nationally and what other restrictions might apply. The version is put in UNH/S009/0057.
C.7
National Business Transaction
A Business Transaction in Open EDI (ISO standard 14662) is defined as "a predefined set of activities and/or processes of organisations which is initiated by an organisation to accomplish an explicitly shared business goal and terminated upon recognition of one of the agreed conclusions by all the involved organisations although some of the recognition may be implicit".
A Business Transaction is typically a Peer-to-Peer Business Transaction and each Business
Transaction is documented in its own Implementation Guide with its own version and revision. The guide will normally include:
Activity diagram which shows all possible information flows
Dependency matrix with all required attributes for each information flow
Description of the acknowledgement process for each flow with a validation table that indicates the error code for non valid transactions
A Business Transaction can be used in different Business Scenarios. This should be expressed in parameters like “Reason for transaction” with different dependencies for each.
The Business Transaction and its version are identified in UNH/0068 by a Business Transaction combined identification, which combines the Business document id with its version. It is a code of 13 characters. The format is CC-GGGGGG-NNN, where
CC
GGGGGG
NNN
Two letter ISO 3166 country code
6 character Business Document identification using uppercase characters A-Z and number 0-9 and the delimiter "-" (minus)
IG version number with leading zeroes
C.8
National ebIX applications (OBPI)
Different Business Transactions are grouped into Overall Business Processes with its own identification (OBPI). Each group can be considered as one standard application that is able to support the transactions. The OBPI is used for addressing and routing the interchange and is put on the
EDIFACT envelope as application reference (UNB/0026).
C.9
National Authority
National authorities as a part of the market rules define information interchange. An authority can be the system operator(s) specifying which data to be sent in a day a head of schedule; it can be the ebIX Modelling Methodology 45
regulator specifying the overall rules for Customer Switching; it can be the national energy business organisation that defines how certain statistical data are sent.
C.10
User Guide
Based on a set of market rules the national ebIX group in close cooperation with the authority will build a User Guide with Business Scenarios as described in the next chapter. The User Guide defines the general business rules for the included Business Scenarios. The guide shall also describe how the users are expected to use the system. Changes on this level can then be done without affecting the technical ebIX documentation.
Changes in the User Guide which only requires changing of parameters should be implemented on a specific date by all users.
The User Guide and its version are not identified in the ebIX information flows.
All national user guides should be available in English
C.11
National Business Scenario
A Business Scenario in Open EDI is defined as "a formal specification of a class of business transactions having the same business goal". In the User Guide the Business Scenarios are the kernel.
Here it is described how the process is automated. A Business Scenario is documented by a sequence diagram showing the information flows needed to carry out the full business case. An information flow will typically correspond to a Business Transaction that will further describe its handling. If the
Business Transaction can have several Reasons for Transaction the Business Scenario must state which to use.
All business rules that have to be implemented in the application shall be stated in the Business
Scenario documentation. They should be separated in three groups:
Rules that should be programmed into the application, which also have to be specified in the
Business Transaction documentation.
Rules that should be parameterised in the application.
Rules that should be handled by the user (manually).
When a new data element is required in a Business Scenario for a Business Transaction a new version of the Business Transaction must be made.
C.12
National code list
The data in the interchanges are often identified using codes. Many codes are stable and sufficient for long period. These can be defined in the document implementation guide. For other codes, new values are required regularly. For these the codes are documented in separate code lists normally issued by the relevant authority. A new version of the code list is typically introduced on a common date for all parties. ebIX Modelling Methodology 46
Appendix D Definitions and glossary
The following definitions are compatible with the current UMM and UN/CEFACT definitions.
Business collaboration:
An activity conducted between two or more parties for the purpose of achieving a specified outcome.
Business document: A set of information components that are interchanged as part of a business activity.
Business document type:
Business entity:
Business Information
Entity (BIE):
Business Information
Model:
Business Object:
It is a set of information components used in one type of business transaction(s) and exchanged between two or more roles. An occurrence of a business document may contain several business transactions of the same kind.
A business document type is defined by the type of business transaction where it is being used, the role responsible for the information in the business transaction(s), the direction of the information flow, the sector
(electricity or gas) and the Business document function code. A business document type has a certain structure. The structure can however be enhanced or reduced dependent on the business sector (electricity or gas), the Ancillary-role (the role explicitly included in the header part of the document) and the “Reason for transaction” (i.e. in which business process the business transaction is used).
Something that is accessed, inspected, manipulated, produced, and worked on in the business.
A piece of business data or a group of pieces of business data with a unique business semantic definition. A Business Information Entity can be a Basic Business Information Entity (BBIE), an Association Business
Information Entity (ASBIE), or an Aggregate Business Information Entity
(ABIE). See also the definition of Core Components.
A model that references all meta-information associated with a specific
Business Process or business process area. The Business Information
Model references Business Entities, Business Information Entities, and
Business Information Objects to accomplish that task.
An unambiguously identified, specified, referenceable, registerable and reuseable scenario or scenario component of a business transaction. The term business object is used in two distinct but related ways, with slightly different meanings for each usage:
In a business model, business objects describe a business itself, and its business context. The business objects capture business concepts and express an abstract view of the business’s “real world”. The term
“modelling business object” is used to designate this usage.
In a design for a software system or in program code, business objects
Business process: reflects how business concepts are represented in software. The abstraction here reflects the transformation of business ideas into a software realization. The term “systems business objects” is used to designate this usage.
The means by which one or more activities are accomplished in operating business practices. The Business Process as described using the
UN/CEFACT Catalogue of Common Business Processes.
Business transaction: A business transaction is a set of business information and business signal exchanges amongst two business partners that must occur in an agreed format, sequence and time period.
A business transaction is a logical unit of business conducted by two ebIX Modelling Methodology 47
Core Components
(CC):
Implementation guide:
Scenario:
Template:
Translation guide: parties that generates a computable success or failure state. The community, the partners, and the process, are all in a definable, and selfreliant state prior to the business transaction, and in a new definable, and self-reliant state after the business transaction. In other words if you are still 'waiting' for your business partner's response or reaction, the business transaction has not completed.
A building block for the creation of a semantically correct and meaningful information exchange package. It contains only the information pieces necessary to describe a specific concept. There are four different categories of Core Components defined by UN/CEFACT/ebXML:
Basic Core Component (BCC):
A Core Component, which constitutes a singular business characteristic of a specific Aggregate Core Component that represents an Object Class. It has a unique Business Semantic definition. A Basic Core Component represents a Basic Core Component Property and is therefore of a Data
Type, which defines its set of values. Basic Core Components function as the Properties of Aggregate Core Components.
Association Core Component (ASCC):
A Core Component, which constitutes a complex business characteristic of a specific Aggregate Core Component that, represents an Object Class.
It has a unique Business Semantic definition. An Association Core
Component represents an Association Core Component Property and is associated to an Aggregate Core Component, which describes its structure.
Core Component Type (CCT):
A Core Component, which consists of one and only one Content
Component, that carries the actual content plus one or more
Supplementary Components giving an essential extra definition to the
Content Component. Core Component Types do not have Business
Semantics.
Aggregate Core Component:
A collection of related pieces of business information that together convey a distinct business meaning, independent of any specific Business
Context. Expressed in modelling terms, it is the representation of an
Object Class, independent of any specific Business Context.
Within ebIX the term Implementation guide (IG) is used for a technical framework describing an EDIFACT message used in several business processes. E.g. UTILTS and UTILMD. In other organisations the term IG may be used slightly differently, e.g. within ETSO the term IG is used for documents describing a complete description of a business process, including the business information model and translation guides.
A formal specification of a class of business activities having the same business goal.
A pattern, such as a part of a model, from which copies (reuse) can be made. A template may typically consist of parts of UML artefacts (e.g. activity and class diagrams). Examples of templates are the message header of a business document, the time series part of a business document containing metered data or a generic acknowledgment process.
Document describing a business document, translated from a syntax neutral class diagram into a specific syntax, such as XML or EDIFACT. ebIX Modelling Methodology 48
Appendix E Examples
These examples will be reviewed and will later be put into the relevant chapters of the document.
An example of 5.1 Business document type:
In the ebIX/CuS project there is defined a unique set of business document types, for change of master data, for each type of register (database), such as a Metering point db and a Meter db:
The business document type “request to update master data” is determined by the receiving roles
(the role responsible for the database).
The business document type “information regarding master data from db-responsible” is determined by the sending role (the role responsible for the database).
The business document type “request for information” is determined by the answering role (the role responsible for the database).
Transaction 1:
Request to Metering Point Administrator (MPA) for change in MP-db:
BGM/1001: “392”
SG2/NAD: “Sender” and “MPA”
SG4/STS/Reason for transaction: Change of supplier, consumer move, change of metered data collector (MDC) etc.
Response from MPA: BGM/1001: “414”
SG2/NAD: “Receiver” and “MPA”
SG4/STS/Reason for transaction: Change of supplier, consumer move, change of metered data collector (MDC) etc.
Transaction 2:
Notification from MPA to concerned parties:
BGM/1001: “E44”
SG2/NAD: “Receiver” and “MPA”
SG4/STS/Reason for transaction: Change of supplier, consumer move, change of metered data collector (MDC) etc. ebIX Modelling Methodology 49
Appendix F Business Document Sets in EDIFACT
F.1
Syntax Specific Header Information for EDIFACT
Below you will find the Class Diagrams to be used for the creation of Business Document Sets and
Dispatches for EDIFACT, for versions 01C and 02B.
BusinessDocumentSet
+identifier : ebIX 01C::QDT::BusinessDocumentSet_ID{SG=0}
...
1. messageReferenceNumber 1 and 2 shall be identical;
2. numberOfSegmentsInMessage shall include also UNH and UNT
1 xxx_BusinessDocument
1
1..*
Type
Data
1
SyntaxSpecificInformation
+messageReferenceNumber1 : char{Data=UNH-0062}
+@messageType : char = UTILMD{frozen, Data=UNH-S009.0065}
+@messageTypeVersion : char = D{frozen, Data=UNH-S009.0052}
+@messageTypeRelease : char = 01C{frozen, Data=UNH-S009.0054}
+@controllingAgency : char = UN{frozen, Data=UNH-S009.0051}
+NationalVersion : Codelist National::Codelist EBO::NationalEdineVersion{Data=UNH-S009.0057}
+numberOfSegmentsInMessage : int{Data=UNT-0074}
+messageReferenceNumber2 : char{Data=UNT-0062}
<<enumeration>>
NationalEdineVersion
(Codelist National.Codelist EBO)
<<Code>>E4NL32{DSC=Edine version = B-con release 8 (June 2005)}
<<Code>>E4NL33{DSC=Edine version = B-con release 9 (November 2005)}
Author
Creation date ksparreb
3/15/05 11:32 AM
Modification date 8/5/05 4:02 PM
Structure Edifact , UTILMD , 01C
Diagram name Header DocumentSet (Message) Edifact 01C
Documentation
Version
CD Description Header Document Set (Message)
Figure 19 BusinessDocumentSet, header information mapped to EDIFACT version 01C
BusinessDocumentSet
+identifier : ebIX 01C::QDT::BusinessDocumentSet_ID{SG=0}
...
1. messageReferenceNumber 1 and 2 shall be identical;
2. numberOfSegmentsInMessage shall include also UNH and UNT
1
Exx_BusinessDocument
1
SyntaxSpecificInformation
+messageReferenceNumber1 : Data types::char{Data=UNH-0062}
+@messageType : Data types::char = UTILTS{frozen, Data=UNH-S009.0065}
+@messageTypeVersion : Data types::char = D{frozen, Data=UNH-S009.0052}
+@messageTypeRelease : Data types::char = 02B{frozen, Data=UNH-S009.0054}
+@controllingAgency : Data types::char = UN{frozen, Data=UNH-S009.0051}
+NationalVersion : Codelist National::Codelist EBO::NationalEdineVersion{Data=UNH-S009.0057}
+numberOfSegmentsInMessage : Data types::int{Data=UNT-0074}
+messageReferenceNumber2 : Data types::char{Data=UNT-0062}
1
Type
<<enumeration>>
NationalEdineVersion
(Codelist National.Codelist EBO)
<<Code>>E5NL32{DSC=Edine version = B-con release 8 (June 2005)}
<<Code>>E5NL33{DSC=Edine version = B-con release 9 (November 2005)}
Data
1..*
Diagram name Header DocumentSet (Message) Edifact 02B
Author ksparreb
Creation date 3/16/05 9:50 AM
Modification date 8/4/05 2:35 PM
Documentation
CD Description Header Document Set (Message)
Structure Edifact, UTILTS , 02B
Figure 20 BusinessDocumentSet, header information mapped to EDIFACT version 02B ebIX Modelling Methodology 50
Despatch both InterchangeControlReferences shall be identical
1
UNA
+@COMPONENT DATA ELEMENT SEPERATOR : char = :{frozen, Data=UNA}
+@DATA ELEMENT SEPERATOR : char = +{frozen, Data=UNA}
+@DECIMAL NOTATION : char = .{frozen, Data=UNA}
+@RELEASE INDICATOR : char = ?{frozen, Data=UNA}
+@Reserved for future use : char = {frozen, Data=UNA}
+@SEGMENT TERMINATOR : char = '{frozen, Data=UNA}
1
UNB
-SyntaxIdentifier : char{Data=UNB-S001.0001=UN0C, UNB-S001.0002=3}
+InterchangeSender : char{Data=UNB-S002.0004, Qualifier=UNB-S002.0007=14}
+InterchangeRecipient : char{Data=UNB-S003.0010, Qualifier=UNB-S003.0007=14 }
+Date : int{Data=UNB-S004.0017}
+Time : int{Data=UNB-S004.0019}
+InterchangeControlReference : char{Data=UNB-0020}
+@TestIndicator : char [0..1] = 1{frozen, Data=UNB-0035}
UNZ
+InterchangeControlCount : char{Data=UNZ-0036}
+InterchangeControlReference : char{Data=UNZ-0020}
1 number of messages in
the interchange
1..*
BusinessDocumentSet
+identifier : ebIX 01C::QDT::BusinessDocumentSet_ID{SG=0}
...
Author
Creation date ksparreb
3/15/05 11:41 AM
Modification date 6/28/05 7:30 PM
Structure Edifact
Diagram name Header Despatch (Interchange) Edifact
Documentation
Version
CD Description Despatch Header for Edifact
Figure 21 Dispatch, header information mapped to EDIFACT ebIX Modelling Methodology 51
Appendix G Introduction to UML
This appendix give an overview of the terms and notation used within the parts of the Unified
Modelling Language (UML) [8] that is specified by UMM. It is mainly an abstract of the original
UML, version 1.5 documentation from the Object Management Group (OMG). It gives an overview of the possibilities UML gives when modelling business processes within the energy industry and explains the artefacts used within ebIX models.
G.1
Terms
Actor: A coherent set of roles that users of UseCases play when interacting with these
UseCases. An actor has one role for each UseCases with which it communicates.
Guard conditions: A condition that must be satisfied in order to enable an associated transition to fire.
Operation: A service that can be requested from an object to effect behaviour. An operation
State
Transitions: has a signature, which may restrict the actual parameters that are possible.
A condition or situation during the life of an object during which it satisfies some condition, performs some activity, or waits for some event.
A relationship between two states indicating that an object in the first state will perform certain specified actions and enter the second state when a specified event occurs and specified conditions are satisfied. On such a change of state, the transition is said to fire. ebIX Modelling Methodology 52
G.2
UseCase diagram
A UseCase diagram shows the relationship among UseCases within a system or other semantic entity and their actors.
UseCase diagrams show actors and UseCases together with their relationships. The UseCase represent functionality of a system or a classifier, like a subsystem or a class, as manifested to external interactors with the system or the classifier.
A UseCases diagram is a graph of actors, a set of UseCases, possibly some interfaces, and the relationships between these elements. The relationships are associations between the actors and the
UseCase, generalizations between the actors, and generalizations, extends, and includes among the
UseCases. The UseCases may optionally be enclosed by a rectangle that represents the boundary of the containing system or classifier.
Figure 22 UseCase diagram
A set of use case ellipses with connections to actor symbols maps to a set of UseCases and Actors corresponding to the UseCase and actor symbols, respectively. The optional rectangle maps onto either a Model with the stereotype «useCaseModel» containing the set of UseCases and Actors, or to a
Classifier, like Subsystem or Class, containing the set of UseCases. An interface in the diagram is mapped onto an Interface in the Model, and the connection between the interface and the actor or
UseCase icons is mapped onto a realization Dependency (an Abstraction dependency being stereotyped «realize») between the Classifiers. Each generalization arrow maps onto a Generalization in the model, and each line between an actor symbol and a UseCase ellipse maps to an Association between the corresponding Classifiers. A dashed arrow with the keyword «include» or «extend» maps to an Include or Extend relationship between UseCases.
UseCase
A UseCase is a kind of classifier representing a coherent unit of functionality provided by a system, a subsystem, or a class as manifested by sequences of messages exchanged among the system
(subsystem, class) and one or more outside interactors (called actors) together with actions performed by the system (subsystem, class). ebIX Modelling Methodology 53
A UseCase is shown as an ellipse containing the name of the UseCase. An optional stereotype keyword may be placed above the name and a list of properties included below the name. As a classifier, a UseCase may also have compartments displaying attributes and operations.
The behavior of a use case is described using plain text. Sequence diagrams are used for describing the interaction between UseCases and their actors.
The name of the UseCase may be placed below the ellipse. The name of an abstract use case may be shown in italics.
The ellipse may contain or suppress compartments presenting the attributes, the operations, and the extension points of the UseCase.
UseCases names should follow capitalization and punctuation guidelines used for Classifiers in the model.
A UseCase symbol maps to a UseCase with the given name. An extension point maps into an
ExtensionPoint within the UseCase.
Actor
An actor defines a coherent set of roles that users of an entity can play when interacting with the entity. An actor may be considered to play a separate role with regard to each UseCase with which it communicates.
The standard stereotype icon for an actor is a “stick man” figure with the name of the actor below the figure.
An actor may also be shown as a class rectangle with the keyword «actor», with the usual notation for all compartments.
Actor names should follow capitalization and punctuation guidelines used for types and classes in the model.
An actor symbol maps to an Actor with the given name. The names of abstract actors may be shown in italics.
Use Case Relationships
There are several standard relationships among UseCases or between actors and UseCases.
Association: The participation of an actor in a use case; that is, instances of the actor and instances of the UseCase communicate with each other. This is the only relationship between actors and UseCases.
Extend: An extend relationship from UseCase A to UseCase B indicates that an instance of
UseCase B may be augmented (subject to specific conditions specified in the extension) by the behavior specified by A. The behavior is inserted at the location defined by the extension point in B, which is referenced by the extend relationship.
Generalization: A generalization from UseCase C to UseCase D indicates that C is a specialization of
D.
Include: An include relationship from UseCase E to UseCase F indicates that an instance of the
UseCase E will also contain the behavior as specified by F. The behavior is included at the location which defined in E. ebIX Modelling Methodology 54
An association between an actor and a UseCase is shown as a solid line between the actor and the
UseCase. It may have end adornments such as multiplicity.
An extend relationship between UseCases is shown by a dashed arrow with an open arrowhead from the UseCase providing the extension to the base UseCase. The arrow is labeled with the keyword
«extend». The condition of the relationship is optionally presented close to the key word. Extension points may be listed in a compartment of the use case with the heading extension points. An extension point is a reference to one location within a UseCase at which action sequences from other UseCase may be inserted. Each extension point has a unique name within a UseCase, and a description of the location within the behavior of the UseCase. The description of the locations of the extension point is given in a suitable form, usually as ordinary text, but can also be given in other forms, like a precondition or a postcondition.
An include relationship between UseCases is shown by a dashed arrow with an open arrowhead from the base UseCase to the included UseCase. The arrow is labeled with the keyword «include».
A generalization between UseCases is shown by a generalization arrow; that is, a solid line with a closed, hollow arrowhead pointing at the parent UseCase.
The relationship between a UseCase and its external interaction sequences is usually defined by an invisible hyperlink to sequence diagrams. The relationship between a UseCase and its realization may be shown as dashed arrow with the keyword «representedClassifier» to collaborations, but may also be defined as invisible hyperlinks.
Figure 23 UseCase diagram with include and extend relations
A path between UseCase and/or actor symbols maps into the corresponding relationship between the corresponding Elements, as described above.
Actor Relationships
There is one standard relationship among actors and one between actors and use cases.
Association: The participation of an actor in a use case; that is, instances of the actor and instances of the use case communicate with each other. This is the only relationship between actors and use cases. ebIX Modelling Methodology 55
Generalization: A generalization from an actor A to an actor B indicates that an instance of A can communicate with the same kinds of use-case instances as an instance of B.
An association between an actor and a use case is shown as a solid line between the actor and the use case.
A generalization between actors is shown by a generalization arrow; that is, a solid line with a closed, hollow arrowhead. The arrowhead points at the more general actor.
Figure 24 Generalisation
A generalization between two actor symbols and an association between actor symbol and a UseCase symbol maps into the corresponding relationship between the corresponding Elements, as described above. ebIX Modelling Methodology 56
G.3
Sequence diagram
A sequence diagram presents an Interaction, which is a set of Messages between Roles within a
Collaboration. A sequence diagram specifies a sequence of communications; it contains a collection of partially ordered Messages, each specifying a communication between a sender role and a receiver role.
A sequence diagram has two dimensions: the vertical dimension represents time, and the horizontal dimension represents different instances. Normally time proceeds down the page. Usually only time sequences are important. There is no significance to the horizontal ordering of the instances.
Various labels (such as timing constraints, descriptions of actions during an activation, and so on) can be shown either in the margin or near the transitions or activations that they label.
Figure 25 Sequence diagram
An arrow with the arrowhead pointing to an object symbol or role symbol within the frame of the diagram maps into a Message dispatched by a CreateObjectAction. The interpretation is that an
Instance is created by dispatching the Message. After the creation of the Instance, it may immediately start interacting with other Instances. This implies that the creation method (constructor, initializer) of ebIX Modelling Methodology 57
the Instance dispatches these Messages. If an object termination symbol (“X”) is the target of an arrow, the arrow maps into a Message that will cause the receiving Instance to be removed. If the object termination symbol appears in the diagram without an incoming arrow, it maps into a Procedure containing a DestroyObjectAction.
Object Lifeline
In a sequence diagram an object lifeline denotes an Instance playing a specific role. It is shown as a vertical dashed line. Arrows between the lifelines denote communication between the Instances playing those roles. Within a sequence diagram the existence and duration of the Instance in a role is shown, but the relationships among the Instances are not shown. The role is specified by a
ClassifierRole; it describes the properties of an Instance playing the role and describes the relationships an Instance in that role has to other Instances.
The lifeline represents the existence of the Instance at a particular time. If the Instance is destroyed during the diagram, then its destruction is marked by a large “X,” either at the arrow mapping to the
Stimulus that causes the destruction or (in the case of self-destruction) at the final return arrow from the destroyed Instance.
The lifeline may split into two or more concurrent lifelines to show conditionality. Each separate track corresponds to a conditional branch in the communication. The lifelines may merge together at some subsequent point.
In some cases, it is necessary to link sequence diagrams to each other; for example, it might not be possible to put all lifelines in one diagram, or a sub-sequence is included in several diagrams; hence, it is convenient to put the common sub-sequence in a separate diagram, which is referenced from the other diagrams. In these cases, the cut between the diagrams can be expressed in one of the diagrams with a dangling arrow leaving a lifeline but not arriving at another lifeline, and in the other diagram it is expressed with a dangling arrow arriving at a lifeline from nowhere. In both cases, it is recommended to attach a note stating which diagram the sequence originates from or continues in.
This is purely notational. The different diagrams show different parts of the underlying Interaction.
Activation
An activation (focus of control) shows the period during which an Instance is performing a Procedure either directly or through a subordinate procedure. It represents both the duration of the performance of the Procedure in time and the control relationship between the activation and its callers (stack frame).
An activation is shown as a tall thin rectangle whose top is aligned with its initiation time and whose bottom is aligned with its completion time. The Procedure being performed may be labeled in text next to the activation symbol or in the left margin, depending on style. Alternately, the incoming arrow may indicate the Procedure, in which case it may be omitted on the activation itself. In procedural flow of control, the top of the activation symbol is at the tip of an incoming arrow (the one that initiates the procedure) and the base of the symbol is at the tail of a return arrow.
In the case of concurrent Instances each with their own threads of control, an activation shows the duration when each Instance is performing an Operation or transition in a state machine. Operations by other Instances are not relevant. If the distinction between direct computation and indirect computation
(by a nested operation call) is unimportant, the entire lifeline may be shown as an activation.
Message and Stimulus
A Stimulus is a communication between two Instances that conveys information with the expectation that action will ensue. A Stimulus will cause an Operation to be invoked, raise a Signal, or cause an ebIX Modelling Methodology 58
Instance to be created or destroyed. A Message is a specification of Stimulus, i.e. it specifies the roles that the sender and the receiver Instances must conform to, as well as the Procedure which will, when executed, dispatch a Stimulus that conforms to the Message.
In a sequence diagram a Stimulus as well as a Message is shown as a horizontal solid arrow from the lifeline of one Instance or ClassifierRole to the lifeline of another Instance or ClassifierRole. In case of a Stimulus from an Instance to itself, the arrow may start and finish on the same lifeline. The arrow is labeled with the name of the Operation to be invoked or the name of the Signal. Its argument values or argument expressions may be presented, as well.
The arrow may also be labeled with a sequence number to show the sequence of the Stimulus
(Message) in the overall interaction. However, sequence numbers are often omitted in sequence diagrams, as the physical location of the arrow shows the relative sequences, but they are necessary in collaboration diagrams. Sequence numbers are useful on both kinds of diagrams for identifying concurrent threads of control. An arrow may also be labeled with a condition and/or iteration expression.
The following arrowhead variations may be used to show different kinds of communications:
Filled solid arrowhead Operation call or other nested flow of control. The entire nested sequence is completed before the outer level sequence resumes. The arrowhead may be used to denote ordinary operation calls, but it may also be used to denote concurrently active instances when one of them sends a Signal and waits for a nested sequence of behavior to complete before it continues.
Stick arrowhead Asynchronous communication; that is, no nesting of control. The sender dispatches the Stimulus and immediately continues with the next step in the execution.
Dashed arrow with stick arrowhead Return from operation call.
Variations
Normally message arrows are drawn horizontally. This indicates the duration required to send the stimulus is “atomic;” that is, it is brief compared to the granularity of the interaction and that nothing else can “happen” during the transmission of the stimulus. This is the correct assumption within many computers. If the stimulus requires some time to arrive, during which something else can occur (such as a stimulus in the opposite direction), then the arrow may be slanted downward so that the arrowhead is below the arrow tail.
A branch is shown by multiple arrows leaving a single point, each possibly labeled by a condition.
Depending on whether the conditions are mutually exclusive, the construct may represent conditionality or concurrency.
A connected set of arrows may be enclosed and marked as an iteration. For a generic sequence diagram, the iteration indicates that the dispatch of a set of stimuli can occur multiple times. For a procedure, the continuation condition for the iteration may be specified at the bottom of the iteration. If there is concurrency, then some arrows in the diagram may be part of the iteration and others may be single execution. It is desirable to arrange a diagram so that the arrows in the iteration can be enclosed together easily.
A lifeline may subsume an entire set of objects on a diagram representing a high-level view. ebIX Modelling Methodology 59
Transition Times
A Message may specify several different times; for example, a sending time and a receiving time.
These are formal names that may be used within Constraint expressions. The set of different kinds of times is open-ended so that users can invent new ones as needed for special situations, such as elapsedTime and startExecutionTime. These expressions may be used in Constraints to designate specific time constraints valid for the Message.
A transition instance (such as a Message in a sequence diagram) may be given a name. A timing constraint is formed as an expression based on the name of the transition. For example, if the name of a Stimulus is stim, its send-time is expressed by stim.sendTime (), and its receive-time by stim.receiveTime (). The timing constraint may be shown in the left margin aligned with the arrow.
Constraints may be specified by placing Boolean expressions, possibly including time expressions, in braces on the sequence diagram.
Figure 26 Sequence diagram with time scale
When it is clear from the context, the name of a Message or the name of a Stimulus may itself be used to denote the time at which the transition started. In cases where the performance of the transition is not instantaneous, the time at which the transition is ended may be indicated by the same name with a prime sign appended to the name. ebIX Modelling Methodology 60
G.4
Activity diagram
An activity diagram is a variation of an UML “state diagram” in which the states represent the performance of actions or subactivities and the transitions are triggered by the completion of the actions or subactivities. The entire activity diagram is attached (through the model) to a UseCase.
A UseCase is described by an Activity diagram and a Sequence diagram Action state
Sequence diagram
An Activity diagram may have one or more
Subactivity diagrams linked through Subactivity states
Subactivity state
Activity diagram
Figure 27 Activity diagram (Overview)
Action state:
An action state is shorthand for a state with an entry action and at least one outgoing transition involving the implicit event of completing the entry action (there may be several such transitions if they have guard conditions). Action states should not have internal transitions. The transitions may include guard conditions and actions. An action state is used to model a step in the execution of a workflow process. Actions operate by and on objects. These objects either have primary responsibility for initiating an action, or are used or determined by the action.
In sequence diagrams, the object responsible for performing an action is shown by drawing a lifeline and placing actions on lifelines. Activity diagrams do not show the lifeline, but each action specifies which object performs its operation. These objects are within ebIX models related to swimlanes.
Frequently the same object is manipulated by a number of successive actions or subactivities. It is possible to show one object with arrows to and from all of the relevant actions and subactivities, but for greater clarity, the object may be displayed multiple times on a diagram. Each appearance denotes a different point during the object’s life. To distinguish the various appearances of the same object, the state of the object at each point may be placed in brackets and appended to the name of the object (for example, PurchaseOrder[approved]). This notation may also be used in sequence diagrams. ebIX Modelling Methodology 61
Subactivity state:
A subactivity state invokes an activity diagram. When a subactivity state is entered, the activity diagram “nested” in it is executed, as any activity diagram would be. The subactivity state is not exited until the final state of the nested diagram is reached.
Guard conditions:
An activity diagram expresses a decision when guard conditions are used to indicate different possible transitions that depend on Boolean conditions of the owning object. UML provides shorthand for showing decisions and merging their separate paths back together. Each possible outcome should appear on one of the outgoing transitions. A predefined guard denoted “else” may be defined for at most one outgoing transition. This transition is enabled if all the guards labelling the other transitions are false.
A decision may be shown in two ways, either by labelling multiple output transitions of an action with different guard conditions or by using the icon provided for a decision (the traditional diamond shape), with one incoming arrow and with two or more outgoing arrows, each labelled by a distinct guard condition.
The same icon can be used to merge decision branches back together, in which case it is called a merge. A merge has two or more incoming arrows and one outgoing arrow. The transition coming from a merge may not have a trigger label or guard expressions.
Swimlanes
An activity diagram may be divided visually into “swimlanes,” each separated from neighbouring swimlanes by vertical solid lines on both sides. The relative ordering of the swimlanes has no semantic significance. Each action is assigned to one swimlane. Transitions may cross lanes. Swimlanes are used to organize responsibility for actions and subactivities. Within ebIX swimlanes will correspond to roles in the Business information models.
Deferred events:
A frequent situation is when an event that occurs must be “deferred” for later use while some other action or subactivity is underway. (Normally an event that is not handled immediately is lost.) This may be thought of as having an internal transition that handles the event and places it on an internal queue until it is needed or until it is discarded. Each state specifies a set of events that are deferred if they occur during the state and are not used to trigger a transition. If an event is not included in the set of deferrable events for a state, and it does not trigger a transition, then it is discarded from the queue even if it has already occurred. If a transition depends on an event, the transition fires immediately if the event is already on the internal queue. If several transitions are possible, the leading event in the queue takes precedence. A deferrable event is shown by listing it within the state followed by a slash and the special operation defe r. If the event occurs, it is saved and it recurs when the object transitions to another state, where it may be deferred again. When the object reaches a state in which the event is not deferred, it must be accepted or lost. The indication maybe placed on a composite state or its equivalents, submachine and subactivity states, in which case it remains deferrable throughout the composite state. A contained transition may still be triggered by a deferrable event, whereupon it is removed from the queue.
It is not necessary to defer events on action states, because these states are not interruptible for event processing. In this case, both deferred and undeferred events that occur during the state are deferred until the state is completed. This means that the timing of the transition will be the same regardless of the relative order of the event and the state completion, and regardless of whether events are deferred. ebIX Modelling Methodology 62
Conditional Forks:
In Activity Diagrams, transitions outgoing from forks may have guards. This means the region initiated by a fork transition might not start, and therefore is not required to complete at the corresponding join. The usual notation and mapping for guards may be used on the transition outgoing from a fork.
Figure 28 Activity diagram ebIX Modelling Methodology 63
G.5
Class diagram
The following pages shows rules for making class diagrams based on the UN/CEFACT Requirements
Specification Mapping (RSM).
Class:
A description of a set of objects that share the same attributes, operations, methods, relationships, and semantics.
Note: In the initial implementation of UML classes the well formedness or the use of operations and methods have not been defined.
All classes shall be normalized. That is to say:
1.
An attribute shall represent a single piece of information
2.
An attribute shall appear only once (i.e. it cannot be repeated)
3.
An attribute shall have a distinct name
4.
Each instance of a class must be uniquely identifiable
5.
There is no positional dependence between the attributes
6.
All attributes contribute to the definition of the class
Association:
An association is the semantic relationship between two or more classes that specifies connections among their instances.
The only relationship permitted in a UMM compliant class diagram is a composite aggregation.
Composite aggregation is a strong form of aggregation, which requires that a part instance be included in at most one composite at a time and that the composite object has sole responsibility for the disposition of its parts. This means that the composite object is responsible for the creation and destruction of the parts. If a composite object is destroyed, it must destroy all of its parts. It may remove a part and give it to another composite object, which then assumes responsibility for it.
All compositions shall be unidirectional.
Role:
A Role is the named specific behavior of an entity participating in a particular context.
A role identifies a specific case of a generic class. In general only target roles should be used. Source roles should be avoided whenever possible. Source roles tend to identify constraints as opposed to behavior.
A role name may be concatenated with a class name to provide a specific type of a generic clas s. ebIX Modelling Methodology 64
Cardinality:
The Cardinality is the number of elements in a set.
The cardinality shall be used for an attribute uniquely to indicate a conditional attribute with the convention “[0..1]” that immediately follows the attribute name. No other attribute cardinality is permitted. A conditional attribute shall have an associated dependency table to describe the conditionality constraint.
The cardinality of an association shall only appear at the target end of the association.
Data type:
A data type is a descriptor of a set of values that lack identity and whose operations do not have side effects. Datatypes include primitive pre-defined types and user-definable types. Predefined types include numbers, string and time. User definable types include enumerations.
An attribute shall use a core components data type.
Constraint:
A constraint is a semantic condition or restriction.
Only XoR constraints are allowed between associations. All associations constraints must be defined in a dependency table. ebIX Modelling Methodology 65
Generalization:
A generalization is a taxonomic relationship between a more general element and a more specific element. The more specific element is fully consistent with the more general element (it has all of its properties, members, and relationships) and may contain additional information.
Generalisations shall be avoided in the modelisation of documents.
Stereotype:
A stereotype is a new type of modelling element that extends the semantics of the meta-model. Stereotypes must be based on certain existing types or classes in the meta-model. Stereotypes may extend the semantics, but not the structure of pre-existing types and classes.
Stereotypes shall only be used within a canonical model to identify classes that have been built from ACCs. Classes that have not been built from an ACC shall not be stereotyped.
An attribute of a class that represents the same concept, as a BCC shall be stereotyped BBIE within a canonical model provided that this is not a class that originates from an ACC.
The only other stereotype permitted within a class in a canonical model shall be the “enumeration” stereotype that shall be used to identify a code list.
ACC and BCC Stereotypes shall be used in the core components repository to identify aggregated core components and basic core components accordingly. An ASCC stereotype is not required within the core component repository since the nature of the association is explicitly expressed in a composition association An ASBIE stereotype shall not be used in a Canonical model since it is explicitly expressed through the use of a composition association and a role.
Enumeration:
An enumeration is a list of named values used as the range of a particular attribute type.
Enumerations shall be used to identify code lists.
In the canonical model an enumeration shall be used to identify a restriction on a generic code list. ebIX Modelling Methodology 66
Association classes:
No association classes are permitted.
No association names are permitted ebIX Modelling Methodology 67
