You are on page 1of 73

OSS through JavaTM Initiative

Core Business Entities Model White Paper


OSS through Java Initiative

COM-WP-CBE_concepts.1.2.doc Copyright 2004 BEA Systems, Inc., Mahindra-British Telecom, Metasolv Software Inc., Motorola, Inc., NEC Corporation, Nokia Networks Oy, Nortel Networks Limited, Sonic Software Corporation, Sun Microsystems, Inc., Telcordia Technologies, Inc. All rights reserved. Use is subject to license terms. Edited by John P. Reilly and Pierre Gauthier, MetaSolv Software Contributors: Dave Raymer, Motorola; Andreas Ebbert, Nokia; Melody Khair, Digital Fairways; Maricio Arango, Sun; Colin Ashford, Nortel TM Forum SID Team John Strassner (Intelliden), Wayne Sigley (Telstra), Helen Hepburn (British Telecom), Chris Hartley (Telstra), and Cliff Faurer (TM Forum)

COM-WP-CBE_concepts.1.2.doc

page 1 / 73

OSS through JavaTM Initiative

Executive Summary
API developers face the task of defining, modeling, and implementing core concepts in the course of almost every project in which they are involved. Core concepts include individuals (such as employees) & organizations (such as customers), products, services, & resources, locations & addresses, along with interactions that involve individuals and organizations. These core concepts represent who, what, when, where, and why that make up the set of fundamental concepts present in todays world. Perceptive developers reuse these concepts across the projects on which they work, but they still must implement them at least once. As well as being time-consuming, this effort also breeds inconsistency, a major threat to interoperability. The OSS through Java initiative has the opportunity to improve the efficiency of API developers and maintain consistency by defining, modeling and implementing these core concepts. This work effort can leverage work already in progress being carried out by the TeleManagement Forums New Generation OSS (NGOSS) Shared Information/Data (SID) Model team. The SID represents a synthesized view of information derived from various industry models. This enables existing applications and software to be leveraged in building systems. The SID, a federation of models, also forms a common information language that the industry can use to describe management information. The scope of this document is the explanation (based on the TM Forum SID) of these core concepts, their associated information models, and the specification of the interfaces, which involve these core concepts. The core concepts are referred to as core business entities in this document. These definitions, information models, and specifications, which together represent the OSS/J API core model, can and should be used as the cornerstone for any subsequent OSS/J API development. The CBE is a subset of the SID that is based on the needs of the OSS/J APIs in existence. The subset may represent complete portions of the SID model or partial portions that contain only higher level SID entities. As new APIs are added or existing APIs are enhanced, the CBE model will expand based on the scope of the new or enhanced API.

COM-WP-CBE_concepts.1.2.doc

page 2 / 73

OSS through JavaTM Initiative

Table of Contents
Executive Summary .......................................................................................................... 2 Table of Contents .............................................................................................................. 3 Table of Figures................................................................................................................. 6 Table of Code Snippets..................................................................................................... 7 1 Preface........................................................................................................................ 8 1.1 1.2 1.3 1.4 1.5 1.6 2 Objectives............................................................................................................ 8 Audience.............................................................................................................. 8 Approval and Distribution .................................................................................. 8 Related Information ............................................................................................ 8 How this document is organized ......................................................................... 8 Revision History for version 2.0 ......................................................................... 9

Introduction............................................................................................................. 10 2.1 2.2 2.3 Opportunity Knocks .......................................................................................... 10 Core Business Entities ...................................................................................... 10 A Starting Point for Core Business Entities (CBE) .......................................... 12

Concepts................................................................................................................... 14 3.1 3.2 3.3 Business entity................................................................................................... 14 Core Business Entity ......................................................................................... 14 Core Model ....................................................................................................... 14

Core Business Entity Modeling Concepts............................................................. 15 4.1 4.2 4.3 4.4 4.5 4.6 4.7 Introduction....................................................................................................... 15 Managed Entities .............................................................................................. 17 Entities .............................................................................................................. 17 Entity Specifications.......................................................................................... 17 Associations ...................................................................................................... 21 Constraints........................................................................................................ 23 Generalization................................................................................................... 23

SID Model Overview............................................................................................... 24


COM-WP-CBE_concepts.1.2.doc page 3 / 73

OSS through JavaTM Initiative

5.1 The Who - Party ................................................................................................ 24 5.1.1 Overview................................................................................................... 24 5.1.2 Party Fundamentals................................................................................... 24 5.1.3 Contact Medium........................................................................................ 25 5.1.4 Party Roles ................................................................................................ 26 5.1.5 Interactions between Parties ..................................................................... 29 5.1.6 Associations between Party Roles ............................................................ 29 5.1.7 Party Names .............................................................................................. 30 5.1.8 Interworking with other business entities ................................................. 31 5.1.9 Example Extension of Party Customer .................................................. 32 5.2 The What Product, Service, and Resource..................................................... 33 5.2.1 Overview................................................................................................... 33 5.2.2 Product Inventory...................................................................................... 35 5.2.3 Service Inventory ...................................................................................... 35 5.2.4 Resource Inventory ................................................................................... 36 5.2.5 Use Cases .................................................................................................. 37 5.3 The Where - Location........................................................................................ 37 5.3.1 Disclaimer ................................................................................................. 38 5.3.2 Overview................................................................................................... 38 5.3.3 Location .................................................................................................... 39 5.4 The When and the Why Business Interaction................................................. 41 5.4.1 Overview................................................................................................... 41 5.4.2 Sample Business Interaction Use Cases ................................................... 46 6 Core Model and SID Adoption Strategies ............................................................ 50 6.1 6.2 Core Model Strategy ......................................................................................... 50 SID Adoption Strategy ...................................................................................... 50

6.3 CBE Scope Defined Using the SID Framework ............................................... 54 6.3.1 Product Domain ........................................................................................ 55 6.3.2 Customer Domain ..................................................................................... 55 6.3.3 Service Domain......................................................................................... 55 6.3.4 Resource Domain...................................................................................... 55 6.3.5 Common Business Entities Domain ......................................................... 56 7 CBE Java Interface Definition Examples ............................................................. 57 7.1 Inventory and Service Activation Interaction Example .................................... 58 7.1.1 Inventory and Service Activation Collaboration Principals ..................... 58 7.1.2 Use-Case Customer Orders A Product ..................................................... 59 7.1.3 Use-Case: Product Order Decomposition................................................. 61 7.1.4 Usage of CBE in Service Activation ........................................................ 62 7.1.5 Code examples of Inventory and Service Activation Usage .................... 63 8 Compatibility with Other Industry Models.......................................................... 66 8.1 ebXML Party Information................................................................................. 66
COM-WP-CBE_concepts.1.2.doc page 4 / 73

OSS through JavaTM Initiative

8.1.1 8.1.2 8.1.3 8.2

PartyId element ......................................................................................... 67 PartyRef element....................................................................................... 68 CollaborationRole element ....................................................................... 69

CBE Representation of ebXMLs Party Information Requirements ................. 70

Glossary and References ................................................................................................ 72 8.3 8.4 Glossary ............................................................................................................ 72 References ......................................................................................................... 72

COM-WP-CBE_concepts.1.2.doc

page 5 / 73

OSS through JavaTM Initiative

Table of Figures
Figure 1 - Fundamental Entities........................................................................................ 10 Figure 2 - Meta-Layers ..................................................................................................... 16 Figure3 - Example of a Core Business Entity................................................................... 17 Figure 4 - Example of Entity Instance Defined by Entity Specification .......................... 19 Figure 5 - Example of Entities and Entity Specifications................................................. 20 Figure 6 - Associations Between Entity and Specification Instances............................... 21 Figure 7 - Example of an Association............................................................................... 22 Figure 8 - Showing How Party Fits In .............................................................................. 24 Figure 9 - Basic Party Model (source: TM Forum) .......................................................... 25 Figure 10 - Initial Party Model (source: TM Forum) ....................................................... 26 Figure 11 - Party and the Main eTOM Roles (source: TM Forum).................................. 28 Figure 12 - Parties Interact Via Their Roles (source: TM Forum) ................................... 29 Figure 13 - Parties Can Be Associated Via Their Roles (source: TM Forum) ................. 30 Figure 14 - Naming For Parties (source: TM Forum)....................................................... 31 Figure 15 - Possible Links to Other Parts of the Core Model (source: TM Forum)......... 32 Figure 16 - Customer Shown As An Extension of Party Role (source: TM Forum)........ 33 Figure 17 - Showing How Products, Services, and Resources Fit In ............................... 34 Figure 18 - Inventory Business Entities............................................................................ 37 Figure 19 - Showing How Locations Fit In ...................................................................... 38 Figure 20 - Initial Location Model.................................................................................... 40 Figure 21 - Showing How Interactions Fit In ................................................................... 41 Figure 22 - Types of Business Interactions (source: TM Forum)..................................... 42 Figure 23 - The Relationship Between Business Interactions and Business Participants (source: TM Forum).................................................................................................. 43 Figure 24 - The Relationship Between Business Interaction and Products, Services, and Resources (source: TM Forum) ................................................................................ 44 Figure 25 - The Relationship Between Business Interactions and Locations (source: TM Forum)....................................................................................................................... 45 Figure 26 Business Interaction Business Entity Model (source: TM Forum) ............... 46 Figure 27 - SID Product Offering ABE ............................................................................ 51 Figure 28 - Sample OSS/J API Trouble Ticket Attributes ............................................... 52 Figure 29 - Sample OSS/J Trouble Ticket Methods......................................................... 52 Figure 30 Current CBE Scope ....................................................................................... 54 Figure 31 - Interaction Principals between Inventory and Activation Components......... 58 Figure 32 - Customer Interaction: Order a New Product.................................................. 59 Figure 33 - Decomposition of a Product Order into Two Service Orders ........................ 61 Figure 34 - Modeling Concepts between Service Activation and CBE............................ 63 Figure 35 - CBE Party Model's Compatibility with ebXML Party .................................. 71

COM-WP-CBE_concepts.1.2.doc

page 6 / 73

OSS through JavaTM Initiative

Table of Code Snippets


Snippet 1 - Query the Product Catalog ............................................................................. 63 Snippet 2 - Use A Specification To Instantiate A Product ............................................... 64 Snippet 3 - Create And Start An Order............................................................................. 64 Snippet 4 - Query Resources............................................................................................. 64 Snippet 5 - ebXML PartyInfo Element............................................................................. 66 Snippet 6 - Example of Two URI References .................................................................. 68 Snippet 7 - Example of the PartyRef Element .................................................................. 69 Snippet 8 - Example of the CollaborationRole Element................................................... 69

COM-WP-CBE_concepts.1.2.doc

page 7 / 73

OSS through JavaTM Initiative

1 Preface
1.1 Objectives
The intention of this document is to provide definitions and to present outline models for an initial set of core business entities (also called shared business entities). A companion Rational Rose model contains the UML representation of the core business entities. The initial set of objects includes Party (individual or organization), Product, Service, Resource, Location and Address, and Interaction (between parties).

1.2

Audience
This guideline is intended for use by various groups specifying APIs within OSS/J.

1.3

Approval and Distribution


This document has been reviewed and approved by the OSS/J Core Business Entity (CBE) team as well as the OSS/J Common team. Subsequent versions will be developed, reviewed, and approved by the CBE team. Versions will also be reviewed and approved by the OSS/J Common team. The TeleManagement (TM) Forum Shared Information and Data Model (SID) team may also provide reviews of subsequent versions. The documents latest version will be made available for distribution on the OSS Through Java web site.

1.4

Related Information
Some of the content of this document was extracted from TM Forum SID documents (GB922 and GB926 series) and the OSS/J Inventory API (JSR142). Copies of these documents are available to registered users on the TM Forum web site and the OSS Through Java website.

1.5

How this document is organized


This document contains a brief introductory section and a section explaining core business entity concepts.

COM-WP-CBE_concepts.1.2.doc

page 8 / 73

OSS through JavaTM Initiative

Following these two sections are separate sections that present the core business entities Party Product, Service, Resource Location & Address Interaction

Each of these sections provides examples of how the core business entities represented in the core model can be used in OSS/J API specifications, such as the Service Activation and Inventory APIs

1.6

Revision History for version 2.0


