intelligent urban water management...

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


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


3

URBANWATER PUBLIC


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.


4

URBANWATER PUBLIC


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


5

URBANWATER PUBLIC


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


6

URBANWATER PUBLIC


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


7

URBANWATER PUBLIC


Table of Contents

History of Changes .................................................................................................................................................. 2

Abstract ................................................................................................................................................................... 3

List of Acronyms ...................................................................................................................................................... 4

List of Figures ........................................................................................................................................................ 10

List of Tables ......................................................................................................................................................... 11

1 Introduction ................................................................................................................................................... 12

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.2.3 ABS Message Response Format..................................................................................................... 28

4.3 Meter Data Converter .............................................................................................................................. 29

4.4 Queue Administration Adapter ................................................................................................................ 31

4.5 Price Update Converter ........................................................................................................................... 31

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

5.1.2 Customer Account Management ..................................................................................................... 37

5.1.3 Tariff Management ........................................................................................................................... 38

5.1.4 Product Offer Management ............................................................................................................. 41

5.1.5 Subscription Management ............................................................................................................... 41

5.2 Interface Operations ................................................................................................................................ 42

5.2.1.1 Customer Management IF............................................................................................................................................ 42 5.2.1.2 Tariff Management IF ................................................................................................................................................... 43 5.2.1.3 Product Offer Management IF ...................................................................................................................................... 43 5.2.1.4 Customer Empowerment IF ......................................................................................................................................... 44 5.2.1.5 Billing and Reporting IF ................................................................................................................................................ 44

6 Operator GUI ................................................................................................................................................ 46

6.1 Integration into the UW Visualization Service.......................................................................................... 46

6.2 Communication with the Gateway ........................................................................................................... 46

6.3 CORS ...................................................................................................................................................... 47

6.4 Katniss Premium Admin Template .......................................................................................................... 47

6.5 Special GUI Requirements ...................................................................................................................... 48

6.6 GUI Design and Screenshots .................................................................................................................. 49

6.6.1 Customer Data Management ........................................................................................................... 49

6.6.1.1 Register a Customer .................................................................................................................................................... 49 6.6.1.2 Edit a Customer ............................................................................................................................................................ 50


8

URBANWATER PUBLIC


6.6.2 Customer Account Management ..................................................................................................... 52

6.6.2.1 Balance Management .................................................................................................................................................. 52 6.6.2.2 Transaction History ...................................................................................................................................................... 52

6.6.3 Tariff Management ........................................................................................................................... 54

6.6.3.1 Create a Tariff .............................................................................................................................................................. 54 6.6.3.2 Edit a Tariff ................................................................................................................................................................... 55

6.6.4 Product Offer Management ............................................................................................................. 56

6.6.4.1 Create a Product Offer ................................................................................................................................................. 56 6.6.4.2 Edit a Product Offer ...................................................................................................................................................... 57

6.6.5 Subscription Management ............................................................................................................... 57

7 ABS Deployment .......................................................................................................................................... 59

8 ABS Configuration ........................................................................................................................................ 61

8.1 Example Tariffs ....................................................................................................................................... 61

8.2 Tariff Specification ................................................................................................................................... 62

8.3 Tariff Configuration for GOLD CCB – Confidential – to be removed in public version ............................ 63

9 Conclusions and Outlook .............................................................................................................................. 68

10 References ................................................................................................................................................... 70

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 Customer Account Management............................................................................................... 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 Subscription Management ........................................................................................................ 78

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


9

URBANWATER PUBLIC


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

11.5.2 Customer Empowerment: Notification Configurations .............................................................. 94

11.5.2.1 Set Threshold Notification Configuration ................................................................................................................ 94 11.5.2.2 Set Price Update Notification Configuration ........................................................................................................... 95 11.5.2.3 Get Threshold Notification Configurations ............................................................................................................. 96 11.5.2.4 Get Threshold Notification Configurations by BalanceId........................................................................................ 96 11.5.2.5 Get Threshold Notification Configuration ............................................................................................................... 97 11.5.2.6 Get Price Update Notification Configurations ......................................................................................................... 97 11.5.2.7 Get Price Update Notification Configuration .......................................................................................................... 98 11.5.2.8 Get Notifications ..................................................................................................................................................... 98 11.5.2.9 Get Last X Notifications .......................................................................................................................................... 99 11.5.2.10 Update a Threshold Configuration ......................................................................................................................... 99 11.5.2.11 Update a Price Update Configuration................................................................................................................... 100 11.5.2.12 Remove a Threshold Notification Configuration ................................................................................................... 101 11.5.2.13 Remove a Price Update Notification Configuration .............................................................................................. 101

11.6 Billing and Reporting IF .................................................................................................................... 102

11.6.1 Get Billing Data ....................................................................................................................... 102

11.6.2 Get Metering Report ............................................................................................................... 103

12 Annex II: Requirements Compliance of the ABS Implementation ............................................................... 104

12.1 Automatic Billing Requirements ........................................................................................................ 104

12.1.1 AB-1: Customer account must be available ............................................................................ 104

12.1.2 AB-2: Include dynamic, real-time, and predictive behaviour in the ICT system ...................... 104

12.1.3 AB-3: Provide adaptive pricing and dynamic tariffs ................................................................. 105

12.1.4 AB-4: Support threshold notifications ...................................................................................... 105

12.1.5 AB-5: Provisioning on customer side is not possible automatic at the moment ...................... 106

12.1.6 AB-6: Centralized rating .......................................................................................................... 106

12.1.7 AB-7: Follow cloud standards and protocols ........................................................................... 107

12.2 Backend Integration Requirements .................................................................................................. 107

12.2.1 BI-1: Invoice data must be available for the payment handling ............................................... 107

12.2.2 BI-2: Open ICT System for integration into other software...................................................... 108

12.2.3 BI-3: Interfaces for import from and export to third party products .......................................... 108


10

URBANWATER PUBLIC


List of Figures

Figure 1: ABS High Level Architecture .................................................................................................................. 16

Figure 2: GOLD CCB – High Level View ............................................................................................................... 20

Figure 3: GOLD CCB – Subscription Data Model .................................................................................................. 22

Figure 4: GOLD CCB – Product Data Model ......................................................................................................... 23

Figure 5: GOLD CCB – Products and Sold Products ............................................................................................ 23

Figure 6: GOLD CCB – Configuration Deployment ............................................................................................... 24

Figure 7: ABS Gateway Overview ......................................................................................................................... 25

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 12: Queue Administration Adapter ............................................................................................................. 31

Figure 13: Price Update Converter ........................................................................................................................ 31

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

Figure 24: Screenshot 'Register Customer' ........................................................................................................... 50

Figure 25: Screenshot 'Edit Customer' – Search Customer .................................................................................. 51

Figure 26: Screenshot 'Edit Customer' – Update Customer .................................................................................. 51

Figure 27: Screenshot 'Balance Management' ...................................................................................................... 52

Figure 28: Screenshot 'Transaction History Overview' .......................................................................................... 53

Figure 29: Screenshot 'Transaction History Details' .............................................................................................. 54

Figure 30: Screenshot 'Tariff Creation' .................................................................................................................. 55

Figure 31: Screenshot 'Edit a Tariff'....................................................................................................................... 56

Figure 32: Screenshot 'Create a Product Offer' ..................................................................................................... 57

Figure 33: Screenshot 'Edit a Product Offer' ......................................................................................................... 57

Figure 34: Screenshot 'Subscription Management Overview' ............................................................................... 58

Figure 35: Screenshot 'Subscription Management - Add a Subscription' .............................................................. 58

Figure 36: ABS Deployment for Development and Integration Tests .................................................................... 59


11

URBANWATER PUBLIC


List of Tables

Table 1: GOLD CCB Configuration – Tariff Specification ...................................................................................... 62

Table 2: GOLD CCB Configuration – Specification of the Parameters to be set in Customer Notifications .......... 63

Table 3: GOLD CCB Configuration – Design Sheet for Products .......................................................................... 64

Table 4: GOLD CCB Configuration – Design Sheet for UTF Components ............................................................ 65

Table 5: GOLD CCB Configuration – Design Sheet for CTF Component ............................................................. 65

Table 6: GOLD CCB Configuration – Design Sheet for ROP Components ........................................................... 66

Table 7: GOLD CCB Configuration – Design Sheet for LIM Components ............................................................. 66

Table 8: GOLD CCB Configuration – Design Sheet for UTB Component Elements ............................................. 67

Table 9: HTTP Result Codes ................................................................................................................................. 71

Table 10: Customer Data Management: Transaction Operation States ................................................................ 72

Table 11: Customer Account Management: Transaction Operation States ........................................................... 75

Table 12: Subscription Management: Transaction Operation States .................................................................... 78

Table 13: Tariff Configuration: Transaction Operation States................................................................................ 82

Table 14: Product Offer: Transaction Operation States ......................................................................................... 88

Table 15: Output Get Transaction History ............................................................................................................. 93

Table 16: Customer Empowerment – Notification: Transaction Operation States ................................................. 94


12

URBANWATER PUBLIC


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.


13

URBANWATER PUBLIC


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.


14

URBANWATER PUBLIC


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.


15

URBANWATER PUBLIC


• 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.


16

URBANWATER PUBLIC


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.


17

URBANWATER PUBLIC


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.


18

URBANWATER PUBLIC


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.


19

URBANWATER PUBLIC


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.


20

URBANWATER PUBLIC


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


21

URBANWATER PUBLIC


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


22

URBANWATER PUBLIC


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).


23

URBANWATER PUBLIC


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.


24

URBANWATER PUBLIC


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.


25

URBANWATER PUBLIC


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.


26

URBANWATER PUBLIC


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.


27

URBANWATER PUBLIC


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.


28

URBANWATER PUBLIC


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


29

URBANWATER PUBLIC


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

30

URBANWATER PUBLIC


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>      <repository fromDate="2011-12-01T01:00:00Z" toDate="2012-12-02T01:00:00Z">      <meter id="ELS3432443232432" vendor="ELSTER-METERING" model=" H5000" version="2.01">          <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>  <meter id="LG3432654287633" vendor="LANDIS&GYR"

model="ULTRAHEAT/COLD qp 150 T150 (2WR7)" version="2.01"> <data obis="1;1;99;1;0;255" attribute="3" class="7" date="2012-12-02T01:02:00Z" task="201210221452330001">0104020412000809060000010000FF0F02120000020412000109060000600A07FF0F02120000020412000309060100011D00FF0F02120000020412000309060100201D00FF0F02120000

</data> </meter> </repository> </root>

Figure 11: Example of Meter Data


31

URBANWATER PUBLIC


4.4 Queue Administration Adapter

The Queue Administration Adapter is for handling the internal administrative commands between the UW Core

Platform’s Monitoring Service and the ABS Gateway as a ‘client’ (see Figure 12).

Figure 12: Queue Administration Adapter

The Queue Administration Adapter does not have any connection to other services. This module serves the

following purposes:

• Connection establishment to initiate the connection to the UW Core Platform as the ‘server’ and

ensure that there is only one instance of the ABS Gateway connected at a time.

• Re-connect to re-establish the connection with the ‘server’ after failures.

• Queue access handling: As there is only one TCP/IP connection opened between the ABS Gateway’s

Adapters and Converters and UW Core Platform, read and write access from the different modules of

the ABS Gateway must be coordinated.

• Keep-alive messages are issued by the UW Core Platform towards the ABS in a recurring manner with

a timing period of typically 1 to 5 minutes to monitor the connection. The ABS Gateway responds

immediately by reporting its internal health state including system parameters like CPU load, network

load, and RAM usage. Thus, the UW Core Platform can check if the services (or: ‘clients’) are still

connected and alive and maintain a list of the active services. The server can take actions when a

service is in a critical state, e.g., raising an alarm in case a service is going to run out of resources.

4.5 Price Update Converter

The Price Update Converter provides an interface for the APS to submit price updates for dynamic tariffs (see

Figure 13).

Figure 13: Price Update Converter


32

URBANWATER PUBLIC


The prices for upcoming times arrive as a message in XML-format which has been negotiated between the APS

and the ABS. Price update requests are first converted and then run through a thorough plausibility test, because

price updates are very sensible for the overall ABS system robustness and reliability. Tests are made for

date/time plausibility, range of values for prices, and others. When these tests are successfully passed, a positive

response (response code = 0) is sent back to the APS on the one side, while on the other side the received

pricing data is converted into the internal format of the Core Billing System and forwarded to the Core Billing

System, respectively. This is necessary because the administration interface to submit new prices to the

employed Core Billing System has a proprietary interface based on file exchange.

Figure 14: Price Update Data Format

Message Format for Price Update Requests. The price update message format is defined between the APS

and the ABS. No other component is affected. The XML schema can be found in the UW Wiki at

http://dev.urbanwater-ict.eu/wiki/PlatformServices/CustomersEmpowermentTools/AdaptivePricingSystem. Figure

15 provides an example with an excerpt of a price update message for a tariff named ‘DynamicTariff’, which

defines the price for the hours of 15:00h (included) to 17:00h (excluded) and from 18:00h (included) to 21:00h

(excluded) on June 07, 2014.

33

URBANWATER PUBLIC


<?xml version ="1.0" encoding ="UTF-8" standalone ="yes"?> <PriceUpdate creationDateTime ="2014-06-06T15:46:42.000+02:00" generatedBy ="..." processingComment ="For test purposes only !"> <PricePlan name=”DynamicTariff” > <PriceComponent > <EffectiveFrom >2014-06-07T15:00:00.000+02:00 </ EffectiveFrom > <EffectiveTo >2014-06-07T17:00:00.000+02:00 </ EffectiveTo > <Price >1.23 </ Price > </ PriceComponent > ...  <PriceComponent > <EffectiveFrom >2014-06-07T18:00:00.000+02:00 </ EffectiveFrom > <EffectiveTo >2014-06-07T21:00:00.000+02:00 </ EffectiveTo > <Price >2.34 </ Price > </ PriceComponent > </ PricePlan > </ PriceUpdate>

Figure 15: Example of Price Update

The format makes use of a PricePlan element that contains a number of PriceComponent elements, where each

PriceComponent holds a start DateTime tag <effectiveFrom> and an end DateTime tag <effectiveTo> together

with the applicable price for that period. The semantics are that the time stated in the <effectiveFrom> tag is

included in the period and the time stated in the <effectiveTo> tag is the first instant of time which is excluded

from the period. There are no restrictions on the number of PriceComponents. However, in practical usage, only

prices for the next or second but next day will be provided. If no PriceComponent for a particular time period is

supplied, the price remains unchanged based on the last valid price prior to the missing time period.

4.6 ABS Notification Server

An internal Notification Server is employed to emit messages to customers and operator staff about certain

events. This may be customer-related information about exceeded consumption or spending limits (so-called

threshold notifications) or new prices or other kinds of warnings.

The format of the notification is commonly defined for all services in the UW Platform. It is publicly available via

the UW Wiki pages at http://dev.urbanwater-ict.eu/wiki/PlatformServices/CorePlatformServices/Notification-

Service.

Figure 16: ABS Notification Server


