Deliverable D5.7 – URBANWATER Grant Agreement: 318602 Project Title: Intelligen Project Acronym: Sev Gra Subject: D5.7 – Automatic and Dissemination Level: PUB Lead beneficiary: Org Revision Preparation V1.0 December 2 This project has received funding from the Europ and demonstration under grant agreement no. 31 This publication reflects only the authors’ views contained therein. – Automatic and dynamic billing system implem nt Urban Water Management System URBANWATER venth Framework Programme Collaborative Project ant Agreement Number 318602 dynamic billing system implementation – BLIC ga Systems GmbH & Co. KG date Period covered Project start date Projec 2014 Months 12 to 22 December 2012 30 pean Union’s Seventh Framework Programme for research, technolog 18602. and the European Union is not liable for any use that may be made o mentation 1 WP5 ct Duration Months gical development of the information
108
Embed
Intelligent Urban Water Management Systemurbanwater-ict.eu/.../2015/...Billing-System-Implementation_v1.0.pdf · Intelligent Urban Water Management System ... D5.7 – Automatic and
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Deliverable D5.7 –
URBANWATER
Grant Agreement: 318602
Project Title:
Intelligent Urban Water Management System
Project Acronym:
Seventh Framework Programme
Grant Agreement Number 318602
Subject:
D5.7 – Automatic and dynamic billing system implementation
Dissemination Level: PUBLIC
Lead beneficiary: Orga Systems GmbH & Co. KG
Revision Preparation date
V1.0 December 2014
This project has received funding from the European Union’s Seventh Framework Programme for research, technological development
and demonstration under grant agreement no. 318602.
This publication reflects only the authors’ views and the European Union is n
contained therein.
– Automatic and dynamic billing system implementation
Intelligent Urban Water Management System
URBANWATER
Seventh Framework Programme
Collaborative Project
Grant Agreement Number 318602
Automatic and dynamic billing system implementation –
PUBLIC
Orga Systems GmbH & Co. KG
Preparation date Period covered Project start date Project Duration
2014 Months 12 to 22 December 2012 30
ding from the European Union’s Seventh Framework Programme for research, technological development
and demonstration under grant agreement no. 318602.
views and the European Union is not liable for any use that may be made of the information
Automatic and dynamic billing system implementation
1
WP5
Project Duration
Months
ding from the European Union’s Seventh Framework Programme for research, technological development
e made of the information
Deliverable D5.7 – Automatic and dynamic billing system implementation
2
URBANWATER PUBLIC
Grant Agreement: 318602
History of Changes
Version Author, Institution Changes
0.1 S. Flake, Orga Systems GmbH & Co. KG Initial document structure, outline of contributors
0.2 G. Sinne Contributions to ABS Gateway Adapters and Converters and ABS deployment
0.3 G. Sinne, J. Heinrichsmeier, M. Koch Operator GUI, Web Services and Web Server Information added
0.4 S. Flake, J. Heinrichsmeier, G. Sinne Core Billing System Information added, High Level Architecture updated
0.5 S. Flake, J. Heinrichsmeier, M. Hennemeyer-Schwenkner, G. Sinne
ABS Configuration added; abstract, introduction and annexes extended
0.6 J. Heinrichsmeier Screenshots of Operator GUI added
0.7 S. Flake Updates on headings, figure and table captions, and references. Conclusions and requirements fulfilment added
1.0
S. Flake Updates and finalization after reviews by Ateknea and UNIZG-FER
Deliverable D5.7 – Automatic and dynamic billing system implementation
3
URBANWATER PUBLIC
Grant Agreement: 318602
Abstract
This deliverable describes the implementation of the automatic and dynamic billing system (in short: ABS) in the
context of the UrbanWater project. In this document, an ‘automatic billing system’ means that the system can
obtain meter read data in regular, short-term intervals and further process these data without human intervention.
This further processing encompasses in particular the conversion of water consumption into monetary values and
the allocation of these charges to the corresponding customer accounts. The term ‘dynamic billing system’, in
turn, shall refer to the ability of the system to manage variable tariffs with dynamically changing prices. Such
tariffs are considered a potentially suitable means to optimize supply and demand and incentivise end users to
adjust their consumption patterns to times when demand is lower and water cheaper.
This document provides a complete specification of a number of exposed interfaces of such an ABS. The
corresponding API is open in the sense that any other billing system is free to implement and offer the same
functionality in order to be integrated into the UrbanWater Platform.
To demonstrate the feasibility of the developed ABS API and in order to provide an ABS implementation that is
able to be used in the upcoming field tests in the UrbanWater project, this document also describes the work
performed to implement and deploy an ABS that is realizing this API. While an existing commercial billing system
could be taken as a basis, that system has been extended by a gateway in order to be integrated with the
UrbanWater Platform.
Deliverable D5.7 – Automatic and dynamic billing system implementation
4
URBANWATER PUBLIC
Grant Agreement: 318602
List of Acronyms
Acronym Full Name
ABS Automatic Billing System
ACC Administration and Configuration Cockpit
AJAX Asynchronous JavaScript + XML
AMQP Advanced Message Queuing Protocol
AMR Automated Meter Reading
API Application Programming Interface
APS Adaptive Pricing System
AS Application Server
BAS Business Administration System
CBF Core Billing Framework
cbm Cubic metre
CCB Convergent Charging and Billing
CHR Charging Rule
CIS Customer Information System
COP Customer Online Portal (also called Online Platform Customer Web Portal)
CORS Cross-Origin Resource Sharing
CPP Critical Peak Pricing
CPU Central Processing Unit
CRM Customer Relationship Management
CRR Crediting Rule
CRUD Create, Read, Update, Delete
CSR Customer Sales Representative
css Cascading Style Sheet
CTF Crediting Tariff
CZK Czech Koruna
DB Database
DMA District Metered Area
DMZ Demilitarized Zone
EUR Euro
Deliverable D5.7 – Automatic and dynamic billing system implementation
5
URBANWATER PUBLIC
Grant Agreement: 318602
GGSN GPRS Gateway Support Node
GPRS General Packet Radio Service
GSM Global System for Mobile Communications
GSMA GSM Association
GUI Graphical User Interface
HLR Home Location Register
HTML Hypertext Transfer Markup Language
HTTP Hypertext Transfer Protocol
ICT Information and Communication Technology
ID Identifier
IF Interface
IP Internet Protocol
IPR Intellectual Property Rights
ISO International Organization for Standardization
ITU International Telecommunication Union
ITU-T ITU Telecommunication Standardization Sector
IUWMS Intelligent Urban Water Management System
JSON JavaScript Object Notation
JVM Java Virtual Machine
LIM Limit
MSC Mobile Switching Center
ORGA Orga Systems GmbH & Co. KG
RAM Random Access Memory
REST Representational State Transfer
ROP Reoccurring Operation
RTE Real-time Environment
SGI Serious Games Interactive
SMSC Short Message Service Center
SQL Structured Query Language
TCP/IP Transmission Control Protocol / Internet Protocol
ToU Time of Use
UC Use Case
Deliverable D5.7 – Automatic and dynamic billing system implementation
6
URBANWATER PUBLIC
Grant Agreement: 318602
UML Unified Modeling Language
UNIZG-FER University of Zagreb Faculty of Electrical Engineering and Computing
UR Usage Rule
URI Unique Resource Identifier
URL Uniform Resource Locator
USDL Unified Service Description Language
UTB Usage Time Band
UTF Usage Tariff
UW UrbanWater
VAS Value-added Service
VAT Value Added Tax
w.r.t. with respect to
WAR Web Application Archive (a file format)
WDN Water Distribution Network
WP Work Package
WS Web Service
XML eXtensible Markup Language
XSD XML Schema Definition
Deliverable D5.7 – Automatic and dynamic billing system implementation
7
URBANWATER PUBLIC
Grant Agreement: 318602
Table of Contents
History of Changes .................................................................................................................................................. 2
List of Acronyms ...................................................................................................................................................... 4
List of Figures ........................................................................................................................................................ 10
List of Tables ......................................................................................................................................................... 11
1.1 Objectives of the UrbanWater Project ..................................................................................................... 12
1.2 Objectives of WP 5 (Customers’ empowerment tools) ............................................................................ 12
1.3 Objectives of this document .................................................................................................................... 14
1.4 Structure of this document ...................................................................................................................... 14
2 High Level Architecture ................................................................................................................................. 16
3 Core Billing System ...................................................................................................................................... 18
4 ABS Gateway – Adapters and Converters .................................................................................................... 25
4.1 Connection to the UW Core Platform ...................................................................................................... 26
4.2 Message Format ..................................................................................................................................... 26
4.2.1 Service IDs ...................................................................................................................................... 27
4.2.2 Publishing the Data Format of Message Payloads .......................................................................... 27
4.3 Meter Data Converter .............................................................................................................................. 29
4.6 ABS Notification Server ........................................................................................................................... 33
5 ABS Gateway - Exposed Web Service Interfaces ........................................................................................ 35
5.1 Data Model .............................................................................................................................................. 36
5.1.1 Customer Data Management ........................................................................................................... 37
6.1 Integration into the UW Visualization Service.......................................................................................... 46
6.2 Communication with the Gateway ........................................................................................................... 46
6.3 CORS ...................................................................................................................................................... 47
8.1 Example Tariffs ....................................................................................................................................... 61
8.3 Tariff Configuration for GOLD CCB – Confidential – to be removed in public version ............................ 63
9 Conclusions and Outlook .............................................................................................................................. 68
11 Annex I – Specification of the ABS Exposed Interfaces................................................................................ 71
11.1 Status Handling .................................................................................................................................. 71
11.2 Customer Management IF .................................................................................................................. 71
11.2.1 Customer Data Management .................................................................................................... 72
11.2.1.1 Register a Customer .............................................................................................................................................. 72 11.2.1.2 Update a Customer Registration ............................................................................................................................ 73 11.2.1.3 Get Data of all Customers ...................................................................................................................................... 73 11.2.1.4 Get Customer Data ................................................................................................................................................ 74 11.2.1.5 De-register a Customer .......................................................................................................................................... 74
11.2.2.1 Set a Balance ......................................................................................................................................................... 75 11.2.2.2 Update a Balance ................................................................................................................................................... 76 11.2.2.3 Get Balances .......................................................................................................................................................... 76 11.2.2.4 Get a Balance ......................................................................................................................................................... 77 11.2.2.5 Get Transaction History .......................................................................................................................................... 77
11.2.3.1 Sell a Product Offer ................................................................................................................................................ 78 11.2.3.2 Activate a Subscription ........................................................................................................................................... 79 11.2.3.3 Get a Subscription .................................................................................................................................................. 80 11.2.3.4 Get the Tariff Name of a Subscription .................................................................................................................... 81 11.2.3.5 Get Tariff Details for a Subscription ....................................................................................................................... 81 11.2.3.6 Deactivate a Subscription ....................................................................................................................................... 82
11.3 Tariff Configuration IF ......................................................................................................................... 82
11.3.1 Tariff Description Format .......................................................................................................... 82
11.3.2 Add a Tariff ............................................................................................................................... 84
11.3.3 Update a Tariff .......................................................................................................................... 85
11.3.4 Get a Tariff ................................................................................................................................ 86
11.3.5 Deactivate a Tariff ..................................................................................................................... 87
11.4 Product Offer IF .................................................................................................................................. 87
11.4.1 Product Offer format ................................................................................................................. 88
11.4.2 Add a Product Offer .................................................................................................................. 88
11.4.3 Get a Product Offer ................................................................................................................... 89
Deliverable D5.7 – Automatic and dynamic billing system implementation
9
URBANWATER PUBLIC
Grant Agreement: 318602
11.4.4 Get all Product Offers ............................................................................................................... 89
11.4.5 Update a Product Offer ............................................................................................................. 90
11.5 Customer Empowerment IF ................................................................................................................ 90
11.5.1 Customer Empowerment: Get Account Information .................................................................. 91
11.5.1.1 Get Customer Data ................................................................................................................................................ 91 11.5.1.2 Get Balances .......................................................................................................................................................... 91 11.5.1.3 Get a Balance ......................................................................................................................................................... 91 11.5.1.4 Get Transaction History .......................................................................................................................................... 92 11.5.1.5 Get Bill Preview ...................................................................................................................................................... 93
Figure 8: Data Format Exchange Procedure ......................................................................................................... 28
Figure 9: Generic ABS response format ................................................................................................................ 29
Figure 10: Meter Data Converter ........................................................................................................................... 29
Figure 11: Example of Meter Data ......................................................................................................................... 30
Figure 14: Price Update Data Format .................................................................................................................... 32
Figure 15: Example of Price Update ...................................................................................................................... 33
Figure 16: ABS Notification Server ........................................................................................................................ 33
Figure 17: ABS and Gateway - External Web Services Interfaces ........................................................................ 35
Figure 18: Value Classes for Customer Management ........................................................................................... 37
Figure 19: Balance Value Classes for Account Management................................................................................ 38
Figure 20: Transaction History Classes for Account Management ........................................................................ 38
Figure 21: Value Classes for Tariff Management .................................................................................................. 40
Figure 22: Value Classes for Product Offer Management ..................................................................................... 41
Figure 23: Value Classes for Subscription Management ....................................................................................... 41
Table 14: Product Offer: Transaction Operation States ......................................................................................... 88
Table 15: Output Get Transaction History ............................................................................................................. 93
Deliverable D5.7 – Automatic and dynamic billing system implementation
12
URBANWATER PUBLIC
Grant Agreement: 318602
1 Introduction
1.1 Objectives of the UrbanWater Project
Improving the efficiency of water management in Europe is recognized as essential for overcoming the growing
exposure of European countries to increasing populations and water scarcity and droughts.
The objective of the UrbanWater Project (http://urbanwater-ict.eu/) is to enable better end-to-end water
management in urban regions, where “17% of the abstracted water is used for public water supply (including
households, the public sector and small businesses) and 15% for industry” (see [1] for more details).
The project will develop an innovative Information & Communication Technology (ICT) based platform for the
efficient, integrated management of water resources.
The system will benefit consumers, water utilities, public authorities, the environment and the general public in
terms of:
• Providing consumers with comprehensive tools enabling them to use water more efficiently, thereby better
adapting overall consumption to the supply possibilities.
• Helping water utilities to meet demand at the right price, according to its pattern of consumption.
• Fostering new partnerships between stakeholders so as to ensure the successful development of the
system and the evolution of the European Water Sector as a global leader.
The IUWMS will likely incorporate:
• advanced metering solutions,
• real-time communication of supply / demand data,
• new data management technologies with real-time predictive capability,
• supply / demand forecasting,
• demand pattern interpretation,
• decision support systems,
• adaptive pricing, and
• user empowerment solutions.
The UrbanWater consortium includes ICT companies, research organizations, water utilities and authorities with
complementary capacities and know-how. Three water utilities included in the group will undertake large-scale
validations on their water supply systems, thus promoting a final outcome that is close to the market and to the
consumers. The final outcome of the project will remain open and interoperable with energy and water
management schemes, thus positively impacting not only water consumption, but overall usage of natural
resources throughout Europe.
1.2 Objectives of WP 5 (Customers’ empowerment tools)
This deliverable is part of the work in work package 5 - Customers‘ empowerment tools. The objectives of work
package 5 are:
• Develop and set up an Online Platform to allow customers to monitor their water consumptions.
• Develop a set of serious games to reinforce customers’ empowerment.
• Develop an adaptive pricing system.
• Develop an automatic and dynamic billing system.
Deliverable D5.7 – Automatic and dynamic billing system implementation
13
URBANWATER PUBLIC
Grant Agreement: 318602
Correspondingly, the work package consists of the following four main tasks.
Task 5.1 – Customers’ Online Platform
The aim of Task 5.1 is to develop and set-up a Web-based Online Platform accessible through different devices
with different interfaces (computers, smart phones, tablets, etc.) to allow customers to monitor their real-time
consumption as well as to see their water consumption forecasts. This Web-based Online Platform will not only
allow customers and water utilities to improve their current communication and will show customers’ statistics and
patterns, but will also be designed to allow water utilities to collect customers’ requirements and queries. Task
5.2, Task 5.3 and Task 5.4 developments will be integrated into this Online Platform. The Online Platform will
offer the possibility of developing third-party plug-ins and integrate them into the website. A public API with the
description of the functionality will be offered. The outputs of Task 5.1 are the Customers’ Online Platform
requirements and design delivered jointly with all customers’ empowerment tools requirements and conceptual
design in the respective deliverables D5.1 and D5.2, as well as D5.3 - Online platform implementation (computer
interface, smart phone and tablet).
Task 5.2 – Serious Games Development
Task 5.2 will develop serious games for customer empowerment. Based on user requirements collected in Task
1.2, an early game prototype will be developed and implemented. The software will be developed using the Unity
3D game engine. Unity 3D includes a simple-to-use development environment. The game prototype will enable
the user to understand basic water systems in private environments and will use game mechanisms to inform and
educate about water consumption to ultimately change user behaviour. The game will use weather predictions
and other data sources to inform the game play and to connect the game experience to the real world. Note that
the early prototype will only enable the user to interact with the game and not to track the user’s decision and
progress in the game. After this prototype, a final solution will be delivered in order to allow a deeper
understanding of water consumption in private environments. The game will use detailed information about the
users’ household water obtained in Task 4.1 (D4.8) and compare this to similar households. The game will enable
competition as well as collaboration such as advising among households based on a number of variables relevant
for water consumption. The outputs of Task 5.2 are the serious game requirements and conceptual design
delivered jointly with all customers’ empowerment tools requirements and conceptual design in the respective
deliverables D5.1 and D5.2, as well as D5.4 – First game prototype implementation and D5.6 - Game solution for
Customer Empowerment using Water Consumption Data.
Task 5.3 – Adaptive Pricing System
Task 5.3 aims to develop a specification of a strategy for the adaptive water pricing that will use the water
demand forecast (Task 4.1) and water supply prediction (Task 4.2) together with the time of use (ToU), critical
peak pricing (CPP) and a set of charging mechanisms such as real-time rating and charging, interval billing and
revenue, requirements provided in Task 1.2 by the water utilities. A model of end-user consumption response to a
certain water supply price and to the price profile will be assessed as well. Optimization methods will then be put
in place to compute water price profiles that will ensure correct water supply system operation and water savings.
Task 5.3 will also focus on determining input and output data formats as well as functional interfaces for adaptive
pricing, and a rule-based mechanism for notifications to enhance the transparency for end-customers. The output
of Task 5.3 is the adaptive pricing system requirements and design to be delivered jointly with all customers’
empowerment tools task in D5.1 and D5.2, as well as D5.5 – Adaptive price system implementation.
Deliverable D5.7 – Automatic and dynamic billing system implementation
14
URBANWATER PUBLIC
Grant Agreement: 318602
Task 5.4 – Automatic Billing System
Task 5.4 aims to develop an automatic and dynamic billing system with innovative price plans (or: tariffs) and
real-time notifications for the customers’ water consumption. Dynamic billing encompasses rating and charging of
water consumption in regular intervals (e.g. every 15 min) and utilizes innovative, dynamic price plans. These
price plans will be built on requirements gathered in the different tasks of WP 1. In addition to the intended
underlying adaptive pricing mechanism, it will be necessary to, e.g., set up more advanced pricing schemes that
consider further context parameters and might offer discounts and bonuses. For example, a prepayment tariff
might allow for a discount on the water price. Another tariff could allow a daily basic allowance of water at a fixed
price but with fees for additional water consumption charged at a dynamically changing, most probably higher
price. Furthermore, real-time threshold notification mechanisms via different communication channels can be part
of a price plan or sold as value-added services. The dynamic billing system to be developed in this task will
consider the adaptive pricing system developed in Task 5.3, and will have interfaces with other components to
automatically obtain data concerning water consumption and provide information about even the most recent
water consumption and related costs as part of bill previews via the Online Platform (see Task 5.1). The
deliverables of Task 5.4 are the automatic and dynamic billing system requirements and design delivered jointly
with all customers’ empowerment tools requirements and conceptual design in the corresponding deliverables
D5.1, D5.2, as well as D5.7 – Automatic and dynamic billing system implementation.
1.3 Objectives of this document
This deliverable D5.7 – Automatic and dynamic billing system implementation describes the architecture, offered
functionality, implementation, and initial deployment of the Automatic and Dynamic Billing System. Please note
that for the sake of brevity we will simply use the term Automatic Billing System (ABS) in the following.
As already outlined in the abstract, by an ‘automatic billing system’ it is meant that a billing system can obtain
meter read data in regular, short-term intervals and further process these data without human intervention.
Further processing includes the automated, immediate conversion of water consumption into monetary values
and the direct allocation of these charges to the corresponding customer accounts. The term ‘dynamic billing
system’, in turn, shall refer to the ability of the system to manage variable tariffs with dynamically changing prices.
Such tariffs are considered a potentially suitable means to optimize supply and demand and incentivise end users
to adjust their consumption patterns to times when demand is lower and water cheaper.
1.4 Structure of this document
Following this introduction, this document contains the following sections:
• Section 2 provides a high level view of the ABS architecture and its connections with the UrbanWater
(UW) Core Platform and other services of the overall UW Platform.
• Section 3 gives a brief description of the commercial billing system GOLD CCB, which is employed in the
UrbanWater project as the so-called Core Billing System. Note that GOLD CCB is IPR background, such
that only limited information about its interfaces, internal components and configuration can be revealed in
this public deliverable.
• Section 4 describes the design and implementation of the message queue Adapters and Convertors of
the ABS in a component called ABS Gateway, which is placed in front of the Core Billing System to
integrate with the UW Core Platform.
• Section 5 deals with the exposed Web Service interfaces of the ABS Gateway, which are particularly
used by GUIs for operator staff and customers.
Deliverable D5.7 – Automatic and dynamic billing system implementation
15
URBANWATER PUBLIC
Grant Agreement: 318602
• Section 6 presents the implementation of an Operator GUI. The Operator GUI encompasses a Tariff and
Product Configurator and it is an integratal part of the UW Visualization Service (also called UrbanWater
Dashboard) and provides a graphical interface to manage customers, tariffs, products and subscriptions.
• Section 7 presents the initial ABS deployment. It is important to mention here that all installed instances
of the ABS are hosted at the ABS provider’s premises (i.e., at ORGA) during all phases of development,
test, integration, and validation (field tests).
• Section 8 describes a configuration of the Core Billing System as a ‘case study’ with different tariffs in
preparation of the field tests. The configuration has been designed and realized in order to have a
reference Core Billing System for test and validation purposes during implementation and as a basis for
the upcoming field tests.
• Section 9 concludes this document with a review of the implemented functionalities against the required
functionalities specified in deliverable D5.1 [11] and by providing an outlook on remaining work for
integration and preparation of the field tests in Spain and the Czech Republic.
Deliverable D5.7 – Automatic and dynamic billing system implementation
16
URBANWATER PUBLIC
Grant Agreement: 318602
2 High Level Architecture
The UW Core Platform serves as the central message broker in the overall UrbanWater Platform (see deliverable
D6.2 – UrbanWater platform architecture design [13]). From the point of view of the UW Core Platform, the
Automatic Billing System (ABS) is therefore considered as yet another service, just as other modules like the
Decision Support System, the Cloud Database, or the Adaptive Pricing System. The UW Core Platform is the
main platform component that the ABS is directly connected with, i.e., all requests and replies between the ABS
and any other service are routed through the Service Bus in the UW Core Platform, which is realized as a
message broker with message queues (see also deliverables D6.2 [13] and D6.4 [14]). There is one exception,
though, which concerns the direct integration of HTML Web pages of the so-called Operator GUI (formally this
was also called ‘Tariff & Product Configurator’) into the UW Dashboard, which unifies the graphical user
interfaces of all services into a single GUI.
Figure 1 shows a high level architecture of the ABS with its three main components and their connection with the
other components of the UrbanWater Platform via exposed interfaces. Most of this public document is about the
design and implementation of these exposed interfaces by means of the ABS Gateway and the Operator GUI,
whereas the internal interfaces and the Core Billing System are only briefly explained due to IPR restrictions.
Figure 1: ABS High Level Architecture
The ABS consists of the following main components, which are shown on the right hand side of Figure 1:
• the Core Billing System, also called backend billing system,
• the ABS Gateway with a number of exposed interfaces offered by
- Adapters and Converters to communicate with the other UW services via message queues
and
- Web Services which offer a various interfaces with operations implemented as REST Web
Services, and
• the Operator GUI offered to utility staff for various tasks in the context of customer, tariff, product and
subscription management.
Deliverable D5.7 – Automatic and dynamic billing system implementation
17
URBANWATER PUBLIC
Grant Agreement: 318602
Core Billing System. For the Core Billing System, a software called GOLD CCB is utilized (CCB is short for
Convergent Charging and Billing). GOLD CCB is a real-time charging, billing and financial management software.
It is designed around a single rating engine with unified concepts across rating and billing and is based on a
common subscriber data management. GOLD CCB provides core billing functionality by supporting all processes
from collecting consumption data, over rating, calculating charges and generating billing information, to producing
bills to customers and managing debt collection. Some more details about GOLD CCB will be provided in Section
3 to help readers to understand the role of this system in the remainder of this document.
ABS Gateway. The ABS Gateway acts as a mediator and translator between the UW Core Platform and the
Core Billing System – this functionality is realized by means of different exposed interfaces which together form
an extensive ABS API. This API is implemented by so-called Adapters and Converters as well as Web
Services. The ABS Gateway decouples the internal (or: backend, proprietary) interfaces of the Core Billing
System from the exposed interfaces which are visible to and used by the UW Core Platform and other UW
services.
The fundamental design choice behind this approach was to provide a platform-independent API for all billing-
related operations and demonstrate its feasibility without changing the employed Core Billing System’s existing
interfaces. Consequently, dedicated adapters and converters need to be built in front of the Core Billing System.
The resulting ABS Gateway thus acts as a mediator and converts the payload of incoming and outgoing
messages, events, and other kinds of provided data (e.g., files) between the formats used in the UW Core
Platform and the Core Billing System.
In many cases, this means to convert messages received and sent via the message queues that are managed in
the UW Core Platform. In order to process these messages, the ABS Gateway has a number of Adapters and
Converters. The ABS Gateway also provides a number of exposed interfaces as Web Services, which basically
realizes an abstraction from proprietary interfaces of the Core Billing System. More details about the ABS API can
be found in Section 5.
Whereas an initial specification of the ABS API has already been specified in an annex of deliverable D5.1, this
document provides an updated, completed and public version of the ABS API. Any other billing system
implementing this API can thus also be deployed and used in the context of the UrbanWater Platform.
Operator GUI. The Operator GUI consists of a number of HTML Web pages that are embedded into the
UrbanWater Visualization Service (also called UW Dashboard). By means of these Web pages, customer data,
tariffs, products, and subscriptions can be managed and statistical reports can be shown. In turn, the Web pages
make extensive use of the various exposed interfaces of the ABS Gateway. More details about the Operator GUI
implementation can be found in Section 6.
In advance to the description of the physical ABS deployment, please note the following: While the ABS API and
the Operator GUI are logically different components, they will be run in the same Web Server instance for the
sake of easier deployment and joint maintenance.
Deliverable D5.7 – Automatic and dynamic billing system implementation
18
URBANWATER PUBLIC
Grant Agreement: 318602
3 Core Billing System
In this section, we briefly describe the billing system GOLD CCB, which is employed as the Core Billing System in
the context of the UrbanWater project. A number of product-related documents that go into further details can be
downloaded from the Web pages of the vendor [8]. Note that this section describes a system that is already at the
market and has not been developed as part of the UrbanWater project. Nevertheless, the information provided in
this section is of relevance in order to understand the tasks and structure of a billing system and the necessary
steps to integrate it into the UW Platform.
The description starts with the main features and functional areas of GOLD CCB. Thereafter, its architecture is
outlined and basic aspects of the system’s data model are described. Based on that data model, it is necessary to
specify a so-called product catalogue as part of a configuration package, which is then used to initialize an
instance of GOLD CCB, such that it becomes operational. Subsequent versions of such configuration packages
are then used to update the system at runtime.1
Main Features. GOLD CCB product features fully support all important aspects of a convergent billing system,
some of which are:
• With an origin in the mobile telecom business, GOLD CCB is able to rate, charge and bill all kinds of
events, network-related and others, generated by voice, data, IP but also any other services. It works
independent from the network technology employed for the service delivery.
• GOLD CCB manages a single, unified product catalogue enabling the flexible combination of services,
tariffs, bonuses, and discounts for easy creation of attractive product offers.
• It offers rule-based rating capabilities in order to implement different pricing schemes, ranging from very
simple pay-per-use tariffs to complex combinations of content and traffic fees together with bonus and
discount applications.
• GOLD CCB provides real-time rating and charging for all services and for all subscribers regardless of
their preferred payment method in order to reduce the risk of revenue leakage significantly. Spending
and credit limit control reduces risks of bad debts.
• GOLD CCB offers automatic account operations either time-based or event-triggered by the use of
Reoccurring Operations (ROPs). ROPs are used to perform periodic changes to the account balances
and realize reoccurring bundles and reoccurring charges.
• GOLD CCB can implement any specific business logic and customized life cycles of services, products
and accounts with its extendable Java plug-in framework.
Functional Areas. From a logical point of view, the functionality of GOLD CCB can be divided into the following
main functional areas:
a) the generation and management of products and tariffs,
b) the creation and management of customers and their accounts, and
c) the processing of event data along the lines of the following processes:
o Mediation: The term ‘mediation’ here refers to a process known from telecommunication: It is a
process that converts event data of certain data types to other data types, usually for billing
1 Later on, it will become clear that this feature has to be used for the processing of price updates, which are received from
the Adaptive Pricing System in regular periods and lead to changes of the dynamic tariffs configured in the product
catalogue.
Deliverable D5.7 – Automatic and dynamic billing system implementation
19
URBANWATER PUBLIC
Grant Agreement: 318602
purposes. Mediation converts and filters incoming event data coming into the internal format of
GOLD CCB.
o Guiding: The term ‘Guiding’ refers to the process that identifies the customer account(s) that
is/are to be charged or compensated for usage.
o Rating: The term ‘Rating’ refers to the process of determining the cost of a particular event.
Rating converts event-related data into a monetary value. Rating may be performed in real-time
or in post-event (i.e., batch) mode. Real-time rating is not necessarily performed only for
prepaid accounts, it can also be performed for postpaid accounts. The rating process selects
the tariff that should be used to calculate the charge. Once rating has priced the event data, it is
charged to a customer account. After this, the event data is going to be handled in the billing
process, e.g., to generate bill files.
o Provisioning: The term ‘Provisioning’ refers to the transformation of a request into a series of
commands that have to be executed in a certain order towards one or several other system
components.
o Billing: The term ‘Billing’, strictly speaking, refers to the process of summing up the charges for
usage events, reoccurring charges and one-time charges. Billing also calculates bill-time
bonuses and discounts and applies taxes. All charges are calculated in the account’s billing
currency. Note that we frequently make use of the term billing in a broader sense to refer to the
system’s overall purpose.
o Payments: Payments can be booked to postpaid and convergent accounts having a primary
postpaid balance. When a payment has been made, the account’s balance is updated.
Payments made are displayed on the invoices and statements. Whereas payments are of
course an important functionality in a commercial setting, there will be no real payments in the
context of the UW project based on the invoices issued by the ABS. The invoices are pro-forma
invoices and are only generated for comparison purposes without the intention to receive
money from field test participants.
o Journaling: GOLD CCB supports international requirements for financial reporting by having
the capability to extract financial data into structured General Ledger feed files for further
accounting processing. Journaling, however, will not be considered in the context of the UW
project.
Deliverable D5.7 – Automatic and dynamic billing system implementation
20
URBANWATER PUBLIC
Grant Agreement: 318602
Figure 2: GOLD CCB – High Level View
High Level Architecture. GOLD CCB has a modular architecture, consisting of core modules, interfaces to third-
party systems, and additional optional modules. GOLD CCB has dedicated modules for network-related real-time
processing and for batch-oriented back office processing. The main modules of GOLD CCB are shown in the
functional high level view in Figure 2:
• Network Interface (IF) Module: The Network IF Module is a customizable module which offers
mediation and provisioning functionality. It can interact with network elements that are common in
telecommunication networks (like Home Location Register (HLR), GPRS Gateway Support Node
(GGSN), Short Message Service Center (SMSC) and Media Switching Center (MSC)) as well as with
other charging gateway systems. The module has two main sub-modules: (a) the Post-event Converter
collects files with usage events and converts them to a format accepted by the Real-time Environment,
and (b) the Unified Provisioning Interface receives provisioning requests from the Real-time Environment
and transforms them into sequences of commands prior to sending them to other system components.
• Real-time Environment (RTE): The RTE handles all performance-critical tasks in GOLD CCB. It has
event-related sub-modules for, e.g., unified rating, provisioning, and notification triggers as well as real-
time and post-event mediation and subscriber lifecycle management.
The RTE
o receives events, decodes and normalizes them to an internal XML format,
o performs the real-time and post-event rating of the event data,
o guides usage and other types of events to the appropriate accounts,
o manages the balances for prepaid and convergent accounts, including balance operations due
to reload events and Reoccurring Operations (ROPs),
o performs credit and spending control functions for postpaid, prepaid and convergent accounts
by monitoring their balances and triggering actions when thresholds are hit,
o dispatches XML-based event messages and is able to re-format their contents (Event
Formatter and Dispatcher - EFD),
Subscriber
GOLD CCB
CBF
BAS
RTE
Network IF Module
ACC
Mediation
Service Usage Invoice
Rating
Productand Tariff
Management
Customerand AccountManagement
Guiding
Billing
Journaling
Payments
Provisioning
Deliverable D5.7 – Automatic and dynamic billing system implementation
21
URBANWATER PUBLIC
Grant Agreement: 318602
The RTE has its own InCore® database, an in-memory database for fast access to account and
subscriber data processed in real-time.
• Administration and Configuration Cockpit (ACC): The ACC is a stand-alone Eclipse™-based GUI, in
which operator staff can create and maintain customer, product, tariff and subscription data and other
system configurations. Note that in the context of the UW project there is a need to provide a Web-
based GUI that is embedded into the UrbanWater Visualization Service and that the ACC cannot be re-
used for this purpose.
• Business Administration System (BAS): The BAS implements significant parts of the business logic
associated with customer, account, product, and tariff management. The BAS provides the GOLD CCB
Standard Interface for integration with external business systems like Customer Relationship
Management (CRM), Order Management or Inventory Control, etc. The responsibility of the BAS is to
provide a unified logical view of the data maintained in the two other modules Core Billing Framework
(CBF, see below) and RTE. Towards external systems, the BAS encapsulates the distribution of data
and functionality between CBF and RTE.
The BAS makes use of the JBoss® Enterprise Application Platform and has its own Oracle® database
that masters the data of customers, accounts, products, tariffs, etc.
• Core Billing Framework (CBF): The sub-modules of the CBF are more storage and data processing-
intensive and comprise event import, bill calculation and export processes. Payments, journaling and
third party systems interaction are also supported by the CBF. The CBF offers configurable sub-modules
and interfaces to support the Billing and Financial Management processes of service providers.
Mediation and Network Provisioning are implemented in the Network IF Module and in the RTE. Guiding and
Rating are implemented in the RTE. The CBF takes care of Billing, Payments and Journaling, while the ACC and
the BAS are responsible for Product and Tariff Management as well as Customer and Account Management. In
addition to the functional areas which can be assigned to a particular GOLD CCB module there are universal
functional areas related to the overall system, for example Notification Management.
Data Model. To understand the rest of this document, it is necessary to outline the meaning of data elements like
customer, account, subscription, product, sold product, and product catalogue. Of course, there are many more
aspects beyond the following high level description of the data model elements. However, these are out of scope
of this document.
GOLD CCB uses a data model to configure customers, accounts, products (or: product offers), tariffs and
subscriptions. The number of data elements of a certain kind that can be maintained by the system is virtually
unlimited, but is particularly depending on the available system resources of the operating system, database
management system, and underlying hardware.
A customer is the owner of one or more accounts and can be identified using the customer number and/or the
customer name. A customer can be an end user, e.g. a private or corporate customer, or a business partner like
a service provider. Account data comprises
• data for handling of financial aspects (e.g. currency, payment method, credit limit, tax map), and
• data necessary for service handling (e.g., mobile number, user ID, meter ID).
There can be different account types, depending on the owner of the account (e.g., private customer, corporate
customer, service provider):
• Prepaid
• Postpaid
• Convergent
• Other
Deliverable D5.7 – Automatic and dynamic billing system implementation
22
URBANWATER PUBLIC
Grant Agreement: 318602
All accounts can have unit-based credit and/or technical balances.
Figure 3: GOLD CCB – Subscription Data Model
A subscription in GOLD CCB represents a basic service that can be attached to an account. GOLD CCB
supports telecom and non-telecom services (e.g., GSM telephony, Internet, Pay TV services). A subscription
always needs a parent account. This parent account may have one or multiple subscriptions. Subscriptions are
always the leaf nodes of an account hierarchy (see Figure 3).
A product (one can also speak of a product offer) in GOLD CCB is defined by means of product components,
which are the basic building blocks. There are different types of product components (see Figure 4):
• In a tariff component, usage, crediting, discount tariffs, one-time fees, and reoccurring operations are
defined.
• A service component describes the network provisioning request(s) that must be generated to
activate/deactivate the product for a subscriber in the network.
• A guiding component contains one or more references to guiding rules. Guiding rules define to which
account an event should be charged and under which circumstances.
• A limit component is used to define the handling of spending limits. It is associated with (a) the value of
the spending limit, (b) a counter balance that stores the amount consumed from the spending limit and
(c) the filters which qualify the usage as relevant for the spending limit.
• A group component indicates an ownership of a specific group by an account. This is a component
typically used in telecommunication to define special rating conditions for intra-group calls (call parties
are within the same group), inter-group calls (call parties are in the same group hierarchy but in different
sub-groups), and friend group calls (subscriber A belongs to a group which has the group of subscriber
B in the group friend list).
Deliverable D5.7 – Automatic and dynamic billing system implementation
23
URBANWATER PUBLIC
Grant Agreement: 318602
Figure 4: GOLD CCB – Product Data Model
Product definitions are bundled to a common product catalogue. A product catalogue is a set of product offers
that can be ‘sold’ to customers (more precisely, to customers’ accounts and subscriptions). Note that a
differentiation has to be made between products and sold products. A sold product is the result of associating a
product with a particular account or subscription (see Figure 5). The customer who owns a subscription to which
a product has been sold is called subscriber.
Figure 5: GOLD CCB – Products and Sold Products
Configuration. The basic idea is to put all information necessary to run an instance of GOLD CCB into a single
configuration package. Basically, a configuration package centralizes (versions of) the specified system settings
and product catalogue in one file. The distribution of a configuration package to the GOLD CCB modules ensures
that these modules work with synchronized and consistent settings. A configuration package consists of a set of
configuration elements, the latter of which are the product catalogue and different module-specific settings, e.g.,
for mediation.
Deliverable D5.7 – Automatic and dynamic billing system implementation
24
URBANWATER PUBLIC
Grant Agreement: 318602
Figure 6: GOLD CCB – Configuration Deployment
A configuration package becomes effective when it is deployed to a Reference Database and the RTE (see
Figure 6). The BAS and CBF have access to the Reference Database in order to retrieve their relevant
configuration data.
Whereas the information provided in this document is public, please note that the product catalogue developed in
the context of the UrbanWater project has to remain confidential due to IPR restrictions. Section 8, which
describes a number of tariffs for water consumption, will therefore not contain the detailed description of the
product catalogue in the final, public version of this deliverable.
Deliverable D5.7 – Automatic and dynamic billing system implementation
25
URBANWATER PUBLIC
Grant Agreement: 318602
4 ABS Gateway – Adapters and Converters
Figure 7 shows an overview of the main blocks of the ABS Gateway, the connections between the ABS Gateway
and the Core Billing System, as well as the connections of the ABS Gateway in the overall context of the UW
Platform. In this section, we focus on the four Adapters and Converters of the ABS Gateway marked green in
Figure 7:
• Meter Data Converter,
• Queue Administration Adapter,
• Price Update Converter, and
• ABS Notification Server.
Note that the additional Web Services, which are also part of the ABS Gateway, are described separately in
Section 5.
Figure 7: ABS Gateway Overview
Implementation. The four main Adapters and Converters are bundled in a standalone program implemented in
the Java programming language. This program runs constantly 24hr/7 days to process incoming messages from
the UW Core Platform and notifications generated by the Core Billing System.
The UW Core Platform does not prohibit that a service is connecting and sending messages to its message
queue as a single instance or as multiple instances. Whereas this is generally an appropriate mechanism, in the
case of the ABS only one single instance per UW Platform installation is feasible. Therefore, the ABS has to take
care of this on its own, such that the implementation ensures that the program runs as a single instance only and
to serve one queue at a time only. To support a more robust approach also at the side of the UW Core Platform,
an extension of the UW service description specification could be made, in which it would need to be specified
whether multiple instances of a service are allowed or not.
Deliverable D5.7 – Automatic and dynamic billing system implementation
26
URBANWATER PUBLIC
Grant Agreement: 318602
Authorisation at the UW Core Platform. The ABS (more precisely: the ABS Gateway) must first actively
connect to the UW Core Platform to become part of the message distribution mechanism. This connection must
be authorised using the internal message queue authorisation system based on username and password
together with some additional queue parameters. The ABS Gateway stores the necessary authorisation data in a
dedicated configuration file to be easily adaptable without the need to change the programming code.
4.1 Connection to the UW Core Platform
The communication technology is driven by the decision to deploy a message queue system based on the OASIS
standard called Advanced Message Queuing Protocol (AMQP) [7]. This message queue system allows a loose
coupling of the services developed by the different project partners. If a service is down for whatever reason, the
UW Core Platform implementing the message queue system can take care that no messages are lost by
buffering messages that cannot directly be sent and thus ensures a reliable delivery of each message on re-
availability of the service.
A message queue system allows partners with different system characteristics to connect with each other.
Whereas in a Web environment only two partners can communicate together based on a one-to-one connection
following the client-server paradigm, a message queue system allows a one-to-many or even a many-to-many
connection following the publish-subscribe messaging pattern.
As stated in deliverable D6.2 [13], message queues are therefore a good choice for distributed systems with
services from different suppliers like in the case of the UW Platform. In many cases, a message contains
information that might be of interest for various other services, e.g., new weather forecast information, or new
meter data. In such cases it is much easier to get all interested parties informed by establishing a publish-
subscribe mechanism, allowing for an indirect link and a rather loose coupling. In contrast, there are cases in
which requests and responses between services should make a tighter coupling with more reliable connection
requirements, as, e.g. in the case of a Web page requesting certain information from a backend component to be
displayed in the Web page.
Use of the terms ‘client’ and ‘server’ in the context of a message queue system: The roles in a message
queue system are not as clear as in a client-server-based Web environment that typically uses requests and
responses. In a message queue system, each communication partner is both client and server once successfully
connected to the message broker of the ‘server’ platform, i.e., the UW Core Platform in the case of the UW
project. The UW Core Platform takes over the role of a central message broker or distributor and could therefore
be called the ‘server’ within this environment. After a successful connection establishment of a new service as a
‘client’ to this server, this new client can also actively send and receive messages at any time and to any
platform’s own service or any other registered partner’s service. Throughout the remainder of this document the
term ‘server’ will therefore also be used to refer to the UW Core Platform as the central message broker and all
other services, including the ABS, are also called ‘clients’.
4.2 Message Format
This section briefly describes the structure of the messages exchanged between services when using the UW
Core Platform. More details about message queues, their format, routing through the UW Core Platform and
security mechanisms can be found in the deliverable D6.4 – UrbanWater Platform Prototype.
Deliverable D5.7 – Automatic and dynamic billing system implementation
27
URBANWATER PUBLIC
Grant Agreement: 318602
4.2.1 Service IDs
The message queue system uses an item-based message subscription model. An item is a string with a dot-
separated notation, where the dots separate different meaning areas of the item, e.g.,
uw.service.abs.monitoring.xml, which refers to the ABS monitoring function – a functionality required to be
offered by each service of the UW Platform. In the context of the UW project, these items are called ‘ServiceIDs’.
Each ServiceID is bound to a particular message format described by means of a machine-readable XML-format.
ServiceIDs are partly defined by the clients, while others are defined by the server platform, e.g., some
ServiceIDs for service monitoring are prescribed.
The ServiceID is used when a client subscribes to messages that will have this item as the topic. The
implementation of the ABS Gateway is supporting the following ServiceIDs:
• uw.service.abs.monitoring.xml: This is for keep-alive-monitoring. Each time a message with such a
topic is received, the ABS Gateway implementation will generate and send a resource report as
response.
• uw.event.metering.newMeterData: The ABS Gateway receives all messages with meter read data
issued with this topic by the water data management system, i.e., the Head-End System.
• uw.event.aps.newPrices: The ABS Gateway receives all incoming messages from the Adaptive Pricing
System (APS) that provide price updates for dynamic tariffs.
• uw.service.notification.notify: The Notification Service module is in charge of managing the use of
external communications (e.g., SMS or emails) from other services. A notification comprises sending a
message in form of an XML structure to the Service Bus. The ABS makes use of the Notification Service
to send notifications to, e.g., customers about reached thresholds or to operator staff in case of alerts
(e.g., when problems occur due to received invalid data).
4.2.2 Publishing the Data Format of Message Payloads
Within the UW Platform, all data is exchanged based on the XML document format and on a common message
structure that defines the syntax of the message header information (see deliverable D6.2 [13]). Each message
generated and distributed within the UW Platform must thus conform to a certain XML schema and must be
associated with a known, unique ServiceID.
However, there is no common, unique definition for the format of the messages’ body, i.e., the message payload.
Note here that the requirements of the services can be very different. But as there must be a way to get to know
the data format of the messages that a service is generating, a data format exchange procedure has to be
established, so that messages can be exchanged without human intervention.
The following Figure 8 illustrates this method. It makes use of the exchange of XML schema files and a central
Service Catalogue managed by the UW Core Platform. XML schema files have the file extension ‘.xsd’. We briefly
outline the procedure in the following but more details can be found in the corresponding UW Wiki pages that are
publicly available at http://dev.urbanwater-ict.eu/wiki/PlatformServices/ManagementServices/ServiceLifecycle-
Management.
Deliverable D5.7 – Automatic and dynamic billing system implementation
28
URBANWATER PUBLIC
Grant Agreement: 318602
Figure 8: Data Format Exchange Procedure
The flow of messages for the data format exchange is as follows (see Figure 8):
1. A reference to the XML schema (i.e., a URL) and the ServiceID are packed together with other service-
specific parameters into a service description file that is created by each service (e.g. for Service A in
Figure 8).
2. The service description file is submitted to the UW Core Platform and stored in a Service Catalogue.
3. The UW Core Platform distributes a message of type ‘uw.event.data.servicedescription’ to all live
services.
4. Those services which are interested in this new service (e.g., service B in Figure 8) request the URL of
the XML schema of the new service from the UW Core Platform.
5. The UW Core Platform provides the URL as a response.
6. Using the obtained URL, interested services (e.g., Service B) download the XML schema. The obtained
XSD file can then be validated and processed (more or less automatically) to adapt to the new or
changed format.
Once the services have agreed to a common format, the data exchange through the UW Core Platform may
commence. In the example above, Service B would now subscribe to the ServiceID at the UW Core Platform to
receive all corresponding messages in the future.
The ABS offers an XML schema for meter data exchange and another XML schema for price updates in the
context of the adaptive pricing mechanism, which will be explained in the following sub-section.
4.2.3 ABS Message Response Format
A response to a received message has to be sent if a requester sends a ‘synchronous message’ via a message
queue, which requires per definition a response of the receiver. As there is no prescribed common format in the
Deliverable D5.7 – Automatic and dynamic billing system implementation
29
URBANWATER PUBLIC
Grant Agreement: 318602
UW Platform for the payload of responses in reply to a synchronous message request, a dedicated response
format for ABS responses has been defined. This payload format is used for responses to incoming messages
about new meter data and price updates.
Figure 9: Generic ABS response format
As shown in Figure 9, the ABS message response contains three fields: a mandatory timestamp, a mandatory
response code, and an optional text field, which can be used for detailed error descriptions. The association of a
response to its corresponding request is ensured by providing the unique ID within the identifier ‘correlationID’
with the response. The ‘correlationID’ is part of the administration data of each message.
The XSD definition of the format and the response codes are provided in the section ‘Response Format’ on the
UW Wiki page for the APS (http://dev.urbanwater-ict.eu/wiki/PlatformServices/CustomersEmpowerment-
Tools/AdaptivePricingSystem).
The following sub-sections discuss the flow of in- and outgoing messages w.r.t. the implemented Adapters and
Converters in more detail.
4.3 Meter Data Converter
The live meter data are supplied by an external service of the meter operator, usually a component called Meter
Data Management (MDM). In the UW project, this is the so-called Head-End System developed in WP 2. The
Head-End System sends validated meter data to the UW Core Platform which stores it in its Cloud Database:
One flow leads to the cloud storage platform which just stores the meter data along with timestamps and the
consumption values (see Figure 10). The other flow leads to the ABS Gateway. The gateway verifies the contents
and checks the plausibility of the supplied data. In case this check fails, the sender (typically the MDM) is
informed by sending a response message as described in Section 4.2.3. Otherwise the gateway converts the
meter data into the format of the ABS and forwards it to the metering interface of the ABS. In this case there will
be no response to the sender.
Figure 10: Meter Data Converter
Deliverable D5.7 – Automatic and dynamic billing system implementation
30
URBANWATER PUBLIC
Grant Agreement: 318602
The ABS performs the pricing of the consumption according to the tariffs of the subscriber. Resulting costs for the
reported consumption are not returned to the cloud database rather entirely stored in the ABS.
Meter Data Format. The implementation of the Meter Data Converter in the ABS Gateway is able to read meter
read in the meter data format that has originally been defined by UW partner Sagemcom. With respect to the
upcoming field tests, the meter data format might be subject to changes due to new requirements for adaptation
to the exiting meter infrastructure of the new partners AQUALIA and OVOD. However, in that case there are only
limited efforts necessary to implement corresponding changes in the Meter Data Converter. In Figure 11 an
example of meter data is shown along with some explanation comments (see also deliverable D3.3, Annex C
[10]).
<?xml version="1.0" encoding="UTF-8"?> <root xmlns="http://www.sagemcom.com/MeterscapeMeterDataExport/0.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sagemcom.com/MeterscapeMeterDataExport/0.1 MeterRead-OS.xsd"> <file-version>0.1</file-version> <generation-date>2012-12-01T01:00:00Z</generation-date> <!-- everytime MDM requests information about meters settings/status --> <!-- information are cached and made available to MDM in a file like this one --> <!-- "repository" element holds a list of "meter" elements --> <!-- "fromDate" attribute is optional, only meters having data changed since this date are reported --> <!-- "toDate" attribute indicates the date at which the data has been reported --> <repository fromDate="2011-12-01T01:00:00Z" toDate="2012-12-02T01:00:00Z"> <!-- "meter" element provides meter's cached/stored information --> <!-- "id" = meter serial number --> <!-- "vendor" = vendor name or identifier --> <!-- "model" = meter commercial name --> <!-- "version" = meter software version --> <meter id="ELS3432443232432" vendor="ELSTER-METERING" model=" H5000" version="2.01"> <!-- "data" elements provide last retrieved values of a meter's attribute --> <!-- this can be used for reporting load profile or log book configuration to the MDM --> <!-- example : class 7's cosem objects capture_objects,capture_period --> <!-- this can also be used to report status --> <!-- example : breaker output_state/control_state/control_mode --> <!-- "obis","attribute","class" identify the requested cosem object attribute --> <!-- "date" is the date at which the data concentrator gets the data from the meter --> <!-- "task" attribute provides the task identifier through which the data was retrieved --> <!-- data is reported in the xml element value as a string of hexadecimal digits --> <data obis="1;2;99;1;0;255" attribute="3" class="7" date="2012-12-02T01:00:00Z" task="201210221452330001">0104020412000809060000010000FF0F02120000020412000109060000600A07FF0F02120000020412000309060100011D00FF0F02120000020412000309060100201D00FF0F02120000 </data> <data obis="1;1;99;1;0;255" attribute="3" class="7" date="2012-12-02T01:00:00Z" task="201210221452330001">0104020412000809060000010000FF0F02120000020412000109060000600A07FF0F02120000020412000309060100011D00FF0F02120000020412000309060100201D00FF0F02120000 </data> </meter> <!-- another meter --> <meter id="LG3432654287633" vendor="LANDIS&GYR"
• For GET operations and DELETE operations, the implementation supports application/x-www-form-
urlencoded parameters.
• For responses, application/json and application/xml are supported, respectively.
The implementation is inspired by the GSMA OneAPI standard used in the telecommunication area [3]. The
OneAPI initiative defines a commonly supported set of lightweight and Web friendly APIs to allow mobile and
other network operators to expose useful network information and capabilities to Web application developers. It
aims at reducing the effort and time needed to create applications and content that is portable across mobile
operators. Nevertheless, this standard is also well applicable for the UrbanWater project.
Deployment. The REST Web Services are deployed on a Web Server using an instance of Apache Tomcat 7.
The implementation of the exposed Web Service interfaces is exported as a WAR file called billing.war and
copied to the Tomcat directory %CATALINA_HOME%\webapps to be executed by the Web Server.
5.1 Data Model
The following sub-sections give an overview of the data types that are used in the exposed interfaces. They are
shown as UML class diagrams for the sake of a better overview of their inter-relationships. The value classes are
the input for creating or updating a data object, e.g., a customer, via a REST Web request. In reply to retrieved
data, an output object will be sent back based on this data structure.
Deliverable D5.7 – Automatic and dynamic billing system implementation
37
URBANWATER PUBLIC
Grant Agreement: 318602
For the creation, update or deletion of a resource, the value objects are combined into data transfer objects that
are transformed to JSON or respectively XML in each answer that is sent back to the request.
5.1.1 Customer Data Management
Figure 18 shows the value classes used for customer management.
At the moment only one AddressInformation and one UserInformation object (for the login information) will be
filled via the Operator GUI per customer. But for future use it is already now possible that a customer has several
addresses, e.g., a home address and an address used for billing. The login information is stored in a
UserInformation object. Also here the data model has already been prepared that one customer can have several
UserInformation objects to have several login accounts per household (CustomerData object), e.g., one account
each for the parents and the children.
A BankAccountInformation object is also intended to be used later and will not be filled via the Operator GUI.
The CustomerTransaction object will be returned in case of a successful registration, update or deletion of a
customer.
Figure 18: Value Classes for Customer Management
5.1.2 Customer Account Management
Figure 19 shows the value classes used for balances in the account management interface.
The BalanceInformation class contains an identifier uniquely identifying the balance (foreignKeyId), the amount
that can be a whole number or decimal, the currency that can be the 3-figure code as per ISO 4217 or a non-
Deliverable D5.7 – Automatic and dynamic billing system implementation
38
URBANWATER PUBLIC
Grant Agreement: 318602
monetary unit description like e.g. ‘cbm’ for cubic metre, an ID of an account the balance belongs to and a
human-readable description of the balance (description). The BalanceTransaction class contains a collection of
BalanceInformation objects and the customerId, the transaction’s reference code, the resourceURL and the
transactionOperationStatus. It will be returned in case of successfully setting or updating of a balance.
Figure 19: Balance Value Classes for Account Management
Figure 20 shows the value classes used for transaction histories in the account management interface. The
HistoryItem class contains information about the customerId, date and time (date), the reference code, the
balance name, the value of the balance before, the value of the balance afterwards, the concrete amount, the
currency, a short description of the history item and the applied productOffer, pricePlan and priceComponent. The
TransactionHistory class contains a collection of HistoryItem objects and the parameters provided to the interface
function call: maxReturnRecords, start date and end date. Please note that the latter ones are the parameters
provided in the request and are not being calculated based on the returned items.
Figure 20: Transaction History Classes for Account Management
5.1.3 Tariff Management
Figure 21 shows the value classes for the tariff management. The format is based on the USDL Pricing Module
[9]. USDL is a platform-neutral language for describing services consolidated from SAP Research projects.
According to the USDL format, a tariff is expressed as a PricePlan. The format used for tariff management in this
interface is a subset of the USDL Pricing Module (thus forming a ‘profile’) with those classes that are essentially
necessary to express the tariffs that are planned to be applicable for water consumption. The USDL Pricing
Module is much richer, as it is meant to be a universal, generic approach to expressing tariffs of any service in the
domain of the “Internet of Services”.
Deliverable D5.7 – Automatic and dynamic billing system implementation
39
URBANWATER PUBLIC
Grant Agreement: 318602
The fees (base fees or charging fees) are described as PriceComponents. The price per unit is defined in a
PriceLevel. The unit is expressed as a PriceMetric. The validity of a PricePlan, PriceComponent or PriceLevel
can be constrained by PriceFences. Within a PriceFence, a certain business entity (represented by a
businessTerm) is compared to a certain value. With the aid of literal attributes different dimensions of the service
consumption process can then be checked.
CustomLiterals are generic custom values. By using quantityLiterals, the quantity aspect and by using
timeLiterals, the temporal aspect of service consumption can be considered.
A name and a description, respectively, can be defined in multiple languages using the description class. It is also
possible to define a tax amount (net or gross).
The USDL class model has been extended to be able to define configurable notification messages that will be
sent in case that, e.g., a defined amount of water has been consumed in the current month. This is done by the
class NotificationConfiguration.
Deliverable D5.7 – Automatic and dynamic billing system implementation
40
URBANWATER PUBLIC
Grant Agreement: 318602
Figure 21: Value Classes for Tariff Management
Deliverable D5.7 – Automatic and dynamic billing system implementation
41
URBANWATER PUBLIC
Grant Agreement: 318602
5.1.4 Product Offer Management
Figure 22 shows the value classes for the ProductOffer management.
The product offer to be created or updated is given as an XML document in the input parameter
productDescription. The format is heavily relying to the USDL standard, in particular the concept of a Service and
ServiceBundle. The product offer contains a list of the associated price plan names, an activationStatus and
name and description in possibly multiple languages.
When requesting a product offer the ProductOffer is returned as an XML document.
The ProductOfferTransaction object will be returned in case of a successful creation or update of a product offer.
Figure 22: Value Classes for Product Offer Management
5.1.5 Subscription Management
Figure 23 shows the value classes for the Subscription management.
The subscription contains the id of the customer, the name of the product offer booked by the customer, the
selected price plan, a list of the preferred notification, which overwrites the default customer’s preferred
notification and the meter id.
When creating a subscription a SubscriptionTransaction request is sent with the customer id, the product name, a
reference code, the subscription id and the transactionOperationStatus.
Figure 23: Value Classes for Subscription Management
The UW Operator GUI shall enable the operator to view and edit customer and account data, designing tariffs
and product offers and booking subscriptions. Only users with operator rights are able to access this GUI
embedded in the UW Visualization Service. For more information about the UW Visualization Service see D6.2 –
Urban Water platform design [13].
Deliverable D5.7 – Automatic and dynamic billing system implementation
42
URBANWATER PUBLIC
Grant Agreement: 318602
5.2 Interface Operations
In the following, we describe the functionality that is offered through the exposed Web Service interfaces and can
be used by other elements of the UrbanWater Platform, in particular the Operator GUI and the COP.
5.2.1.1 Customer Management IF
The implemented Customer Management interface is offered to support lifecycle management operations
concerning customers, i.e., operations for registration, update, de-registration, and getting customer data. The
operations provide functionality only for the utility operator staff to manage end customers and their subscriptions.
Note that the operations offered by the Customer Management interface cannot be called by the COP! For the
COP, the Customer Empowerment IF is offered (see Section 5.2.1.4)
In this interface, the concepts and specifications of the ‘Customer Profile’ defined by the GSMA OneAPI standard
have been considered as far as possible [4]. We think that this standard is also well applicable for this part of the
ABS, as it comprises a set of REST APIs for Customer and Account Management.
The Customer Management interface is divided into three parts:
• The Customer Data Management interface is offered to support lifecycle management operations concerning customers, i.e., operations for registration, update, de-registration, and getting customer data.
• The Customer Account Management interface is offered to support operations concerning the retrieval of account balances and transaction histories. A customer account can be associated with a number of product offers (also called subscriptions) and monetary or non-monetary balances. Implicitly, when a product is sold to a customer, one or more balances are bound to a customer’s account.
• The Subscription Management interface is offered to ‘sell’ product offers to customers and activate metering services.
The Customer Data Management part offers the following operations (see Section 11.2.1 for the technical
specification):
• Register a Customer • Update a Customer Registration • Get Data of all Customers • Get Customer Data • De-register a Customer
The Customer Account Management part offers the following operations (see Section 11.2.2 for the technical
specification):
• Set a Balance • Update a Balance • Get Balances • Get a Balance • Get Transaction History
The Subscription Management part offers the following operations (see Section 11.2.3 for the technical
specification):
Deliverable D5.7 – Automatic and dynamic billing system implementation
43
URBANWATER PUBLIC
Grant Agreement: 318602
• Sell a Product Offer. This is to add a new subscription to the ABS; it is however not yet possible to charge for the subscription, as some necessary parameters might not yet be available (e.g. the meter ID).
• Activate a Subscription. This operation is used to really activate a subscription, by supplying all necessary product parameter values, such that rating, charging and billing can afterwards be performed for this subscription.
• Get Subscription Details. This operation is used to obtain information about a specific subscription. • Get Tariff Details for a Subscription. This is a helper operation to extract dedicated information from a
subscription. • Get the Tariff Name of a Subscription. This is another helper operation to extract dedicated information
from a subscription. • Deactivate a Subscription. This operation is to finalize a running subscription.
5.2.1.2 Tariff Management IF
The basic task of this implemented interface is to provide operations to import tariffs and product offers into the
ABS. Through the Tariff Management IF, the ABS Gateway will receive tariff and product offer configurations from
the Operator GUI and initiate a re-configuration of the ABS’s internal repository of tariffs and product offers.
Basically, a tariff specifies one-time fees, recurring fees and usage fees; the specified fees may include or
exclude VAT, and each tariff configuration has a validity period.
In the context of the UrbanWater project, we allow for ‘dynamic tariffs’, i.e., tariffs for which the usage fee will
frequently be changed at runtime. We can offer a dynamic tariff for water consumption that takes into account that
there is information available through smart water meters about the water consumption with a resolution of an
hourly consumption. Correspondingly, we can offer a tariff that can change its usage fees for water consumption
(at most) once per hour. Daily newly determined prices are sent from the APS to the ABS a few hours in advance,
e.g., at 16:00h on the preceding day. Note that also the customers and in certain cases also home devices (i.e.,
smart meter gateways) have to be informed about price updates.
The approach is that the Operator GUI allows putting together a formal tariff description comprising the fees and
rules in a platform-independent manner as an XML document. As mentioned before we used significant parts of
the USDL Payment Module in our implementation. A REST Web Service operation accepts such tariff description
from the Operator GUI. The following operations are offered:
• add a new tariff to the ABS, • update an existing tariff in the ABS, • get tariff information from the ABS, • deactivate an existing tariff in the ABS.
The technical specification of these operations can be found in Section 11.3.
5.2.1.3 Product Offer Management IF
Similar to tariff configurations, product offers can be specified in the Operator GUI. Basically, a product offer is
built by specifying a name and associating one or more tariffs to it. Additionally, some more parameters need to
be specified later, when a product offer is ‘sold’ to a customer, resulting in a ‘subscription’.
Once the description of a product offer is complete, a REST Web service request will be sent from the Operator
GUI to the Automatic Billing System, the latter of which will offer the following operations:
• add a new product offer to the ABS, • update an existing product offer in the ABS, • get product offer information from the ABS, • deactivate an existing product offer in the ABS.
The technical specification of these operations can be found in Section 11.4.
Deliverable D5.7 – Automatic and dynamic billing system implementation
44
URBANWATER PUBLIC
Grant Agreement: 318602
5.2.1.4 Customer Empowerment IF
The Customer Empowerment interface offers a range of operations that can be called by REST Web Service
requests from the COP. We distinguish between the following two interface parts:
• The implemented Account part of the Customer Empowerment interface is offered to support customer-initiated operations concerning the retrieval of account balances and transaction histories. These operations are only requesting available information stored in the ABS, they don’t change any data.
• The Notification part of the Customer Empowerment interface allows customers to configure notification messages for, e.g., retrieving consumption and tariff update messages. Changes to notification configurations are also possible. Notifications can be sent out as emails, SMSs and/or as messages in the COP – this can also be configured by the customers themselves. Note: At the time of writing this document, the implementation of this part of the Customer Empowerment interface has not been performed, as it has to be clarified whether this functionality is really required for the field tests or not. Technically, the Core Billing System already supports user-specific notifications; however, further implementation in the ABS Gateway and the COP will be necessary, but are subject of prioritisation w.r.t. other open items to address.
The Account part supports the following operations (see Section 11.5.1 for the technical specification):
• get customer data – to obtain general customer data like address, current subscriptions and applicable tariffs,
• get all balances associated with the customer’s account – note that a customer can have multiple balances, e.g. a balance for the water metering and for the related costs,
• get a certain balance associated with the customer’s account – an additional balance-related operation necessary for certain views in the Online Platform,
• get a transaction history – to obtain a list of debits and credits on the customer’s account for a certain timing period,
• get a bill preview – to get a view of the next invoice based on the customer’s current account status.
The Notification part offers the following operations (see Section 11.5.2 for the technical specification):
• add a threshold notification configuration – the effect is that a threshold notification is generated when reaching the configured limit of water consumption or costs in a specified timing period,
• add a price update notification configuration – the effect is that a price update notification is generated and sent out via the configured bearer (email, SMS, GUI) each time an update of the applicable dynamic tariff occurs,
• get all threshold notification configurations specified for a customer, • get a certain threshold notification configuration specified for a customer, • get all price update notification configurations specified for a customer, • get a certain price update notification configuration specified for a customer, • get all notifications dedicated for a customer generated during a certain timing period – this operation is
called to display and let the customer review notifications in the Online Platform GUI, • get the last x notifications dedicated for the customer – this is also to display and let the customer review
notifications in the Online Platform GUI, but limited to a certain maximum number of notifications, • update an existing threshold configuration, • update an existing price update configuration, • remove an existing threshold notification configuration, • remove an existing price update notification configuration.
5.2.1.5 Billing and Reporting IF
Some operations for billing and reporting are provided by the ABS for backend systems like an operator’s Customer Information System (CIS) or CRM System for invoicing and reporting purposes. In UrbanWater, this is
Deliverable D5.7 – Automatic and dynamic billing system implementation
45
URBANWATER PUBLIC
Grant Agreement: 318602
an optional interface, meaning that an actual integration with a backend system will only be realized as part of the project when upcoming requirements make this inevitable. At the time of writing this document, there has not been any requirement of this kind yet.
The Billing and Reporting part offers the following operations (see Section 11.6 for the technical specification):
• get billing data – this operation returns metering and billing data for invoicing purposes, • get metering report – this operation returns a list of aggregated meter data for one or more water meters
under consideration.
Deliverable D5.7 – Automatic and dynamic billing system implementation
46
URBANWATER PUBLIC
Grant Agreement: 318602
6 Operator GUI
The UW Operator GUI enables operator staff to view and edit customer and account data, design tariffs and
product offers and generate subscriptions. Only users with operator staff access rights are able to use this GUI,
which is embedded into the UW Visualization Service. For more information about the UW Visualization Service
see deliverable D6.2 – Urban Water platform design [13].
6.1 Integration into the UW Visualization Service
The Operator GUI is hosted by means of HTML pages (and additional files) on a server at Orga Systems’
premises and loaded via AJAX 3 into the body of the UW Visualization Service (http://dev.urbanwater-
ict.eu:8080/VisualizationService/) when clicking in the vertical menu on ‘Customers' Empowerment Tools’ and
then on ‘Automatic Billing System’. While opening the service, the UW Visualization Service loads the required
JavaScript files (*js) and style files (*css) which are referenced in the header of the Operator GUI’s HTML pages.
6.2 Communication with the Gateway
The Operator GUI communicates via REST Web Service requests using jQuery4, AJAX and the ABS Gateway
Web Service interfaces presented in Section 5.2 to access, create or manipulate the data stored in the backend.
The jQuery.ajax() function is used to make the HTTP request calls from the Operator GUI to the ABS Gateway.
The type of request is specified in the AJAX object property called ‘type’: data are received via an HTTP GET,
created via HTTP POST, updated via HTTP PUT and deleted via an HTTP DELETE request. For an HTTP POST
and PUT request, the data to be sent are specified in the body of the request.
The typical JavaScript code for an AJAX request looks as follows: var request = jQuery.ajax({ type : "GET|POST|DELETE|PUT", async : false, dataType : 'json',
crossDomain : true, url : URL,
data : data });
request.done(function(result) { callback(result);
}); request.fail(function(jqXHR, textStatus) {
jAlert(error_msg); }
3 AJAX is short for asynchronous JavaScript + XML. With AJAX, Web applications can exchange data with a server
asynchronously in the background without interfering with the display and behavior of the Web page, see
http://en.wikipedia.org/wiki/Ajax_(programming). 4 jQuery is a cross-platform JavaScript library designed to simplify the client-side scripting of HTML, see
http://en.wikipedia.org/wiki/JQuery.
Deliverable D5.7 – Automatic and dynamic billing system implementation
47
URBANWATER PUBLIC
Grant Agreement: 318602
6.3 CORS
An Apache Tomcat Web Server version 7.0.50 is used to deploy the Operator GUI and the ABS Gateway at
ORGA’s premises, which leads to a distributed deployment of the Web page for the UW Visualisation Service
across different domains. However, due to security restrictions, Web Browsers don't allow cross domain requests,
which are necessary to get a complete Web page displayed, i.e., the outer frame with the UW Visualisation
Service’s main menu and the inner body with, e.g., the Operator GUI. To overhaul this drawback, a Cross-Origin
Resource Sharing (CORS) mechanism must be enabled on the Web Server that is running at ORGA. For the
Apache Tomcat Web Server, the following CORS configuration is therefore placed in its
<es>Gestión de estado de cuentas</es> <pt>Gestão de status da conta</pt>
<cz> řízení Stav ú čtu</cz> </translation>
... </translations>
Deliverable D5.7 – Automatic and dynamic billing system implementation
49
URBANWATER PUBLIC
Grant Agreement: 318602
If the regarding HTML page contains an element which matches the translation id, e.g. <h3 class="balanceTitle">Balance Management</h3>
the element text is translated into the given language.
The HTML content can also be created "on the fly" when, e.g., content is created dynamically. For this, it is
helpful to make use of the notation for up to five placeholders (in curly brackets) in the text to be translated, e.g.:
<translation id="transactionsCurrentMonth"> <en>Current month (from {0} to {1})</en> <de>Aktueller Monat (von {0} bis {1})</de> <es>Mes en curso (de {0} a {1})</es>
<pt>Mês atual (de {0} a {1})</pt> <cz>Aktuální m ěsíc (od {0} do {1})</cz> </translation>
6.6 GUI Design and Screenshots
Prior to implementing the HTML pages for the Operator GUI they had been designed using the Balsamiq Mockup
tool6. A PDF document with a number of mockups is available at http://urbanwater-ict.eu/wp-content/uploads/-
2014/12/GUI_Mockup_UrbanWater_Operator_v1.0.pdf, while the following Screenshots shall give a rough
overview of the implemented Operator GUI.
6.6.1 Customer Data Management
6.6.1.1 Register a Customer
A customer can be registered in the ABS on this page (see Figure 24). Except of the company and the additional
address information (address2) all fields are mandatory. The email is additionally checked for validity and the
telephone number must be in the international format, i.e., with a preceding country code according to the ITU-T
recommendation E.164 [6].
The number of persons in the household might influence the price for the water consumption (depending on the
tariff). The selected preferred notification can be overwritten by the subscription settings.
6 Available at: https://balsamiq.com/
Deliverable D5.7 – Automatic and dynamic billing system implementation
50
URBANWATER PUBLIC
Grant Agreement: 318602
Figure 24: Screenshot 'Register Customer'
6.6.1.2 Edit a Customer
An already registered customer can be searched (see Figure 25), viewed and updated on this page (see Figure
26). The customer to be edited can either be searched by ID or by name. One can search either for active
customers, deactivated customers or for all customers. When a customer is searched by name, a list of
customers is displayed which match the search pattern (here: customers which name starts with a ‘w’).
After a customer has been selected, the corresponding data can be updated, e.g., the customer can be
deactivated.
Deliverable D5.7 – Automatic and dynamic billing system implementation
customerId String customerId is the URL-escaped customer ID. It must exist in the
ABS.
Mandatory
subscriptionId String The URL-escaped subscriptionId of the previously sold or activated
product offer. It must exist for the customer specified by
customerId.
Mandatory
transaction-
OperationStatus
Enum This indicates the desired resource state, in this case
‘Deactivated’. See above for further explanation.
Mandatory
referenceCode String The referenceCode must be unique per request. It is the reference
for reconciliation purposes.
Mandatory
Output: In case of success HTTP code ‘200’ and a JSON or XML response object with
transactionOperationStatus=”Deactivated”, customerId, subscriptionId, productName, referenceCode and
resourceURL is returned.
In case of a failure, a response object with transactionOperationStatus either set to “Denied” or “Refused” and an
exception with an appropriate error description is returned. An HTTP error code according to Table 9 is sent back.
11.3 Tariff Configuration IF
The Tariff Configuration interface is offered by the ABS to manage tariffs in the ABS. This interface makes use of
a parameter called transactionOperationStatus with pre-defined states as listed in Table 13.
Table 13: Tariff Configuration: Transaction Operation States
Status Description
Set A tariff has been successfully added.
Updated A successful update for a tariff was made.
Deactivated A tariff has been successfully deactivated.
Denied There was a problem with accessing the resource. The exception in the response will
explain the reason.
11.3.1 Tariff Description Format
The tariff to be created, updated or viewed is specified as an XML document and is based on the USDL Pricing
Module (see Section 5.1.3).
According to the USDL format a tariff can be equated to a PricePlan. The fees (base fee, usage fee, etc.) are
described as PriceComponents. The price per unit is defined in a PriceLevel, e.g., a base fee can be expressed
Deliverable D5.7 – Automatic and dynamic billing system implementation
83
URBANWATER PUBLIC
Grant Agreement: 318602
with the priceMetric “MONTH” and the absoluteAmount=4.0, a charging fee with the priceMetric “cbm” and the
absoluteAmount=”2.0”.
The validity of a PricePlan, PriceComponent or PriceLevel can be constricted by PriceFences. All valid
components within a price plan are added to get the total price.
Here is an example of a pricePlan description for a simple tariff with a base fee and usage fee:
<pricePlan> <currency>EUR</currency>
<descriptions> <language>en</language> <type>FREE_TEXT_LONG</type> <value>Base fee 4.00 EUR per month, 2.00 EU R per cbm.</value> </descriptions> <effectiveFrom>2014-01-01T00:00:00+01:00</effec tiveFrom> <effectiveTo></effectiveTo> <names>