Class abstraction

This section describes the concept of the OSB library in terms of classes.

This document currently shows what we have planned in January 2001 (with the exception of PriceList) and needs rework: Describe the classes (usage) from what we know today.

Top level classes

Diagram shows the top level classes of the OSB library. Top level classes are the OSB abstraction of the real world; you can consider them as the interface between reality and the internals of the OSB library:

Diagram OSB top level classes

OSB system

This class describes the environment and configuration of the billing system. For the a telecommunication company (network operator or service provider) the billing system is the mediator between the networks and the network users.


This class is an abstraction for all business partners and holds their attributes such as addresses or payment connections.

An Associate does not need to have a contract. This allows to register prospective customers and the integration of a lead tracking system.

The attribute AssociateType defines the role the associate plays in our business: customer, wholesale partner, partner network, ... . AssociateType can be used to define which business procedures are applicable for the partner:

A customer is an end user of the available networks and offered services. The structure of corporate customers may be reflected by an internal hierarchy where several children are assigned to one parent. Customers are rated for their network usage and periodically billed.

Wholesale partner
Service providers do not operate their own network. Instead they have a bulk contract with one or more network operator, either on a per call basis or for a given bandwidth. The network operator rates the usage of the network by the partner's customers and regularly provides the results to the wholesale partner.

The network operator may give the wholesale partner restricted access to the billing system for subscriber administration, provisioning and reporting.

If the customers of the wholesale partner are maintained in the OSB system, the network operator may rate and bill the individual customers. Of course this implies that every call is rated twice, once for the wholesale partner, once for the customer.

Partner network
The operator of a network must corporate with other networks in order to provide worldwide services: interconnect and long distance carriers, ISPs, roaming partners, ... . In general one party allows the other party's subscribers access to its network and vice versa. A partner network plays a duplicate role: on one hand it is our customer, on the other hand we are its customer. We have to rate the usage of our network by the partner and we have to track our usage of the partner's network for reconciliation.

Content provider
The operator of an OSB system may offer the services of a content provider to its users. OSB allows to process usage records generated by the content provider and supports settlements with the content provider. A content record is rated1) for the respective customer and for reconciliation with the content provider.

1) In this context, rating might just means"use the charge as determined by the contect provider".

Rework Associate.AssociateType: This does not comply with proper object oriented design, use inheritance! (This requires that we develop a clear picture of common and specific functionality.


This base class models the networks available to the OSB operator. Besides different network types, e.g. GSM, ISDN, Internet, ... , we also distinguish between two kind of networks: the ones owned and managed by the OSB operator and partner networks.

Own network

This class describes the networks owned by the OSB billing system operator. For these networks the billing system must:

Partner network

This class models foreign networks who's resources are used by the OSB operator. Usually there is no need to for the billing system to know configuration details about partner networks, for OSB it does not matter whether a partner network is a real network or a service provider.
For a service provider these are the backbone networks used by the services offered, while for network operators this might be interconnect carriers, networks of a different type, roaming partners (for mobile networks), ... .

Network element

The class NetworkElement and its descendants model the properties of the various network elements: switches, HLRs, ... .

Financial transaction

This base class provides the attributes common for all financial transactions. It has two prominent descendants:

A financial transactions always refers to an associate. During billing OSB generates one invoice for each contract, so a financial transaction may refer to a contract also.

We require that OSB can interface any financial system: FinancialTransaction must be designed to offer a stable interface towards OSB.


The class Contract models the agreements between the OSB operator and its associates and tracks the history. It defines the general terms and conditions such as payment terms, billing date and interval, method of payment, ... . A Contract is the OSB entity for which an invoice is generated.

A contract per se does not -and never should- restrict the products available for an associate. The class product will support the definition of such business rules.


A Product is the offer of the OSB operator to its potential subscribers. The class product originates from the retail sales concept to group several parts into -well- a product. We extend this concept to cover also the requirement of the partner and wholesale business.

A product consists of several ProductPart. An sample product might be offered as follows:

From a technical perspective there doesn't see to be a big difference between a product and a product part. We might as well define a product as a product part that has no parents.

Product part

ProductPart is an abstract base class for all items that can be part of a product. Possible product parts are: goods, resources, network services, value added services (such as invoice generation for a wholesale partner), tariff systems, charges, ... .
A ProductPart may itself be made up of other ProductPart. A GSM subscription, for example, needs a least a SIM card, the service telephony and a MSISDN (telephone number). Cascading parts list enable us to provide a mechanism to structure a product. This is the taks of the class ProductPartGroup that also supports restrictions on the parts it contains, e.g., "exactly one of the items must be selected".

The attribute mandatory defines whether the part is a necessary, integral part of the product or if it optional.
If we define mandatory as an integer, then we can support different levels of priviledges.
Complete list of supported ProductPart: usage service, network service, VAS, ...

Price list

The class PriceList is responsible to define all subscription and onetime charges for a product or product part. The class has to provide information about:

Amount is itself a class that provides multi currency support.

Personalized product

The class PersonalizedProduct links a sold product to a contract and an associate. The class is responsible to keep track of the history: When was the product sold, what is the minimum duration of the subscription, ... .

A personalized product is billed as part of the contract it belongs to. The link to Associate allows us to identify user of the product.

If the associate is hierarchically structured the links PersonlizedProduct — Contract — Associate on the one hand and PersonlizedProduct — Associate on the other hand do not necessarily point to the same instance of Associate as show in the diagram below:

There are two possiblities to find all PersonalizedProducts of an Associate: Either we look at all the contracts of the associate or we browse through all of its descendants. (Note that both methods are valid also if the associate does not below to a hierarchy.) Both possiblities are also applicable when searching the contractual owner of a personlized product.
Of course we have to ensure that for either task both methods yield the same result. The following rule must always be satisfied:
The associate who owns the contract of a personalizedProduct must either be itself the user of the product or an ancestor of the product user.

Any application or class that changes the relationship between either a
+ ContractAssociate
+ PersonlizedProductContract
+ PersonlizedProductAssociate
is responible for the correct maintenance of all relations. The behaviour of OSB in case of mismatch is undefined, though detected mistakes will be notified.
Clarify the relationship to Product: Will we allow for product upgrades that are applicable to everybody?
  Walk through the following business scenario:
We want to add a new service to a product. This service should be available to all subscribers of the product. What are the necessary steps?
1) OK: Define the service as a product part and add it to the product.
2) OK: In case of a network service: Upgrade all affected tariff systems.
3) BUT HOW does the service "come" to the customer, or more specific, to the personalized product?