Version 2.0 Author John Reilly State Draft Comments Add CBE coverage of SID Framework; place interface definitions into a separate document Improved Figure 4 Added chapter 7.1 Updated doc name and version number for inclusion in 1.2 Design Guidelines.

Date 12 Apr 2004

23 Apr 2004 8 Dec 2004

2.1 1.2

Andreas Ebbert John Reilly

Draft Final

COM-WP-CBE_concepts.1.2.doc

page 9 / 73

OSS through JavaTM Initiative

2 Introduction
2.1 Opportunity Knocks
Throughout the years, API developers have repeatedly come up with definitions and implementations of core concepts such as locations, addresses, individuals, and organizations, products, services, and resources. These attributes represent a core set of objects that should be defined and implemented once, and then reused again and again. This represents an opportunity for the OSS through Java initiative to define a set of core business entities (sometimes referred to as shared business entities) represented in a core model. The end result would be a java package for the core business entities, javax.oss.cbe, and its associated XML schema. Any OSS/J API should use the core model as a starting point for API development. The use of this model would resolve the overlaps and inconsistencies already present in some OSS/J APIs. It would also eliminate any future inconsistencies and duplication of effort. Additionally, the core model could be distributed to several repositories to implement the model with different technologies and/or differentnative schemas As new APIs are developed, additional core business entities may be added to the core model.

2.2

Core Business Entities


The first step is to identify a set of core business entities. The things in which any enterprise is interested can be represented by entities that answer five fundamental questions as shown in the figure below.
<<concept>> Who (Party) <<concept>> Where (Location)

<<concept>> When (TimePeriod)

<<concept>> Why (Reason)

<<concept>> What (Thing)

Figure 1 - Fundamental Entities

For example, an SLA Violation Alarm (Notification) about Service is communicated to SLA Management (Organization). The SLA Violation

COM-WP-CBE_concepts.1.2.doc

page 10 / 73

OSS through JavaTM Initiative

Alarm may result in a Billing Credit Notification being sent to a Customer (Individual or Organization) at the Customers home Address. The initial scope of the core business entity package would include The Who Party and Party Roles (Customer, Service Provider and so forth) The What - Product, Service, and Resource The Where - Location & Address The When and Why - Interaction Parties are individuals and organizations that interact with an enterprise as the enterprise carries out its day-to-day business. Parties play roles as they interact with an enterprise. The roles parties play can be customers, employees, suppliers, partners, the enterprise and its organizations, and so forth. Parties and the roles parties play represent a distillation of all the attributes, associations and behavior that customers, employees, and so forth have in common. Examples from an attribute perspective include name, location and address, and contact medium. From a behavioral perspective, parties come into existence, their status is tracked during their life of interest to the business, and they are eventually no longer of business interest. Location is a concept representing a place, such as a structure like a building. An address is not a type of location but is a means of finding a location. Addresses may have aliases, for instance Cnr Surf and Roban streets may be an alias for (refers to the same location) as 15 Roban Street. Unlike parties and interactions, which are distillations of things common to a number of different objects, locations and addresses are not abstractions but business entities in their own right that are associated to a number of other business entities, including parties, interactions, resources, services, products, and so forth. A Product is an externally facing representation of a service and/or resource procured by the market. For example, a real-time broadcast of a football match. A Service is an intangible realization of a Product or something provided in support of a Product. For example, a video streaming connection used to transmit the football match to a customers PDA; an installation service provided for a cable modem. A Resource is part of an enterprises infrastructure utilized by a Service or a good procured by the market. One example of a resource is a wireless network (infrastructure) utilized by the video streaming connection. Another example is an inventory of cable modems (goods procured by the market) offered to the market. Interactions are arrangements, contracts, communications and activities that involve parties playing a role. For example, a prospective customer may

COM-WP-CBE_concepts.1.2.doc

page 11 / 73

OSS through JavaTM Initiative

request information about a real-time football match broadcast product offering. This request may then become an order for the broadcast to be sent to the customers PDA. This order is another type of interaction. Interactions, like parties, represent a distillation of attributes, associations, and behavior common to requests, responses, notifications, and agreements. For example, in addition to all forms of interactions involving parties playing a role, interactions also involve products, services, resources, product offerings, locations, and addresses from an association perspective. A number of core business entities, such as Party and Interaction, represent abstract concepts. As such, their concrete subclasses inherit the behaviors, attributes, and associations of the abstract class. Use Cases associated with the abstract class can also be inherited. The benefits of Use Case inheritance will be shown via example in this white paper. With the introduction of UML 1.3, a new relationship between use cases was introducedgeneralization. A generalization relationship between parent and child use cases is one in which the child is a more specialized form of the parent use case. The child inherits the behaviors of its parents and adds new behaviors, and specializes in behaviors inherited from the parent. Generalized use cases typically involve abstract actors and abstract classes.

2.3

A Starting Point for Core Business Entities (CBE)


Today the communications and information service industry is awash with information and data models and model fragments. Organizations and forums such as the OSS through Java Initiative (OSS/J), Object Management Group (OMG), DMTF (Distributed Management Task Force), T1M1 committee of the Alliance for Telecommunications Industry Solutions (ATIS), International Telecommunications Union (ITU), Internet Engineering Task Force (IETF), and Internet Protocol Detail Record Organization (iPDR.org), TeleManagement Forum and others, have developed models and model fragments. These models have formed the foundation for fruitful attempts at OSS interoperability. While it is unfortunate that we have so many models, their existence has pointed out the pressing need for a shared information model. What would be better than these disparate models is a shared information/data model that represents a synthesized view of a number of these industry models. This synthesized model would form a common information/data language for the industry along with facilitating interoperability among diverse sets of applications. This is the focus of a major initiative underway in the TeleManagement Forums Shared Information and Data Modeling team (SID) The SID model is gaining acceptance within the communications and information services industry. For example, the TM Forums DEN-ng project is an application representing the practical implementation of the

COM-WP-CBE_concepts.1.2.doc

page 12 / 73

OSS through JavaTM Initiative

SID model. TM Forum Catalyst projects are using the SID as an interoperability model for products, services, and resources. The OMG is planning to present the SID documents as a OMG white paper that recommends the use of the SID as the foundation for the OMGs Telecom Domain Task Force configuration independent model. ITU/T1M1 are using the SID as a source for its Global Telecom Data Dictionary (GTDD). The SID model contains a set of common business entity definitions and models that can be used to form the foundation for the core model of OSS/J CBEs (shared business entities using TM Forum terminology). This foundation can be extended as needed by OSS/J APIs, but the foundations basic structure should not be compromised.

COM-WP-CBE_concepts.1.2.doc

page 13 / 73

OSS through JavaTM Initiative

3 Concepts
3.1 Business entity
A business entity is a thing of interest to the business. Business entities are characterized by attributes. Business entities also possess other properties, such as involvement in associations with other business entities or entity types and exhibition of behavior. These properties (attributes, associations, and behavior) of business entities may be inherited by the other entity types or other business entities.

3.2

Core Business Entity


Core business entities represent five basic concepts present in the day-today running of every enterprise. The concepts are who, what, where, when and why. A core business entity may be an object that primarily supports a group of TM Forum eTOM processes. These business entities support processes in the Product, Service, and Resource layers of the eTOM. A core business entity may also be a business entity that is common to a number of eTOM processes, for example Location and Address. Core business entities can represent an abstraction, such as a superclass, or a real world object.

3.3

Core Model
The core model contains the artifacts that fully describe core business entities. The artifacts include core business entity definitions and UML models. The UML models contain class diagrams that document the attributes and operations of the core business entities.

COM-WP-CBE_concepts.1.2.doc

page 14 / 73

OSS through JavaTM Initiative

4 Core Business Entity Modeling Concepts


Note: The contents of this chapter are a modified extract from the OSS/J Inventory API Specification (JSR 142). The concepts presented in the Inventory API have been generalized here so that they apply to the Core Business Entity model.

4.1

Introduction
The framework for meta-modeling data proposed in this document is based on an architecture composed of three layers. Each of the layers provides different levels of abstraction. These layers are defined as follows: The meta-model layer is comprised of the descriptions that define the structure and semantics of core business entity models (i.e., information model for meta-data). The model layer is comprised of the meta-data that describes the core business entity information. This layer is also referred to as meta-data or core business entity model. Core models could be translated to specific schema definitions for various repositories (e.g., XML Schema, SQL DDL, LDAP Schema, etc.) The instance layer is comprised of the core business entity information stored in the repository. This information is also referred to as core data. The meta-model defines a subset of UML elements to be used for modeling Core Business Entities. The meta-model uses the UML concepts of class, association and constraint to model the elements managed entity, entity, entity specification and association. (see Meta Layers Figure).

COM-WP-CBE_concepts.1.2.doc

page 15 / 73

OSS through JavaTM Initiative

Meta-model Layer

Managed Entity

Entity

Entity Specification

Association

Model Layer

<<Association Interface>> SubscriberSubscribesProduct <<Entity Interface>> VPN_Product

<<Entity Interface>> Subscriber Instance Layer

0..*

0..*

VPN_1 SP1 Inc. VPN_2

Figure 2 - Meta-Layers

The core model defines completely the meta-model layer and partially the model layer. Core business entity models are expressed using class diagrams (see the following chapters). Object diagrams (snapshots), which are the instantiations of class diagrams, may be used to provide examples and explore particular situations. The Core Meta-model extends the UML vocabulary with the following concepts: Entity with stereotype Entity Interface (<<Entity Interface>>). Entities are value type objects representing for example inventory concepts such as Product, Service and Resource. Entity Specification with stereotype Specification Interface (<<Specification Interface>>). Entity Specifications are value type objects representing for example specifications of inventory entities. Association with stereotype Association Interface (<<Association Interface>>). A class diagram representing a Core Business Entity Model could contain the following elements:

COM-WP-CBE_concepts.1.2.doc

page 16 / 73

OSS through JavaTM Initiative

Interfaces with stereotype Entity Interface (<<Entity Interface>>) and their methods to get and set their attributes, leveraging the Entity concept defined in the Core Business Entity meta model. Interfaces with stereotype Specification Interface (<<Specification Interface>>) and their methods to get and set their attributes, leveraging the Entity Specification concept defined in the Core Business Entity meta model. Associations (Aggregation is a special form of association). Some associations are represented as first class objects with stereotype Association Interface (<<Association Interface>>) Constraints Generalizations

4.2

Managed Entities
A Managed Entity is the root class for all Core Business Entity model entities and entity specifications.

4.3

Entities
An Entity is used to represent core business entity objects, which share the same structural and behavioral features. Entities can be represented as interfaces with stereotype Entity Interface (<<Entity Interface>>). The entity contains a list of methods to get and set its attributes.
<<Entity Interface>> Resource getAttributeValues() setAttributeValues() getAllPopulatedAttributes()

Figure3 - Example of a Core Business Entity

4.4

Entity Specifications
An Entity Specification captures invariant characteristics and constraints applicable to all instances of the same business entity. For example, a GoldBroadbandAccessServiceSpecification may capture the characteristics, configuration and QoS parameter ranges, specific to a Gold Broadband Access service offering. Several specification instances may exist for the same inventory entity type. For example, Gold, Silver and Bronze specifications may be defined for a BroadbandAccessService. A Product Specification includes features,

COM-WP-CBE_concepts.1.2.doc

page 17 / 73

OSS through JavaTM Initiative