34

URBANWATER PUBLIC


For the ABS, all customer notifications are generated in the Core Billing System, which checks the affected

customers’ balances after rating and charging of newly received meter data. If a condition of an internal rule

about a consumption threshold or a changed price is evaluated to true, the Core Billing System emits a HTTP-

formatted request to the ABS Gateway’s Notification Server. Note that this module is implemented as a Web

Server, but it has no relationship with the server for the Web Services described in Section 5. The HTTP-

formatted request is re-formatted into the common notification format of the UW Platform as described in the UW

Wiki mentioned above. The UW Core Platform forwards the message to the platform’s Notification Service that

takes care about the final delivery to the customers and operator staff.

As there is no delivery confirmation defined for notifications and no information about successful delivery is

reported back to the ABS, no response format has to be considered in this case.


35

URBANWATER PUBLIC


5 ABS Gateway - Exposed Web Service Interfaces

In this section, the exposed Web Service interfaces of the ABS Gateway are presented. They form an abstraction

from a particular billing system by providing essential functionality for tariff configuration, product offer definition,

and customer management functionality.

The individual operations offered through the exposed Web Service interfaces are described in detail in Annex I

in Section 11 of this document. Note that this annex is an updated and extended version of Annex A of

deliverable D5.2 [12]. In D5.2, the data types of some of the operation parameters were not yet specified, but this

is presented now in Section 5.1 of this document. This (a) completes the interface specification and (b) makes the

interface specification available to the public2.

Figure 17: ABS and Gateway - External Web Services Interfaces

The following implemented exposed Web Service interfaces are described in the remainder of this document:

• Customer Management IF

with Customer Data, Customer Account, and Subscription Management (see Section 11.2)

• Tariff Configuration IF (see Section 11.3)

• Product Offer IF (see Section 11.4)

• Customer Empowerment IF (see Section 11.5)

2 Note that the visibility of deliverable D5.2 was restricted to UrbanWater consortium members and the EC, but this

deliverable D5.1 is public, such that these interfaces can be implemented by any other party offering a billing system with

platform-independent external interfaces for tariff configuration, product offer definition, and customer management.


36

URBANWATER PUBLIC


Note that the Customer Management, Tariff Configuration, and Product Offer Interfaces are used by the Operator

GUI which is described in Section 6. The Customer Empowerment Interface is used by the Online Platform

Customer Web Portal (or: Customer Online Portal, COP).

Additionally, a ‘Billing And Reporting IF’ is specified in Section 11.6, however, this interface is considered as

optional and is not implemented in the UW project (see also the corresponding requirements fulfilment

description in Section 12.2.3).

The functionality is provided via Web Service interfaces based on REST Web Services to access, create or

manipulate the data stored in the ABS in a CRUD-fashion (i.e., functions to Create, Read, Update, and Delete).

The following meaning is given to the standard REST HTTP methods:

• GET retrieve information about resources

• POST add a resource or set a specific value

• PUT update a resource

• DELETE remove data

The concrete URI syntax for accessing the services provided by the ABS has the following layout:

http://{domain}/billing/{interface}/{resourcePath}

For example, the URI http://urbanwater-ict.eu/billing/account/000112233/Bal_Main1 allows a GET operation to

retrieve the value of the balance ‘Bal_Main1’ of the customer with the customerId ‘000112233’.

Generally, the input parameters necessary to supply together with the requests can have the following formats:

• For POST operations and PUT operations the implementation supports application/json, application/xml

and/or application/x-www-form-urlencoded parameters.

• 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.


37

URBANWATER PUBLIC


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-


38

URBANWATER PUBLIC


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”.


39

URBANWATER PUBLIC


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.


40

URBANWATER PUBLIC


Figure 21: Value Classes for Tariff Management


41

URBANWATER PUBLIC


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].


42

URBANWATER PUBLIC


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):


43

URBANWATER PUBLIC


• 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.


44

URBANWATER PUBLIC


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


45

URBANWATER PUBLIC


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.


46

URBANWATER PUBLIC


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.


47

URBANWATER PUBLIC


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

$CATALINA_HOME/conf/web.xml file:

<filter-mapping> <filter-name>CorsFilter</filter-name>