Personalized product part

The class PersonalizedProductPart provides the details about a purchased product. One important information stored by this class are resource identifiers that are used by the rating process to assign usage records to the involved parties. In general the class will be extensivly used during rating and billing.

Clarify the relationship to ProductPart. Is there a connection at all or is everything handled via the product?


The class Resource describes the properties of the resources that are necessary for each subscriber to access and use the networks.
For GSM networks this is the SIM card and the MSISDN that is needed for some services. Other examples are e-mail addresses or URLs.

The relationship between Resource and PersonalizedProductPart in the class diagram is correct only for a distinct time:
The originating customer is identified using the date/time and resource information contained in a usage record. This requires that at any time a resource may be assigned to one ProductPart at most. It is however acceptable that the ownership of a resource changes over time: Precisely the relation is not many-to-zero/one, but many-to-many.

Usage record source

Base class for all sources of usage records that defines a unique interface for UsageRecordStream. The classes Network and NetworkElement are derived from UsageRecordStream, the architecture also supports sources that are not part of a network, e.g. content providers. For another example consider an operator offering a directory inquiry service that automatically connects the user. When a customer uses this service, the system that initiates the network connection should generate an appropriate usage record.

Usage record stream

This class models the properties of a collection of usage records, they are generated by a network or an external system. A UsageRecordStream can be a flat file, or a permanent stream of usage record that, for instance, are generated by the hot-billing interface of a network element.

Describe how prepaid, the real real-time thing, fits into the concept of usage record streams: Most probably we'll find out that it is enough to accept standard UNIX IPC mechanisms: TCP/IP or message queues.

Usage record

UsageRecord is the base class for all kinds of usage record. OSB can rate usage records only for entities that can be identified using the information in the usage record itself or the usage record stream it belongs to. For example we can assign a usage record to a customer only if it contains at least one reference to a resource. Without resource information rating is possible only for the networks involved in the call.
As already mentioned above, OSB handles also usage records, eventually rated, of external systems. This is one feature, that makes OSB convergent.

Define how we are going to handle (periodical) subscription charges generated by other systems: How do we know where they should appear on the invoice.
One possiblity is to define types of charges imported into OSB. Note that if the service should be billed by OSB (theoretically this must be possible), it is most probably more suiteable to define it as a ProductPart.

Tariff system

This class is responsible to define the rating of the network usage. TariffSystem is derived from [GSM 12.05].
The rating of the network usage is isolated from other charges for better maintainability and to allow multiple usage of a tariff system.

Define exactly for which product parts a tariff system is needed. The "problem" currently is that I want 1 TariffSystem per product and network type (else tariff systems might get tricky to maintain). Most probably the following rule will help:
+ A product must have exactly one tariff system for each type of network.
+ A tariff system must support all services of its network type contained in the product.

For a comprehensive description of TariffSystem please refer to the next chapter.

Marketing plan

The class MarketingPlan implements the marketing concepts of the business world. Marketing plans allow the configuration of discounts or additional charges that

  1. are granted with respect to other charges and debits,
  2. depend on the past behaviour of the customer,
  3. are valid only for a short time.

Let me explain this by sample promotions:

  1. 10% discount on all calls if the total usage charge for one invoice is above 888 S$.
    120 free SMS every month.
  2. 5% off the invoice amount if you have paid the last 6 invoices in time.
  3. 50% reduction on calls to Hongkong during Chinese new year.

Technically speaking a MarketingPlan is an ordered collection of MarketingAction that may be assigned to an Associate, Contract and a Product. ordered means that marketing actions are applied in a well defined sequence.
Because a marketing plan can be assigned to a contract or associate OSB also allows for cross product marketing.

Marketing action

The class MarketingAction is the base class for all kinds of promotions: Discounts, free calls, call charge reduction, minimum contract duration, ... .
Marketing actions may have a validity period. They divide into 2 categries: some can be applied at rating time while other can only be evaluated when the invoice is generated.

Marketing actions have a tendency to require historical data that are currently not maintained in OSB. The only solution is a pragmatic approach: Define what data are needed and collect them somewhere in the rating or billing process.

One general requirement is that the account status of a customer is as accurate as possible. This minimizes the financial risk of the OSB operator and at the same improves its service to the customer. It is, e.g., desirable to notify the customer via SMS how many free minutes are left.
OSB therefore applies markting action as early as possible.

We'll have to develop a concept how we handle prorated marketing actions that are applied at rating time. One possible approach is:
Assume that the current status of the subscriber will remain unchanged during the time period under question. If later the assumption becomes invalid we will reapply the marketing actions based on the new facts.