such as height, weight, and so forth, common to all instances of a Product Offering based on the specification. The use of the Entity Specification/Entity modeling pattern provides a number of benefits over using a pattern that models invariant characteristics as attributes of an Entity. First, the attribute values are not duplicated for each instance of an entity characterized by the same specification. Second, when updating one or more characteristics, only the specification instance characteristics require updating as opposed to the characteristics embedded in each entity instance. Third, if the last entity for a specification is deleted, then entity specification characteristics remain, as opposed to losing the entity specification characteristics if the characteristics are embedded within each entity instance. In some cases, a characteristic, such as color, may take on multiple possible values. To satisfy this requirement an Entity Characteristic and Entity Characteristic Value is used. Color would be an instance of Entity Characteristic. There would be an instance of Entity Characteristic Value for each possible color, say for a Product, such as red, blue, green, and so forth. This pattern allows new characteristics and their values to be added or inactivated without impacting the model. Each Entity instance associated with an Entity Specification would be associated to the characteristic value chosen for the Entity. For example, Jims cell phone is associated with red; Joans phone is associated with blue. Adding a new color does not impact any existing entities, nor does inactivating an existing color. Catalogs are collections of entity specifications (e.g., service catalog composed of service specifications, product catalog composed of product specifications, resource catalog composed of resource specifications, and so forth.). An entity instance is defined by a single entity specification. (The same entity specification may be used to define multiple entity instances.) Note that some entity instances may refer to no entity specification and still be valid ones. Another possible use of entity specifications is in the Customer SLA API. For example, an SLA specification could be the repository for standard terms and objectives used to create SLA entity instances. Additionally, the specifications could contain standard compensation amounts, such as discounts and rebates, which could be associated to SLA entity instances, if SLA objectives are not met. Associations among these entity specifications would define rules as to how the terms, objectives, and compensation amounts can be used together to define an SLA instance. For example, one type of objective may only be compensated via a discount, and not a cash rebate. A number of other OSS/J APIs including those planned in the API roadmap, such as Customer Order Management, Workforce Management, Trouble

COM-WP-CBE_concepts.1.2.doc

page 18 / 73

OSS through JavaTM Initiative

Ticketing, could take advantages of entity specifications. For example, a specification list of commonly performed tasks could find a home as Workforce Management specifications.

Inventory Model
<<Specification>> BroadbandAccessSpecification transferVolume supportType getTransferVolume() setTransferVolume() getSupportType() setSupportType()

Instances
GoldAccess : BroadbandAccessSpecification # supportType = priviledged # transferVolume = 1000000

describes

describes

BobsAccess : BroadbandAccess # domain = java.org # password = sarah # username = bob

<<Entity>> BroadbandAccess username password domain getUsername() setUsername() getPassword() setPassword() getDomain() setDomain()

Figure 4 - Example of Entity Instance Defined by Entity Specification

In order to define the characteristics of complex entities (e.g., service bundles containing multiple services, devices containing shelves, cards and ports, etc.) entity specifications could also participate in associations with other entity specifications. An example of relationships between entities and entity specifications is presented on the following diagram.1

Relationship meaning is discerned as in reading from top to bottom, left to right. For example, in Figure 4 - Example of Entity Instance Defined by Entity Specification, the describes relationship is read as BroadbandAccessSpecification describes BroadbandAccess.
COM-WP-CBE_concepts.1.2.doc page 19 / 73

OSS through JavaTM Initiative

<<Specification Interface>> ProductSpecification

describes <<Entity Interface>> Product

aggregates aggregates <<specification Interface>> ServiceSpecification

<<Specification Interface>> BroadbandAccessSpecification

<<Specification Interface>> E-MailSpecification

<<Specification Interface>> BackupServiceSpecification

describes aggregates describes <<Entity Interface>> Service

describes

aggregates

<<Entity Interface>> BroadbandAccess

<<Entity Interface>> E-Mail

<<Entity Interface>> Backup

Figure 5 - Example of Entities and Entity Specifications

The following instance diagram (corresponding to the information model on Figure 5 - Example of Entities and Entity Specifications) provides examples of relationships between entity and specification instances.

COM-WP-CBE_concepts.1.2.doc

page 20 / 73

OSS through JavaTM Initiative

goldInternetService : ProductSpecification

: aggregates : aggregates goldBAccess : BroadbandAccessSpecification : describes : aggregates

goldEmail : E-MailSpecification goldBackup : BackupServiceSpecification

: describes bobsInternetSu b : Product : aggregates : describes : describes bobsAccess : BroadbandAccess : aggregates : aggregates

bobsBackup : Backup bobsEmail : E-Mail

Figure 6 - Associations Between Entity and Specification Instances

4.5

Associations
Associations are the means by which binary relationships between entities and entity specifications are represented. Associations are characterized by their cardinality and the roles at each association end.

COM-WP-CBE_concepts.1.2.doc

page 21 / 73

OSS through JavaTM Initiative

<<Association Interface>> OwnerOwnsResource

<<Entity Interface>> PartyRole

0..* +owner

0..*

<<Entity Interface>> Resource

+ownedResource

Figure 7 - Example of an Association

No specific implementation is assumed for associations defined in the core business entity model. However, it is expected that with the OSS/J API in most cases associations will be implemented as first class objects (that is, Java classes). The recommended implementation of the associations could be explicitly captured in the information model, using a constraint for the association, indicating that first class objects or attributes should be used. The separation of object structure from associations allows the creation and removal of associations without affecting the objects themselves. The following rules apply to core business entity associations: When creating an association the two entity instances linked by the association must exist in the core business entity repository. When one of the entity instances linked by an association instance is deleted, the association instance should be deleted as well. If the association instance is not deleted, then, in order to maintain referential integrity, references to a deleted entity must be updated to be null. Containment is a special type of relationship. It is of particular importance for business entities such as the resource inventory business entities, for example, representing physical equipment hierarchies. There shouldnt be

COM-WP-CBE_concepts.1.2.doc

page 22 / 73

OSS through JavaTM Initiative

any difference in the way containment relationships are managed by the OSS/J APIs. For some functions specific containment based queries may be defined. In order to allow validation, association rules are used. Association rules are a metadata concept and can be accessed through the APIs, such as the Inventory API, i.e., the client will not only be able to retrieve the list of supported association types but also the rules applying to these associations. Each association rule consists of the following components: The type of each entity involved in the association; The role of each entity; The cardinality constraints; The constraints on the entities involved in the association.

An association is considered valid if it satisfies all the requirements of the corresponding association rule. Although association rules may appear similar to entity specifications, there are fundamental differences between the two concepts. Entity specifications are dynamically created while association rules are not. The primary goal of the entity specifications is to allow specialization according to a predefined set of parameters, while the primary goal of association rules is to provide means for validation.

4.6

Constraints
Constraints are used to attach consistency rules to model components. Constraints for the Core Business Entity model may be described in informal language (e.g., English) or could be formally expressed in Object Constraint Language (OCL) as described in the UML specification. Note that for instance the association rules are captured in Core Business Entity information models as constraints attached to the association links.

4.7

Generalization
Generalization represents a classification relationship between classes. The most important characteristic of this relationship is the substitutability. This requires that wherever a super-class is used in a model, it is possible to replace it with one of its subclasses with no effect on the properties of the model. This means that all attributes, associations and constraints of a super-class should be inherited by its subclasses.

COM-WP-CBE_concepts.1.2.doc

page 23 / 73

OSS through JavaTM Initiative

5 SID Model Overview


5.1 The Who - Party
Note: The contents of this chapter are a modified extract from the TeleManagement Forums Shared Information/Data (SID) Model document GB922 Addendum 1P.

5.1.1

Overview
This chapter answers the question who? and deals with people and organizations in the context of the eTOM, which looks at processes from a Service Providers point of view. The eTOM is a business process model or framework that provides the enterprise processes required for a service provider. [eTOM]
<<concept>> Who (Party) <<concept>> Where (Location)

<<concept>> When (TimePeriod)

<<concept>> Why (Reason)

<<concept>> What (Thing)

Figure 8 - Showing How Party Fits In

Organizations can be internal (department, subsidiary) or external to the Service Provider (suppliers, customers). Individuals can be internal (employees, board members) or external to the Service Provider (customers, organization contacts, shareholders).

5.1.2

Party Fundamentals
Figure 9 - Basic Party Model shows a Party representing an Individual or Organization. 2

All entities referenced in this chapter are fully described in the SID addenda.
COM-WP-CBE_concepts.1.2.doc page 24 / 73

OSS through JavaTM Initiative

Party

partyId

Individual gender placeOfBirth nationality maritalStatus driversLicenceNr passportNr skills disabilities aliveDuring : TimePeriod

Organization companyNr isLegalEntity industrySector existsDuring : TimePeriod

Figure 9 - Basic Party Model (source: TM Forum)

In this model, both organization and organization unit (e.g. consortium, parent company, subsidiary, division, department, branch or team) are represented by the Organization entity, which should be subclassed as required. Organization can also represent government agencies, clubs, charities and educational & religious organizations While Party is not a term often used in the business, the concept of a person or a company is often heard, and the Party abstraction makes the domain model easier to understand.

5.1.3

Contact Medium
A Party can be contacted using a contact medium, which is an abstraction of the commonly used contact types: eMail, Postal Address, telephone, fax etc. When there is a need to show that a Business Entity is only valid for a certain time, this will be shown by an attribute called validFor, of type TimePeriod. In the design model, temporal support may be implemented in other ways, but this approach has been chosen for the analysis model as it shows the requirement without cluttering up the model.

COM-WP-CBE_concepts.1.2.doc

page 25 / 73

OSS through JavaTM Initiative

Contact Medium validFor : T imePerio.. . mayBeReachedUsing 0..n Party partyI d 0..n

PartyContactM edium EmailContact Individual gender placeOfBirth nationality maritalStatus driversLicenceNr passportNr skills disabilities aliveDuring : T imePeriod 0..n +countryOfBirth 1 Country Organization companyNr isLegalEntity industrySector existsDuring : T imePeriod eMailAddress eMailProtocol PostalContact

this will get converted to Location in a later version

Figure 10 - Initial Party Model (source: TM Forum)

An Organization (unit) can contain other Organization (unit)s in a hierarchy.

5.1.4

Party Roles
People and Organizations exhibit complex behavior. A lot of the behavior can be grouped, based on a particular context, or participation in a certain interaction. For instance, a child at school will behave as a student and an adult may behave as a teacher. A person, playing cricket, may behave as a bowler, a batsman or as a fielder or wicket-keeper. These behavior groups will change over time and will cause problems if we model them using inheritance / specialization. Also we need to allow for the fact that a Party may play many roles at one time (an employee may also be a customer, a graduate student may also be a tutor) By modeling PartyRole as a separate concept from Party, we allow for proper representation of these complex sets of behaviors. When looking at the eTOM, we see that in the Value Network, Parties play roles in the context of an interaction to provide Customer value. This interaction may be per service or per event (e.g. a phone call).

COM-WP-CBE_concepts.1.2.doc

page 26 / 73

OSS through JavaTM Initiative

Note that these are roles and that individual organizations (and organizational entities) can adopt different roles in different value networks. Roles represent activities that businesses can engage in and, for example, a service provider may be the customer facing service provider in one value network and a third party (e.g. wholesale) service provider in another. Relationships are established between the roles, hence the business relationship context model. In todays fast-moving marketplace, relationships can be very short-lived compared with the more static relationships of the traditional telecommunications market. By focusing on roles rather than organizations, a more flexible business relationship context model can be achieved. Organizations can adopt and shed roles dynamically, but the relationships between the roles are established, so the adoption of a particular role will also define the relationship of the organization playing that role towards another role player. [eTOM] The Value Network roles defined in the eTOM are shown as subclasses of PartyRole in Figure 11 Note that even though we are modeling from the point of view of the service provider, we need to model all of the value chain. In todays marketplace, companies must implement an end-to-end value stream and have an integrated and customer-centric technology foundation. It is also necessary to be a part of and to manage eBusiness communities (EBCs), which are networks of relationships linking businesses, customers and suppliers to create a unique business entity that is re-configurable, to meet customer needs. In order to develop customer relationship solutions, companies must extend beyond their own boundaries to encompass the entire extended enterprise and make this transparent to the customer. [eTOM]

COM-WP-CBE_concepts.1.2.doc

page 27 / 73

OSS through JavaTM Initiative

T hese are business entities, not software classes

PartyRole status

Party partyId

Value Netw ork Role Service Prov ider Em ployee employmentStatus employeeNr currentSalary : Money Customer favouriteColor Ve nd or Interme diary Service Provider

Th ird P arty Se rvi ce Provider

Complementary Provider

Fu nc tio n or Process Provider

Figure 11 - Party and the Main eTOM Roles (source: TM Forum)