<url-pattern>/*</url-pattern> </filter-mapping> <filter>

<filter-name>CorsFilter</filter-name> <filter-class>org.apache.catalina.filters.CorsF ilter</filter-class>

<init-param> <param-name>cors.allowOrigin</param-name>

<param-value>*</param-value> </init-param>

<init-param> <param-name>cors.allowed.methods</param-nam e>

<param-value>GET,POST,HEAD,OPTIONS,PUT</par am-value> </init-param> <init-param> <param-name>cors.allowed.headers</param-nam e> <param-value>Content-Type,X-Requested-With, accept,Origin,Access- Control-Request-Method,Access-Control-R equest-Headers </param-value> </init-param>

<init-param> <param-name>cors.exposed.headers</param-nam e>

<param-value>Access-Control-Allow-Origin,Ac cess-Control-Allow- Credentials

</param-value> </init-param>

</filter>

6.4 Katniss Premium Admin Template

In order to achieve a common look and feel for all Web pages shown within the UW Visualization Service, the

Katniss Premium Admin Template5 is used. This package contains a set of css3, jQuery plugins, and further

custom elements. The Operator GUI uses following jQuery plugin features from Katniss:

5 Available at http://themeforest.net/item/katniss-premium-admin-template/3878281


48

URBANWATER PUBLIC


• jQuery validate plugin • jQuery uniform plugin • jQuery flot bar chart • jQuery alert

In addition, the following jQuery plugins stored on the ORGA server are used and included in the header of the

HTML pages of the Operator GUI:

• jQuery datepicker • jQuery flot order bar chart plugin • jQuery autocomplete function

6.5 Special GUI Requirements

Layout Restrictions. The Operator GUI is designed for a desktop PC. The lowest supported resolution is

1024x768 pixel.

Browser support. All common browsers should be supported. The Operator GUI fulfils this requirement. The

Operator GUI has been successfully tested with Firefox 25, Google Chrome 38, Internet Explorer 11, and Safari

5.1.7.

Multilingual Support. In the UrbanWater consortium a multilingual support of the VisualizationService GUIs has

been agreed. The Operator GUI fulfils this requirement. The HTML pages can be displayed in English, German,

Spanish, Portuguese and Czech. The supported languages and the default language are specified in a

configuration file called config.xml as follows, where the language codes are given in ISO 639-1 (en, de, es, pt,

cz); <configuration> <supportedLanguages>en, de, es, pt, cz</supportedL anguages> <defaultLanguage>cz</defaultLanguage> … </configuration>

The HTML page is displayed in the given default language (e.g., Czech). If the default language is not defined in

the config.xml file, the pages will be displayed in English. The language can be switched by passing the URL

parameter ‘lang’, e.g., http://dev.urbanwater-ict.eu:8080/VisualizationService?lang=es: the page is translated then

into the given language parameter (here: Spanish). The given language parameter must be supported (specified

in supportedLanguages), otherwise the page is displayed in the default language.

The translation is done when the init method of each HTML page is called up. The multilingual texts are included

in an XML file as follows: <translations> <translation id="balanceTitle">

<en>Balance Management</en> <de>Kontostandsverwaltung</de>

<es>Gestión de estado de cuentas</es> <pt>Gestão de status da conta</pt>

<cz> řízení Stav ú čtu</cz> </translation>

... </translations>


49

URBANWATER PUBLIC


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.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/


50

URBANWATER PUBLIC


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.


51

URBANWATER PUBLIC


Figure 25: Screenshot 'Edit Customer' – Search Customer

Figure 26: Screenshot 'Edit Customer' – Update Customer


52

URBANWATER PUBLIC



6.6.2.1 Balance Management

Operator staff can change the account balance of a customer, e.g., to manually adjust the balance in case of

refunds or, in particular for demo purposes, to reset a balance to a certain initial value.

Figure 27: Screenshot 'Balance Management'

6.6.2.2 Transaction History

The transaction history for a selected customer can be displayed for the current period (first of current month until

current date) or a recent month (see Figure 28). For statistical purposes, the history is not only illustrated for the

subscribed tariff, but also for alternative tariffs available for the subscribed product offer. The transaction history is

shown as bar chart.


53

URBANWATER PUBLIC


Figure 28: Screenshot 'Transaction History Overview'

When clicking on the subscription, further history details are shown on another page (see Figure 29). Transaction

history details are displayed in a multi-bar chart for a period that can be selected by the user (for up to the last 12

months). The multi-bar chart shows the water consumption as well as the applicable and potential costs of all

tariffs within the selected product offer. A transaction history table is shown in a pop-up window for each tariff

when clicking on the respective “history” button next to the tariff name in the multi-bar chart’s legend.


54

URBANWATER PUBLIC


Figure 29: Screenshot 'Transaction History Details'

6.6.3 Tariff Management

6.6.3.1 Create a Tariff

To define a new tariff, first some general information, such as a tariff name, a textual description and a validity

period must be specified (see the upper part of Figure 30).

Then, the tariff can be composed based on (a) a one-time fee, (b) a base fee and/or (c) a usage fee. All these

components are optional, but at least one should be selected. Only when a component is selected (i.e., the

corresponding check box is clicked), the appropriate details are enabled to be filled in.

For a base fee, additionally included free units can be defined. This makes only sense, if also a usage fee is

defined where a price for 1 cbm can be configured (that in this case will first be charged when the free units are

consumed).

Concerning usage fees, we distinguish between ‘configurable tariffs’ (i.e., configurable by means of the GUI) and

‘dynamic tariffs’ – only one of these two types of usage fees can be configured. For a configurable tariff, a

consumption limit and a rule can be specified – so far, we allow two types of rules: (a) a discount is granted when

the consumption during a billing period keeps below a certain value, or (b) another price is applied if the

consumption exceeds a certain value.


55

URBANWATER PUBLIC


In case that the dynamic tariff has been selected, rules for verifying the validity of the price changes can be

defined to ensure that, e.g., variable prices remain within lower and upper price limits and have a feasible time

resolution (e.g., that each time period for a variable price is valid for at least one hour).

Figure 30: Screenshot 'Tariff Creation'

6.6.3.2 Edit a Tariff

An existing tariff can be updated on this page, e.g., it can be activated and deactivated by clicking the appropriate

radio button (see Figure 31).


56

URBANWATER PUBLIC


Figure 31: Screenshot 'Edit a Tariff'

6.6.4 Product Offer Management

6.6.4.1 Create a Product Offer

On this Web page, a new product offer can be created and one or more tariffs can be assigned to it (see Figure

32).


57

URBANWATER PUBLIC


Figure 32: Screenshot 'Create a Product Offer'

6.6.4.2 Edit a Product Offer

Once a product offer has been created, the associated tariffs can be updated on another page (see Figure 33).

Figure 33: Screenshot 'Edit a Product Offer'


In the Subscription Management, the already generated subscriptions for a selected customer can be shown (see

Figure 34). New subscriptions can be added and already booked subscriptions can be edited and unsubscribed.


58

URBANWATER PUBLIC


Figure 34: Screenshot 'Subscription Management Overview'

Figure 35 shows an example of a subscription that is being created: A meter id has been entered, the default

preferred notification configuration has been changed to ‘SMS’ and ‘GUI’, and a tariff has been selected. When

the ‘Save’ button is clicked, the subsription will be enabled in the ABS.

Figure 35: Screenshot 'Subscription Management - Add a Subscription'


59

URBANWATER PUBLIC


7 ABS Deployment

Figure 36 shows the (slightly simplified) ABS deployment for the development and integration test phase. This

environment comprises of a virtual machine running with the operating system Linux on ORGA’s own server farm.

It is located in a so-called Demilitarized Zone7 (DMZ) behind a company firewall, but still separated from the

company’s Intranet through a second firewall.

Corresponding firewall rules ensure that only communication between services on UW Core Platform and the

ABS are allowed and that no request is routed from the outside through the DMZ into the Intranet. The DMZ

isolates the deployed virtual machine with the ABS software from two sides. It is not possible to start

communications into the Intranet because all communication traffic into that direction is blocked by the 2nd

firewall shown on the right in Figure 36. Only connections initiated from the Intranet are possible using a secured

and encrypted channel. These are used for maintenance, monitoring and, if necessary, for updates.

Temporarily (and not shown in Figure 36), the Java program for the ABS Gateway Adapters and Converters was

also executed on a Desktop PC in the ORGA Intranet to test the interoperation with the UW Core Platform. And,

of course, early instances of all other components were also run on the computers of the involved development

engineers during development and (unit) testing.

Figure 36: ABS Deployment for Development and Integration Tests

Thus, the complete ABS is bundled in a single Virtual Machine, which could be moved as a whole to a different

server environment if desired. This can, e.g., be at another partner’s premise. However, IPR restrictions and

licenses requirements currently prohibit the transfer of this system to a different place.

At the time of writing, there is only one instance of the UW Core Platform running to connect with. Thus it is not

possible for the Java program with the ABS Gateway Adapters and Converters to attach to another UW Core

Platform instance. In turn, if a second instance of the Java program with the ABS Gateway Adapters and

Converters would connect to the UW Core Platform, these two instances would interfere with each other: Every

7 For an explanation of DMZ, see http://en.wikipedia.org/wiki/DMZ_(computing)


60

URBANWATER PUBLIC


message would then be distributed to both instances, causing interferences in the message processing. The Java

program for the ABS Gateway Adapters and Converters therefore takes care not to be started twice on the same

machine. Nevertheless, this does not prohibit problems if the same program is started on a different machine.

The Operator GUI and the ABS Gateway Web Services are deployed in a single instance of an Apache Tomcat

Web Server. Both components are basically answering requests from the UW Visualisation Service and the COP.

During development and test we frequently switch between an instance of the Core Billing System GOLD CCB

and a mySQL database, as it is sometimes more efficient for early tests of new functions to work with a simple

backend system to test functionality on the gateway layer.

The built-in components of the Core Billing System GOLD CCB run on a JBoss Application Server (AS), make

use of an Oracle Database (DB), and several other processes are employed to monitor the system’s status.

ABS Deployment for the Field Tests. The deployment for the upcoming field tests will look very similar to the

development and test environment described above. The deployment architecture is basically copied onto

different (virtual) machines. The main differences of the deployment for the field tests will be as follows:

• The Web Server is connected to the GOLD CCB only – not using the mySQL database that has been

introduces for intermediate tests.

• The connections to the UW Core Platform are using different IP ports. This allows the test architecture to

remain as is and to run it in parallel, but independent from the field test’s live systems.


61

URBANWATER PUBLIC


8 ABS Configuration

This section describes the structure of a number of tariffs specified and configured for GOLD CCB as the

employed Core Billing System in the context of the UrbanWater project. These tariffs are to be considered as a

‘case study’; of course, many other kinds of tariffs can be configured in the system. The approach here was to

specify and realize typical and feasible, sometimes maybe visionary (and not yet regulatory permitted) water

consumption tariffs as a basis for the upcoming field tests.

Following the decision to enable transparency and enable customers to compare the costs that would arise from

different tariffs, water consumption is rated and charged in real-time for five different example tariffs and five

reference balances that are linked to the tariffs respectively. All charges (called ‘events’) are recorded in parallel

to be able to view and directly compare the consumption and cost history later on. The billing period is one

(calendar) month and therefore the balances (more precisely: the real-time balances in the RTE) will be reset at

the beginning of the first day of each month. Each tariff comprises a base fee and a usage rating. For both,

monetary values are numbers in a configured respective currency – the configuration shown in the following has

EUR as the currency, however, in consideration of the planned field tests in Spain and the Czech Republic, CZK

can also be configured.

• The base fee consists of a monthly fee with the same monetary value as of the price and a free water

volume (credit) to be consumed before rating and charging starts. The monthly fee and the free volume

depend on the number of persons in household, regarded simply as a factor ‘n’ for the time being.

• The usage rating consists of the price expressed as money per cubic metre. The dimension of water

consumption is cubic metre (m³) for all tariffs. All input numbers, real time balances and recorded fields

have the precision of six decimals following the decimal point. Internal calculations are done by ‘double’

precision (by means of C++ compiler).

8.1 Example Tariffs

The five tariffs T1 to T5 configured in this ‘case study’ for the GOLD CCB have the following features:

1. Tariff T1 is a comparatively simple tariff: The base fee is 4.00 EUR per person and the consumption

price is 2.00 EUR per cubic metre, regardless of the time of day. No free volume is granted.

2. Tariff T2 is a ‘penalty’ tariff. The base fee is 4.00 EUR per person with no free volume granted. The price

depends on the previous consumption in the ongoing month. If the consumption so far is less than or

equal to 4.5 cbm per person, then rating and charging is at 2.00 EUR per cbm. If water consumption

becomes higher than 4.5 cbm per person, then the price is at 3.00 EUR per cbm. At the time of tariff

switching, a corresponding customer threshold notification is generated in the Core Billing System and

sent in real-time to the Notification Server in the ABS Gateway for further processing.

3. Tariff T3 is a ‘get free volume for higher base fee’ tariff. With the monthly base fee of 8.00 EUR per

person, a free volume of 4.5 cbm per person is granted. Rating and charging to the price of 2.00 EUR

per cbm will not commence before the free volume is consumed. Remaining free volume is not carried to

the next month. At the time when rating and charging starts, a corresponding customer threshold

notification is generated in the Core Billing System and sent in real-time to the Notification Server in the

ABS Gateway for further processing.

4. Tariff T4 is a ‘reward’ tariff. The base fee is 4.00 EUR per person with no free volume granted. The price

is 2.00 EUR per cubic metre. If at the end of the month the consumption is less than or equal to 4.5 cbm

per person, then a discount of 10% will be applied on the bill.


62

URBANWATER PUBLIC


5. Tariff T5 is a dynamic tariff. No base fee is imposed and no free volume is granted. The usage price may

change with every hour. The pricing scheme for the whole next day is fixed and announced until 16:00h.

8.2 Tariff Specification

The following Table 1 shows a first specification of the usage rating, base fees, and additional conditions for the

five tariffs described above. Note that the prices are to be seen as examples only – in the field tests they will differ

based on the local requirements. The reader should therefore focus here on the different mechanisms employed,

in particular thresholds, notifications, and price updates. The initial prices for T5 are set to 2.00h per hour, but are

of course overwritten soon by the Price Update mechanism of the APS.

The variables used for the timebands have to be further formalized in the configuration of GOLD CCB, but not

shown here for the sake of brevity. It should be clear that ‘allDayAllTime’ refers to all instances of time and that

‘dyn24_01’ to ‘dyn24_24’ refer to the different hours of a day.

Table 1: GOLD CCB Configuration – Tariff Specification

Tariffs 2 and 3 are enabled to trigger customer threshold notifications. The following Table 2 shows the

specification of the parameters to be set in customer notifications.

Tariff Usage rating Conditions

Price[EUR/cbm] Timeband

Fee[EUR]

Credit[cbm]

T1 2.00 allDayAlltime n * 4.00 0

2.00 allDayAlltime if consumption <= n * 4.5 cbm

3.00 allDayAlltime if consumption > n * 4.5 cbm

T3 2.00 allDayAlltime n * 8.00 n * 4.5 Credit used first

T4 2.00 allDayAlltime n * 4.00 010% discount at bill timeif consumption <= n * 4.5 cbm

2.00 dyn24_01

2.00 dyn24_022.00 dyn24_032.00 dyn24_042.00 dyn24_052.00 dyn24_062.00 dyn24_072.00 dyn24_082.00 dyn24_092.00 dyn24_102.00 dyn24_112.00 dyn24_122.00 dyn24_132.00 dyn24_142.00 dyn24_152.00 dyn24_162.00 dyn24_172.00 dyn24_182.00 dyn24_192.00 dyn24_202.00 dyn24_212.00 dyn24_222.00 dyn24_232.00 dyn24_24

Dynamic price.Announced until 4pm the day before

Monthly base

T2 n * 4.00 0

T5 0 0


63

URBANWATER PUBLIC


Table 2: GOLD CCB Configuration – Specification of the Parameters to be set in Customer Notifications

8.3 Tariff Configuration for GOLD CCB – Confidential – to be removed in public version

For the EC and the reviewers: In this sub-section, important parts of the configuration of the commercial billing

system GOLD CCB are revealed. They have to be considered as confidential due to IPR restrictions and will

therefore be removed in the final published version of this deliverable D5.7.

We are also aware that the table format used in this section does not comply with the standard table layout used

in the rest of this document. However, the following tables have been externally generated and were copied as

images into this document. We consider a conversion into the standard table layout as an additional,

unnecessary effort.

In GOLD CCB, the definition of the tariff part of the configuration mainly resides in a file in XML-format called the

‘Product Catalogue’. The hierarchical structure of the Product Catalogue enables us to explain its elements in a

top-down manner (see also the GOLD CCB configuration information in Section 3 ).

Topmost element is the so called ‘Product’. One special type of product, the ‘Network Service Product’, is the

container for the ‘meter id’ and has to be mentioned first. The meter id is the unique identifier of the water

consumption measuring device. By selling this network service product to a certain subscription, a link is

generated between a meter id and an account. The purpose is to guide the meter readings (called ‘tickets’),

containing the consumption value, date and time of reading and the meter id itself, to the linked account for rating

and charging. The (tariff-related) product is a collection of components. The components used in the UW

configuration are ‘Usage Tariffs’ (UTF), ‘Crediting Tariffs’ (CTF), ‘Limits’ (LIM), and ‘Reoccurring Operations’

(ROP). UTFs contain a collection of so-called ‘Usage Rules’ (UR) and are responsible for rating and charging of

the tickets. CTFs contain a collection of so-called ‘Crediting Rules’ (CRR) and are responsible for counting up the

water consumption. LIMs contain a collection of thresholds linked to a certain balance and are responsible for

customer notifications. ROPs contain a collection of ‘Charging Rules’ (CHR), responsible to charge the base fee,

and CRRs, responsible to credit free volume. ROPs are automatically scheduled by an internal time table. They

also have the power to reduce the base fee and the free volume in case of first activation anywhere in the month

by percentage. The billing system is also able to refund remaining base fees in case of deactivation at any time in

the current month. URs consist of a balance, a price, and conditions (e.g., ‘Usage Time Band’, UTB) to decide if

this UR will be applied to a ticket or not. CRRs are mostly like URs with the main difference that the rated

measure is not drawn from a balance (charged) but instead added to the balance (credited).

At the start of this section, the decision to compare five tariffs by means of distinct real-time balances and event

records was mentioned. In addition, the number of persons in a household has to be considered. The Product

Catalogue design solution to these requirements is as follows. On the one hand there is only one main product

comprising all five usage tariffs, the crediting tariff, and all five reoccurring operations. On the other hand we

made multiple copies of this main product and gave them distinct names. The following Table 3 shows the

collection of corresponding product components and the product naming convention.

Type AccountID Timestamp Balance before Balance after

discount {account_id} {bill cutoff}

allowance {account_id} {event/input/start} WaterCount WaterCount

freevolume {account_id} {event/input/start} WaterCount WaterCount

Notifications


64

URBANWATER PUBLIC


Table 3: GOLD CCB Configuration – Design Sheet for Products

The term {n} in the product name expands to the number range from 1 to 8 and corresponds to the number of

persons in a household. The term {x} expands to the number range from 1 to 5 and corresponds to the chosen

tariff. This is the designed naming convention and will lead to 40 distinct products (named ‘P_1T1’ to ‘P_8T5’). As

an example, the product with the name ‘P_5T3’ refers to ‘a 5-person household with chosen tariff number T3’.

Note that limit components for the tariffs T1, T4 and T5 are missing, because only tariffs T2 and T3 comprise

customer notifications. Some more tariffs have to be set in the configuration due to technical requirements, but

these are not necessary here to understand the approach.

The following Table 4 shows the design sheet for the UTF components that have been named as component

classes in the previous Table 3. In Table 4, the different usage rules per tariff are shown with, among others, their

name, affected balance, measure (i.e., a volume like cbm), priority, applicable time band, and the factor (i.e. unit

size) and costs to multiply the units in the incoming ticket with. Details about further elements are omitted for the

sake of brevity.

Product

Name Type Class

Usage Tariff UTF_T1

Usage Tariff UTF_T2

Usage Tariff UTF_T3

Usage Tariff UTF_T4

Usage Tariff UTF_T5

Crediting Tariff CTF_WaterConsumption

Reoccurring ROP_{n}R1





Limit LIM_{n}T2

Limit LIM_{n}T3

P_{n}T{x}

LOGICAL/ProductCatalog/ProductCatalogCore (Products)

Component


65

URBANWATER PUBLIC


Table 4: GOLD CCB Configuration – Design Sheet for UTF Components

The following Table 5 shows the design sheet for the CTF component. This CTF component with its crediting rule

tracks the monthly water consumption.

Table 5: GOLD CCB Configuration – Design Sheet for CTF Component

The following Table 6 shows the design sheet for the ROP components. Tariffs T1 to T3 have a monthly base fee

and the fee depends on the number of people in the household, which is formalized in that table. Details about

further ROP components are omitted for the sake of brevity.

Tariff

Name Name Balance Measure Prio Enable Require Time bandUnit

size

Cost per

unit

UTF_T1 UR_T1 BG_OneMonth_Main1 Volume1 0 UTB_AllDayAnyTime 1.000 2.000000

UR_T2T BG_OneMonth_Allowance_T2 Aux_V2 10 RC_T2_L 1.000 1.000000

UR_T2L BG_OneMonth_Main2 Volume2 10 RC_T2_L 1.000 2.000000

UR_T2D Bal_Main_post Aux_V2 0 RC_T2_H 1.000 0.000000

UR_T2H BG_OneMonth_Main2 Volume2 0 RC_T2_H 1.000 3.000000

UR_T3F BG_OneMonth_Free_Volume 0 1.000 1.000000

UR_T3P BG_OneMonth_Main3 0 1.000 2.000000

UTF_T4 UR_T4 BG_OneMonth_Main4 Volume4 0 UTB_AllDayAnyTime 1.000 2.000000

UR_T5S01 UTB_dyn24_01 1.000 2.000000

UR_T5S02 UTB_dyn24_02 1.000 2.000000

UR_T5S03 UTB_dyn24_03 1.000 2.000000

UR_T5S04 UTB_dyn24_04 1.000 2.000000

UR_T5S05 UTB_dyn24_05 1.000 2.000000

UR_T5S06 UTB_dyn24_06 1.000 2.000000

UR_T5S07 UTB_dyn24_07 1.000 2.000000

UR_T5S08 UTB_dyn24_08 1.000 2.000000

UR_T5S09 UTB_dyn24_09 1.000 2.000000

UR_T5S10 UTB_dyn24_10 1.000 2.000000

UR_T5S11 UTB_dyn24_11 1.000 2.000000

UR_T5S12 UTB_dyn24_12 1.000 2.000000

UR_T5S13 UTB_dyn24_13 1.000 2.000000

UR_T5S14 UTB_dyn24_14 1.000 2.000000

UR_T5S15 UTB_dyn24_15 1.000 2.000000

UR_T5S16 UTB_dyn24_16 1.000 2.000000

UR_T5S17 UTB_dyn24_17 1.000 2.000000

UR_T5S18 UTB_dyn24_18 1.000 2.000000

UR_T5S19 UTB_dyn24_19 1.000 2.000000

UR_T5S20 UTB_dyn24_20 1.000 2.000000

UR_T5S21 UTB_dyn24_21 1.000 2.000000

UR_T5S22 UTB_dyn24_22 1.000 2.000000

UR_T5S23 UTB_dyn24_23 1.000 2.000000

UR_T5S24 UTB_dyn24_24 1.000 2.000000

UTF_T5 BG_OneMonth_Main5 Volume5 0

LOGICAL/ProductCatalog/ProductCatalogCore (Components.Usage Tariffs)

Usage rule(s)

UTF_T2 UTB_AllDayAnyTime

UTF_T3 Volume3 UTB_AllDayAnyTime

Tariff

Name Name Balance MeasureUnit

size

Cost per

unit

CTF_WaterConsumption CRR_WaterConsumption BG_OneMonth_WaterCount Volume 1 1

LOGICAL/ProductCatalog/ProductCatalogCore (Components.Crediting Tariffs)

Crediting rule(s)


66

URBANWATER PUBLIC


Table 6: GOLD CCB Configuration – Design Sheet for ROP Components

The following Table 7 shows the design sheet for the LIM components. The thresholds are linked to the balance

‘WaterCount’ (see CTF component) and are responsible for triggering the customer notifications if the balance is

crossed by an event. Some more elements have to be set in the configuration, but are very technical and are not

necessary here to understand the approach.

Table 7: GOLD CCB Configuration – Design Sheet for LIM Components

The following Table 8 shows the design sheet for UTB component elements. This is the design sheet for the

component element ‘Usage Time Band’ (UTB). The readout time of the measuring device is used to be compared

ROP Frequency

Name Type Name Balance Charge Name Balance Credit

ROP_1R1 Monthly Fixed DM_FOM CHR_1R1 BG_OneMonth_Main1 4.000000

ROP_2R1 CHR_2R1 8.000000

ROP_3R1 CHR_3R1 12.000000

ROP_4R1 CHR_4R1 16.000000

ROP_5R1 CHR_5R1 20.000000

ROP_6R1 CHR_6R1 24.000000

ROP_7R1 CHR_7R1 28.000000

ROP_8R1 CHR_8R1 32.000000

ROP_1R2 Monthly Fixed DM_FOM CHR_1R2 BG_OneMonth_Main2 4.000000 CRR_1R2 BG_OneMonth_Allowance_T2 4.500000

ROP_2R2 CHR_2R2 8.000000 CRR_2R2 9.000000

ROP_3R2 CHR_3R2 12.000000 CRR_3R2 13.500000

ROP_4R2 CHR_4R2 16.000000 CRR_4R2 18.000000

ROP_5R2 CHR_5R2 20.000000 CRR_5R2 22.500000

ROP_6R2 CHR_6R2 24.000000 CRR_6R2 27.000000

ROP_7R2 CHR_7R2 28.000000 CRR_7R2 31.500000

ROP_8R2 CHR_8R2 32.000000 CRR_8R2 36.000000

ROP_1R3 Monthly Fixed DM_FOM CHR_1R3 BG_OneMonth_Main3 8.000000 CRR_1R3 BG_OneMonth_Free_Volume 4.500000

ROP_2R3 CHR_2R3 16.000000 CRR_2R3 9.000000

ROP_3R3 CHR_3R3 24.000000 CRR_3R3 13.500000

ROP_4R3 CHR_4R3 32.000000 CRR_4R3 18.000000

ROP_5R3 CHR_5R3 40.000000 CRR_5R3 22.500000

ROP_6R3 CHR_6R3 48.000000 CRR_6R3 27.000000

ROP_7R3 CHR_7R3 56.000000 CRR_7R3 31.500000

ROP_8R3 CHR_8R3 64.000000 CRR_8R3 36.000000

Offset Charging rule Crediting rule

LOGICAL/ProductCatalog/ProductCatalogCore (Components.Recurring Operations)

LOGICAL/ProductCatalog/ProductCatalogCore (Components.Limits)

LIM Default Thresholds

Name Name Value

LIM_1T2 4.500000

LIM_2T2 9.000000

LIM_3T2 13.500000

LIM_4T2 18.000000

LIM_5T2 22.500000

LIM_6T2 27.000000

LIM_7T2 31.500000

LIM_8T2 36.000000

LIM_1T3 4.500000

LIM_2T3 9.000000

LIM_3T3 13.500000

LIM_4T3 18.000000

LIM_5T3 22.500000

LIM_6T3 27.000000

LIM_7T3 31.500000

LIM_8T3 36.000000

THR_FreeVolume 99.90%

THR_Allowance 99.90%


67

URBANWATER PUBLIC


to the validity periods of the time bands. If the result of the comparison is true, then the related usage rule (see

UTF component) will be considered to be usable. The ‘start’ value of the validity period is included and the ‘end’

value is excluded. Details about further UTB settings are omitted for the sake of brevity.

Table 8: GOLD CCB Configuration – Design Sheet for UTB Component Elements

There are many more technical details to be considered to get the GOLD CCB system into a consistent and

ready-to-deploy state. However, these go beyond the scope of this document and are omitted here.

MON TUE WEN THU FRI SAT SUN start end

UTB_AllDayAnyTime X X X X X X X 00:00 24:00

UTB_dyn24_01 X X X X X X X 00:00 01:00

UTB_dyn24_02 X X X X X X X 01:00 02:00

UTB_dyn24_03 X X X X X X X 02:00 03:00

UTB_dyn24_04 X X X X X X X 03:00 04:00

UTB_dyn24_05 X X X X X X X 04:00 05:00

UTB_dyn24_06 X X X X X X X 05:00 06:00

UTB_dyn24_07 X X X X X X X 06:00 07:00

UTB_dyn24_08 X X X X X X X 07:00 08:00

UTB_dyn24_09 X X X X X X X 08:00 09:00

UTB_dyn24_10 X X X X X X X 09:00 10:00

UTB_dyn24_11 X X X X X X X 10:00 11:00

UTB_dyn24_12 X X X X X X X 11:00 12:00

UTB_dyn24_13 X X X X X X X 12:00 13:00

UTB_dyn24_14 X X X X X X X 13:00 14:00

UTB_dyn24_15 X X X X X X X 14:00 15:00

UTB_dyn24_16 X X X X X X X 15:00 16:00

UTB_dyn24_17 X X X X X X X 16:00 17:00

UTB_dyn24_18 X X X X X X X 17:00 18:00

UTB_dyn24_19 X X X X X X X 18:00 19:00

UTB_dyn24_20 X X X X X X X 19:00 20:00

UTB_dyn24_21 X X X X X X X 20:00 21:00

UTB_dyn24_22 X X X X X X X 21:00 22:00

UTB_dyn24_23 X X X X X X X 22:00 23:00

UTB_dyn24_24 X X X X X X X 23:00 24:00

Weekday Validity periodName

LOGICAL/ProductCatalog/ProductCatalogCore (Component Elements.Time

Bands.Usage Time Bands)


68

URBANWATER PUBLIC


9 Conclusions and Outlook

In this deliverable, the implementation of the ABS has been presented with the approach to re-use an existing

real-time billing system at the billing system’s ‘core’ and a gateway in front of it to act as a mediator between the

UW Core Platform (and its built-in and other services) and the ABS.

The ABS Gateway offers different interfaces, some of which are directly integrated with the UW Core Platform by

means of message queues based on AMQP, while others offer REST Web Services based on standards like the

GSMA OneAPI and USDL. The latter are in particular useful for interaction with graphical user interfaces, be it the

Operator GUI and the UW Visualisation Service for management tasks or the Customer Online Platform for end

customers like households.

Functional tests for each of the ABS components have been performed to ensure their correctness:

• For the Core Billing System, test tickets have been generated and sent with a ‘ticket simulator’ to rate

and charge different to demo accounts and balances and validate the correct charging according to the

specified tariff features, in particular the threshold notifications.

• Concerning the ABS Gateway, integration with the UW Core Platform’s message queue system is

already at an advanced state; the message queues for meter reads, queue management, price updates

and notifications have already been tested. As further format changes are possible, in particular for the

meter data, this is an ongoing task.

• For the Operator GUI, non-automated tests have been undertaken from the user perspective (i.e.,

operator staff). These tests covered the implemented functionalities and ensure that the GUI is working

properly in conjunction with the ABS Gateway and that feedback provided by the GUI matches the

expected behaviour.

Annex II describes how the requirements identified for the ABS in deliverable D5.1 are met by the implementation

of the ABS. For most requirements, a complete fulfilment can be reported. Currently, there are the following

issues that still have to be addressed to complete the implementation of the ABS in the upcoming weeks in early

2015:

• Clarify whether a new meter data format is necessary to be supported in the Meter Data Converter for

the field tests. If necessary, change the converter implementation appropriately.

• Clarify privacy-related issues w.r.t. customer data. If there is no customer-related information allowed to

be stored in the ABS itself apart from the meter ID, the format for threshold and price update

notifications needs to be changed, as the email address and mobile number are not known in the Core

Billing System and need to be added and processed in a different component at the operator’s premises.

• Clarify whether customer-specific notification configurations are required as part of the field tests. In that

case, some more of the specified Web Services of the Customer Empowerment IF and corresponding

HTML pages have to be implemented and integrated into the Customer Online Portal.

• Some functions of the Operator GUI have not been completely unit-tested, in particular the product offer

and subscription functions.

• The layout of the pro-forma invoices has not been defined yet. This is due to the recent addition of

AQUALIA and OVOD to the consortium – the design shall be aligned to the layout that is common to

their customers.

• Whereas most of the unit tests have been performed for the Operator GUI, the ABS Gateway, and the

Core Billing System based on the configured five tariffs, the complete end-to-end process of (1) tariff,

product, and subscription definition in the Operator GUI, (2) meter data generation (be it live or

simulated) and sending, and (3) immediate rating and charging after reception of the meter data at the


69

URBANWATER PUBLIC


ABS has not been tested yet. We consider this to be part of the integration that will be performed during

the next weeks in early 2015.


70

URBANWATER PUBLIC


10 References

[1] 3GPP, “Open Service Access (OSA); Parlay X web services; Part 7: Account management”, Technical

Specification TS 29.199-07, Rel-9, December 2009. Available at: http://www.3gpp.org/DynaReport/29199-

07.htm, last accessed on 2014-12-11.

[2] European Commission, “Water Scarcity and Drought in the European Union”, European Union, 2010.

Available at: http://ec.europa.eu/environment/water/quantity/pdf/brochure.pdf, last accessed on 2014-12-11.

[3] GSMA, “GSMA OneAPI”. Available at: http://www.gsma.com/oneapi, last accessed on 2014-12-10.

[4] GSMA, “Specification of the Customer Profile RESTful NetAPI”, OneAPI (v3), February 2013. Available at:

http://www.gsma.com/oneapi/customer-profile-restful-netapi/, last accessed on 2014-12-11.

[5] GSMA, “Specification of the Payment RESTful NetAPI”, OneAPI (v3), February 2013. Available at:

http://www.gsma.com/oneapi/payment-restful-netapi/, last accessed on 2014-12-11.

[6] ITU-T, Telecommunication Standardization Sector of ITU. "The International Public Telecommunication

Numbering Plan". ITU, November 2010. Available at: http://www.itu.int/ITU-T/recommendations/rec.aspx?-

rec=E.164, last accessed 2014-12-22.

[7] OASIS. “Advanced Message Queuing Protocol (AMQP)”, Version 1.0, OASIS Standard, October 2012.

Available at: http://docs.oasis-open.org/amqp/core/v1.0/amqp-core-complete-v1.0.pdf and via

http://www.amqp.org/, last accessed on 2014-12-11.

[8] Orga Systems GmbH & Co. KG. “GOLD Convergent Charging and Billing”. Available at:

http://www.orga-systems.com/products/gold-convergent-charging-and-billing/, last accessed on 2014-12-10.

[9] Unified Service Description Language (USDL). Available at: http://www.linked-usdl.org and

https://github.com/linked-usdl, last accessed on 2014-12-15.

[10] UrbanWater FP7 Project Consortium, “D3.3 – SQL Azure database”. European Commission, 2014. To be

published.

[11] UrbanWater FP7 Project Consortium, “D5.1 – Customers' empowerment tools system requirements”.

European Commission, 2013. Available at: http://urbanwater-ict.eu/wp-content/uploads/2014/08/-

URBANWATER-D5.1-Customers-empowerment-tools-system-requirements.pdf, last accessed on 2014-12-

22.

[12] UrbanWater FP7 Project Consortium, “D5.2 – Customers’ empowerment tools design”. Consortium

deliverable with restricted access. European Commission, 2013.

[13] UrbanWater FP7 Project Consortium, “D6.2 – UrbanWater platform architecture design”. European

Commission, 2013. Available at: http://urbanwater-ict.eu/wp-content/uploads/2014/08/URBANWATER-D6-2-

UrbanWater-platform-architecture-design.pdf, last accessed on 2014-12-22.

[14] UrbanWater FP7 Project Consortium, “D6.4 – UrbanWater platform prototype”. European Commission, 2014.

To be published.


71

URBANWATER PUBLIC


11 Annex I – Specification of the ABS Exposed Interfaces

Annex I describes in detail the exposed Web service interfaces for the ABS. This is an updated and extended

version of the specification presented in Annex A of deliverable D5.2 [12].

11.1 Status Handling

The REST functions provide status/error handling by using the HTTP-status code. The HTTP codes listed in

Table 9 will be used by the operations specified in the remainder.

Table 9: HTTP Result Codes

Code Short Description Description

200 OK Successful HTTP request.

201 Created The request has been fulfilled, and a new resource has been

created (post request).

400 Bad request The request cannot be fulfilled due to bad syntax. Also used if data to

be created exists already or data to be modified or received does not

exist in the ABS.

401 Unauthorized The request requires user authentication.

403 Forbidden The request was a legal request, but the server is refusing to respond

to it.

404 Not found The requested page could not be found: mistake in the host or path of

the service URI.

405 Method not allowed A request was made of a page using a request method not supported

by that page.

412 Precondition failed The precondition given in the request evaluated to be false by the

server.

500 Internal Server Error The server encountered an unexpected condition which prevented it

from fulfilling the request. Used e.g. if data could not be

created/updated in the ABS.

11.2 Customer Management IF

For customer management, we make use of the concepts and specifications of the GSMA OneAPI standard [3],

which come from the telecommunication area. The OneAPI initiative defines a set of lightweight and Web friendly

APIs to allow network operators to expose useful network information and capabilities to Web application

developers. We think that this standard is also well applicable for the ABS as part of the UrbanWater platform, as

it comprises a set of REST-based APIs for the required interfaces for Customer and Account Management as

well as for rating, charging and billing of meter reads.


72

URBANWATER PUBLIC



The Customer Data Management interface is offered by the ABS to support lifecycle management operations

concerning customers, i.e., operations for registration, update, de-registration, and getting customer data. This

interface makes use of a parameter called transactionOperationStatus with the following pre-defined states.

Table 10: Customer Data Management: Transaction Operation States

Status Description

Registered A successful registration was made.

Deregistered A successful de-registration was made.

Updated A successful update of a registration was made.

Denied There was a problem with accessing the resource. The exception in the response will

explain the reason.

Refused There was a problem with the parameters. The exception in the response will explain the

reason.

The basic layout of the rest calls is as follows: http://{IP_address}:{portNo}/billing/customerData/{ customerId}

The URI part “customerData” identifies the customer data part of the interface. The concrete action to be

performed, e.g., registration of a customer, is recognized by the HTTP operation type and the corresponding URI.

The path parameter “customerId” is missing when the customer data of all customers is requested.

The Customer Management interface uses GET, PUT, POST, and DELETE operations:

• GET operation to retrieve the customer data

• POST operation to register a new customer into the ABS

• PUT operation to update an existing customer

• DELETE operation to delete the registration of a customer

11.2.1.1 Register a Customer

Resource Id: Billing.CustomerData.RegisterCustomer

Description: This operation adds a new customer to the ABS.

Input: String @customerId; String @role; Enum @transactionOperationStatus; String @referenceCode; String

@title; String @firstName; String @lastName; String @company; String @country; String @zipCode; String

@street; String @houseNumber; String @email; String @phoneNumber

Input Parameter Type Description Occurrence

customerId String customerId is the URL-escaped customer ID. This ID must not yet

exist in the ABS.

Mandatory

Role String The role of the new customer. Could be one of:

“Customer” | ”Commercial” | “Industry” | “ServiceProvider”

Mandatory

transaction-

OperationStatus

Enum This indicates the desired resource state, in this case ‘Registered’.

See above for further explanation.

Mandatory


73

URBANWATER PUBLIC


referenceCode String The referenceCode must be unique per request. It is the reference

for reconciliation purposes.

Mandatory

title,

firstName,

...

phoneNumber

Strings Customer Data that is provided with the request. While we require

the parameters to be mandatory, in some cases it is ok to leave a

string empty, e.g., for private customers the parameter “company”

remains empty.

Mandatory

Output: In case of success HTTP code ‘201’ and a JSON or XML response object based on the

“CustomerTransaction” value object (see section 5.1.1) with transactionOperationStatus=”Registered”,

customerId, 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 error description and an HTTP error code according to Table 9 is returned.

11.2.1.2 Update a Customer Registration

Resource Id: Billing.CustomerData.UpdateCustomerRegistration

Description: This operation is used to change the customer data attributes described above in the operation

RegisterCustomer (except the customerId, which is fixed).

Input: String @customerId; String @role; Enum @transactionOperationStatus; String @referenceCode; String

@title; String @firstName; String @lastName; String @company; String @country; String @zipCode; String

@street; String @houseNumber; String @email; String @phoneNumber


customerId String customerId is the URL-escaped customer ID. Mandatory

role String The new role of the customer. Could be one of:

“Customer” |”Commercial” | “Industry” | “ServiceProvider” …

Optional

transaction-

OperationStatus

Enum This indicates the desired resource state, in this case ‘Updated’.


Mandatory



Mandatory

title,

firstName,

...

phoneNumber

Strings (Selected) customer data that is to be updated. Optional


“CustomerTransaction” value object (see section 5.1.1) with transactionOperationStatus=”Updated”, customerId,

referenceCode and resourceURL is returned.


exception with an appropriate error description and an HTTP error code according to Table 9 is returned.

11.2.1.3 Get Data of all Customers

Resource Id: Billing.CustomerData.GetAllCustomersData

Description: This operation retrieves the registration data of a specific group of customers from the ABS. The

input parameter role refers to the customer group under consideration; note that if it is left empty, data of all

customerswill be returned (ok for a demo, but will lead to runtime problems in productive mode).


74

URBANWATER PUBLIC


Input: String @role

Output: In case of success, the list with the registration data of all customers for the specified role (or all if input

parameter role is empty) based on the “CustomerData” value object (see section 5.1.1) comprising the specified

customerId, the role, title, firstName, lastName, company, country, zipCode, street, houseNumber, email and

phoneNumber, otherwise an exception with error description and an HTTP error code according to Table 9.

11.2.1.4 Get Customer Data

Resource Id: Billing.CustomerData.GetCustomerData

Description: This operation retrieves the registration data of the customer with a certain customerId from the

ABS. Same operation as for the customer described in the customer empowerment interface (see 11.5.1.1).

Input: String @customerId

Output: In case of success, the customer registration data of the customer based on the “CustomerData” value

object (see section 5.1.1) with the specified customerId, the role, title, firstName, lastName, company, country,

zipCode, street, houseNumber, email and phoneNumber is returned.

In case of failure an exception with error description and an HTTP error code according to Table 9 is sent back.

11.2.1.5 De-register a Customer

Resource Id: Billing.CustomerData.DeregisterCustomer

Description: This operation marks a customer as deregistered in the ABS.

Input: String @customerId; Enum @transactionOperationStatus; String @referenceCode



transaction-

OperationStatus

Enum This indicates the desired resource state, in this case

‘Deregistered’. See above for further explanation.

Mandatory



Mandatory


“CustomerTransaction” value object (see section 5.1.1) with transactionOperationStatus=”Deregistered”,

customerId, referenceCode and resourceURL is returned.


exception with an appropriate error description and an HTTP error code according to Table 9 is returned.


The Customer Account Management interface is offered by the ABS to support operations concerning the

retrieval of account balances and transaction histories as well as the manipulation of account balances. A

customer account can be associated with a number of activated products (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. This is because selling a product means that a customer subscribes to one or

more services for a certain tariff; and a tariff consists of a number of charging rules that affect one or more

balances.

This interface makes use of a parameter called transactionOperationStatus with the following pre-defined states.


75

URBANWATER PUBLIC


Table 11: Customer Account Management: Transaction Operation States

Status Description

Set A balance has been successfully set.

Updated A successful update of a balance was made.


explain the reason.


reason.

The basic layout of the rest calls is as follows: http://{IP_address}:{portNo}/billing/account/{custo merId}/action

The URI part “account” identifies the account management part of the interface. The concrete action to be

performed, e.g., receiving of a balance, is recognized by the HTTP operation type and the corresponding URI.

The part “action” will be replaced by the concrete action to be performed, e.g., “history” for retrieving the history

transactions of a customer. If a certain balance is received, set or updated the “action” will be replaced by the

balanceId.

The Customer Management interface uses GET, PUT and POST operations:

• GET operation to get all balances or a specific balance of a customer

• POST operation to set a balance of a customer

• PUT operation to update a balance of a customer

11.2.2.1 Set a Balance

Resource Id: Billing.Account.SetBalance

Description: This operation sets a balance to a certain absolute amount. It overwrites the current value of the

balance. This operation is primarily for convenience reasons, as it is very helpful for demo purposes to set a

balance to a well-defined initial value. In a productive environment, only the operation UpdateBalance should be

used.

Input: String @customerId; String @transactionOperationStatus; String @referenceCode; String @balanceId;

Double @amount; String @currency; String @description



transaction-

OperationStatus

Enum This indicates the desired resource state, in this case ‘Set’. See

above for further explanation.

Mandatory



Mandatory

balanceId String A URL-escaped identifier identifying the balance to update. Mandatory

amount Double Balance Information Data that contains the amount and currency to

update together with a description that should appear in a

transaction history statement.

Mandatory

currency String Mandatory

description String Mandatory


76

URBANWATER PUBLIC



“BalanceTransaction” value object (see section 5.1.2) with transactionOperationStatus=”Set”, customerId,

referenceCode and resourceURL including the balance information with the old values of the balance is returned.



11.2.2.2 Update a Balance

Resource Id: Billing.Account.UpdateBalance

Description: This operation is used for adding or removing an amount from or to a balance, thereby changing the

value of a balance. The specified amount will be added or subtracted from the current balance amount.

Input: String @customerId; String @transactionOperationStatus; String @referenceCode; String @balanceId;

Double @amount; String @currency; String @description



transaction-

OperationStatus



Mandatory



Mandatory

balanceId String A URL-escaped identifier identifying the balance to update. Mandatory

amount Double Balance Information Data that contains the amount and currency to

update together with a description that should appear in a

transaction history statement.

Mandatory

currency String Mandatory

description String Mandatory

Output: In case of success HTTP code ‘200’ and a JSON or XML response object with

transactionOperationStatus=”Updatet”, customerId, referenceCode and resourceURL based on the

“BalanceTransaction” value object (see section 5.1.2) is returned. In addition the balance information with the old

values of the balance is returned.


exception with an appropriate error description is returned. An HTTP error code according to Table 9 is sent back.

11.2.2.3 Get Balances

Resource Id: Billing.Account.GetBalances

Description: This operation results in getting all account balances of a customer. Balances might refer to

monetary balances for, e.g., water, electricity, gas, or other collected data like water consumption, other fees or

revenues. The resulting response may therefore contain a list of balances associated with the account. The

different balances of an account can be uniquely distinguished by their IDs. No transactionOperationStatus or

referenceCode is needed, since this operation does not change anything in the ABS.


Output: In case of success, the list of balances based on the “BalanceInformation” value object (see section

5.1.2), each with an ID, a balance value, and the corresponding unit (€, £, cbm, bonus/credit points, etc.),

otherwise an exception with error description and an HTTP error code according to Table 9.


77

URBANWATER PUBLIC


11.2.2.4 Get a Balance

Resource Id: Billing.Account.GetBalance

Description: This operation results in getting one specific balance for a customer. A balance might refer to a

monetary balance for, e.g., water, electricity, gas, or other collected data like water consumption, other fees or

revenues. The resulting response therefore contains a balance related to the account. The different balances of

an account can be uniquely distinguished by their IDs. No transactionOperationStatus or referenceCode is

needed, since this operation does not change anything in the ABS. Same operation as for the customer

described in the customer empowerment interface (see 11.5.1.3).

Input: String @customerId; String @balanceId

Input

Parameter

Type Description Occurrence

customerId String customerId is the URL-escaped customer ID. This ID must not yet

exist in the ABS.

Mandatory

balanceId String A URL-escaped identifier identifying the balance to retrieve. If this ID

is empty, all balances will be returned.

Optional

Output: In case of success, if a balanceId was provided a list of balances based on the “BalanceInformation”

value object (see section 5.1.2) containing one balance object with the considered balanceId, the balance value,

and the corresponding unit (€, £, cbm, bonus/credit points, etc.). If no balanceId was provided, the list contains all

balances related to the account of the customer is returned. In case of failure, the output is an exception with

error description and an HTTP error code according to Table 9.

11.2.2.5 Get Transaction History

Resource Id: Billing.Account.GetHistory

Description: This operation returns the history of transactions performed on the customer’s account. No

transactionOperationStatus or referenceCode is needed, since this operation does not change anything in the

ABS. Though the input parameters maxReturnRecords, startDate, and endDate are optional, at least one of them

should be provided in order to limit the resulting list of transactions to a certain timing period. To further limit the

list of transactions, a list of balance IDs and product IDs can also be provided. Same operation as for the

customer described in the customer empowerment interface (see 11.5.1.4).

Input: String @customerId; Long @maxReturnRecords; String @startDate; String @endDate; String

balanceAndSubscriptionIds



maxReturnRecords Long The maximum number of entries is an optional parameter

restricting the number of data records that should be

returned.

Optional

startDate String The start time for the interval defining the data records that

should be returned. The format is yyyy-mm-ddThh:mm:ss.

Optional

endDate String The end time for the interval defining the data records that


Optional

balanceAnd

SubscriptionIds

String List of IDs referring to the balances and subscriptions to limit

the resulting data to be returned. If this is empty, the

Optional


78

URBANWATER PUBLIC


consumption data and related costs of all transactions in the

specific timing period will be returned.

The list of IDs needs to be provided in a well-defined syntax,

as attribute-value pairs with delimiter ; as follows:

balanceId1:Bal_Main1;balanceId2:Bal_Main2;…;balanceIdN:

Bal_MainN

structuredProd Boolean

This optional parameter indicates if the transaction history

should be ordered and summed up (transaction summary for

product offers).

Optional

formatted Boolean This optional parameter indicates if the amount shall be

rounded and the date string formatted.

Optional

Output: In case of success, a list with transactions performed on the customer’s account in the specified timing

period based on the “TransactionHistory” value object (see section 5.1.2), together with information about the

balance(s) before and after these transactions and the tariff that was used to charge the customer’s transaction.

The elements of the list depend on the parameter values, e.g., if no startDate is specified, but maxReturnRecords

and endDate are specified, the list contains the most recent n (<= maxReturnRecords) transactions of the

account. The semantics of other parameter value combinations are. An overview of the different outputs

depending on the given parameter values can be found in Table 15.

In case of a failure, an exception with error description and an HTTP error code according to Table 9 is returned.


The Subscription Management interface is offered by the ABS to sell product offers to customers and activate

metering services and related value-added services. This interface makes use of a parameter called

transactionOperationStatus with the following pre-defined states.

Table 12: Subscription Management: Transaction Operation States

Status Description

Set A product offer has been successfully sold.

Activated A subscription has been successfully activated.

Deactivated A subscription has been successfully deactivated.


explain the reason.


reason.

11.2.3.1 Sell a Product Offer

Resource Id: Billing.Subscription.AddSubscription

Description: This operation is to sell a product offer to a customer. A successful sale of a product is resulting in a

(not yet activated) subscription and is the step prior to be able to activate the subscription for a customer. The

approach in UrbanWater is to have a configuration tool that allows a utility operator to sell a customer one or

more product offers (e.g., a service bundle consisting of a water metering service and a threshold notification

service) and thus to generate new subscriptions in the ABS.


79

URBANWATER PUBLIC


It is important to mention here that it is possible to generate “virtual” or “simulation” subscriptions here as well.

This allows that at runtime virtual charges will also be calculated for all other tariffs that are offered for the product

offer under consideration. These data can then be used by information services to display and compare actual

and virtual costs based on different applied tariffs.

Input: String @customerId; String @productName; String @transactionOperationStatus; String

@referenceCode; String @productParameters


customerId String customerId is the URL-escaped customer ID. It must exist in the

ABS.

Mandatory

productName String The product offer name. It must exist in the ABS. Mandatory

transaction-

OperationStatus



Mandatory

referenceCode String The referenceCode must be unique per request. It is the

reference for reconciliation purposes.

Mandatory

productParameters String There might be product-specific parameters that need to be set

when a product is sold. For example, “tariff:dynamicTariff_v1.2”

will apply the tariff with identifier “dynamicTariff_v1.2” for the

subscription. Another example is “simulationSubscriptions:yes”,

which will initiate the generation of simulation subscriptions for all

possible alternative tariffs.

These parameters and their values need to be provided as a list

in a well-defined syntax, e.g. as attribute-value pairs with

delimiters : and ; as follows:

parameterName_1_:value_1_;


...

parameterName_N_:value_N_

Optional


transactionOperationStatus=”Set”, customerId, an identifier for the subscription (subscriptionId), productName,

referenceCode and resourceURL is returned.



11.2.3.2 Activate a Subscription

Resource Id: Billing.Subscription.ActivateSubscription

Description: This operation is to activate a subscription for a customer; this is the step prior to be able to actually

run and charge a product usage for a customer. The approach in UrbanWater is to have a configuration tool that

allows an operator to activate a product offer. Again, there might be certain parameters that need to be set when

activating a subscription for a customer, e.g. a meter ID or a mobile phone number (for notifications).

Input: String @customerId; String @subscriptionId; String @transactionOperationStatus; String

@referenceCode; String @subscriptionParameters


80

URBANWATER PUBLIC



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

product. It must exist for the customer specified by

customerId.

Mandatory

transaction-

OperationStatus


‘Activated’. See above for further explanation.

Mandatory



Mandatory

subscriptionParameters String There might be product-specific parameters that need to be

set when a subscription is activated. These parameters and

their values need to be provided as a list in a well-defined

syntax, e.g. as attribute-value pairs with delimiters : and ; as

follows:



...


Optional


transactionOperationStatus=”Activated”, customerId, subscriptionId, productName, referenceCode and

resourceURL is returned.



11.2.3.3 Get a Subscription

Resource Id: Billing.Subscription.GetSubscription

Description: This operation allows retrieving information about a subscription in the ABS. Note that it may be not

yet activated or already activated.

Input: String @customerId; String @subscriptionId



ABS.

Mandatory

subscriptionId String The URL-escaped subscriptionId of the previously sold or activated

product. It must exist for the customer specified by customerId.

Mandatory

Output: The description of the subscription as an XML document. Associated with the subscription is the

previous sold or activated product identified by the given subscriptionId, for the productOffer format description

see 11.4.1. Here a rough overview of the subscription format:

<subscription>

<customerId></customerId>

<productOffer>


81

URBANWATER PUBLIC


… </productOffer >

</subscription>

Tariff information is limited to the currently valid and future pricing information (for obtaining the complete history

of prices, the operation GetTariff has to be used). In the case of failure, an exception with an error description and

an HTTP error code according to Table 9 is returned.

11.2.3.4 Get the Tariff Name of a Subscription

Resource Id: Billing.Subscription.GetTariffName

Description: This operation allows retrieving information about the tariff associated with a subscription of a

specific customer with a certain meter (identified by a meter ID).

Input: String @customerId; String @meterId



ABS.

Mandatory

meterId String The URL-escaped meterId of the water meter installed at the

customer. It must exist for the customer specified by customerId.

Mandatory

Output: In case of success, the unique name and ID of the relevant tariff is returned, otherwise an exception with

error description and an HTTP error code according to Table 9.

11.2.3.5 Get Tariff Details for a Subscription

Resource Id: Billing.Subscription.GetTariff

Description: This operation allows retrieving information about the tariff associated with a product sold to a

specific customer with a certain meter (identified by a meter ID). The standard format for the tariff used is USDL

as far as possible.

Input: String @customerId; String @meterId; Sting @startDate; String@endDate



ABS.

Mandatory

meterId String The URL-escaped meterId of the water meter installed at the

customer. It must exist for the customer specified by customerId.

Mandatory

startDate String The start date and time for the validity period of the tariff under

consideration. The format is yyyy-mm-ddThh:mm:ss.

Optional

endDate String The end date and time for the validity period of the tariff under


Optional

Output: In case the meterId is well-known for the customer specified by customerId in the ABS, the operation

returns the desired USDL-based tariff description. If the start- and endDate are specified, the information

contained in the USDL document is limited to the tariff elements that are valid in that timing period. Note that in

case of dynamic prices, there can be many price changes and therefore a lot of information. In case of failure, an



82

URBANWATER PUBLIC


11.2.3.6 Deactivate a Subscription

Resource Id: Billing.Subscription.DeactivateSubscription

Description: This operation is used to terminate the subscription of a sold product in the ABS at a desired point

of time. This means that after that point of time the associated service will no longer work for the customer. It also

implies that the customer will no longer be charged according to the associated tariff.

Input: String @customerId; String @subscriptionId; String @transactionOperationStatus; String @referenceCode



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


‘Deactivated’. See above for further explanation.

Mandatory



Mandatory


transactionOperationStatus=”Deactivated”, customerId, subscriptionId, productName, referenceCode and




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.


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


83

URBANWATER PUBLIC


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>

<language>en</language> <type>NAME</type> <value>Tariff1</value> </names> <planComponents> <names> <language>de</language>

<type>NAME</type> <value>USAGE_FEE</value> </names> <descriptions> <language>en</language> <type>FREE_TEXT_LONG</type> <value>UsageFee = 2.00 EUR per cbm</val ue> </descriptions> <paymentModality>POST</paymentModality> <priceLevels> <absoluteAmount>2.0</absoluteAmount> <descriptions> <language>en</language> <type>FREE_TEXT_LONG</type> <value>Charging Rule</value> </descriptions> <negotiable>false</negotiable> <priceMetric>PriceMetric_cbm</priceMetr ic> </priceLevels> </planComponents> <planComponents> <names> <language>en</language> <type>NAME</type> <value>BASE_FEE</value> </names> <descriptions> <language>en</language> <type>FREE_TEXT_LONG</type>

<value>BaseFee = 4.00 EUR</value> </descriptions> <paymentModality>POST</paymentModality>


84

URBANWATER PUBLIC


<priceLevels> <absoluteAmount>4.0</absoluteAmount> <descriptions> <language>en</language> <type>FREE_TEXT_LONG</type> <value>Base Fee</value> </descriptions> <negotiable>false</negotiable> <priceMetric>PriceMetric_Month</priceMe tric> </priceLevels> </planCo0mponents> </pricePlan>

<priceMetric> <factor>1.0</factor> <names> <language>en</language> <type>NAME</type> <value>Month</value> </names>

<priceMetricId>PriceMetric_Month</priceMetricId > </priceMetric> <priceMetric> <factor>1.0</factor> <names> <language>en</language>

<type>NAME</type> <value>Month</value> </names> <priceMetricId>PriceMetric_Month</priceMetricId > </priceMetric>

11.3.2 Add a Tariff

Resource Id: Billing.Tariff.AddTariff

Description: This operation adds a new tariff to the ABS. The approach in UrbanWater is to have a configuration

tool that allows putting together a formal tariff description with, e.g., reoccurring base fees, time bands, and other

pricing rules in a platform-independent manner as an XML document. It is planned to use the standard format for

so-called Price Plans of the Universal Service Description Language USDL here as far as possible.

Input: String @tariffName; String @transactionOperationStatus; String @referenceCode; String

@tariffDescription


85

URBANWATER PUBLIC



tariffName String The new tariff name. It must not yet exist in the ABS. Mandatory

transaction-

OperationStatus



Mandatory



Mandatory

tariffDescription String The new tariff as an XML document, see Section 11.3.1 The format

is heavily relying and conforming to the USDL standard, in

particular the concept of a Price Plan.

Mandatory

Output: In case of success HTTP code: ‘201’ and a JSON or XML tariff transaction response object with

following parameters is returned:

• transactionOperationStatus=”Set”

• tariffId: unique id of the new tariff

• referenceCode: reference for reconciliation purposes

• resourceURL: the URL of the used resource

In case of an error a response object with transactionOperationStatus either set to “Denied” or “Refused” and an

exception with appropriate error description is returned; an HTTP code according to the error situation is given

back:

• invalid request (parameter invalid or missing): HTTP “400 Bad Request”

• tariff to be created already exists in the ABS: HTTP “400 Bad Request”

• requester executing this operation is neither a “Provider” nor an “Operator”: HTTP “401

UNAUTHORIZED”

• tariff could not be registered in the ABS due to internal problems: “500 Internal Server Error”

11.3.3 Update a Tariff

Resource Id: Billing.Tariff.UpdateTariff

Description: This operation changes an existing tariff in the ABS. The approach in UrbanWater is to have a

configuration tool that allows putting together a formal tariff description with, e.g., reoccurring base fees, time

bands, and other pricing rules in a platform-independent manner as an XML document. It is planned to use the

standard format for so-called Price Plans of the Universal Service Description Language USDL here as far as

possible [9].

Input: String @tariffName; String @transactionOperationStatus; String @referenceCode; String

@tariffDescription


86

URBANWATER PUBLIC



tariffName String The unique tariff name. It must already exist in the ABS. Mandatory

transaction-

OperationStatus



Mandatory



Mandatory

tariffDescription String The changed tariff as an XML document, see Section 11.3.1. The

format is heavily relying and conforming to the USDL standard, in

particular the concept of a Price Plan.

Mandatory



• transactionOperationStatus=”Updated”

• tariffId: unique id of the changed tariff




exception with appropriate error description is returned; an HTTP code according to the error situation (see Table

9) is given back:


• tariff to be updated does not exist in the ABS: HTTP “400 Bad Request”


UNAUTHORIZED”

• tariff could not be updated in the ABS due to internal problems: “500 Internal Server Error”

11.3.4 Get a Tariff

Resource Id: Billing.Tariff.GetTariff

Description: This operation allows retrieving a tariff description. The standard format used is USDL as far as

possible.

Input:String @tariffName; String @startDate; String @endDate


tariffName String tariffName is the name of the tariff under consideration. It must exist

in the ABS.

Mandatory

startDate String The start date and time for the validity period of the tariff under


Optional

endDate String The end date and time for the validity period of the tariff under


Optional

Output: In case the tariffName is well-known in the ABS, the operation returns the desired USDL-based tariff

description, see Section 11.3.1. If the start- and endDate are specified, the information contained in the USDL

document is limited to the tariff elements that are valid in that timing period. Note that in case of dynamic prices,

there can be many price changes and therefore a lot of information.


87

URBANWATER PUBLIC


In case of failure a response object with transactionOperationStatus either set to “Denied” or “Refused” and an


9) is given back:


• tariff to be received does not exist in the ABS: HTTP “400 Bad Request”

• tariff could not be received from the ABS due to internal problems: “500 Internal Server Error”

11.3.5 Deactivate a Tariff

Resource Id: Billing.Tariff.DeactivateTariff

Description: This operation is used to deactivate a tariff in the ABS. This means that it will not be possible to use

the tariff anymore, i.e., it will not be possible to assign this tariff to a service to form a product. Of course, currently

offered products that make use of this tariff and already sold products will still be able to utilize this tariff. If the

tariff under consideration should not be applied anymore, the UpdateProductOffer operation has to be used.

Input: String @tariffName; String @transactionOperationStatus; String @referenceCode


tariffName String The tariff name. It must exist in the ABS. Mandatory

transaction-

OperationStatus


‘Deactivated’. See above for further explanation.

Mandatory



Mandatory



• transactionOperationStatus=”Deactivated”

• tariffId: unique id of the deactivated tariff





9) is given back:


• tariff to be deactived dos not exist in the ABS: HTTP “400 Bad Request”


UNAUTHORIZED”

• tariff could not be updated from the ABS due to internal problems: “500 Internal Server Error”

11.4 Product Offer IF

The Product Offer interface is offered by the ABS to import product offers (i.e., combinations of services/service

bundles and tariffs) into the ABS. This interface makes use of a parameter called transactionOperationStatus with

the following pre-defined states.


88

URBANWATER PUBLIC


Table 14: Product Offer: Transaction Operation States

Status Description

Set A product offer has been successfully added.

Updated_Activated A successful update of a product offer was made and the product offer is activated.

Updated_Deactivated A successful update of a product offer was made and the product offer is deactivated.


explain the reason.

Refused There was a problem with the parameters. The exception in the response will explain

the reason.

11.4.1 Product Offer format

The product offer to be created, updated or viewed is specified as an XML document and is heavily relying and

conforming to the USDL standard, in particular the concept of a Service and ServiceBundle. Associated with the

Service resp. productOffer is a list of pricePlans (= tariffs), see Section 11.3.1 for the tariff/pricePlan format.

Here an example of a productOffer:

<productOffer> <id>17</id> <name>Private Water</name> <description>Water for private households </descri ption> <activationStatus>active</activationStatus> <pricePlans> <pricePlan>

… </pricePlan>

<pricePlan> …

</pricePlan> </pricePlans>

</productOffer>

11.4.2 Add a Product Offer

Resource Id: Billing.ProductOffer.AddProductOffer

Description: This operation allows adding a product offer to the ABS; this is the step prior to be able to ‘sell’ a

product to customers. The approach in UrbanWater is to have a configuration tool that allows putting together

service information (e.g., about a water metering service or a notification service) and assign to it one or more

tariffs in order to produce a product description in a platform-independent manner as an XML document. It is

planned to use the standard format for Services and ServiceBundles of USDL here as far as possible.

Input: String @productName; String @transactionOperationStatus; String @referenceCode; String

@productDescription


89

URBANWATER PUBLIC



productName String The new product name. It must not yet exist in the ABS. Mandatory

transaction-

OperationStatus



Mandatory



Mandatory

productDescription String The new product offer as an XML document, see Section 11.4.1.

It is intended that the productDescription contains at least a

descriptionText, the activationStatus of the product offer and a

list of the linked tariffs. Later on, for a subscription, one of these

tariffs has to be selected to build a subscription for a customer.

Mandatory

Output: In case of success HTTP code ‘201’ and a JSON or XML productOfferTransaction response object with

the following parameters is returned:


• productId: unique id of the new product offer





9) is returned:


• product offer to be created exists already in the ABS: HTTP “400 Bad Request”


UNAUTHORIZED”

• product offer could not be registered in the ABS due to internal problems: “500 Internal Server Error”

11.4.3 Get a Product Offer

Resource Id: Billing.ProductOffer.GetProductOffer

Description: This operation allows retrieving information about a product offer in the ABS. It is planned to use the

standard format for Services and Service Bundles of the USDL here as far as possible, see Section 11.4.1

Input: String @productName

Output: The product description as an XML document. Product information is limited to the currently valid and

future pricing information (for obtaining the complete history of prices, the operation GetTariff has to be used for

the tariffs contained in the product offer). In the case of failure, an exception with an error description and an

HTTP code according to Table 9 is returned.

11.4.4 Get all Product Offers

Resource Id: Billing.ProductOffer.GetAllProductOffers

Description: This operation allows retrieving information about all product offers in the ABS. It is planned to use

the standard format for Services and Service Bundles of the USDL here as far as possible.

Input:

Output: A list of product descriptions as an XML document, see Section 11.4.1. Product information is limited to

the currently valid and future pricing information (for obtaining the complete history of prices, the operation


90

URBANWATER PUBLIC


GetTariff has to be used for the tariffs contained in the product offer). In the case of failure, an exception with an

error description and an HTTP code according to Table 9 is returned.

11.4.5 Update a Product Offer

Resource Id: Billing.ProductOffer.UpdateProductOffer

Description: This operation is used to update a product offer in the ABS. It is possible to activate and deactivate

a product offer as well as adding or removing tariffs linked to that product offer. In case that the product offer has

been deactivated it will not be possible to sell the product anymore to customers. Of course, already sold

products will remain unaffected.

Input: String @productName; String @transactionOperationStatus; String @referenceCode; String

@productDescription


productName String The product name. It must exist in the ABS. Mandatory

transaction-

OperationStatus

Enum This indicates the desired resource state: if the product offer

shall be activated ‘Updated_Activated’ and if it shall be

deactivated ‘Updated_Deactivated’. See above for further

explanation.

Mandatory



Mandatory

productDescription String The updated product as an XML document, see Section 11.4.1. It

is intended that the productDescription contains at least a

descriptionText, the activationStatus of the product offer and a list

of the linked tariffs.

Mandatory

Output: In case of success HTTP code ‘200’ and a JSON or XML response object with the following parameters

is returned:

• transactionOperationStatus=” Updated_Activated” or ” Updated_Deactivated”

• productId: unique id of the deactivated product





9) is returned:


• product offer to be updated does not exist in the ABS: HTTP “400 Bad Request”


UNAUTHORIZED”

• product offer could not be updated in the ABS due to internal problems: “500 Internal Server Error”

11.5 Customer Empowerment IF

The Customer Empowerment interface is divided into an Account part for retrieving balances and transaction

histories and a Notification part to configure notification messages for, e.g., retrieving consumption and tariff

update messages. It is offered by the ABS to support customer-initiated operations concerning the retrieval of


91

URBANWATER PUBLIC


account balances and transaction histories. In contrast to the operator-centric customer management interface,

manipulation of account balances is not possible here.

11.5.1 Customer Empowerment: Get Account Information

The Account part of the Customer Empowerment interface is offered by the ABS to support customer-initiated

operations concerning the retrieval of account balances and transaction histories. In contrast to the operator-

centric customer management interface, manipulation of account balances is not possible here.

11.5.1.1 Get Customer Data

Resource Id: Billing.CustomerEmpowerment.CustomerData.GetCustomerData

Description: This operation retrieves the data of the customer with a certain customerId from the ABS. Same

operation as for the operator described in the customer management interface (see Section 11.2.1.4).


Output: In case of success, the registration data of the customer based on the value class “CustomerData” (see

section 5.1.1) with the specified customerId, the role, title, firstName, lastName, company, country, zipCode,

street, houseNumber, email and phoneNumber is returned, together with information about subscribed products

and applicable tariffs.

In case of a failure an exception with error description and an HTTP error code according to Table 9 is sent back.

11.5.1.2 Get Balances

Resource Id: Billing.CustomerEmpowerment.Account.GetBalances

Description: This operation results in getting all account balances of a customer. The different balances of an

account can be uniquely distinguished by their IDs. No transactionOperationStatus or referenceCode is needed,

since this operation does not change anything in the ABS.


Output: In case of success, the list of balances based on the value class “BalanceInformation” (see section

5.1.2), each with an ID, a balance value, and the corresponding unit (EUR, cbm).

In case of failure an exception with error description and an HTTP error code according to Table 9 is sent back.

11.5.1.3 Get a Balance

Resource Id: Billing.CustomerEmpowerment.Account.GetBalance

Description: This operation results in getting one specific balance for a customer. The different balances of an

account can be uniquely distinguished by their IDs. No transactionOperationStatus or referenceCode is needed,

since this operation does not change anything in the ABS. Same operation as for the operator described in the

customer management interface (see Sections 11.2.2.4 and 11.2.1.4).


Input

Parameter

Type Description Occurrence


ABS.

Mandatory

balanceId String A URL-escaped identifier identifying the balance to retrieve. If

specified, it must exist for the customer specified by customerId. If

this ID is empty, all balances will be returned.

Optional


92

URBANWATER PUBLIC


Output: In case of success, if a balanceId was provided a list of balances based on the value class

“BalanceInformation” (see section 5.1.2) containing one balance object with the considered balanceId, the

balance value, and the corresponding unit (€, £, cbm, bonus/credit points, etc.). If no balanceId is provided, the

list contains all balances related to the account of the customer. In case of failure, the output is an exception with

error description. An HTTP error code according to Table 9 is sent back.

11.5.1.4 Get Transaction History

Resource Id: Billing.CustomerEmpowerment.Account.GetHistory

Description: This operation returns the history of transactions performed on a customer’s account. It can be

used to show customers in a Web-based graphical interface their water consumption and related costs. No


ABS. Though the input parameters maxReturnRecords, startDate, and endDate are optional, at least one of them

should be provided in order to limit the resulting list of transactions. To further limit the list of transactions, a list of

balance IDs and product IDs can also be provided. Same operation as for the operator described in the customer

management interface (see 11.2.2.5).

Input: String @customerId; Long @maxReturnRecords; String @startDate; String @endDate; String

@balanceAndSubscriptionIds



the ABS.

Mandatory

maxReturnRecords Long The maximum number of entries is an optional parameter

restricting the number of data records that should be returned.

Optional

startDate String The start time for the interval defining the data records that


Optional

endDate String The end time for the interval defining the data records that


Optional

balanceAnd

SubscriptionIds

String List of IDs referring to the balances and subscriptions to limit

the resulting data to be returned. If this is empty, the

consumption data and related costs of all transactions in the

specific timing period will be returned.

The list of IDs needs to be provided in a well-defined syntax,

as attribute-value pairs with delimiter ; as follows:

balanceId1:Bal_Main1;balanceId2:Bal_Main2;balanceIdN:Bal

_MainN

Optional

structuredProd Boolean This optional parameter indicates if the transaction history

should be ordered and summarized (transaction summary for

product offers).

Optional

Formatted Boolean This optional parameter indicates if the amount shall be

rounded and the date string formatted.

Optional

Output: In case of success, a list with transactions performed on the customer’s account based on the value

class “TransactionHistory” (see section 5.1.2) in the specified timing period, together with information about the

balance(s) before and after these transactions and with the tariff that was used to charge the customer’s

transaction. The elements of the list depend on the parameter values, e.g., if no startDate is specified, but


93

URBANWATER PUBLIC


maxReturnRecords and endDate are specified, the list contains the most recent n (<= maxReturnRecords)

transactions of the account. The following table gives an overview of the different output depending on the given

parameter values:

Table 15: Output Get Transaction History

Parameter

Possibility

Start

Date

End

Date

maxReturn

Records Output

P1 All history items since the last bill run are returned.

P2 X All history items since the provided start date are

returned.

P3 X X All history between the provided startDate and the

provided end date are returned.

P4 X X Maximal the next maxReturnRecords ems history items

starting from the start date are returned.

P5 X X X

All history between the provided startDate and the

provided end date are returned. The maxReturnRecords

parameter is ignored.

P6 X All history items since the last bill run and until the

provided end date are returned.

P7 X X Maximal the last maxReturnRecords history items ending

with the end date are returned.

P8 X Maximal the last maxReturnRecords history items ending

with the current date are returned.

The semantics of other parameter value combinations are analogous. In case of a failure, an exception with error

description is returned and an HTTP error code according to Table 9 is sent back.

11.5.1.5 Get Bill Preview

Resource Id: Billing.CustomerEmpowerment.Account.GetBillPreview

Description: This operation returns an on-demand bill preview of the current accounting period. The returned

formatted (HTML- or PDF-)document has the layout of a bill with all necessary data, like the customer name and

address, the account and meter Ids, the balance values before and after the bill period, and the history of

transactions performed in the considered period. It can be used to show customers in a Web-based graphical

interface their water consumption and related costs. No transactionOperationStatus or referenceCode is needed,

since this operation does not change anything in the ABS.


Output: In case of success, a formatted document (e.g., in HTML or PDF) with all necessary data of the current

accounting period (“bill preview”). In case of a failure, an exception with error description is returned and an HTTP

error code according to Table 9 is sent back.


94

URBANWATER PUBLIC


11.5.2 Customer Empowerment: Notification Configurations

The Notification part of the Customer Empowerment interface allows customers to configure notification

messages for, e.g., retrieving consumption and tariff update messages. This interface makes use of a parameter

called transactionOperationStatus with the following pre-defined states.

Table 16: Customer Empowerment – Notification: Transaction Operation States

Status Description

Set A notification configuration has been successfully set.

Updated A notification configuration update has been successfully performed.

Removed A notification configuration has been successfully removed.


explain the reason.

Refused There was a problem with the parameters. The exception in the response will explain

the reason.

11.5.2.1 Set Threshold Notification Configuration

Resource Id: Billing.CustomerEmpowerment.Notification.SetThresholdConfiguration

Description: This operation allows a customer to define a threshold value for a metering service and a

corresponding notification text. This is part of the configuration of a notification service, to which the customer

must have previously been subscribed to.

Input: String @customerId; String @balanceId; String @transactionOperationStatus; String @referenceCode;

Double @thresholdValue; String @notificationKind; String @notificationText; String @notificationParameters



the ABS.

Mandatory

balanceId String balanceId is the URL-escaped balance ID for which the

notification threshold is to be set. It must exist for the

customer specified by customerId.

Mandatory

transaction-

OperationStatus

Enum This indicates the desired resource state, in this case ‘Set’.


Mandatory



Mandatory

thresholdValue Double The value at which the notification should be triggered. Mandatory

notificationKind String The kind of notification, i.e., how the notification shall be sent

to the customer, can be one or more of ‘email’, ‘SMS’ or

‘GUI’, e.g., ‘SMS;GUI’.

Mandatory

notificationText String The text to send (can be based on a template). Mandatory

notificationParameters Strings Additional service-specific parameters to consider, e.g.,

“reset:monthly; resetDate:1; repeat:yes”. In this case, the

semantics is that on the first of each month the threshold

monitoring is “reset” to zero and a notification is sent each

Optional


95

URBANWATER PUBLIC


time when another thresholdValue-many balance units (e.g.,

kwh or € or £) have been consumed.

These parameters and their values need to be provided as a

list in a well-defined syntax, e.g. as attribute-value pairs with




...


Output: In case of success HTTP code: ‘201’ and a JSON or XML “set threshold notification configuration”

response object parameters with following parameters is returned:


• customerId

• balanceId

• referenceCode




9) is given back:


• addressed customer or/and its regarding balance does not exist in the ABS: HTTP “400 Bad Request”


UNAUTHORIZED”

• threshold notification could not be set in the ABS due to internal problems: “500 Internal Server Error”

11.5.2.2 Set Price Update Notification Configuration

Resource Id: Billing.CustomerEmpowerment.Notification.SetPriceUpdateConfiguration

Description: This operation allows a customer to configure how to automatically receive notifications for tariff

price updates. This is part of the configuration of a notification service, to which the customer must have

previously been subscribed to.


@referenceCode; String @notificationKind; String @notificationText; String @notificationParameters



the ABS.

Mandatory

subscriptionId String subscriptionId is the URL-escaped subscription ID for which

the price update notification configuration is to be set.

Mandatory

transaction-

OperationStatus

Enum This indicates the desired resource state, in this case ‘Set’.


Mandatory



Mandatory

notificationKind String The kind of notification, i.e., how the price update notification Mandatory


96

URBANWATER PUBLIC


shall be sent to the customer, can be one or more of ‘email’,

‘SMS’ or ‘GUI’, e.g., ‘SMS;GUI’.

notificationText String The text to send (can be based on a template). Mandatory

notificationParameters Strings Additional service-specific parameters to consider.






...


Optional

Output: In case of success HTTP code: ‘201’ and a JSON or XML “set price update notification configuration”

response object parameters with following parameters is returned:


• customerId

• subscriptionId

• referenceCode




9) is given back:


• addressed customer or/and its regarding subscription does not exist in the ABS: HTTP “400 Bad

Request”

• customer who executes this operation is neither a “Provider” nor an “Operator”: HTTP “401

UNAUTHORIZED”

• price update notification could not be set in the ABS due to internal problems: “500 Internal Server Error”

11.5.2.3 Get Threshold Notification Configurations

Resource Id: Billing.CustomerEmpowerment.Notification.GetThresholdConfigurations

Description: This operation allows a customer to look up all threshold notification configurations for all of the

balances associated with the account.


Output: In case of success, a list with the threshold notification configurations, each comprising a balanceId,

notificationConfigId, threshold value, notification kind, notification text and notification parameters. 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.5.2.4 Get Threshold Notification Configurations by BalanceId

Resource Id: Billing.CustomerEmpowerment.Notification.GetThresholdConfigurationsByBalanceId

Description: This operation allows a customer to look up the threshold notification configurations for a specific

balance.



97

URBANWATER PUBLIC




ABS.

Mandatory


notification threshold is to be set. If specified, it must exist for the

customer specified by customerId. If this ID is empty, all

threshold notification configurations of all balances related to the

account of the customer are returned.

Optional

Output: In case of success, a list with the threshold notification configurations, each comprising the balanceId,

notificationConfigId, threshold value, notification kind, notification text and notification parameters. If no balanceId

is provided, the list contains all threshold notification configurations of all balances related to the account of the

customer. 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.5.2.5 Get Threshold Notification Configuration

Resource Id: Billing.CustomerEmpowerment.Notification.GetThresholdConfiguration

Description: This operation allows a customer to look up a specific threshold notification configuration.

Input: String @customerId; String @notificationConfigId



ABS.

Mandatory

notificationConfigId String notificationConfigId is the URL-escaped ID of the threshold

notification configuration. If specified, it must exist for the

customer specified by customerId. If this ID is empty, all

threshold notification configurations of all balances related to the

account of the customer are returned.

Optional

Output: In case of success, the threshold notification configuration for the specified notificationConfigId. If no

notificationConfigId is specified, a list of threshold notification configurations, each comprising a balanceId,

notificationConfigId, threshold value, notification kind, notification text, and notification parameters is returned. In

case of a failure, a response object with transactionOperationStatus either set to “Denied” or “Refused” and an


11.5.2.6 Get Price Update Notification Configurations

Resource Id: Billing.CustomerEmpowerment.Notification.GetPriceUpdateConfigurations

Description: This operation allows a customer to look up all price update notification configurations for all of the

subscriptions associated with the account.


Output: In case of success, a list with the price update notification configurations, each comprising a

subscriptionId, notificationConfigId, notification kind, notification text, and notification parameters. In case of a

failure, an exception with error description is returned.


98

URBANWATER PUBLIC


11.5.2.7 Get Price Update Notification Configuration

Resource Id: Billing.CustomerEmpowerment.Notification.GetPriceUpdateConfiguration

Description: This operation allows a customer to look up a specific price update notification configuration.

Input: String @customerId; String @notificationConfigId



ABS.

Mandatory

notificationConfigId String notificationConfigId is the URL-escaped ID of the price update

notification configuration. If specified, it must exist for the

customer specified by customerId. If this ID is empty, all price

update notification configurations of all subscriptions related to

the account of the customer are returned.

Optional

Output: In case of success, the price update notification configuration for the specified notificationConfigId. If no

notificationConfigId is specified, a list of price update notification configurations, each comprising a subscriptionId,

notificationConfigId, notification kind, notification text, and notification parameters 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.5.2.8 Get Notifications

Resource Id: Billing.CustomerEmpowerment.Notification.GetNotifications

Description: This operation allows a customer to look up all notifications (not their configurations) associated

with the customer’s account.8

Input: String @customerId; String @fromDate; String toDate



ABS.

Mandatory

fromDate String This parameter specifies the oldest notification date and time to

be considered. If it is empty, there is no time restriction in this

regard. The format is yyyy-mm-ddThh:mm:ss

Optional

toDate String This parameter specifies the latest notification date and time to

be considered. If it is empty, there is no time restriction in this

regard. The format is yyyy-mm-ddThh:mm:ss.

Optional

Output: In case of success, a list with the relevant notifications, each comprising of a timestamp and notification

text. In case of a failure, a response object with transactionOperationStatus either set to “Denied” or “Refused”

8 Alternatively, this functionality is supported centrally by the UW platform. This means that the ABS will send out

notifications to a generic “Notification Message Broker” that manages notification messages initiated from other

service modules.

In addition to (a) the notification text, (b) sender and (c) receiver information, there might be other parameters necessary to

provide details how to deliver the notification (via SMS (which needs a phone number), email (which needs an email

address) or in a Web Portal (which needs a customerId))


99

URBANWATER PUBLIC


and an exception with an appropriate error description is returned. An HTTP error code according to Table 9 is

sent back.

11.5.2.9 Get Last X Notifications

Resource Id: Billing.CustomerEmpowerment.Notification.GetLastXNotifications

Description: This operation allows a customer to look up the latest X notifications (not their configurations) for all

balances or a specific balance associated with the customer’s account.9

Input: String @customerId; String balanceId; Long @numberOfNotifications; String lookupDate



the ABS.

Mandatory

balanceId

String balanceId is the URL-escaped balance ID for which the

notification threshold is to be set. If specified, it must exist for

the customer specified by customerId. If this ID is empty, all

threshold notifications of all balances related to the account of

the customer – within the specified time limits – are returned.

Optional

numberOfNotifications Long The maximum number of notifications to be returned. Mandatory

lookupDate String This parameter specifies the date and time, from which the

previous X notifications have to be determined. If it is empty,

the current date and time is assumed. The format is yyyy-mm-

ddThh:mm:ss.

Optional

Output: In case of success, a list with the relevant notifications, each comprising of a timestamp and notification

text. 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.5.2.10 Update a Threshold Configuration

Resource Id: Billing.CustomerEmpowerment.Notification.UpdateThresholdConfiguration

Description: This operation is to update a configuration of a threshold notification with a new threshold value,

notification kind, notification text and/or other configuration parameters in the ABS.

Input: String @customerId; String @balanceId; String @transactionOperationStatus; String @referenceCode;

Double @thresholdValue; String @notificationKind; String @notificationText; String @notificationParameters



the ABS.

Mandatory


notification threshold is to be set. It must exist for the


Mandatory

transaction-

OperationStatus


‘Updated’. See above for further explanation.

Mandatory

9 Alternatively, this functionality is supported centrally by the UW platform. (see also the operation getNotifications above)


100

URBANWATER PUBLIC




Mandatory

thresholdValue Double The new value at which the notification should be triggered. Optional

notificationKind String The new kind of notification, i.e., how the notification shall be

sent to the customer. Can be one or more of ‘email’, ‘SMS’ or

‘GUI’, e.g., ‘SMS;GUI’.

Optional

notificationText String The new text to send (can be based on a template). Optional







...


Optional

Output: In case of success HTTP code ‘200’ and a JSON or XML “threshold configuration” response object with

transactionOperationStatus=”Updated”, the customerId, the balanceId, a referenceCode and the resourceURL is

returned.



11.5.2.11 Update a Price Update Configuration

Resource Id: Billing.CustomerEmpowerment.Notification.UpdatePriceUpdateConfiguration

Description: This operation allows a customer to update a configuration that specifies how to automatically

receive notifications for tariff price updates. This is part of the configuration of a notification service, to which the

customer must have previously been subscribed to.


@referenceCode; String @notificationKind; String @notificationText; String @notificationParameters



the ABS.

Mandatory

subscriptionId String subscriptionId is the URL-escaped subscription ID for which

the price update notification configuration is to be set.

Mandatory

transaction-

OperationStatus

Enum This indicates the desired resource state, in this case ‘

Updated’. See above for further explanation.

Mandatory



Mandatory

notificationKind String The new kind of notification, i.e., how the price update

notification shall be sent to the customer. Can be one or

more of ‘email’, ‘SMS’ or ‘GUI’, e.g., ‘SMS;GUI’.

Optional

notificationText String The new text to send (can be based on a template). Optional



Optional


101

URBANWATER PUBLIC






...


Output: In case of success HTTP code ‘200’ and a JSON or XML “price update configuration” response object

with transactionOperationStatus=”Updated”, the customerId, the subscriptionId, a referenceCode and the



exception with an appropriate error is returned. An HTTP error code according to Table 9 is sent back.

11.5.2.12 Remove a Threshold Notification Configuration

Resource Id: Billing.CustomerEmpowerment.Notification.RemoveThresholdConfiguration

Description: This operation is used to remove a threshold notification configuration from the ABS. This means

that it will not be possible to receive corresponding notifications anymore. Of course, already sent notifications will

still be available to be seen in the history of notifications (see operations GetNotifications and

GetLastXNotifications).

Input: String @customerId; String @notificationConfigId; String @transactionOperationStatus; String

@referenceCode



ABS.

Mandatory


notification threshold is to be removed. It must exist for the


Mandatory


notification configuration. It must exist for the customer with the

specified customerId.

Mandatory

transaction-

OperationStatus

Enum This indicates the desired resource state, in this case ‘Removed’.


Mandatory



Mandatory


transactionOperationStatus=”Removed”, the customerId, the balanceId, the notificationConfigId, the

referenceCode and the resourceURL is returned.



11.5.2.13 Remove a Price Update Notification Configuration

Resource Id: Billing.CustomerEmpowerment.Notification.RemovePriceUpdateConfiguration


102

URBANWATER PUBLIC


Description: This operation is used to remove a price update notification configuration from the ABS. This means

that it will not be possible to receive corresponding notifications anymore. Of course, already sent notifications will

still be available to be seen in the history of notifications (see operations GetNotifications and

GetLastXNotifications).

Input: String @tariffName; String @transactionOperationStatus; String @referenceCode



ABS.

Mandatory

subscriptionId String subscriptionId is the URL-escaped subscription ID for which the

price update notification configuration is to be removed.

Mandatory


notification configuration. It must exist for the customer with the

specified customerId.

Mandatory

transaction-

OperationStatus

Enum This indicates the desired resource state, in this case ‘Removed’.


Mandatory



Mandatory


transactionOperationStatus=”Removed”, the customerId, the subscriptionId, the notificationConfigId, the

referenceCode and the resourceURL is returned.



11.6 Billing and Reporting IF

This interface is provided by the ABS for backend systems like an operator’s Customer Information System (CIS)

or ERP System for invoicing and reporting purposes. In UrbanWater, this is an optional interface, meaning that an

actual integration with a backend system will not necessarily be realized as part of the project.

11.6.1 Get Billing Data

Resource Id: Billing.Account.GetBillingData

Description: This operation returns metering and billing data for invoicing purposes. No


ABS. The input parameters startDate and endDate are mandatory to limit the resulting amount of data.

Input: String @customerId; String @startDate; String @endDate


customerId String customerId is a URL-escaped unique customer ID. Mandatory

startDate String The start time for the interval defining the data that should be

returned. The format is yyyy-mm-ddThh:mm:ss.

Mandatory

endDate String The end time for the interval defining the data that should be


Mandatory


103

URBANWATER PUBLIC


Output: In case of success, a list with (aggregated) meter data and corresponding billing data related to the

customer’s account in the specified timing period. In case of a failure, an exception with error description and an

HTTP error code according to Table 9 is returned.

11.6.2 Get Metering Report

Resource Id: Billing.Account.GetMeteringReport

Description: This operation returns a list of (aggregated) meter data for one or more water meters under

consideration. No transactionOperationStatus or referenceCode is needed, since this operation does not change

anything in the ABS. The input parameters startDate and endDate are mandatory to limit the resulting amount of

data. Further service-specific parameters can be used to narrow down the resulting data set.

Input: String @customerId; String @startDate; String @endDate ; String @reportParameters


customerId String customerOrGroupId is either (a) a URL-escaped unique customer

ID or (b) a well-known, pre-defined customer group, referring, e.g.,

to the households of a suburb or district.

Mandatory

startDate String The start time for the interval defining the data that should be


Mandatory

endDate String The end time for the interval defining the data that should be


Mandatory

reportParameters String Additional service-specific parameters to consider.

These parameters and their values need to be provided as a list in

a well-defined syntax, e.g. as attribute-value pairs with delimiters :

and ; as follows:


...


Optional

Output: In case of success, a list with (aggregated) meter data related to the customer’s account in the specified

timing period. In case of a failure, an exception with error description and an HTTP error code according to Table

9 is returned.


104

URBANWATER PUBLIC


12 Annex II: Requirements Compliance of the ABS Implementation

This annex maps the requirements for the ABS identified in deliverable “D5.1 – Customer’s empowerment tools

system requirements” [11] to the implementation of the ABS. For each requirement, a filled table is presented

using the following template:

Requirement# Code number of the requirement identified in deliverable D5.1.

Requirement Description of the requirement according to deliverable D5.1

Comment Brief comment describing how this requirement is accomplished through the proposed

design and implementation

Related section Link to the section of this deliverable where the compliance of the requirement is explained

12.1 Automatic Billing Requirements

12.1.1 AB-1: Customer account must be available

Requirement# AB-1

Requirement Customer account must be available

Comment For at least one customer an account needs to be available in the ABS

Related section Test accounts have been created during development to test the configuration of the Core

Billing System, the functioning of the Web Services for Customer Data Management, and

the Operator GUI.

In the field tests, only anonymised customer data w.r.t. names, addresses, etc. will be

used to respect privacy issues of the utility partners’ real customers. This also means that

no mobile phone numbers or email addresses will be known in the ABS and thus the ABS

cannot generate notifications with associated phone numbers – in the upcoming

integration, the generation of notifications to be sent by the ABS to the notification

message queue has therefore to be slightly adapted (only use the customer ID and

indicate the type of notification delivery without any mobile phone number and/or email

address).

12.1.2 AB-2: Include dynamic, real-time, and predictive behaviour in the ICT system

Requirement# AB-2

Requirement Include dynamic, real-time, and predictive behaviour in the ICT system

Comment The ABS should support dynamic pricing, real-time rating and predictive behaviour.

Predictive in this case means to give a forecast based on the actual consumption data.

Related section Dynamic behaviour is implemented in the ABS Gateway’s Price Update Converter (see

Section 4.5) and the Core Billing System by means of dynamic tariffs with variable prices

(up to a resolution that prices can be changed per day per hour). The ABS Gateway is able

to receive day-ahead price updates with an hourly resolution from the Adaptive Pricing

System via a message queue in the UW Core Platform, convert it to an internal format and

forward this to the Core Billing System to re-configure the corresponding tariff(s).

Real-time Rating is implemented in the ABS Gateway’s Meter Data Converter (see Section


105

URBANWATER PUBLIC


4.3) and the Core Billing System: The ABS Gateway is able to receive meter reads from

the Head-End System and/or Cloud Database via a message queue in the UW Core

Platform, immediately converts them to an internal format and forwards these data to the

Core Billing System’s Real-time Environment RTE for rating and charging. Whereas the

Core Billing System’s RTE has proven real-time capabilities under high load, additional

load tests still need to be performed as part of the validation to evaluate the processing

time in the ABS Gateway.

Predictive behaviour: The Adaptive Pricing System uses a one-day-ahead prediction of

water consumption with the scope of an entire DMA zone to decide on how to impose

prices. This is built into the optimisation procedure for price calculation in the Adaptive

Pricing System. The ABS then takes the calculated prices to update the dynamic tariff(s)

as described above (see again Section 4.5).

12.1.3 AB-3: Provide adaptive pricing and dynamic tariffs

Requirement# AB-3

Requirement Provide adaptive pricing and dynamic tariffs

Comment The price changes from the Adaptive Pricing System need to be used in the ABS.

Related section As already stated above for AB-2, dynamic tariffs can be configured in the Core Billing

System and price changes are received at the ABS Gateway’s Price Update Converter

and then forwarded to the Core Billing System to update the prices, in particular for the

next day.

12.1.4 AB-4: Support threshold notifications

Requirement# AB-4

Requirement Support threshold notifications

Comment The ABS system must support threshold notifications to inform the customer on given or

user-defined triggers about consumption, cost or predictions.

Related section Threshold notifications about consumption and related costs are supported on the level of

tariff definitions. Two example tariffs have been configured, implemented and tested for

this, focusing so far on consumption (see Section 8). Predictions are published by means

of the one-day-ahead prices for dynamic tariffs through the Notification Server in the ABS

Gateway (see Section 4.6).

The exposed Web Service interfaces offer operations to accept user-defined thresholds

(see Section 11.5.2). However, although there is built-in support in the employed Core

Billing System to set and update thresholds even during runtime via the Administration IF

of the BAS, the implementation of the Web Services and corresponding GUI Web pages

still have to be made. Currently, we are able to set user-specific thresholds manually using

the proprietary BAS interface and the ACC of GOLD CCB.


106

URBANWATER PUBLIC


12.1.5 AB-5: Provisioning on customer side is not possible automatic at the moment

Requirement# AB-5

Requirement Provisioning on customer side is not possible automatic at the moment

Comment Even if at the moment it is not possible to provision devices on the customer side, it should

be possible to include this feature in the future, so the ABS needs to support that feature.

Related section This requirement refers to the functionality of the ABS to be able to send information to the

meters installed at the customers’ premises. A fundamental prerequisite, however, is that

the provisioned (or: addressed) meter has a display to present the information to the

customer. This is currently not the case, and instead the UW Platform provides a Web

GUI, i.e., the Customer Online Platform.

From the point of view of the ABS, this functionality can nevertheless be offered based on

the currently employed notification mechanism (see Section 4.6). Rule-based triggers to

send out information (and even commands for re-configuration) to meters can be easily

defined as part of the ABS configuration – the only parameter to change is the ‘channel’.

Currently, notifications are sent using the channels ‘email’, ‘SMS’, and ‘COP’. As soon as

the UW Notification Service also accepts notifications for another channel called, e.g.,

‘METER’ and a set of message types like ‘display’ and ‘command’ are agreed, this

requirement is completely met.

12.1.6 AB-6: Centralized rating

Requirement# AB-6

Requirement Centralized rating

Comment Following the survey a centralized rating capability is preferred and the ABS should be

realized central.

Related section This is directly reflected by design and implementation of the ABS (see Section 2).


107

URBANWATER PUBLIC


12.1.7 AB-7: Follow cloud standards and protocols

Requirement# AB-7

Requirement Follow cloud standards and protocols

Comment The ABS should follow common protocols and interfaces for the interaction with other

modules.

Related section All exposed interfaces of the ABS are either implemented for messages following the

AMQP standard (see Section 4) or are offered as REST Web Services (see Section 5).

The format for tariffs used in the exposed interface for Tariff Management is a subset (or:

profile) of the USDL standard (see Section 5.1.3). The REST Web Services are following

the concepts of the GSMA OneAPI, in particular the customer management [4] and

payment [5]. Currently, the OneAPI customer profile is a beta release with only a small

number of operations, such that this was extended to offer full CRUD (create, read,

update, delete) functionality. For the OneAPI account management API, there is not yet a

REST specification; the latest available standard is the discarded preceding ParlayX

SOAP specification from 2009 [1]. We therefore transferred the ParlayX SOAP API to a

REST interface in the same style as the available REST OneAPI specifications.

12.2 Backend Integration Requirements

12.2.1 BI-1: Invoice data must be available for the payment handling

Requirement# BI-1 (optional)

Requirement Invoice data must be available for the payment handling

Comment For a correct payment handling it is required to hand over the bill data file to Business

Integration components.

Related section This is an optional requirement and a special case of requirement BI-3 (see below). Due to

the employment of a commercial billing system as the Core Billing System, the fulfilment of

this requirement is ensured, as the software is already productive at various operator’s

sites. Integration with the individual operator’s components that track payments is

commonly a customisation task out of scope of the UW project.

There is no need in the context of the UW project to hand over bill data to another system,

as the ABS account statements can only be pro-forma invoices for comparison and

evaluation purposes. Regulatory requirements even prohibit charging customers based on

some of the charging methods investigated in this project. Correspondingly, no efforts

have been spent to fulfil this requirement in the context of the UW project.


108

URBANWATER PUBLIC


12.2.2 BI-2: Open ICT System for integration into other software


Requirement Open ICT System for integration into other software

Comment The interfaces to backend systems need to follow common protocols to enable integration

into third party software components.

Related section From the point of view of the UW Core Platform as an ‘open ICT system’ and the ABS as a

‘backend component’, this requirement is fulfilled by design and implementation of the ABS

Gateway with (a) its Adapters and Converters following the AMQP standard and (b) the

exposed Web Service interfaces as REST Web Services following the GSMA OneAPI

standard (see Sections 4 and 5).

12.2.3 BI-3: Interfaces for import from and export to third party products


Requirement Interfaces for import from and export to third party products

Comment The interfaces to backend systems need to follow common protocols to enable integration

into third party software components.

Related section This is an optional and more generic requirement than requirement BI-1 (see above). In

the case of the ABS, exports are in particular necessary to report to, e.g., Customer

Information, Customer Relationship Management, Revenue Assurance and Bill Handling

Systems. Though these systems are frequently SAP systems, direct integration with third

party software systems is always a customization task. However, with the UW Platform

there is now an appropriate alternative approach to integrate with third party software

based on AMQP and/or REST Web Services.

intelligent urban water management...

Documents