The role entity represents the common behavior by a Party when acting in the role. This model explicitly separates the information held about individuals and organizations from the roles that they perform and the relationships the Service Provider forms with them. for example, a Service Provider may wish to keep a list of Phone Dealers (including competitors) to help in determining shop placements. The Organizations are stored, with a role of Phone Dealer, but there may never be any Interaction between the dealers and the Service Provider. An Employment Position or Post is represented by creating an Organization Role of type POST for the relevant organization unit. e.g. .the Org unit Western Region has a Post of Western Region Data Quality Coordinator. A Party Role linked to Western Region is created for this Post and employees can be assigned to the Post using interactions. Typically, there would only be one person assigned to a Post at any point in time (using TimePeriods). Note: In the value network, roles may not be exclusive, e.g. a customer may also be a supplier In a number of cases, we are interested in parties playing a combination of roles, e.g. staff, who use our services, get staff discount and suppliers who, use or products, are preferred suppliers.

COM-WP-CBE_concepts.1.2.doc

page 28 / 73

OSS through JavaTM Initiative

5.1.5

Interactions between Parties


Combining Figure 9 - Basic Party Model and Figure 11 - Party and the Main eTOM Roles gives us the model shown in Figure 12 - Parties Interact Via Their Roles. Sets of Party Specification entities together with Party Specification Policy entities provide rules, conditions, and allowable actions for Parties and Party Roles. These entities are not shown in the model.
PartyRoleGroup allows Party Roles to be grouped (e.g. into Customer

Demographics) An Interaction will involve one or more Parties playing roles participating in the value network to provide Customer value. An Interaction may have links to Product & Location.
Interaction Pa rty Role 0..n 0..n Int era ct ion validFor : T imePerio ... * 1.. * PartyRole status * 1 Pa rty partyId

Pa rtyRole Group

Value Netw ork Role

Th ese are b usiness e nt iti es, not software c la sses

Individual gender placeOfBirth nationality m aritalStatus driversLicenceNr passportNr skills disabilities aliveDuring : T im ePeriod

Organization companyNr isLegalEntity industrySector existsDuring : T imePeriod

Figure 12 - Parties Interact Via Their Roles (source: TM Forum)

5.1.6

Associations between Party Roles


We need to be able to show associations between Parties playing roles that are not directly involved in the value network. Examples of these associations include

Organizational associations in the service providers own business (organization unit employee, organization unit organization unit) Associations in other Organizations participating in the value network (organization unit employee, organization unit organization unit)

COM-WP-CBE_concepts.1.2.doc

page 29 / 73

OSS through JavaTM Initiative

Associations allowing us to determine the make-up of a household (household member household member) Associations showing family make-up (parent-child)
PartyRoleAssociation and any subclasses must not be linked to Location, Product or Interaction.
Party Role Association associationT ype validFor : T imePeriod status

Party Role Organization Assoc

Party Role Household Assoc

Party Role Family Assoc +from *

Int eraction validFor : T imePerio ... *

+to

PartyRole status * 1

Pa rty partyId

1..*

Figure 13 - Parties Can Be Associated Via Their Roles (source: TM Forum)

5.1.7

Party Names
An individual is referred to by their name. This name can change over time (e.g. After marriage, by deed poll) and to allow for this we will model an individuals name as a separate entity. Similarly, organizations can change their names (e.g. from Telecom to Telstra) and we will also model organization names as a separate entity. Note that this model does not allow for individual name or organization name aliases.

COM-WP-CBE_concepts.1.2.doc

page 30 / 73

OSS through JavaTM Initiative

Party partyId

PartyName valid Fo r : T imePerio ... 0.. * 0. .* n IndividualName formattedName aristocraticT itle salutation givenNam e preferredGivenName middleNam e fam ilyNamePrefix fam ilyName fam ilyGeneration qualifications +nameRuleCountry 1 Country 1..* Language alp ha be tNam e 1 dia lectN ame s

I nd ivi du al gender placeOfBirth nationality m aritalStatus driversLicenceNr passportNr skills disabilities aliveDuring : T imePeriod

1..n

this will get converted to Location in a later version

Orga ni zation c om pan yN r isLegalEnt ity industrySe ctor existsDu rin g : T im ePeriod 1 1..n Organization Name tradingName

T hese are business entities, not software classes

Figure 14 - Naming For Parties (source: TM Forum)

5.1.8

Interworking with other business entities


Figure 15 - Possible Links to Other Parts of the Core Model shows the main Party classes and the expected connections to other parts of the core model. This is for information only and is not guaranteed to be complete. Note also that the Location linkages will be refined after the Location model facet has been defined.

Note that having PartyContactMedium allows us to store a default set of contacts for a Party, which can be overridden by PartyRole if there are any role-based contacts. In most cases, only the one set of contacts would be required. Contact details for a Post would use a PartyRole ContactMedium.

COM-WP-CBE_concepts.1.2.doc

page 31 / 73

OSS through JavaTM Initiative

to be ref ined later

Address

Con tac t Me dium v alidFor : TimePer... 0..n Location Party Location 0..n 0..n

mayBeReachedUsing P ar ty Role Location

0..n

0..n

0..n PartyRole status 1 * 1..* Interaction Party Role

Party party Id

Agreement

* In te rac tion v alidFor : TimePer...

Figure 15 - Possible Links to Other Parts of the Core Model (source: TM Forum)

Notes: Note that these entities represent business concepts in a Service Provider that conforms to the eTOM process model [eTOM]. Entities that are outside the scope of this model facet are shown with a white fill color. This is intended as a minimalist model. Subtypes and attributes should be added as required. The attributes shown should be considered as suggested, not required.

5.1.9

Example Extension of Party Customer


The figure below shows how a Customer business entity represents an extension (from an information model perspective) of Party. A number of attributes (such as name and contact medium) and associations now reside in the Party core business entity.

COM-WP-CBE_concepts.1.2.doc

page 32 / 73

OSS through JavaTM Initiative

<<bus ines sentity>> IdentityContactMedium


(f rom Party )

<<busines sentity>> PartyRole


(from Party)

0 ..n accessedVia usedAs 0..n <<bus ines sentity>> Custom erAccountContact contactType validFor : Tim ePeriod

0..n

<<busines sentity>> Cus tom er custom erID custom erStatus custom erRank 1..n posseses 0..n 0..n <<busi nesse nti ty>> Cus tom erAccount accountID accountNam e accountType accountStatus 0..n references 0..n 1..n 1 1

requests 0..n

<<busi ness e nti ty>> Custom erQuote/Offer


(f rom C ustomer Interaction)

r eceivesABil lDur ing

0..n

<<busi ness e nti ty>> Cus tom erAccountBillCycle billCycle validFor : Tim ePeriod

exem ptedFrom TaxesVia

0..n stab il ityMea sure dBy

<<bus ines s entity>> Cus tom erAccountTaxExem ption iss uingJuris diction certificateNum ber validFor : Tim ePeriod

<<busines sentity>> Cus tom erAccountRelationship relations hipType validFor : Tim ePeriod 0 ..n <<bus iness entity>> Custom erAccountCreditProfile creditProfileID creditProfileDate 1 validFor : Tim ePeriod

<<bus ines sentity>> Cus tAcctCreditProfileReference includes 0..n financialInstitutionNam e financialInstitutionAccoutNum ber financialInstitutionAccountType financialInstitutionContactNam e financialinstitutionContactMedium

Figure 16 - Customer Shown As An Extension of Party Role (source: TM Forum)

5.2
5.2.1

The What Product, Service, and Resource


Overview
Note: The contents of this chapter are a modified extract from the TeleManagement Forums Shared Information/Data (SID) Model document GB922 Addendum 1P and the OSS/J Inventory API (JSR 142). This chapter answers the question what? and deals with products offered by an enterprise, the services through with a product is realized or supported, and the resources utilized by products and services.

COM-WP-CBE_concepts.1.2.doc

page 33 / 73

OSS through JavaTM Initiative

<<concept>> Who (Party)

<<concept>> Where (Location)

<<concept>> When (TimePeriod)

<<concept>> Why (Reason)

<<concept>> What (Thing)

Figure 17 - Showing How Products, Services, and Resources Fit In

Product, Services, and Resources are specializations of the Entity Specification and Entity modeling concepts presented in the Core Business Entity Modeling Concepts chapter of this paper. Core what business entities are

Product Specification and Product Service Specification and Service Resource Specification and Resource

Each of these three pairs of business entities is described below, followed by a model that depicts how these business entities fit into part of the core model. The three pairs of business entities are commonly referred to as Inventory core business entities. Operation business processes require information on planning, availability, usage and state of various products, services and resources. OSS components such as Order Management, Service Impact Analysis, Planning cannot be built without this knowledge. Therefore, inventory information cannot be local to a specific component, but must be considered as enterprise data, that although stewarded by specific OSS components, needs to be shared across the enterprise. In emerging scenarios for e-business, some information may also be shared across enterprises in a controlled way. The variety of inventory information can be classified in three groups defining three Inventory functions focused on products, services or resources. Each function has its specific set of inventory entities and relationships, its specific business logic and interacts with different subset of OSS functions. However, all Inventory functions share common abstractions (e.g. entities, associations, specifications) and common base interaction model (e.g. queries based on traversal of relationships, atomic update procedures etc.). The Inventory functions are central part of an integrated OSS solution. They provide storage of physical resources and configurations, network topology,

COM-WP-CBE_concepts.1.2.doc

page 34 / 73

OSS through JavaTM Initiative

logical resources, services, customer account information, products, etc. They also provide the business operations required by other OSS components in order to query, monitor, assign and update the inventory information. The Inventory functions are described in the following sections.

5.2.2

Product Inventory
The main responsibility of the Product Inventory is to manage the Product Catalog and keep track of the of product subscriptions. The Product Catalog defines the product offering from marketing perspective and consists of collection of product specifications. Each product specification describes a product. Several product specifications may be defined for the same product type. For example, the Product Catalog may define Gold, Silver and Bronze VPN products. Product specifications are associated with service specifications, stored in the Service Catalog, thus capturing the relationship between a product and the set of services bundled by this product. Each subscription is captured in the Product Inventory through a product instance associated with the corresponding specification in the catalog. The product instance is also associated with the subscriber of the product and the related subscriber account information. The information stored in the Product Inventory is used by SLA management, Trouble Ticketing, Billing and Customer Order Management OSS/J APIs. Product Inventory is part of the eTOM Customer Relationship Management and Operations and Product Lifecycle Management processes.

5.2.3

Service Inventory
The main responsibility of the Service Inventory is to manage the Service Catalog and keep track of planned, subscribed and provisioned services. The Service Catalog captures the engineering view of the Service Providers offering and consists of collection of service specifications. Service specifications define the services from an engineering perspective. Several service specifications may be defined for the same service type. For example the Service Catalog may define Gold, Silver and Bronze VPN services. Service specifications are associated with resource specifications, stored in the Resource Catalog, thus capturing the relationship between a service and the set of resources supporting this service. Each subscription is captured in the Service Inventory through a set of service instances associated with the corresponding specifications in the Service Catalog, the subscribed product, bundling these services and the users (recipients) for these services.
COM-WP-CBE_concepts.1.2.doc page 35 / 73

OSS through JavaTM Initiative

The information stored in the Service Inventory is used by SLA management, Trouble Ticketing, Billing Mediation, Service Activation, Service planning, Process Quality Management, Service Impact Analysis, Service Problem Resolution, Customer Order Management, Provisioning Control and Service Quality Management OSS/J APIs. Service Inventory is part of the eTOM Service Management and Operations and Product Lifecycle Management processes.

5.2.4

Resource Inventory
The Resource Inventory stores network and computing equipment, logical resources and topology. This function keeps track of the physical and geographical configuration of the network, equipment inventory (cards, ports, etc.), physical connectivity, and logical connectivity of the different network layers. Resource Discovery components populate and synchronize the Resource Inventory. Data in the Resource Inventory is used by Provisioning Control OSS/J API to design services and understand where capacity is available. It is also used for root-cause alarm analysis and network activation. Resource Inventory is part of the eTOM Resource Management and Operations and Product Lifecycle Management processes. The figure below depicts the Inventory core business entities along with their relationship to Party, another core business entity.

COM-WP-CBE_concepts.1.2.doc

page 36 / 73

OSS through JavaTM Initiative

p roductSpecificationAggregatesProductSpecifiacation

productAggregatesProduct

+aggregatedProduct
subscriberSubscribesProduct

+aggregateProduct

* * +subscribedProduct <<Interface>> ProductValue 0..* (from product)

describes

<<Interface>> ProductSpecificationValue
0..1

0..*

(from produ...

0..* +product
p roductAggregatesService
serviceAggregatesService

0..*
p roductSpecificationAggregatesServiceSpecification
serviceSpecificationAggregatesServiceSpecification

0..*

+subscriber
0..* +recipient

+service 0..*

+aggregatedService * * +aggregateService
0..*
*

<<Interface>> 1 ... >> PartyValue

0..*

<<Interface>> PartyRoleValue

<<Interface>> +deliveredServiceServiceValue
0..*

<<Interface>> ServiceSpecificationValue (from servi...


*

(from service)
0..*
describes

0..* +owner

0..* +service

0..1

0..*

resourceSupportsService +resource 0..*

resourceSpecificationsSupportServiceSpecification

<<Interface>>
+ownedResourceResourceValue 0..* (from resource) 0..*
describes 0..1

0..*

<<Interface>> ResourceSpecificationValue (from resour...


*

ownerOwnsResource

+aggregatedResource

+aggregateResource

resourceAggregatesResources
resourceSpecificationAggregatesResourceSpecification

Figure 18 - Inventory Business Entities

5.2.5

Use Cases
Exemplary use cases for Inventory Business Entities can be found in the OSS/J Inventory API Specification (JSR 142).

5.3

The Where - Location


Note: The contents of this chapter are a modified extract from the TeleManagement Forums Shared Information/Data (SID) Model document GB922 Addendum 1L. This chapter answers the question where? and deals with locations, such as buildings addresses, geographic locations and so forth, where customers are found, resources are situated, services are provided, and so forth.

COM-WP-CBE_concepts.1.2.doc

page 37 / 73

OSS through JavaTM Initiative

<<concept>> Who (Party)

<<concept>> Where (Location)

<<concept>> When (TimePeriod)

<<concept>> Why (Reason)

<<concept>> What (Thing)

Figure 19 - Showing How Locations Fit In

5.3.1

Disclaimer
This Location model is complex and has a number of subtleties. It provides a high level framework, explains broad concepts and gives illustrative examples. Actual solutions for particular requirements will be dependant factors such as

Country address standards State/ country / province map standards Service Provider network inventory addressing standards Equipment vendor equipment naming & addressing conventions Whether textual only or map based representations will be provided

It is expected that when this model is used in TeleManagement Forum NGOSS Catalyst projects, the feedback will clarify its application & usage.

5.3.2

Overview
A Service Provider will be interested in the location of many things:

Where is the customer (more on this later)? Where is our equipment? Where is the fault and where is the nearest person who could repair the equipment? Where did the cyclone pass (and what equipment may have been affected)? Where is growth for this product? Where can we expand our business operations? Where are our service vans and the work sites (optimize work dispatch)? Where (which shops) do we require products to be shipped? Where do I send the bill for Customer Xs use of product Y? Where do I need additional employees?

COM-WP-CBE_concepts.1.2.doc

page 38 / 73

OSS through JavaTM Initiative

Who owns this property (advise of digging) {note property may be rented, i.e. customer living at property may not be owner}

Note that the business requirements will not just be Resource related but will also be required by marketing, corporate strategic, etc processes. In some cases, these locations will be well-defined points. In others, they may be fuzzily defined regions of interest. The Location model needs to allow us to answer questions like What is the nearest network access point to the Customers location that can provide this product? Network, Customer and Product Capability should not just be seen as separate location views.

5.3.3

Location
We will define location as a generic concept that can answer the question Where ? A Location is an area, position, or portion of space that somebody or something can be in; a location can also be a locality, a dwelling (or some other structure via associations to the Resource Model). In this model an abstract modeling concept, used to generalize Location Coordinate, Address and Geographic Area and Structure. This model provides four options for locating something geographically:

With a defined (named) location {Structure} With an address {Address} With a (named) area {Geographic Area} With a survey location (geocode) e.g. a GPS position for an off-shore oil rig {Location Coordinate}

The way that the Location hierarchy is defined is the key to this model. A model that represents the high level concepts is shown below.

COM-WP-CBE_concepts.1.2.doc

page 39 / 73

OSS through JavaTM Initiative

<<businessentity>> 1 LocationSpecification

defines 0..n playedBy 0..n 0..n 1 0..n

<<businessentity>> LocationRole

ManagedEntity
(from Managed Entity Business Entities)

0..n

madeUpOf

identifiesPlacementOf

<<businessentity>> Location 0..n

ManagedEntityPlacement
(from Managed Entity Business Entities)

<<businessentity>> Address 0..n graphicallyPositions 0..n <<businessentity>> LocationCoordinate 0..n 0..n graphicallyPositions

liesWithin 0..n 0..n

<<businessentity>> GeographicArea

0..n

Roles include where the ManagedEntity is located, (one or more) Places at which the ManagedEntity terminates (for entities such as connections), where a ManagedEntity (such as a ProductOffering) is available, and so forth

graphicallyPositions 0..n

<<businessentity>> Structure
(from Resource)

Figure 20 - Initial Location Model

A location is a location that can be represented graphically. By definition then, a locations attributes includes some type of coordinates that facilitate the locations graphical positioning. An address is a structured textual way of describing how to find a location, geographic area, or structure. It is usually composed of an ordered list of names based on context specific rules. A geographic area is a location that has (existing, planned, or former) things of interest to an enterprise. Things of interest include products, services, and resources. Characteristics include associated parties (property owner, property lessee, and so forth). A structure is a physical resource that may be considered a location. A structure is a set of inter-related parts (resources) that function as a whole. Entity Specifications in the form of Location Specifications are used in this part of the CBE model also. Location Specifications specify such things as address formats, such as Australian and European formats, as well as the way in with geographic areas can be aggregated, such as a city in a state in a country. APIs that can employ this CBE include but is not limited to the Customer Order Management API (the locations where product offerings are to be installed), Activation API (where is the product, service, or resource that is to be activated), Trouble Ticketing API (where is the trouble), and the Fault Monitoring API (where did the fault occur).

COM-WP-CBE_concepts.1.2.doc

page 40 / 73

OSS through JavaTM Initiative

5.4
5.4.1

The When and the Why Business Interaction


Overview
Note: The contents of this chapter are an extract from the TeleManagement Forums Shared Information/Data (SID) Model document GB922 Addendum 1BI. This chapter answers the question when and why? and deals with communications, activities, and agreements that involve products, services, and resources found at locations, such as buildings addresses and so forth.
<<concept>> Who (Party) <<concept>> Where (Location)

<<concept>> When (TimePeriod)

<<concept>> Why (Reason)

<<concept>> What (Thing)

Figure 21 - Showing How Interactions Fit In

In the course of doing business a service provider interacts with individuals and organizations (or parts of organizations). Interactions also include activities and communications between systems and between systems and parties. These interactions take the form of requests, responses, notifications, agreements, and commands. The figure below depicts the various types of business interactions.

COM-WP-CBE_concepts.1.2.doc

page 41 / 73

OSS through JavaTM Initiative

references

0..n

0..n

BusinessInteraction interactionDate interactionDescription interactionDateComplete interactionStatus interactionID name

Request

Response

Notification

Ag reem ent
(f rom Agreement)

Figure 22 - Types of Business Interactions (source: TM Forum)

Individuals, organizations, and systems, and so forth involved in interactions are collectively referred to as business participants. In fact, a business participant may be a party playing a certain role or a resource playing a role, such as a system or piece of equipment. During an interaction, a party can play different roles as a business participant. For example, Bob Smith, a party playing the role of a customer, requests information about cable modem service from Joe Jones, a party playing the role of a customer service representative. The figure below depicts the relationship that business participants have with all types of interactions. In this example, the type of interaction is an inquiry request. In fact, all types of interactions participate in the relationships described in this section. This is illustrated by the examples used through this section. A number of APIs can take advantage the Business Interaction Core Business Entity. For example, an alarm is a type of notification created as the result of an alarm being sensed by a fault monitoring process. The Fault Monitoring API is used to communicate this to an SLA process. The SLA process may recommend a rebate be issued customer base on an SLA in place with the customer. The recommendation is communicated to a billing mediation process via a rebate notification type of interaction via the SLA API.

COM-WP-CBE_concepts.1.2.doc

page 42 / 73

OSS through JavaTM Initiative

PartyRoleType
(f ro m Pa rty )

BusinessParti cipantType

1.. 1
classifies BusinessInteraction interactionDate interactionDescription interactionDateComplete 0..n interactionStatus interactionID name involves Resou rceRoleType
(f ro m Re sou rc e Spe ci fica tio n)

0.. n
0..n BusinessParticipant

PartyRole
(from Party)

ResourceRole
(f rom Resource)

Figure 23 - The Relationship Between Business Interactions and Business Participants (source: TM Forum)

As described in the example above, the inquiry request type of interaction from Bob Smith involves a product offering that is made available by a service provider. The figure below depicts the involvement that products, services, and resources have with all types of interactions.

COM-WP-CBE_concepts.1.2.doc

page 43 / 73

OSS through JavaTM Initiative

<<busines s entity>> ProductSpecification


(f rom Product Specif ication)

<<bus ines s entity>> Produ ctOffe ring


(f rom Product Specif ication)

<<bus ines s entity>> Product


(f rom Prod uct )

0..1

0..1

0..1

involvedIn

involvedIn

<<b usine s sentity>> Bus ines sInteraction interactionDate interactionDes cription interactionDateCom plete 1 interactionStatus interactionID com prises

0..n 0..n

0..n

<<bus ines s entity>> Busine ssIn ter action Item qua ntity 1..n ac tion 0..n 0..n 0..n

0..n

0..1 <<busi nes se ntity>> ServiceSpecification


(f rom Serv ice Specif ication)

0..1 <<busines s entity>> Service


(f rom Serv ice)

0..1 <<bus ines s entity>> Res ource Spec ific ati on


(f rom Resource Specif ication)

0..1 <<bus ines s entity>> Res ource


(f rom Resource)

Figure 24 - The Relationship Between Business Interaction and Products, Services, and Resources (source: TM Forum)

Similarly, if Bob Smith already has cable modem, the request may reference an entity, such as a product, provided to Bob. Product offerings obtained by a customer are called products. During the interaction, Bob Smith may also provide information about the location, for example address, of his cable modem. Therefore, as shown in the figure below, an interaction also can involve one or more addresses.

COM-WP-CBE_concepts.1.2.doc

page 44 / 73

OSS through JavaTM Initiative

Location
(f ro m Lo ca ti on )

BusinessInteractionLocation
(from Business Interaction)

0..n 0..n +speci fi esTheLo cationFor

+specifiesTheLocationFor 0..n BusinessInteraction interacti onD ate interacti onD escripti on interacti onD ate Co mpl ete interacti onStatus 1 interacti onID na me

0..n compriseOf 1..n BusinessInteractionItem quantity action

Figure 25 - The Relationship Between Business Interactions and Locations (source: TM Forum)

In summary, a business interaction involves a number of other business entities, including product offerings, products, locations, and business participants. By using the concept of a business interaction, each of its various types, such as agreement and notification, can inherit the interactions relationships, attributes and behaviors without having to explicitly show these for each type. For example, it would be quite redundant and unstable to show an agreement and a notification, and a request, and a response, and a command each participating in relationships to parties, locations, entity specifications and entities. What would happen if this was done and another type of interaction was discovered? The full Interaction model is shown if the figure below.

COM-WP-CBE_concepts.1.2.doc

page 45 / 73

OSS through JavaTM Initiative

CustomerAccount
(f rom Customer)

Bu sine ssIn teractio nType 0..n pro vid edFor 1

Location Produ ct
(f rom Product )

+categ orizedBy

ProductSpecification
(f rom Product Specif ication)

ProductOffering
(f rom Pro duct Of f ering )

(f rom Location)

0..n +s peci fiesThe Location For 0 ..n 0..n

0..1

0..1

0..1

ServiceSpecification
(f rom Serv ice Specif ication)

involvedIn involvedIn 0..1

involvedIn BusinessInteractionLocation 0..n +speci fiesTh eLocatio nFor

BusinessInteraction 0..n interactionDate 0..n interactionDescription interactionDateC om plete interactionStatus 1 interactionID name 0..n 0..n compri seOf involves 0..n 0..n

references

Service
(f rom Serv ice)

0..n 0..1 0..n 0..n +references 0..n 0..n 0..n 0..n 0..n 0..n 1..n ofInterestTo 0..n 0..n 0..n

BusinessInteractionItem quantity action

BusinessInteractionRole interactionRole

carriedOutAccordingTo

carriedOutVia

0..n 0..n ProcessDefintion


(f rom Process Def inition)

Resource Specification 0..1


(f rom Resource Specif ication)

involves 0..1 Resource


(f ro m Res our ce )

BusinessParticipant 1 defines 0..n 0..n

Process
(f rom Pro cess)

Figure 26 Business Interaction Business Entity Model (source: TM Forum)

5.4.2

Sample Business Interaction Use Cases


These examples show, how the concept of a business interaction is first used to model an abstract use case, which is then extended in the seconde use case to a specific business interaction.

5.4.2.1

Initiate Business Interaction (abstract use case)


Note: In this use case the business participant is a party playing a role. A party (individual or organization) business participant begins a communication, arrangement, or activity with another party. The interaction may consist of a number of items (interaction items). Each item involves a single entity specification (such as a product offering, service specification, or resource specification) or an entity (product, service, or resource) in which the parties already has some interest. Parties can play one or more roles (such as customer, employee, service provider and so forth) as they interact. Interactions also typically involve locations at which an entity or business participant resides. Interactions can be related to other interactions; for example, a response is made as a reply to request.

5.4.2.1.1 Brief Description (Use Case ID UC111)

5.4.2.1.2 Preconditions
Business participants identified, type of interaction identified; optionally a related interaction may be identified.

COM-WP-CBE_concepts.1.2.doc

page 46 / 73

OSS through JavaTM Initiative

5.4.2.1.3 Postconditions
New interaction is created and optionally linked to related interaction(s). Supporting interaction items are created, each item linked to one entity (product, service, or resource) specification or entity.

5.4.2.1.4 Extension Points


None.

5.4.2.1.5 Basic Flow When there are no related interactions


1. The system creates an interaction. 2. The system associates the interaction with the business participants involved. 3. The system asks the initiating party for locations associated to the interaction. 4. The business participant provides the locations associated to the interaction. 5. The system associates the locations to the interaction. 6. The system creates an interaction item (repeated until the party is complete with providing items). 7. The system asks if the interaction deals with an existing entity or something new. a. The business participant provides an answer. b. The system determines whether the interaction involves a product (specification), service (specification) or resource (specification). c. The system provides access to the appropriate query from which the business participant selects an item. d. The business participant selects an item. e. The system creates an interaction item and associates it with the applicable entity or entity specification. f. The system then asks for a location for a new item. g. The business participant provides specifies the location (optional). h. The system associates the interaction item with the location (optional).

5.4.2.1.6 Alternate Flow (AF1) When the interaction is related to another interaction
The system creates an association between the related interactions. The system creates an association between each of the related interaction items.

COM-WP-CBE_concepts.1.2.doc

page 47 / 73

OSS through JavaTM Initiative

5.4.2.2

Receive Inquiry Request (parent is Initiate interaction)


A note on symbols used for inheriting use cases

I - inherited unchanged S inherited and specialized N new

Additionally the step and use case ID of the parent use case is annotated, for example

(I step 2a, UC111) (N)

Alternate flows inherited are referenced as AFxx, where xx is the alternate flow number, for example

(I AF1, step 1, UC111)

5.4.2.2.1 Brief Description


A business participant, playing the party role of a customer (could be a prospective customer), requests information.

5.4.2.2.2 Preconditions
Business participant identified, type of interaction is inquiry request.

5.4.2.2.3 Postconditions
An inquiry request has been created

5.4.2.2.4 Extension Points


None

5.4.2.2.5 Basic Flow


The system creates an inquiry request. (S step 1, UC111)

The system associates the interaction with the business participants involved (I step 2, UC111) The system asks the initiating business participant for the locations associated to the interaction. (I step 3, UC111) The business participant provides the location associated to the interaction. (I - step 4, UC111) The system associates the location with the interaction. (I step 5, UC111)
COM-WP-CBE_concepts.1.2.doc page 48 / 73

OSS through JavaTM Initiative

The system creates an interaction item (repeated until the business participant is finished providing items). (I step 6, UC111)

COM-WP-CBE_concepts.1.2.doc

page 49 / 73

OSS through JavaTM Initiative

6 Core Model and SID Adoption Strategies


This chapter describes how the Core Business Entity model will be integrated with the OSS/J Common API. This chapter also decribes the strategy for adopting the SID model as the foundation for the CBE model. The key point in both adoption strategies is that the CBE will be incrementally developed based on the information needs of current and new OSS/J APIs.

6.1

Core Model Strategy


Being a core model, it is natural that there should be a strong relationship between the CBE model and the OSS/J Common API. For example, as a new JSR/API is developed the CBE model will be extended to include the business entities within the scope of the new API and then the business entities, and their interfaces will be passed on for inclusion in the Common API. Examples of these business entities and interfaces are described in the chapter 7 CBE Java Interface Definition Examples. Similarly, XML schema representations of the CBE will be included in the Common API.

6.2

SID Adoption Strategy


The SID model adoption strategy describes how the SID model will become the foundation for the OSS/J CBE model. The CBE model may or may not contain the same level of detail that is contained in the SID model. For example, consider the SID Product Offering Aggregate Business Entity (ABE) shown in the figure below. An ABE is a cohesive group of related entities.

COM-WP-CBE_concepts.1.2.doc

page 50 / 73

OSS through JavaTM Initiative

Figure 27 - SID Product Offering ABE

The CBE model could adopt only the Product Offering business entity, its association to Product Specification, and the association between Product Offering and itself (via Bundled Product Offering). The CBE model would be consistent with the SID model; it would just not contain the same level of detail. This level of adoption would represent the current level of detail contained in the OSS/J Inventory API. Or, the CBE model adoption could also include the two subclasses of Product Offering. This adoption would necessitate a change to the Inventory API. The CBE model adoption strategy may also exclude SID model ABEs. For example, there is no current need for product pricing rules in any OSS/J APIs. Therefore, the SID Product Pricing Rule ABE would not be adopted. Additionally, the CBE may represent an extension of the SID if the SID does not contain the necessary business entities. These extensions will be related back to the SID team for inclusion in the SID model. Existing business entities within the SID model may also be further detailed to support an OSS/J API. These details will also be forwarded to the SID team. The figure below shows a sample of OSS/J API Trouble Ticket business entity attributes that could be included as SID Trouble Ticket business entity attributes. The SID Trouble Ticket business entity does not currently have any attributes that characterize it.

COM-WP-CBE_concepts.1.2.doc

page 51 / 73

OSS through JavaTM Initiative

Figure 28 - Sample OSS/J API Trouble Ticket Attributes

Methods added during the development of an API will also be passed on to the SID team for inclusion in the system view of the SID model. The figure below shows a sample of OSS/J API Trouble Ticket methods that could be contributed to the SID model.

Figure 29 - Sample OSS/J Trouble Ticket Methods

The adoption of the SID will not instantaneously be present within the entire set of OSS/J APIs. The adoption will occur over time. During the

COM-WP-CBE_concepts.1.2.doc

page 52 / 73

OSS through JavaTM Initiative

interim, it will be necessary to map some current API information models to the CBE/SID model. As the CBE model evolves, some business entities used by a single API may found to be used by other APIs. In this case the entities will be moved to the CBE model. Also, as new APIs are developed, additional portions of the SID will be included in the CBE model.

COM-WP-CBE_concepts.1.2.doc

page 53 / 73

OSS through JavaTM Initiative

6.3

CBE Scope Defined Using the SID Framework


As the CBE continues to adopt SID Aggregate Business Entities (ABEs), the scope of CBEs will expand. The figure and text below describes the current scope of the CBEs using the SID Framework. The figure shows the SID Framework (made up of domains and ABEs) along with the CBE work that has been planned, is in process, and has been completed for each ABE.

Market / Sales
Market Strategy & Plan Market Segment Marketing Campaign Competitor Contact/Lead/Prospect Sales Statistic Sales Channel

Product
Product Product Specification

Strategic Product Portfolio Plan Product Offering

Product Performance Product Usage Statistic

Customer
Customer Customer Interaction Customer Order Customer Statistic Customer Problem Customer SLA

Applied Customer Billing Rate Customer Bill

Customer Bill Collection Customer Bill Inquiry

Service
Service Service Specification Service Applications Service Configuration Service Performance Service Usage Service Strategy & Plan Service Trouble Service Test

Resource
Resource Resource Specification Resource Topology Resource Configuration Resource Performance Resource Usage

Resource Strategy & Plan Resource Trouble Resource Test

Supplier / Partner
Supplier/Partner S/P Plan S/P Interaction S/P Product S/P Order S/P SLA

S/P Performance S/P Problem S/P Statistic

S/P Bill S/P Bill Inquiry S/P Payment

Enterprise
(Under Construction)

Common Business
Party Location Business Interaction Policy Agreement

- Planned - In process - Complete

Figure 30 Current CBE Scope

A number of the SID level one ABEs shown in Figure 30 decompose into lower levels of ABEs. A figure or figures that depict all of the lower levels ABEs does not yet exist. Also, some CBEs do not contain all the detail entities described in the SID. The following paragraphs describe the coverage in more detail, domain by domain.

COM-WP-CBE_concepts.1.2.doc

page 54 / 73

OSS through JavaTM Initiative

6.3.1

Product Domain
The CBEs in the Product domain adopted the core entities from the Product Specification and Product ABEs. These entities are Product Specification and Product. No other SID Product entities dependent upon Product Specification and Product, such as Product Characteristic and Product Specification Version, were adopted. Future versions of CBEs may include these dependent entities to further characterize Product Specification and Product.

6.3.2

Customer Domain
It is anticipated that the next version of CBEs will include Customer and Customer Problem (Trouble Ticket) entities. A future Customer Management API will also use the Customer CBE. Since these CBEs are planned, it is yet to be determined the number of SID ABE entities that will be adopted.

6.3.3

Service Domain
Service domain CBEs include a number of ABEs, including Service Specification, Service, Service Performance, Service Trouble, and Service Usage. Similar to Product in the Product domain, the Service CBE only includes the core entity, Service, from the SID Service ABE. Service Specification includes the SID Service Specification core entity, Service Specification, along with Service Level Specification and Service Level Objective. Again, the adoption strategy for these two CBEs did not include all the detailed (dependent) entities from the corresponding SID ABEs. Service Performance includes the Key Quality Indicator CBE, but will be expanded as other OSS/J APIs, such as QoS, are revised to adopt the CBE model. The Service Trouble CBE is also under development and will be used by the SQM API. Service Usage is planned as a CBE for use by a future version of the Billing API.

6.3.4

Resource Domain
Included as Resource domain CBEs are Resource Specification, Resource, Resource Performance, Resource Usage, and Resource Trouble. Following the pattern established in the Product and Service domains, Resource Specification and Resource adopt the core entities from their respective SID ABEs. Resource Performance and Resource Trouble CBEs are under development as part of the SQM API contribution to CBEs. Additional work will be done when the QoS API adopts the CBEs. Resource Usage is planned as a CBE for use by a future version of the Billing API.

COM-WP-CBE_concepts.1.2.doc

page 55 / 73

OSS through JavaTM Initiative

6.3.5

Common Business Entities Domain


The Common Business Entities domains CBEs include Party, Location, Business Interaction, and Agreement. Party and Location CBEs include only the core entities from their respective SID ABEs. There are planned updates to the SID Location ABE, which may impact Location CBEs. Business Interaction is planned for a future version of the SA API. Work has already begun on incorporating Business Interaction as a CBE. It will also be used by a future version of the Trouble API.

COM-WP-CBE_concepts.1.2.doc

page 56 / 73

OSS through JavaTM Initiative

7 CBE Java Interface Definition Examples


The CBE packages define a set of interfaces that represent the upper layers of a generic information model within the OSS domain. The CBE packages are composed of the following sub packages. The CBE Core package defines three basic core types of managed entities:
Entity Specification Association

The CBE Service, Resource and Product packages defines a basic Service, Resource and Product Model composed of:

Service, Resource, and Product Entities Service-, Product- and ResourceSpecifications Service-, Product- and ResourceAssociations

The CBE Location package, which defines the Location Model Entities like:
Location

The CBE Party package, which defines the Party Model Entities like:
PartyValue PartyRoleValue

The CBE DataType package defines Common Data Types like:


OrganizationName TimePeriod

Etc

The following section contains the detailed description of the CBE Java Interface definitions and some usage examples. The equivalent XML definitions can be found in the related XML CBE Schemas XSDs.

COM-WP-CBE_concepts.1.2.doc

page 57 / 73

OSS through JavaTM Initiative

7.1

Inventory and Service Activation Interaction Example


By design, the Inventory API and Service Activation API are meant to be used in conjunction. This chapter will provide an overview over the most prominent use-case, which spans the Inventory and Service Activation API, and demonstrates how the usage of CBE facilitates that use-case.

7.1.1

Inventory and Service Activation Collaboration Principals

Customer Care

Product Catalog

Activat e Product

<<Inventory>> Product Inventory


Service Catalog

<<Service Activation>> Order Manager

Act ivate Servic e

<<Inventory>> Service Inventory

<<Service Activation>> Service Activator

Resource Catalog Activate Resource <<Inventory>> Resource Inventory

<<Service Activation>> Resource Activator

Figure 31 - Interaction Principals between Inventory and Activation Components

Figure 31 shows how Inventory and Activation components work together in principal. From top to bottom, the three layers for product, service and resource handling are shown. A client to a layer, i.e. the customer support is a client (user) of the product layer, will request the available items from the inventory and use the activation component to request the creation of that particular item. How this works in detail is explained in the following Figure 32 and Figure 33. Because of the close relationship between the Inventory and Activation component on each layer, commercially available products are expected to

COM-WP-CBE_concepts.1.2.doc

page 58 / 73

OSS through JavaTM Initiative

implement both APIs to synchronize the inventory of available items with the business logic, how they are provisioned.

7.1.2

Use-Case Customer Orders A Product

Customer

CRM Web Frontend

Product Inventory

Product Activat ion

1. browse Products

1.1. query Product Catalog

1.1. 1. Product Specificat ions 1.2. display Products

2. order Product 2.1. create Product Instance 2.1.1. create aProduct

2.1.2. new Product Instance

2.2. create CreateOrder Instance 2.2.1. create 2.2. 2. new Creat eOrder aCreateOrder

2.3. assign Product Instance

2.4. start Order

3. decompose and process Order

2.5. status feedback 4. order completed success fully 4.1. status feedback

5. use Product

Figure 32 - Customer Interaction: Order a New Product

In this sequence diagram, the use-case of a client, who visits a website to order a new product, is shown.
COM-WP-CBE_concepts.1.2.doc page 59 / 73

OSS through JavaTM Initiative

The client visits a website, which allows him to order new products The CRM Web application contacts the Product inventory and queries the product catalog The product inventory returns all available product specifications for the customer The customer is presented a choice of available products on the website. The customer selects a product and starts the provisioning process of that products The Product Inventory is used to create a new instance of the requested product, based on the available product specification The Product Activation component is used to create a new CreateOrder instance. The product (from the product inventory) is put inside the order (from the product activation). The Product Activation component is requested to start the order Through the web GUI, the client can follow the current state of the order The order is processed internally, how the decomposition and order processing is done in detail, is explained in Figure 33. The Product Activation component processed the order and completed successfully The client can now use the product

COM-WP-CBE_concepts.1.2.doc

page 60 / 73

OSS through JavaTM Initiative

7.1.3

Use-Case: Product Order Decomposition

Product Activation

Service Inventory 1

Service Activation 1

Service Inventory 2

Service Activation 2

1. query Service Catalog

2. query Service Catalog

3. create Service A Instance

4. create CreateOrder Instance with Servic e A 5. start CreateOrder

6. create Service B Instance 7. create CreateOrder Instance with Service B 8. start CreateOrder 9. order completed

10. order completed

Figure 33 - Decomposition of a Product Order into Two Service Orders

After a Product Activation component received the request to process a CreateOrder for a product, it has the task to split the product into services, which are included in that product, and make sure that these services are provisioned. From the product specification of the product, which the Product Activation component is about to provision, it extracts the dependant services. In this example, it is assumed that the product depends on two services: Service A and Service B. Service Inventory 1 is queried for the available services Service Inventory 2 is queried for the available services

COM-WP-CBE_concepts.1.2.doc

page 61 / 73

OSS through JavaTM Initiative

Based on the information in the service catalogs and the needed services for the product, the decision is made to activate service A with Service Activation component 1, and Service B with Service Activation component 2. Service Inventory 1 is used to create an instance of Service A With Service Activation 1, a new CreateOrder is instantiated and the service instance from step 3 is put inside the order. The order is started. Service Inventory 2 is used to create an instance of Service B With Service Activation 2, a new CreateOrder is instantiated and the service instance from step 6 is put inside the order. The order is started. Service Activation 1 processed the order, provisioned Service A and completed successfully. Service Activation 2 processed the order, provisioned Service B and completed successfully.

7.1.4

Usage of CBE in Service Activation


The way the common business objects are used in service activation can be split into two main aspects. The first aspect is, that service activation components need the ability to handle the objects, that were created by an inventory components. Therefore the API has to reuse the definitions of ProductValue, ServiceValue and ResourceValue, as they are defined in CBE. The second aspect is that the order, which is a container for products, services and resources and tracks the provisioning process for the contained items, can be modeled as a BusinessInteraction. How that is reflected in the Service Activation API is shown in Figure 34 below. Note that the currently available Service Activation API does not support CBE, but will be through new releases.

COM-WP-CBE_concepts.1.2.doc

page 62 / 73

OSS through JavaTM Initiative

<<Interface>> BusinessInteraction
(from ja vax .oss.cbe. ...)

<<Interface>> BusinessInteractionItem
(from javax.oss.cbe. ...)

1..* 0..* 0..1 <<Interface>> Product Value


(from javax.oss.cbe. ...)

0..*

0..* 0..1 <<Interface>> ResourceValue


(from javax.oss.cbe. ...)

0.. 1 <<Interface>> ServiceValue


(f ro m j ava x.os be. .. .) s.c

<<Interface>> OrderValue
(f ro m j ava x.oss.ord er)

<<Interface>> ServiceValue
(f ro m j ava x.os s.servi ce)

<<Interface>> CreateOrdervalue
(from javax.oss.order)

<<Interface>> ModifyOrderValue
(from javax.oss.order)

<<Interface>> CancelOrderValue
(from ja vax .oss.order)

Figure 34 - Modeling Concepts between Service Activation and CBE

In this figure, it is depicted, how the OrderValue derives from the BusinessInteraction, which aggregates a number of BusinessInteractionItems. Those items refer to a product, service or resource. The ServiceValue from CBE has a derived ServiceValue in the javax.oss.service package, which is there for backwards compatibility, since this is where the ServiceValue was defined prior to CBE.

7.1.5

Code examples of Inventory and Service Activation Usage


Finally, some code examples are provided, how the Inventory and Service Activation API can be used in conjunction. With these examples, the most important steps of the use-cases (Figure 32 & Figure 33) are broken down to code level.
Snippet 1 - Query the Product Catalog

JVTInventorySession myInvSession = // obtain reference to Session Bean // create query value QueryProductCatalog myQuery = myInvSession.makeQueryValue(QueryProductCatalog.class.getName()); // query product catalogue InventoryValueIterator myIterator = myInvSession.queryInventory(myQuery, new String[0]); // iterate through the result while(true) { // read next values

COM-WP-CBE_concepts.1.2.doc

page 63 / 73

OSS through JavaTM Initiative

InventoryValue[] invValues = myIterator.getNextInventoryValues(10); // end of iteration if length of returned array is zero if (invValues.length == 0) break; // do something } myIterator.remove();

Snippet 2 - Use A Specification To Instantiate A Product


JVTInventorySession myInvSession = // obtain reference to Session Bean // query product catalog -> list of ProductSpecifications SpecificationValidator mySpecVali = myFavouriteProdSpec.makeValidator(); // implementation alternative 1 InventoryEntityValue myProductValue = myInvSession.makeInventoryEntityValueFromSpecification( myFavouriteProdSpec.getInventoryKey()); if (mySpecVali.validate(myProductValue) ) { InventoryKey myProductKey = myInvSession.createInventoryEntityByValue(myProductValue); } // implementation alternative 2 InventoryKey myProductKey2 = myInvSession.createInventoryEntityFromSpecification( myFavouriteProdSpec.getInventoryKey(), null);

Snippet 3 - Create And Start An Order


JVTActivationSession myActSession = // obtain reference to Session Bean // Create a CreateOrder OrderValue myCreateOrderValue = myActSession.makeOrderValue(CreateOrderValue.class.getName()); // Create an OrderItem for the Order BusinessInteractionItem myOrderItem = myActSession.makeOrderItemFromCBE(myProductValue); myCreateOrderValue.setBusinessInteractionItems( new BusinessInteractionItem[1] {myOrderItem}); // create the order on the activation server OrderKey myOK = myActSession.createOrderByValue(myCreateOrderValue); // change an attribute after order was created myCreateOrderValue = myActSession.getOrderByKey(myOK); myCreateOrderValue.setRequestedCompletionDate(); myActSession.setOrderByValue(myCreateOrderValue); // start the provisioning workflow myActSession.startOrderByKey(myOK);

Snippet 4 - Query Resources


JVTInventorySession myInv = // obtain reference to Session Bean System.out.println(myProductKey.toString()); QueryValue myServProdQV, myResByServQV; mySPQV = myInv.makeQueryValue(QueryServicesByProduct.class.getName()); myRSQV = myInv.makeQueryValue(QueryResourcesByService.class.getName()); mySPQV.setProductKey(myProductKey); InventoryValueIterator myIt = myInv.queryInventory(mySPQV ); for (InventoryValue[] values = myIterator.getNextInventoryValues(10); values.length>0;) { for (int i = 0; i<values.length; i++) { ServiceKey aSKey = ((ServiceValue)values[i]).getInventoryKey(); System.out.println(aSKey.toString()); myRSQV.setServiceKey(aSKey); InventoryValueIterator resources = myInv.queryInventory(myRSQV);

COM-WP-CBE_concepts.1.2.doc

page 64 / 73

OSS through JavaTM Initiative

// iterate through ResourceValues } }

COM-WP-CBE_concepts.1.2.doc

page 65 / 73

OSS through JavaTM Initiative

8 Compatibility with Other Industry Models


The Core Business Entity (CBE) model must be compatible with other industry models, and if not, should be easily extendable in order to become compatible. Easy extensibility implies that the framework of the CBE should not have to be significantly changed. Note, that via its relationship with the TM Forums Shared Information/Data (SID) model, that the CBE model is by default compatible with the SID model. This chapter investigates, using an example, the compatibility of the CBE model to other industry models. ebXML Party Information is used as an example. An ebXML UML-like model could not be located. Therefore, the textual and XML representation of ebXMLs Party information is used to describe the information requirements. Following this description, the CBE UML model version of ebXMLs Party information is shown. Complementing the UML model is an explanation of how the CBE model is compatible with the ebXML information requirements and how the CBE model can easily be extended to accommodate the ebXML requirements. Chapter 8.1 ebXML Party Information is taken directly from the ebXMLs Collaboration-Protocol Profile and Agreement Specification v1.0, dated 10 May 2001.

8.1

ebXML Party Information


The PartyInfo element identifies the organization whose capabilities are described in this CPP and includes all the details about this Party. More than one PartyInfo element MAY be provided in a CPP if the organization chooses to represent itself as subdivisions with different characteristics. Each of the subelements of PartyInfo is discussed later. The overall structure of the PartyInfo element is as follows:
Snippet 5 - ebXML PartyInfo Element

<PartyInfo> <PartyId type="..."> <!--one or more--> ... </PartyId> <PartyRef xlink:type="...", xlink:href="..."/> <CollaborationRole> <!--one or more--> ... </CollaborationRole> <Certificate> <!--one or more--> ... </Certificate> <DeliveryChannel> <!--one or more--> ... </DeliveryChannel> <Transport> <!--one or more--> ...

COM-WP-CBE_concepts.1.2.doc

page 66 / 73

OSS through JavaTM Initiative

</Transport> <DocExchange> <!--one or more--> ... </DocExchange> </PartyInfo>

The PartyInfo element consists of the following child elements: One or more REQUIRED PartyId elements that provide a logical identifier for the organization. A REQUIRED PartyRef element that provides a pointer to more information about the Party. One or more REQUIRED CollaborationRole elements that identify the roles that this Party can play in the context of a Process Specification. One or more REQUIRED Certificate elements that identify the certificates used by this Party in security functions. One or more REQUIRED DeliveryChannel elements that define the characteristics of each delivery channel that the Party can use to receive Messages. It includes both the transport level (e.g. HTTP) and the messaging protocol (e.g. ebXML Message Service). One or more REQUIRED Transport elements that define the characteristics of the transport protocol(s) that the Party can support to receive Messages. One or more REQUIRED DocExchange elements that define the Message-exchange characteristics, such as the Message-exchange protocol, that the Party can support.

8.1.1

PartyId element
The REQUIRED PartyId element provides a logical identifier that MAY be used to logically identify the Party. Additional PartyId elements MAY be present under the same PartyInfo element so as to provide for alternative logical identifiers for the Party. If the Party has preferences as to which logical identifier is used, the PartyId elements SHOULD be listed in order of preference starting with the most-preferred identifier. In a CPP that contains multiple PartyInfo elements, different PartyInfo elements MAY contain PartyId elements that define different logical identifiers. This permits a large organization, for example, to have different identifiers for different purposes. The value of the PartyId element is any string that provides a unique identifier. The identifier MAY be any identifier that is understood by both Parties to a CPA. Typically, the identifier would be listed in a well-known directory such as DUNS or in any naming system specified by [ISO-3166].
COM-WP-CBE_concepts.1.2.doc page 67 / 73

OSS through JavaTM Initiative

The PartyId element has a single IMPLIED attribute: type that has a string value. If the type attribute is present, then it provides a scope or namespace for the content of the PartyId element. If the type attribute is not present, the content of the PartyId element MUST be a URI that conforms to [RFC2396]. It is RECOMMENDED that the value of the type attribute be a URN that defines a namespace for the value of the PartyId element. Typically, the URN would be registered as a well-known directory of organization identifiers. The following example illustrates two URI references.
Snippet 6 - Example of Two URI References
<PartyId type = "uriReference">urn:duns:123456789</PartyId> <PartyId type = "uriReference">urn:www.example.com</PartyId>

The first example is the URN for the Party's DUNS number, assuming that Dun and Bradstreet has registered a URN for DUNS numbers with the Internet Assigned Numbers Authority (IANA). The last field is the DUNS number of the organization. The second example shows an arbitrary URN. This might be a URN that the Party has registered with IANA to identify itself directly.

8.1.2

PartyRef element
The PartyRef element provides a link, in the form of a URI, to additional information about the Party. Typically, this would be the URL from which the information can be obtained. The information might be at the Party's web site or in a publicly accessible repository such as an ebXML Registry, a UDDI repository, or an LDAP directory. Information available at that URI MAY include contact names, addresses, and phone numbers, and perhaps more information about the Business Collaborations that the Party supports. This information MAY be in the form of an ebXML Core Component [ccOVER]. It is not within the scope of this specification to define the content or format of the information at that URI. The PartyRef element is an [XLINK] simple link. It has the following attributes: a REQUIRED xlink:type attribute, a REQUIRED xlink:href attribute, an IMPLIED type attribute.

COM-WP-CBE_concepts.1.2.doc

page 68 / 73

OSS through JavaTM Initiative

8.1.2.1

xlink:type attribute
The REQUIRED xlink:type attribute SHALL have a FIXED value of "simple". This identifies the element as being an [XLINK] simple link.

8.1.2.2

xlink:href attribute
The REQUIRED xlink:href attribute SHALL have a value that is a URI that conforms to [RFC2396] and identifies the location of the external information about the Party.

8.1.2.3

type attribute
The value of the IMPLIED type attribute identifies the document type of the external information about the Party. It MUST be a URI that defines the namespace associated with the information about the Party. If the type attribute is omitted, the external information about the Party MUST be an HTML web page.
Snippet 7 - Example of the PartyRef Element

<PartyRef xlink:type="simple" xlink:href="http://example2.com/ourInfo.xml" type="uri-reference"/>

8.1.3

CollaborationRole element
The CollaborationRole element associates a Party with a specific role in the Business Collaboration that is defined in the Process-Specification document [ebBPSS]. Generally, the Process Specification is defined in terms of roles such as "buyer" and "seller". The association between a specific Party and the role(s) it is capable of fulfilling within the context of a Process Specification is defined in both the CPP and CPA documents. In a CPP, the CollaborationRole element identifies which role the Party is capable of playing in each Process Specification documents referenced by the CPP.
Snippet 8 - Example of the CollaborationRole Element

<CollaborationRole id="N11" > <ProcessSpecification name="BuySell" version="1.0"> ... </ProcessSpecification> <Role name="buyer" xlink:href="..."/> <CertificateRef certId = "N03"/> <!-- primary binding with "preferred" DeliveryChannel --> <ServiceBinding name="some process" channelId="N02" packageId="N06"> <!-- override "default" deliveryChannel for selected message(s)--> <Override action="OrderAck" channelId="N05" packageId="N09" xlink:type="simple" xlink:href="..."/> </ServiceBinding> <!-- the first alternate binding --> <ServiceBinding channelId="N04" packageId="N06">

COM-WP-CBE_concepts.1.2.doc

page 69 / 73

OSS through JavaTM Initiative

<Override action="OrderAck" channelId="N05" packageId="N09" xlink:type="simple" xlink:href="..."/> </ServiceBinding> </CollaborationRole>

To indicate that the Party can play roles in more than one Business Collaboration or more than one role in a given Business Collaboration, the PartyInfo element SHALL contain more than one CollaborationRole element. Each CollaborationRole element SHALL contain the appropriate combination of ProcessSpecification element and Role element. The CollaborationRole element SHALL consist of the following child elements: a REQUIRED ProcessSpecification element, a REQUIRED Role element, zero or one CertificateRef element, and one or more ServiceBinding elements. The ProcessSpecification element identifies the Process-Specification document that defines such role. The Role element identifies which role the Party is capable of supporting. The CertificateRef element identifies the certificate to be used. Each ServiceBinding element provides a binding of the role to a default DeliveryChannel. The default DeliveryChannel describes the receive properties of all Message traffic that is to be received by the Party within the context of the role in the identified Process-Specification document. Alternative DeliveryChannels MAY be specified for specific purposes, using Override elements as described below.

8.2

CBE Representation of ebXMLs Party Information Requirements


The figure below depicts the CBE representation of the ebXMLs Party Information Requirements. The darkly shaded business entities (Party and Party Role) represent a portion of the Party core business entities. The ebXML information requirements are modeled as extensions to the model. No structural changes to the CBE model are necessary. ebXML PartyID and PartyRef are shown as extensions to the Party business entity. These could become part of the core business entity model, as they could be of general interest and not just specific to ebXML parties.
PartyRole is used as it was intended in the CBE. eBusinessCollaborator and ebXMLCollaborationRole, appear as subclasses of PartyRole. The eBusinessCollaborator subclass represents the focal point for the child elements of ebXML PartyInfo,

except for the two elements mentioned in the previous paragraph, that were considered extensions of Party. The ebXMLCollaborationRole is the

COM-WP-CBE_concepts.1.2.doc

page 70 / 73

OSS through JavaTM Initiative

focal point for the child elements of the ebXML CollaborationRole. The association between the eBusinessCollaborator and ebXML CollaborationRole is handled by the existing PartyRoleAssociation business entity. The subclass eBusinessCollaboratorPlaysebXMLCollaborationRole was added to illustrate the use of the PartyRoleAssociation business entity.

<<businessentity>> PartyReference 0..n descr ib ed By 1 <<busines sentity>> Party <<busi nesse ntity>> PartyRoleAs sociation 1 1

identifiedBy 0..n

<<busi ness entity>> Pa rtyID

plays <<busi nesse ntity>> eBusines sCollaboratorPlays ebXMLCollaboratorRole 0..n references 0..n 1..n securityFunctionsUse 1 <<busines sentity>> ebXMLCollaborationRole 1 <<busines sentity>> eBusiness Collaborator 1 rec ievesMessa gesVia 1 1 1 1 1 1..n <<businessentity>> DeliveryChannel 0 ..n <<busines sentity>> PartyRole

<<bus iness entity>> Certificate

m essageProtocolDefinedBy 1..n <<businessentity>> Transport

interactionsDefinedBy capab leOfPlaying 1 <<busi ness e ntity>> Pr ocess Sp eci fi catio n uses 1 ..n

m essageExch angeC har acteri sticsDefinedBy 1..n b oundToDeliveryChannelVia <<busi ness en tity>> DocExchange

<<busi ness entity>> ServiceBinding

1 <<busi nessentity>> Role

0..1 <<bus iness entity>> CertificateRef

Figure 35 - CBE Party Model's Compatibility with ebXML Party

COM-WP-CBE_concepts.1.2.doc

page 71 / 73

OSS through JavaTM Initiative

Glossary and References


8.3 8.4 Glossary References
Description TM Forum Shared Information and Data (SID) Model http://www.tmforum.org/browse.asp?catID=1158&sNode=1158&Exp= Y&linkID=26657 Analysis Patterns Reusable Object Models by Martin Fowler ISBN 0-201-89542-0 http://www.awl.com/cseng/titles/0-201-89542-0/apsupp/roles2-1.html Dealing with Roles http://martinfowler.com/apsupp/roles.pdf Patterns for things that change with time http://martinfowler.com/ap2/timeNarrative.html Alliance Common Information Architecture (AT&T, BT & Concert) version 3.1, 15 Dec 2000 GB921 Version 2.5 Open GIS Consortium http://www.opengis.org/ Postal Address Version 1.1 http://www.xml.org/ ISO 3166 Country Codes (2 Character) Business Modeling with UML, Business Patterns at Work Hans-Erik Eriksson, Magnus Penker ISBN 0-471-29551-5 Generic network information model Recommendation M.3100 (07/95) http://www.itu.int/rec/recommendation.asp?type=folders&lang=e&pare nt=T-REC-M.3100 Australian Standard AS 4590-1999 : Interchange of client information http://www.standards.com.au/catalogue/script/Details.asp?DocN=stds0 00023947 Data Model Patterns , Conventions of Thought http://www.dorsethouse.com/books/dmp.html Commission 7 Working Group 1 Reforming the Cadastre http://www.swisstopo.ch/fig-wg71/cad2014.htm Cadastre 2014 A VISION FOR A FUTURE CADASTRAL SYSTEM http://www.swisstopo.ch/figwg71/cad2014/download/cad2014_eng.pdf Open Location Services Initiative http://www.openls.org/ US Geological Survey LAND USE/LAND COVER

Reference SID

Fowler-AP

Fowler-Role Fowler-Time ACIA eTOM OGIS ADDRESSXML ISO-3166 Bus-Patterns M3100

AS4590

Hay Cadastre

OLS LAND USE

COM-WP-CBE_concepts.1.2.doc

page 72 / 73

OSS through JavaTM Initiative

Egenhofer ISO / DIS 19109 ANSI T1.2531999

USPS-28 SDSFIE/FMS FIE IAI/IFC ISO 10303

CLASSIFICATION Modified Anderson Classification http://rockyweb.cr.usgs.gov/public/mrgb/mrgblulcdefs.html Max J. Egenhofers List of Publications http://www.spatial.maine.edu/~max/pubs.html Draft International Standard. Geographic Information Rules for Application Schema American National Standard for Telecommunications - Information Interchange Code Description and Codes for the Identification of Location Entities for the North American Telecommunications System Postal Addressing Standards - Publication 28, November 2000 http://pe.usps.gov/cpim/ftp/pubs/Pub28/pub28.pdf Spatial Data Standard SDSFIE/FMSFIE Release 2.10 : (ANSI Standard NCITS 353) http://tsc.wes.army.mil/products/tssds-tsfms/tssds/sdsnews.asp International Alliance for Interoperability (IAI). http://iaiweb.lbl.gov/ ISO 10303 : Industrial automation systems and integration Around 60 parts have been published, many of these are of interest for Location

COM-WP-CBE_concepts.1.2.doc

page 73 / 73

You might also like