Technical_Whitepaper_MAXXO

MAXXO
– Your Internet Business Enabler
 Alturos Software AG | Whitepaper Functional Guide The official documentation on what MAXXO is. A must for all users who are involved in technical sales conversations and an impuls for marketing to create sales tools. Authors Alexander Ladinig, Software Factory Expert at Alturos Software AG Revision Number This revision is 2.0, based on MAXXO version 2.17
 Alturos Software AG www.alturos-group.com/alturos/solutions/maxxo.html | Seedammstraße 3 | CH 8808 Pfäffikon SZ | Switzerland office@alturos.com 1 Disclaimer This document contains information protected by Swiss and US copyright laws, international treaty provisions and all other applicable national laws. Copyright © by Alturos Software AG, 2008 All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Alturos Software Institute AG. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and Alturos Software Institute AG was aware of a trademark claim, the designations have been printed with an indication of a trademark (®,™), all other computer and software names listed in this publication are brand names and/or registered trademarks of the respective manufacturers. Purchasing and the use of hardware, software programs and applications presented in this document are subject to license terms and conditions. The hardware, programs and applications have been included for their instructional value and better illustration. They have been tested with care, but are not guaranteed for any particular purpose. Alturos Software Institute AG does not offer any warranties or representations, nor does it accept any liability with respect to the hardware, programs and applications, unless stated otherwise in writing (e.g. Alturos Software Institute AG License Agreement). This document may contain screen shots and other components of a graphical user interface (GUI). Examples shown in this document are only used to illustrate how functionality may be represented to a user. The final product may significantly differ from windows shown in this document in functionality and in look and feel. The illustrations have only been used as a design instrument and to convey complex content. This document is for informational purposes only and subject to change without notice. ALTUROS SOFTWARE INSTITUTE AG MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT. The content of this document does not represent an endorsement by Alturos Software Institute AG. Companies, names, and/or data used in screens are fictitious, unless otherwise noted. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-2 Content of this document This document has the objective to give a detailed overview of the MAXXO’s functionality and is written to summarize all the services and components realized in MAXXO. For the technical experienced reader this paper provides an insight into the system architecture and is concerned with all the technology used for this software. To proof that you are dealing with a high-quality and stable software this guide sums up all the considered quality aspects as performance, scalability, availability and code conventions for realizing a state of the art product. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-3 Table of Contents DISCLAIMER CONTENT OF THIS DOCUMENT REVISION HISTORY 1
 INTRODUCTION 1.1 WHY MAXXO? 1.2 WHO IS THE AUDIENCE? 1.3 WHAT IS MAXXO? 1.4 FOR THE TECHNICAL PROSPECT 1.5 DEFINITIONS, ACRONYMS AND ABBREVIATIONS 2
 MAXXO IN OVERALL 2.1 MAXXO’S ACTORS 2.2 MAXXO’S SERVICES 2.2.1 PORTAL@MAXXO - THE PORTAL MANAGEMENT SERVICE 2.2.2 PROFILE@MAXXO - THE USER MANAGEMENT SERVICE 2.2.3 EVENT@MAXXO - THE EVENT SERVICE 2.2.4 MESSAGE@MAXXO – THE MESSAGING SERVICE 2.2.5 BILLING@MAXXO – THE BILLING SERVICE 2.2.6 ADDITIONAL COMPONENTS USED BY MAXXO’S SERVICES 2.2.6.1 LOG@MAXXO - THE APPLICATION LOG 2.2.6.2 AUDIT@MAXXO – A SIMPLE LOG OF CHANGES 2.2.6.3 ADMIN@MAXXO - THE ADMIN CALL CENTER 2.2.6.4 SSO@MAXXO – THE SINGLE SIGN ON PLUG-IN 2.2.6.5 PAY@MAXXO – THE PAYMENT PROCESSOR SYSTEM 3
 MAXXO IN DETAIL 3.1 PORTAL MANAGEMENT SERVICE 3.1.1 PORTAL@MAXXO ENTITIES 3.1.2 PORTAL@MAXXO FUNCTIONALITY 1-2
 1-3
 1-8
 1-9
 1-9
 1-9
 1-9
 1-10
 1-11
 2-17
 2-17
 2-17
 2-17
 2-18
 2-18
 2-19
 2-19
 2-19
 2-20
 2-20
 2-21
 2-21
 2-21
 3-22
 3-22
 3-22
 3-24
 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-4 3.2 USER MANAGEMENT SERVICE 3.2.1 PROFILE@MAXXO ENTITIES 3.2.2 PROFILE@MAXXO FUNCTIONALITY 3.2.3 USER LIFECYCLE STATUS 3.2.4 USER LOCKING STRATEGY 3.3 EVENT SERVICE 3.3.1 EVENT@MAXXO FUNCTIONALITY FOR USER MANAGEMENT SERVICE 3.3.2 EVENT@MAXXO FUNCTIONALITY FOR PORTAL MANAGEMENT SERVICE 3.3.3 EVENT@MAXXO FUNCTIONALITY FOR BILLING PROCESS SERVICE 3.4 MESSAGING SERVICE 3.4.1 ARCHITECTURE 3.4.2 MESSAGE TEMPLATE SPECIFICATION 3.4.3 MESSAGE SERVICE IMPLEMENTATION 3.4.4 EMAIL MESSAGE SERVICE IMPLEMENTATION 3.4.5 EMAIL MESSAGE SERVICE WITH JMS 3.4.6 MESSAGE DATA STRUCTURE 3.4.7 MESSAGE@MAXXO FUNCTIONALITY FOR MESSAGE TEMPLATE 3.4.8 MESSAGE@MAXXO FUNCTIONALITY FOR MESSAGE COMPOSITION 3.5 BILLING SERVICE 3.5.1 BILLING@MAXXO ENTITIES 3.5.2 BILLING@MAXXO BUSINESS METHODS 3.5.3 SET-UP THE BILLING SYSTEM 3.5.4 SYSTEM CONFIGURATION 3.5.5 BUSINESS PARTNERS 3.6 APPLICATION LOG 3.6.1 APPLICATION LOG ENTRY ENTITY 3.6.2 LOG@MAXXO FUNCTIONALITY 3.6.3 AUDIT@MAXXO FUNCTIONALITY 4
 ROADMAP FOR FUTURE REQUIREMENTS 4.1 NEW SERVICES / FEATURES 4.1.1 SOCIAL NETWORKING 4.1.2 REPORTING SERVICE 4.1.3 USER HISTORY 4.1.4 TRANSACTION MONITORING www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-24
 3-25
 3-28
 3-30
 3-31
 3-32
 3-32
 3-32
 3-33
 3-33
 3-33
 3-33
 3-34
 3-34
 3-34
 3-35
 3-37
 3-38
 3-38
 3-39
 3-39
 3-42
 3-45
 3-46
 3-47
 3-47
 3-47
 3-47
 4-49
 4-49
 4-49
 4-49
 4-49
 4-50
 1-5 4.1.5 EXPORT / IMPORT OF PORTAL GROUPS 4.1.6 RISK CHECK API 4.2 EXTENSION OF EXISTING SERVICES / COMPONENTS 4.2.1 MESSAGING SERVICE EXTENSION 4.3 VOTING FOR REQUIREMENTS 5
 USED TECHNOLOGY 5.1 USED STANDARDS 5.2 USED FRAMEWORKS 5.3 USED SOFTWARE 6
 SYSTEM ARCHITECTURE 6.1 SYSTEM OVERVIEW 6.1.1 RMI / SOAP COMMUNICATION 6.1.2 PAYMENT SYSTEM INTERFACE 6.1.3 CALLBACKS VIA EVENT SERVICE 6.1.4 ADMIN GUI INTERFACE 6.2 BUSINESS / SERVICE LAYER 6.2.1 METADATA-BASED VALIDATION WITH HIBERNATE 6.2.2 STATELESS SERVICES 6.2.3 EJB 3.0 INTERCEPTOR 6.2.4 SSO – THE SINGLE SIGN-ON 6.3 PERSISTENCE LAYER 6.3.1 GENERIC FUNCTIONALITY 6.3.2 HIBERNATE FILTERS 6.3.3 DAO LAYER 6.3.4 DATABASE SCHEMA 6.4 CROSS SECTION FUNCTIONALITY 6.4.1 EXCEPTION HANDLING 6.4.2 MULTI-CLIENT CAPABILITY 6.4.3 TRANSACTIONS 6.4.4 LOCKING AND ISOLATION LEVEL 6.4.5 LOGGING 6.4.6 STATISTICS AND MANAGEMENT 6.4.7 ASYNCHRONOUS FUNCTIONALITY www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 4-50
 4-50
 4-51
 4-51
 4-52
 5-53
 5-53
 5-53
 5-54
 6-55
 6-56
 6-56
 6-56
 6-58
 6-59
 6-59
 6-59
 6-60
 6-60
 6-60
 6-61
 6-61
 6-61
 6-62
 6-62
 6-62
 6-62
 6-62
 6-63
 6-63
 6-63
 6-64
 6-64
 1-6 6.4.8 CONFIGURATION OVER DATABASE 6.4.9 REPORTING 6.5 TESTING FRAMEWORK 6.5.1 SIMPLE UNIT TEST 6.5.2 BUSINESS TEST 6.5.3 CONTAINER TEST 6.5.4 WEBSERVICE TEST 6.5.5 LOAD TEST 7
 QUALITY 7.1 PERFORMANCE 7.2 BENCHMARKS 7.3 SCALABILITY 7.4 AVAILABILITY 7.5 SOFTWARE STABILITY 7.5.1 CONTINUOUS INTEGRATION 7.5.2 CODE GUIDELINES 8
 REFERENCES 8.1 BENCHMARK 8.1.1 TESTENVIRONMENT 8.1.2 TEST RUNS APPENDIX 9.1 TECHNICAL BACKGROUND FOR TRIGGERING THE BILLING PROCESS OVERVIEW AUTHORIZATION BILLING DATE TRIGGER WORKFLOW: PORTALGROUP LEVEL WORKFLOW: USER LEVEL VATS AND INVOICE TOTALS 9
 TABLE OF FIGURES 6-65
 6-65
 6-65
 6-65
 6-65
 6-66
 6-66
 6-66
 7-67
 7-67
 7-67
 7-67
 7-68
 7-68
 7-68
 7-68
 8-69
 8-69
 8-69
 8-69
 8-72
 8-72
 8-72
 8-72
 8-73
 8-73
 8-73
 8-73
 8-76
 9-78
 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-7 Revision History Date 01.03.2008 31.10.2008 Revised by Alexander Ladinig Alexander Ladinig Activities Initial Version Update to MAXXO version 2.17 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-8 1 Introduction 1.1 Why MAXXO? MAXXO makes sure your business will develop successfully! Because you’ve found out that inhousedevelopment was too inefficient, cost-intensive and on top of everything the output does not satisfy you at all. Because your business model is unique and needs a flexible multi portal platform that you can easily extend with any further portal solutions. Because you expect a growing number of customers and therefore you need a robust and scalable business platform to support further increase. Because you are expecting a web-based user interface allowing your administrators and customers to access your portal integration platform without installing any client software. For all these reasons MAXXO is the standard in portal business intelligence. With enterprise features and a robust architecture it is the first choice for all your businesses. 1.2 Who is the audience? This functional specification guide is written for all who interested and are responsible for marketing and sales activities. So – as already mentioned in the beginning - this document shall provide a discussion fundament for every kind of technical sales conversations and shall provide all information needed for marketing people to create their sales tools. 1.3 What is MAXXO? From the technical point of view the MAXXO software is a back-end standalone application, which offers a set of public interfaces and a set of Java API calls to provide a common and powerful platform for realizing any kind of web portal solutions. With this approach it is possible that several portal groups with their set of different portal solutions can access to all provided platform components as user management, single sign on, billing, and lots more. The supplied set of interfaces for using the MAXXO services and their components are splitted into two groups - a set of interfaces for the web-based GUI part and a set of interfaces for the portal part. To guarantee reliability and accuracy each API call is enriched with information about the calling portal. Because the MAXXO software and its platform components is written in 100% pure Java and therefore entirely developed using the Java EE platform, it will run on basically any operating system. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-9 It is packaged in a Java Enterprise Archive (ear-file) and can be deployed into any J2EE conform and cluster-able application server – like JBoss application server – and can run with any RDBMS database. This includes Oracle, PostgreSQL, MySQL and others. The current development of the MAXXO product includes a range of services to offer a wide band with helpful functionalities. These services are: • • • • • Billing Service User Management Service Portal Management Service Event Service Messaging Service For an outline of these services visit the next chapter “MAXXO in overall” to get a feeling of the MAXXO’s core functionality. But to gain a detailed insight of MAXXO’s services and its components the chapter “MAXXO in detail” is written. 1.4 For the technical prospect As already mentioned in the introduction chapter this document spends some additional chapters for technical experienced people like developers, system architects and network administrators. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-10 These technical chapters give an overview about the well designed, flexible and easy-kept system architecture of the MAXXO software (referring to chapter 6) and demonstrate how stable, robust and fail-proof the MAXXO application is built and developed by summarizing the quality aspects (referring to chapter 7). 1.5 Definitions, acronyms and abbreviations1 API: Application Programming Interface An application-programming interface is a source code interface that an operating system or library provides to support requests for services to be made of it by computer programs. BLOG: Web Log A blog (a portmanteau of web log) is a website where entries are commonly displayed in reverse chronological order. "Blog" can also be used as a verb, meaning to maintain or add content to a blog. Many blogs provide commentary or news on a particular subject; others function as more personal online diaries. A typical blog combines text, images, and links to other blogs, web pages, and other media related to its topic. The ability for readers to leave comments in an interactive format is an important part of many blogs. Most blogs are primarily textual, although some focus on art (artlog), photographs (photoblog), sketchblog, videos (vlog), music (MP3 blog), audio (podcasting) are part of a wider network of social media. Micro-blogging is another type of blogging, which consists of blogs with very short posts. CMS: Content Management System A content management system is a system used to manage the content of a Web site. Content management systems are deployed primarily for interactive use by a potentially large number of contributors. For the purposes of a page, Content Management means Web Content Management. The content managed includes computer files, image media, audio files, electronic documents and web content. The idea behind a CMS is to make these files available inter-office, as well as over the web. CRUD: Create, Read, Update, Delete CRUD functions are the four basic functions of persistent storage, a major part of nearly all computer software. 1 The definitions for the abbreviations have been taken over by http://en.wikipedia.org . 1-11 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com Sometimes CRUD is expanded with the words retrieve instead of read or destroy instead of delete. It is also sometimes used to describe user interface conventions that facilitate viewing, searching, and changing information; often using computer-based forms and reports. DOI: Double Opt In This feature is optional. A unique ID can be generated by the platform. This ID can be sent with help of the messaging service to the customer which then can acknowledge the DOI by clicking on the link to the portal. The portal acknowledges the DOI with the ID parsed from the customer's request. FAX: Facsimile FAX is a telecommunications technology used to transfer copies (facsimiles) of documents, especially using affordable devices operating over the telephone network. When sending documents to people at large distances, faxes have a distinct advantage over postal mail in that the delivery is nearly instantaneous, yet its disadvantages in quality and its proprietary format have relegated it to a position beneath email as the prevailing form of electronic document transferral. GUI: Graphic User Interface A GUI is a type of user interface that allows people to interact with a computer and computer-controlled devices. Instead of offering only text menus, or requiring typed commands: graphical icons, visual indicators or special graphical elements called "widgets", are presented. Often the icons are used in conjunction with text, labels or text navigation to fully represent the information and actions available to a user. The actions are usually performed through direct manipulation of the graphical elements. HTML: HyperText Mark-up Language HTML is the predominant mark-up language for web pages. It provides a means to describe the structure of text-based information in a document - by denoting certain text as links, headings, paragraphs, lists, and so on - and to supplement that text with interactive forms, embedded images, and other objects. HTML is written in the form of labels (known as tags or elements), surrounded by angle brackets. HTML can also describe, to some degree, the appearance and semantics of a document, and can include embedded scripting language code that can affect the behaviour of web browsers and other HTML processors. HTTP: HyperText Transfer Protocol HTTP is a request/response protocol between a client and a server. The client making an HTTP request such as a web browser - is referred to as the user agent. The responding server - which stores or creates www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-12 resources such as HTML files and images - is called the origin server. In between the user agent and origin server may be several intermediaries, such as proxies, gateways and tunnels. HTTP is not constrained to using TCP/IP and its supporting layers, although this is its most popular application on the Internet. IP: Internet Protocol The IP is a data-oriented protocol used for communicating data across a packet-switched internet work. IP is a network layer protocol in the Internet protocol suite and is encapsulated in a data link layer protocol (e.g., Ethernet). As a lower layer protocol, IP provides the service of communicable unique global addressing amongst computers. JIRA: JIRA is a bug tracking, issue tracking, and project management application developed to make a process easier to track within a group of people. JIRA has been designed with a focus on task achievement, is instantly usable and is flexible to work with. JMS: Java Messaging Service The JMS API is a messaging standard that allows application components based on the Java 2 Platform, to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous. PDF: Portable Document Format The PDF is an open standard for document exchange. PDF is a fixed-layout document format, which is used for representing two-dimensional documents in a manner independent of the application software, hardware, and operating system. Each PDF file encapsulates a complete description of a 2-D document (and, with Acrobat 3-D, embedded 3-D documents) that includes the text, fonts, images, and 2-D vector graphics that compose the document. PGP: Pretty Good Privacy Pretty Good Privacy is a computer program that provides cryptographic privacy and authentication. PGP is often used for signing, encrypting and decrypting e-mails to increase reliability for e-mail communications. PGP was originally created by Philip Zimmermann in 1991. RDBMS: Relational DataBase Management System A relational database is a database that conforms to the relational model, and refers to a database's www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-13 data and schema (the database's structure of how that data is arranged). Common usage of the term "Relational database management system" technically refers to the software used to create a relational database, but sometimes mistakenly refers to a relational database. RMI: Remote Method Invocation The Java Remote Method Invocation API, or Java RMI, is a Java application-programming interface for performing the object equivalent of remote procedure calls. There are two common implementations of the API. The original implementation depends on Java Virtual Machine (JVM) class representation mechanisms and it thus only supports making calls from one JVM to another. The protocol underlying this Java-only implementation is known as Java Remote Method Protocol (JRMP). In order to support code running in a non-JVM context, a CORBA version was later developed. Usage of the term RMI may denote solely the programming interface or may signify both the API and JRMP, whereas the term RMI-IIOP, read RMI over IIOP, denotes the RMI interface delegating most of the functionality to the supporting CORBA implementation. RSS: Really Simple Syndication RSS is a family of Web feed formats used to publish frequently updated content such as blog entries, news headlines or podcasts. An RSS document, which is called a "feed," "web feed," or "channel," contains either a summary of content from an associated web site or the full text. RSS makes it possible for people to keep up with their favourite web sites in an automated manner that's easier than checking them manually. RSS content can be read using software called an "RSS reader", "feed reader" or an "aggregator". The user subscribes to a feed by entering the feed's link into the reader or by clicking an RSS icon in a browser that initiates the subscription process. The reader checks the user's subscribed feeds regularly for new content, downloading any updates that it finds. SMS: Short Message Service SMS is a communications protocol allowing the interchange of short text messages between mobile telephony devices. The SMS technology has facilitated the development and growth of text messaging. The connection between the phenomenon of text messaging and the underlying technology is so great that in parts of the world the term "SMS" is used colloquially as a synonym for a text message from another person or the act of sending a text message. SMS as used on modern handsets was originally defined as part of the GSM series of standards in 1985 as a means of sending messages of up to 160 characters, to and from GSM mobile handsets. Since then, support for the service has expanded to include alternative mobile standards such as ANSI CDMA networks and Digital AMPS, as well as satellite and landline networks. Most SMS messages are mobile-towww.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-14 mobile text messages, though the standard supports other types of broadcast messaging as well. SMTP: Simple Mail Transfer Protocol SMTP is a relatively simple, text-based protocol, in which one or more recipients of a message are specified (and in most cases verified to exist) along with the message text and possibly other encoded objects. The message is then transferred to a remote server using a procedure of queries and responses between the client and server. Either an end-user's email client, MUA (Mail User Agent), or a relaying server's MTA (Mail Transport Agents) can act as an SMTP client. An email client knows the outgoing mail SMTP server from its configuration. A relaying server typically determines which SMTP server to connect to by looking up the MX (Mail eXchange) DNS record for each recipient's domain name (the part of the email address to the right of the at (@) sign). SMTP is a "push" protocol that does not allow one to "pull" messages from a remote server on demand. To do this a mail client must use POP3 or IMAP. SOAP: Simple Object Access Protocol SOAP is a protocol for exchanging XML-based messages over computer networks, normally using HTTP/HTTPS. SOAP forms the foundation layer of the Web services stack, providing a basic messaging framework upon which abstract layers can be built. There are several different types of messaging patterns in SOAP, but by far the most common is the Remote Procedure Call (RPC) pattern, in which one network node (the client) sends a request message to another node (the server) and the server immediately sends a response message to the client. SOAP is the successor of XML-RPC, though it borrows its transport and interaction neutrality and the envelope/header/body from elsewhere, probably from Web Development Data Exchange (WDDX). SSO: Single-Sign-On In a homogeneous IT infrastructure or at least where a single user entity authentication scheme exists or where a user database is centralized, single sign-on is a visible benefit. All users in this infrastructure would have a single set of authentication credentials, e.g. in an organization which stores its user database in a LDAP database. The single-sign-on (SSO) mechanism is realized in the User Management Service for users dedicated to portal groups. WSDL: Web Service Definition Language The WSDL defines services as collections of network endpoints, or ports. WSDL specification provides an XML format for documents for this purpose. The abstract definition of ports and messages are separated www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-15 from their concrete use or instance, allowing the reuse of these definitions. A port is defined by associating a network address with a reusable binding, and a collection of ports defines a service. Messages are abstract descriptions of the data being exchanged, and port types are abstract collections of supported operations. The concrete protocol and data format specifications for a particular port type constitutes a reusable binding, where the messages and operations are then bound to a concrete network protocol and message format. In this way, WSDL describes the public interface to the web service. XML: eXtensible Mark-up Language XML is a general-purpose mark-up language. It is classified as an extensible language because it allows its users to define their own elements. Its primary purpose is to facilitate the sharing of structured data across different information systems, particularly via the Internet. It is used both to encode documents and serialize data. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 1-16 2 MAXXO in overall 2.1 MAXXO’s actors For describing a software product first of all it’s necessary to discuss the different actors operating in a software product. Therefore an overview of all defined actors in MAXXO is outlined: • Admin User and Call Center: To configure and maintain business objects using a web based GUI an administrator or call center user is installed. Depending on the different permissions assigned to this actor will be able to log on to the administration and call center application. • Portal: For executing portal relevant roles a portal actor connects on behalf of a "real user". • Payment System: The payment system actor is used to act as an external 3rd party service. • Timer: A timer or batch job (cron job) actor triggers a use case. • Intern: The internal actor is a virtual user. A use case might trigger sub use cases. 2.2 MAXXO’s services The objective of this chapter is to present a short summary of the realized services and their implemented components. At this point, a brief overview of the platform application will be provided to get a feeling about the main functionality of MAXXO. For a more detailed description see the next chapter – Chapter 3 “MAXXO in detail”. 2.2.1 portal@MAXXO - The portal management service The portal management service is the core service of the MAXXO application because with this component you are able to configure your business application. So it serves as a central repository to configure the platform components for each of your portals. It is important to know that portals are organized in portal groups and share the same users that can be activated resp. deactivated for each portal in a portal group. Notice that a portal always belongs to exact one portal group and a user with a unique user ID only belongs to one portal group. As described in the chapter “2.2.6.3 SSO@MAXXO” the single-sign-on mechanism is integrated in MAXXO, which is solved by portal groups. This means that a user once logged in on a portal can access to all other portals assigned to the same portal group without logging in again. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 2-17 2.2.2 profile@MAXXO - The user management service An essential and very important service for a web based software product is the user management service. This service component handles the user accounts and profile management like creating, managing and deactivating of users and searching for them. The user management service focus on two main services: • • Firstly the data storage of user accounts and profile information Secondly the SSO login mechanism of users dedicated to portal groups 2.2.3 event@MAXXO - The event service For notifying purposes the event service is implemented which delivers events to portals or internal MAXXO components. This service dispatches these events to all subscribed listeners, which is implemented as `transaction save`, so in case of an error the event is dispatched again. For the sake of completeness let’s discuss shortly the task of listeners and subscribers: Listeners are systems like the MAXXO software components or different portals. Each component has the possibility to subscribe to a set of event types. If a subscriber could not be called for delivering an event a warning statement is logged. If a delivery of an event needs to be suspended after the maximum number of retries an error statement is logged and the administrator is notified. The registered portals receive notifications with http(s) calls. Via the portal management service this http URL has to be preconfigured. The registration of events is done via the admin call center GUI of the MAXXO application. In the same order as they have been received the events are sent. If a listener is not able to retrieve an event, the event has to be resent for a configurable number of times and after a configurable delay time. In case that the message could not be delivered after a configurable number of retries, the message is suspended. Notice that the message is not deleted! Suspended messages are revocable through a Java API call triggered by an administration user interface. Additionally the event service logs each event received and each event dispatched. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 2-18 2.2.4 message@MAXXO – The messaging service The messaging service’s purpose is to handle message driven communications between a system and a user in an asynchronous way. A system, a portal or any component will be able to call the messaging service to send messages to one or many users based on a message template and dynamic runtime content. A message template is a static object defined by an administrator. The message template includes static content (e.g. header and footer information), the message format (text or HTML) and placeholders for dynamic content that will be filled in by the caller of the service. The service allows to query, to create, to update, to activate and to deactivate message templates. To configure the message types and templates the Java API offers interfaces as well as for sending the messages. In the current software version of MAXXO the communication channel of messages is limited to text and HTML formatted emails with the possibility to add attachments. 2.2.5 billing@MAXXO – The billing service Getting billing@MAXXO all setup and ready to run is not without effort. Are you going to accept credit cards? How often are your customers going to get invoices? How are they going to receive these invoices? By email or by mail? How much time can a customer take to pay an invoice? What happens if a customer doesn't pay? All these answered questions and processes are taken care off by the billing service. billing@MAXXO can run your billing following your defined business rules. Invoice generating - following complex business rules and taxes, customer self-care through its web-based interface and automatic payment processing are only some of the billing@MAXXO's time-saving features. MAXXO version 2.1 offers also the possibility to integrate business partners. For this case
 a
 new
 billing
 engine
actor
is
introduced
that
is
used
to
represent
B2B
cash
flows.
 2.2.6 Additional components used by MAXXO’s services Now we have discussed all the core services of MAXXO. Next to these services a set of other components are implemented to offer a wide range of functionality in MAXXO. This chapter gives an overview of which services are dependent from which components and subsystems included in the MAXXO product. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 2-19 Dependency User Mgmt. Portal Mgmt. Event Messaging Billing SSO Admin Call Center Application Log Payment System Services User Mgmt. Portal Mgmt. Event Messaging Billing SSO x x x x x x x x x x x x x x x x x x x x x x x X x x x Table 1: Service - Component Dependency Matrix 2.2.6.1 log@MAXXO - The application log First of the additional components the `application log` is mentioned here. log@MAXXO as an internal component is used by all MAXXO services to support all components with functionality for recording activities in application instances. Java APIs are available to log the activity information and to search for recorded log entries by various search criteria. Primarily the application log component is used for debugging, logging uncommon events that occur in an application instance. Of course, it is ensured that the log entry is always written - even if a runtime error occurs which performs a transaction rollback. Additionally an email is automatically sent to an administrator in a configured time interval to notify him about the count of occurred exceptions. 2.2.6.2 audit@MAXXO – A simple log of changes An audit log is the simplest, yet also one of the most effective forms of tracking data changes. The idea is that at any time something significant happens, some record indicating what happened and when it occurred is written into the database. Therefore log for auditing is part of MAXXO’s business logic. For example, a call center assistant is changing the credit card information of a customer, the audit component logs
by
whom
and
when
the
information
was
changed
‐
audit@MAXXO
is
purely
for
that!

 Because
audit
log
is
easy
to
write
but
harder
to
read
‐
especially
as
it
grows
large
‐
audit@MAXXO
offers
a
search
 functionality
for
finding
the
information
you
want.
“audit@Maxxo"
tracks
all
changes
‐
who
did
what
and
when.
 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 2-20 2.2.6.3 admin@MAXXO - The admin call center For a fully developed software product it is essential to connect with it as easy as possible. With the admin call center component MAXXO is accessible from anywhere, with only a web browser. No installation of any client software is necessary. A web based GUI guarantees instant availability for customers to login and quickly review their invoice history, downloading them as PDF files, submit an online payment using credit cards and update any of their payment or profile information. That’s what we call customer self-care with MAXXO. Also for administrators it is easy to search for application logs, to trigger the billing process, to register and activate users, to manage messaging templates and of course to set up the portal groups with all the corresponding and individual portals. 2.2.6.4 SSO@MAXXO – The single sign on plug-in One of the state of the art technologies – when talking of web solutions combining different applications – is the single-sign-on mechanism. The MAXXO user management service and the MAXXO single sign on server uses the SSO plug-in to automatically authenticate users within one portal group. A user can access several services within one portal group with only one login. If the user is already authenticated from the portal group the single sign on plug-in will automatically identify the user and log him/her in. If the service ticket is invalid or expired the user will automatically be logged out. 2.2.6.5 pay@MAXXO – The payment processor system A payment processor system is a service, provided by a company dedicated to this that allows your company to receive payments with instruments such as credit cards or direct debit from bank accounts. Some of these payment processors also let you to electronically submit transactions from a billing system such as billing@MAXXO. This is a powerful concept: when billing@MAXXO runs the billing process, it can also get the generated invoices automatically paid with your customer's credit cards or banking information. This enables several other automation features: payment retries, notification to your customers about the results of their payments (usually via email), etc. Bear in mind that billing@MAXXO has two payment service providers „Heidelpay” and „WireCard“ fully integrated to do any automatic payment processing. Further payment service providers (e.g. „Datatrans“) will follow. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 2-21 3 MAXXO in detail Now that you have gained a complete overview of the MAXXO multi portal platform services it is time to dwell on the MAXXO software. Therefore the application with its services and corresponding components are described in detail for technical sales conversations and for input to marketing to create sales tools. 3.1 Portal management service Let’s start again with the core functionality of MAXXO – the portal management service. Here we discuss the portal@MAXXO object entities and the service functionality. 3.1.1 portal@MAXXO entities Figure 1: portal@MAXXO Object Model 3.1.1.1 Portal entity www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-22 As already mentioned a portal is assigned to one portal group – identified by the portal group key. It has a set of portal hosts owned by this portal. In addition each portal has its event notification URL configured where the event service can publish events for this portal. 3.1.1.2 Portal group entity Each portal group has its redemption and deposit variant configured. For that there are two possibilities of the payment methods available: • • the ‘credit-card' mechanism for paying the ‘direct-debit’ mechanism for paying For each portal group it is possible to configure a maximum of invalid login attempts before a user is going to be locked. For details about the locking strategy see chapter “3.2.4 User locking strategy”. 3.1.1.3 Portal host entity The portal host profile information is needed to determine the portal at the single sign on validation, whereby the host name must be unique. The portal host name – either the domain name or the IP (internet protocol) address – can be defined exactly or with wildcards. In order to define wildcards the ‘isWildcarded’ flag is set to true. Then the host name will be automatically prefixed with a wildcard, e.g. "alturos.org" => "*.alturos.org". The following restrictions are applied to the usage of wildcarded host names • • Wildcards should not be included in the host name explicitly For security reasons wildcards are applied on next level domains only, e.g. the wildcarded host name "alturos.org" would match host names like "w3.alturos.org" or "smtp.alturos.org", but not "ws01.intern.alturos.org" nor "alturos.org" 3.1.1.4 Payment system properties entity Every portal group contains in initial data their own payment-system properties. The payment system properties have a one-to-many relation with the portal group. It means that a portal group could contain zero or more payment systems. In the current MAXXO version exists only two payment system properties for every portal group. There are two kinds of payment system properties: • USERTYPE.TEST: If a user has the type USERSTATUS.TEST the system always calls the INTEGRATOR_TEST interface from the specific payment system. • USERTYPE.REGULAR: If a user has type USERSTATUS.REGULAR the system always calls the LIVE interface from the specific payment service provider (The initial data for the live interface contains the payment service provider properties for the INTEGRATOR_TEST). www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-23 3.1.2 portal@MAXXO functionality The Java API link to this service: org.alturos.components.portal.PortalManagementServiceInterfaceCommon org.alturos.components.portal.PortalManagementServiceInterfaceGUI org.alturos.components.portal.PortalManagementServiceInterfacePortal The portal management service provides following functionality: • CRUD’s for portals and portal groups: Creates, reads, updates and deletes a portal or portal group and its data. A portal group groups one or more different portals. A deleted portal cannot be activated again. • List portals and portal groups: Retrieves all configured / activated / locked portals or portal groups (for an user) or returns a list of all portals in the (callers) portal group. • Activate / deactivate user for portal (with password check): A portal can activate and deactivate users, which are in that portal group the portal is assigned to. But portals cannot activate and deactivate users for other portals. Optionally the system checks the password. • Lock / unlock user for portal: User's account will be locked / unlocked for the given portal, authentication will be denied / allowed. But a portal cannot lock / unlock users for other portals. 3.2 User management service In this section the user management service profile@MAXXO and its object entities are described in detail. Additionally the user lifecycle status and the service functionality are mentioned. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-24 3.2.1 profile@MAXXO entities Figure 2: profile@MAXXO Object Model 3.2.1.1 User entity First of all each user is defined by its user type. So far you have to distinguish between two types of user: • • Regular user: In general we operate with regular user, which is the default value. Test user: For test purposes it is possible to create according users. The difference to the regular user is that for the test user the external activities are suppressed resp. ignored, e.g. no real payments, etc. are possible. In addition to the user type it is possible to identify the user’s subject, e.g. its. real name, address, email, etc. Furthermore the user has a user profile and a billing profile, which is the billing extension of the user’s profile. At last each user has a user’s account status within the system. To come to know with it visit chapter “3.2.3 User lifecycle status”. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-25 3.2.1.2 User profile entity The user's profile entity encapsulates the user data from the user entity and is used to identify the user as subject or as person. Amongst others following user data attributes are defined: • • • • • • • • • • • Gender: The user's salutation, e.g. "Ms." or "Mr.". Title: The (academic) title, e.g. "Dr.". First name: The first name(s) of the user. Last name: The surname of the user. Organization: The organization name. Email: The user's email address. Address: The user's mailing address. Phone number: The phone number part of the user's phone address. Mobile phone number: The mobile phone number part of the user's phone address. Fax phone number: The fax phone number part of the user's phone address. ... 3.2.1.3 Billing profile entity The billing profile is the extension of the user’s profile and has following attributes defined: • Bank account: The bank account data includes information like the basic bank account number, the bank routing code, the bank institute name, the country part of the bank and the account’s owner name. • Commerce type: Defines the different types of commerce for business client with obligatory VAT (value-added tax) and business client who are free from VAT or private clients. • Credit card: The credit card date stores the credit card number, the name of the credit card holder, the credit card type (VISA or MasterCard) and the card expired date (expiry month and year). Multiple credit cards per user are supported. • • Currency: Defines the preferred currency the user is used to operate. Deposit variant: The user can choose for its deposit variant between credit card or direct debit for the payment mechanism. • Invoice delivery method: Defines the user's preferences concerning delivery of invoices. The user can choose between invoice sending via email (as PDF attachment) or invoice sending via paper (the invoice will be printed and sent via post) or both. • Redemption variant: The user can choose for its redemption variant between credit card and direct debit for the payment mechanism. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-26 3.2.1.4 Address entity The user’s mailing address includes all mailing relevant address information: • • • • • City Country State / Province Street and street number ZIP code 3.2.1.5 User password entity For security reasons the password is used only in one-way mode, so the system neither return the password in plain text nor keep the plain text at all. Also returning encoded hash-value is avoided as well. In case that the user has forgotten its password a password recovery procedure is implemented which delivers a question and requires a correct answer. 3.2.1.6 Additional attributes To handle additional attributes for a user it is possible to define several ‘key-value’ pairs. Notice that the value for a key has to be unique for the user’s portal group. 3.2.1.7 User search criteria For the expert user search it is possible to use following search criteria: • • • • • • • • • • City Country Email First name Last name State Street User Status User Type ZIP code All criterias can be optional and combined with "AND" if they are provided. If no criterias are specified, all entries will be returned. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-27 3.2.2 profile@MAXXO functionality The Java API link to this service: org.alturos.components.user.UserManagementServiceInterfaceCommon org.alturos.components.user.UserManagementServiceInterfaceGUI org.alturos.components.user.UserManagementServiceInterfacePortal The user management service provides following functionality: • CRUD’s for user: Creates / registers, reads, updates and deletes a user account / profile. A new created user is assigned to a specific portal group. The administrator enters a user key, but if the entered user key appears to be not unique in scope of the portal group the platform could generate a number of suggestions based on entered user id. The number of suggestions is specified as a parameter. A deleted user is no longer available for the portal and is marked as deleted. • Find users (simple or expert search): Finds a list of users, optionally using the simple or expert search criteria. • Get user by email / key: Retrieves the user profile data by its email address or user key for the current portal group. • • Get user count (for portal group): Gets the (total) number of users for a portal group. Get activated portals for a user: Checks if the user is assigned for the portal group and which portals are activated for the user. • Lock / activate user: In case that the user is locked the authentication won’t be granted anymore. When the user is activated it can be authenticated successfully by the assigned portals. Only a registered or locked user can be activated. • Reset / recover / resume a password: If the user has forgotten the password, it could be recovered in the following steps: 1 2 An admin or a portal requests a so-called password-recovery-question, which has to be answered by the user. If the answer and the user's email address is correct, the system generates a new password, assigns it to the user and sends it to the requestor. The requestor is responsible for the delivery of the password to the end user. Note: Any white space character in the answer is not considered by the check. In case of resuming a password the system generates a new password, assigns it to the user and sends it to the requestor. The requestor is responsible for the delivery of the password to the end user. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-28 • Create / acknowledge / trigger DOI: After a user has been registered a portal can send a DOI request by email to the user to confirm its email address. Then the user has to click on the DOI link in the email for his account activation. The link points to the portal where the user wants to be registered to. Additionally an admin can trigger an event to a portal to generate a new DOI for a user. Update / check / get custom user data: Offers a generic way to store additional user attributes for portal groups. With this feature the additional user attributes for one portal group can be set. It is also possible to set a uniqueness flag for an attribute value in the portal group. Further it is possible to check if additional user attribute value exists for additional attribute key/value. Reset user action: Resets the outstanding resp. the required action for the specified user. The outstanding resp. the required action is some action, which is done by a portal, but either it has no concern with the user management system or can not be done by the system internally. Once the action is done, it must be reset, i.e. marked as done. • • Note: Neither the portal nor the admin, but only the system can set an action. The action does not affect the authentication and the user management workflows. • • Change user type: Changes the user type. Check user key: Checks if the user key is not used. Remarks on updating an user profile In the user management service it is possible to change the user profile data. While the admin user can change resp. reset the password without entering the old one, the portal use has to provide the valid old password to change the password. There exists two ways to update the password: • Changing password: it updates the password on the user's request; the user has to provide the current password • Resetting password: it updates the current password by the admin or portal user without any user interaction Note: Resetting the password is quite dangerous, thus, it should be used in an exceptional case only, and if the password is reset the administrator or portal actor is responsible to deliver a new password to the user. If the user is of type "regular" and has no binding actions assigned (e.g. for payments) the administrator can set its type to "test" (possible user types are handled in chapter “3.2.1.1 User entity”). In this case the type is not mutable anymore. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-29 3.2.3 User lifecycle status This section describes the possible status a user can have using profile@MAXXO - the user management service. Figure 3: User Lifecycle Status User Status UNREGISTERED CREATED Description An unregistered user. A user account has been registered. Possible Next Status CREATED DOI_SENT ACTIVATED LOCKED (TEMPORARY) DELETED www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-30 DOI_SENT A double opt in email has been sent to the user to acknowledge the email address. ACTIVATED LOCKED (TEMPORARY) DELETED LOCKED ACTIVATED DELETED ACTIVATED DELETED LOCKED_TEMPORARY A user account has been locked temporary for reached maximum failed logins; the user can't log on. LOCKED A user account has been locked; the user can't log on. DELETED A user account has been permanently deactivated. Table 2: Possible User Status 3.2.4 User locking strategy The timeout – given in milliseconds – for the user locking and also the user locking strategy can be configured in the portal group where the user is assigned. Possible user locking strategies are: • Locking forever: Once the maximum login failures threshold is broken the user will be locked forever. • • Locking never: The user is never locked automatically. Locking temporary constant: Once the maximum login failures threshold is broken the user will be locked but after a timeout the user lock will be resetted. • Locking temporary progressive linear: Once the maximum login failures threshold is broken the user will be locked but after a timeout the user lock will be resetted. If the threshold is broken again a linearly larger timeout is used. • Locking temporary progressive logarithmic: Once the maximum login failures threshold is broken the user will be locked but after a timeout the user lock will be resetted. If the threshold is broken again a logarithmically larger timeout is used. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-31 3.3 Event service A detaillled description of event@MAXXO - the event service is placed here. This chapter describes all possible event notification types passed to the portals over http. It is clarified that the implementation of this service warranties fail-safety and is cluster-able to guarantee the delivery of events. 3.3.1 event@MAXXO functionality for user management service The Java API links to this service: org.alturos.components.notification.EventEnum The event service for the user management provides the following functionality: • • Register user: A new user is created resp. registered. Update user profile: A user is deactivated / unassigned for one specific portal or a user-profile is changed, i.e. a user gets a new email address. Additionally a password is changed / resetted or an outstanding action (credit card expiry, leaving without warning, number of failed logins, etc.) has been reset, i.e. removed from the user. • Create / acknowledge / trigger DOI: An administrator sends the information to create a new DOIkey for a user. A user-status is changed to the state 'activated'. For reproducing the previous status, the event has also a parameter, which contains the user status before activation. • Lock / activate / delete user: A user-status is changed to the state 'locked', ‘locked temporal’, ‘activated’ or ‘deleted’. For reproducing the previous status, the event has also a parameter, which contains the user status before activation. By deleting a user, the system fires this event. • • • Recover / resume password: A user-password is changed resp. updated. Update custom user data: A portal specific user information has been updated. Trigger credit card expiration: The credit card data (user billing profile) will expire / is expired or is blocked. • ... 3.3.2 event@MAXXO functionality for portal management service The Java API links to this service: org.alturos.components.notification.EventEnum The event service for the portal management provides following functionality: • Assign / unassign / lock / unlock user for portal: The user is assigned (activated) / unassigned (deactivated) / locked / unlocked for one specific portal. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-32 3.3.3 event@MAXXO functionality for billing process service The Java API links to this service: org.alturos.components.notification.EventEnum The event service for the billing process provides the following functionality: • • Create purchase / subscription order: The user creates a new purchase resp. subscription order. Update purchase / subscription order: The user updates an existing purchase resp. subscription order. • Trigger billing process / finish order: The billing-engine resp. the administrator creates a new invoice or creates a new invoice under threshold (without payment) and executes an automatic payment for a user. The payment-call for a user succeeds or fails resp. is a chargeback or is rejected. • Start preauthorisation process: The billing-engine resp. the administrator preauthorisation-call succeeds or fails for a user. 3.4 Messaging service This chapter provides a detailed overview how the messaging service is designed and implemented. It has to be emphasised that in the current MAXXO version only the message type email – in text or HTML format – with attachment functionality is implemented. 3.4.1 Architecture The messaging service uses the open source framework "Apache Velocity" for creating and merging the message templates – static content with the variable content. The message delivery is performed by using message type specific implementation classes - e.g. for sending emails and SMS. So new implementations for new message types and channels can be plugged-in easily and transparently without changing the interface. 3.4.2 Message template specification The message template specification describes a message template that can be used for sending messages by using various communication channels (email, SMS, etc.). The message type enumeration specifies the type of message and also the communication channel, which is used for sending the message. The message template is specific for the message type because each type has its own www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-33 restrictions or features that it supports (e.g. SMS-messages are limited to text and 160 characters length). Each message template has its lifecycle, which is stored as "templateState" (the possible values are defined in the template state enumeration). The message template must be activated before it can be used for sending the messages. 3.4.3 Message service implementation The message service is responsible for the maintenance of message templates, which will be used to send the message. There is no detailed design for the message template operations because they are simple CRUD-operations on the message template specification entity. The message template defines the layout of the message body and contains placeholders, which will be filled with variable data from the template parameters (where the key matches the placeholder in the text) when the "send message" or "preview message" function is called. If there is no matching key in the template parameters, an exception will be thrown when the "send message" function is called. The message service uses Velocity to render the message – to fill the placeholders – and instantiates a message service implementation for the specified message type, which is responsible for delivering the message to the receivers. For a description of the velocity template language (VTL) see the velocity user guide. The language syntax is described in the reference guide. How velocity can be used to render dynamic content in your application is described in the developer guide. 3.4.4 Email message service implementation The email implementation uses the Java-Mail-API to send emails. The required session-properties (i.e., hostname, ports, technical user, …) are configured by using the configuration service which stores them in the database. The content type for the messages is plain text or HTML format. Also the possibility for mail attachments is provided. Therefore a multipart-message is created, where one part contains the plain text and the others contain the attachments. 3.4.5 Email message service with JMS To ensure a better performance for sending mails, the most time consuming operation is handled asynchron by using an intermediate JMS system (Apache ActiveMQ). In this solution the message service implementation creates a message map containing the input parameters for creating the mail (the template, template parameters, sender, receiver) and writes this message to a JMS queue after performing some basic validations that must be handled synchronous. When the message is delivered to a designated queue-listener (e.g. a message driven bean), the message is composed and sent to the intended receivers. This solution allows to scale the message sending process by providing more message www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-34 consumers (in a clustered environment) and to decouple the time consuming process of sending from the service invocation process. The next diagram shows how the JMS System decouples the mail sending process from the point of calling the service. Figure 4: Mail Sending Process via JMS System 3.4.6 Message data structure 3.4.6.1 Message type A message type defines the technical implementation for the delivery of the message. • SMTP Text Email: SMTP based email. The message body is defined by an alphanumeric text and This message is unformatted. • SMTP HTML Email: SMTP based email. The message body is defined by a HTML code. This message is formatted. • SMTP Text and HTML Email: SMTP based email. The message body is defined by an alphanumeric text and HTML code. The email client will decide if HTML or text is displayed. This message is formatted. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-35 • SMS Message: Message type for cell phones. The message body is defined by a short text and is unformatted. Blog Message: The message is posted on a blogging site. End users will read messages through web pages or based on an RSS client. Fax Message: The message is delivered by FAX. The message body is defined by HTML code. This message is formatted. Internal Notification: The message is delivered to the internal mailbox. The message body is defined by an alphanumeric text. The message is unformatted. • • • In the current MAXXO software version only the message type “SMTP Text and HTML Email” is supported. 3.4.6.2 Message attachments Message Attachments are supported for the message type "Email". 3.4.6.3 Message template A message template defines the static content, style and type of a message. It has a template state described as follows: Template State New Activated Suspended Description Template has been created. Template has been activated. Template has been suspended. Restrictions The template cannot be used to send a message. The template cannot be modified. The template cannot be used to send a message. The template cannot be modified. The template cannot be used to send a message. The template cannot be activated. Deleted Template is marked as deleted. Table 3: Message Templates The message template has following attributes defined: • Message template external ID: The external reference for the message template is unique and can be modified and defined by the administration user. A portal might use an external key to reference to a template. The template administrator matches the external ID to the www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-36 corresponding template by defining the message template external ID field. This field might also be empty. • • • Message type ID: The reference to a message type ID. Message state ID: The reference to a message state ID. Message recipients: Field to define the message recipients. In case of an email-recipient, this is a list of email addresses. A template variable should be used to keep the recipient's address dynamic or to set the recipients explicitly at runtime. • Message sender: Field to define the message sender. In case of an email this is the sender's email address. A template variable should be to keep the sender's address dynamic or to set the sender's address explicitly at runtime. • • • • Message title: The title of a message. Message body text: The message body in case of an unformatted text messages. Message body HTML: The message body in case of a formatted text messages. Digital Signature Required Flag: Indicates if the message shall be signed using a digital signature. Not supported by all message types. The implementation of digital signatures is not realized in the current MAXXO version. • Header required flag: Indicates if a standard message header should be added automatically (static text, which is configurable by a CMS). • Footer required flag: Indicates if a standard footer message should be added automatically (static text, which is configurable by a CMS). 3.4.7 message@MAXXO functionality for message template The Java API link to this service: org.alturos.components.message.MessageServiceInterfaceGUI The message service for the message template configuration provides following functionality: • CRUD’s of message template: Creates, reads (by name or id), updates and deletes a message template. • • • List message templates: Lists all message templates matching a given filter criteria. Activate message template: Activates a message template so it can be used to send messages. Suspend message template: Suspends a message template so it can be modified and deleted. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-37 3.4.8 message@MAXXO functionality for message composition The Java API link to this service: org.alturos.components.message.MessageServiceInterfaceCommon org.alturos.components.message.MessageServiceInterfacePortal The message service for the message composition provides following functionality: • • Preview message: Creates a message object for previewing without sending it to the recipient. Send test message: Sends a test message based on a template and dynamic content to validate the configuration of the messaging service. • Send message: Sends a message based on a template and dynamic content. The mail server configuration (e.g., hostname, technical user, etc.) is stored in the database. 3.5 Billing service The billing service supports all portals and applications with functionality related to ordering, invoicing, payments and in a future release dunning. The billing component is communicating with a preconfigured payment service provider – in the current MAXXO version the two payment broker systems „Heidelpay” and „WireCard“ are used. Integrating „Datatrans“ as an additional payment service provider is planned for the next release. Any other additional PSP can be configured upon request. In general each portal group could have its own payment service provider configured. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-38 3.5.1 billing@MAXXO entities Figure 5: billing@MAXXO Object Model 3.5.2 billing@MAXXO business methods 3.5.2.1 Create purchase order Creates a purchase order based on a list of the requested co-called one-time products. Depending on the used purchase order processing, the order will be processed by the automated billing process or will execute immediately. The automated billing process works with the following processing types: • • NEXT_SUBSCRIPTION and NEXT_BILLING_PROCESS The immediately billing process call works only with this processing type IMMEDIATE. Credit vouchers are not allowed for this kind of purchase order. 3.5.2.2 Create subscription order Creates a subscription order based on the requested subscription order parameters. Depending on the used subscription interval and the subscription order processing, the order will be processed by the automated billing process or will wait for manual finish. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-39 The automated billing process works with the following processing types: • • REGULAR IMMEDIATE The 'manual' billing process works only with this processing type DYNAMIC. Short description of the 'functional' validation handling: The system checks some important subscription order attributes and their dependencies: • • • Active since: if the active since timestamp isn't set, the current system date will be set. Active until: if the active until timestamp isn't set, the subscription order will have an open end. Billing profile of the user: checks if the credit card or bank account of a user is set. Short description of the subscription order processing: In case that the subscription order processing is REGULAR, the system only executes the default functional validation handling. After this the order will be persisted. Credit vouchers are allowed for this kind of subscription order. If the subscription order processing is DYNAMIC and the payment reservation volume is defined and the payment method is CREDIT_CARD, then a request to the payment service provider for the payment reservation will be done, whereby the specified payment reservation volume is used as the reservation volume and the subscription duration frame [active until – active since] as time-frame. If the subscription order is DYNAMIC and the payment-type is CREDIT_CARD, the billing engine throws a validation exception, if no payment reservation volume is set. Also the billing-engine will check the expiration date of the credit card in combination with the active until timestamp and throws an exception if the credit card is expired. Credit vouchers are not allowed for this kind of subscription order. And in the case that the subscription order processing is IMMEDIATE, the system only executes the default functional validation handling. Furthermore the system generates immediately an invoice and calls the payment service provider for the first period. If the next payment period is reached, the billing service will handle this kind of order like a subscription order in processing REGULAR. Credit vouchers are not allowed for this kind of subscription order. 3.5.2.3 Find orders This method finds orders using the search criteria. Nonempty attributes of the order search criteria will be used to perform conjunctive search by corresponding fields. The search is performed by adding an implicit wildcard before and after the search criterion for alphanumeric types. All list attributes are required and will be used to perform an inner disjunctive search. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-40 3.5.2.4 Update order This business method updates order data of subscription and purchase orders. Note, that only orders in state ACTIVE and RESERVED are updatable, and following attributes are updateable attributes: quantity, description, additional description and price. Following attributes are not updatable: user ID, status and processing. Short description of the 'functional' validation handling for a subscription order: The system checks some important subscription order attributes and their dependencies. Not updateable attributes are: type and product ID The active since attribute is updatable only if subscription order never passed the billing process. Updating a subscription order: In case that the subscription order processing is REGULAR, the system only executes the default functional validation handling. After this the order will be persisted. Credit vouchers are allowed for this kind of subscription order. If the subscription order processing is IMMEDIATE, the system only execute the default functional validation handling. Credit vouchers are not allowed for this kind of subscription order. If order references subscription with DYNAMIC and the state of the payment reservation is changed, the billing service makes a request to the payment service provider for payment reservation update. And in case that the subscription order processing is DYNAMIC, the payment reservation volume is defined and the payment method is CREDIT_CARD, then the request to the payment service provider for the payment reservation will be done, whereby the specified payment reservation volume is used as the reservation volume and subscription duration frame [active until – active since] as time frame. If the subscription order is DYNAMIC and the payment type is CREDIT_CARD}, the billing engine throws a validation exception, if no payment reservation volume is set. Also the billing-engine will check the expiration date of the credit card in combination with ‘active until’ and throws an exception if the credit card is expired. Credit vouchers are not allowed for this kind of subscription order. Updating a purchase order: Only purchase orders in the processing types NEXT_SUBSCRIPTION and NEXT_BILLING_PROCESS are modifiable. The system checks a couple of important purchase order attributes and their dependencies. 3.5.2.5 Finish order After finishing an order an invoice is being created. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-41 Note, that only subscription orders, which reference to DYNAMIC products can be finished. If the order doesn't exist, the billing system creates a new one and continues the started use case. Some facts for dynamic subscription orders: If the order's payment method is CREDIT_CARD and the order has a payment reservation, the reservation will be converted in the real payment, otherwise a regular payment request will be done. Only in case that the reservation amount covers the required final amount or the payment service provider can handle a payment overflow the payment can be created successfully - otherwise the payment system transaction will fail. With the attribute payment type it is possible to set a specified purpose for the order. Be aware to use the correct payment type – credit card or direct debit. These attributes could be updated: quantity, description, additional description and price. If the subscription order is DYNAMIC and the payment type is CREDIT_CARD, the billing-engine will check the expiration date of the credit-card in combination with the ‘active until’ timestamp and throws an exception if the credit card is expired. If an order has a reservation resp. a preauthorisation, the billing engine always calls the payment provider. In case that the reservation has expired or the reserved value has exceeded, the billing engine tries to capture the reservation. It could be possible that this call would go through successfully. But the default case is that the payment-system provider throws an exception and the billing engine catches them and decides to call the 'normal' debit mechanism. 3.5.2.6 Finish order without payment After finishing an order without payment an invoice is created. Note, that only subscription orders, which reference to DYNAMIC products can be finished. If the order doesn't exist, the billing system creates a new one and continues the started use case. Some facts for dynamic subscription orders: These attributes could be updated: quantity, description, additional description and price. If the subscription order is DYNAMIC and the payment-type CREDIT_CARD, the billing-engine will check the expiration date of the credit card in combination with the ‘active until’ timestamp and throws an exception if the credit-card is expired. 3.5.3 Set-up the billing system First of all it’s necessary to configure the basic data that a billing system needs. Below is an overview of www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-42 the data, which has to be provided: • • • • Items: Represent the catalogue of goods or services your company sells. Item categories: These are groups of items. Customers: These people buy and pay. Purchase orders: A customer's subscription or purchase is represented in billing@MAXXO by 'purchase orders'. • Order periods: Here it is configured how often customers receive an invoice. Let's take a look at how these data elements interact: Figure 6: Billing System Entities The items represent the products and services that are offered. Items are bought by customers by placing purchase orders. Periodically, a batch process called ‘billing process’ will run and generate invoices based on these purchase orders. The invoices will then be paid by the customers by submitting payments, or the system can automatically process these payments through its automatic payment processing feature. 3.5.3.1 Item categories An item needs to belong to at least one category and that is why item categories are the very first thing which need to be configured. Item categories are also referred in billing@MAXXO as 'item types'. Categories help to group items, and this grouping will be helpful later on for running a report or for invoice calculations. For example, you might want to know how much you have invoiced your customers for a given month, excluding taxes. You can create as many categories as you want. 3.5.3.2 Items Mainly, items are the catalogue of products and services that a company sells. There are other factors affecting how much customers pay the company, such as taxes and discounts. These too have to be www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-43 represented as items in billing@MAXXO. Let's go briefly over some of the item's attributes: • • Number: It is a way to identify the item. Items will be ordered using this number in an invoice. Percentage: Useful for representing a value calculated as a percentage of the total, such as a value added tax. • Price: A flat number being the cost of one unit of this item. The price can be entered in many currencies if the system is configured for multiple currencies. 3.5.3.3 Customers Now that the goods are set up to be sold, let's enter the information regarding the buyers. For a new customer billing@MAXXO needs the basic information about a customer. The login name and the password allow the user to access the service to review the invoice, submit payments and other customer self-care operations. The email is very important because billing@MAXXO notifies the customers of billing related events, such as when a new invoice is ready, a payment has been processed or a reminder about late payments etc. 3.5.3.4 Order periods Now it is time to define how often customers will be billed, and therefore, how often they should pay. Another way of viewing this is what type of subscriptions will be available for the customers. We need to define the order periods now because it is required before the next step, which is creating a purchase order. It is used to pay for services on a monthly basis. billing@MAXXO can handle any number of days, weeks months or years as an order period. Also, the 'one-time' order period represents a purchase that does not recur. 3.5.3.5 Purchase orders We are ready for sales, now that we have customers and items to sell to them. Purchase orders in billing@MAXXO represent sales. This could be a one-time purchase or a subscription into which the customer pays on a regular basis. A purchase order is like a bag with many items that a customer buys. 3.5.3.6 Generating invoices Once all the customers and their purchase orders have been entered, there are still no invoices. So, how are they generated in billing@MAXXO? There are two ways: • Billing process: This is the recommended way to generate invoices. It is an automated process that runs periodically, going through all the orders and generating invoices only when necessary. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-44 • Manually: This will create an invoice out of the selected order. This is not the way to generate the bulk of your invoices, but it is helpful when you want to create an invoice immediately, instead of waiting for the next billing process to run. In any case, an invoice is never created line by line with arbitrary values. Invoices always get created from purchase orders. An invoice can always be traced to its originating purchase order. It is a way of saying, “you will only bill a customer if that customer first bought something from you”. In the same line, an invoice is never modified directly. The invoice could be deleted, the order could be changed and the invoice could be generated again. The idea is to have a consistent model where documents and the reasons for their existence could be traced. 3.5.4 System configuration The data alone is not enough to run billing@MAXXO. It is also necessary to configure the billing process itself and other system-wide parameters. It’s not important to get into the details of all these parameters, but the most important parameters need to be discussed to run the billing. 3.5.4.1 Notifications billing@MAXXO will notify customers about various events, the most important one being most likely a new invoice. By default, these notifications have text that might not suit the company, so it is very important to review and edit the text for those that will be used. 3.5.4.2 Invoice reminders Invoice reminders can be sent to the customers after the portal received the invoice event from the event service by using the messaging service. 3.5.4.3 The billing process The billing process is the batch process that will generate invoices. After invoices are generated the auto-payment could be triggered, however auto-payment could be triggered independent as well. As soon as authorization is given and billing date reached, the billing process iterates through portal groups using pessimistic locking over portal group's billing process entry for duration of process, so that no other process could interfere. Within a portal group, the billing process iterates through all active or locked users. Each user is processed in a new transaction so that a failure with a single user does not interrupt the whole process and other users can be processed. Within each of these transactions, billing process collects all orders, generates new invoices if needed, which will include old ones, if it was not yet properly balanced. 3.5.4.4 The payment processing www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-45 The payment processing system is needed to transfer money from or to the customer (i.e. debit and credit operations). Therefore a customer account within the external payment service provider has to be created resp. registered. On the one hand money from the customers account to the MAXXO account is transferred (“debit the customer”) and vice versa (“credit the customer”). In the current MAXXO software version the external payment service provider „Heidelpay” and „WireCard“ are integrated. The payment service provider is encapsulated in an abstract way so that additional payment service provider (from other brokers) could be added in the future. The problem is that each payment processor has its own API. In plain English, each payment processor talks a different language so we need an “interface” for each of them. Right now, billing@MAXXO supports two payment processors: Heidelpay and WireCard. Creating new interfaces to support other payment processors is not difficult, but it requires the development of a plug-in, which is out of the scope of this guide. 3.5.5 Business partners If
 you
 want
 to
 distribute
 charged
 money
 from
 a
 customer
 for
 special
 products
 distributed
 over
 different
 business
 partners
MAXXO
provides
for
each
business
partner
its
own
invoice
template
and
payment
system
channel.
 How
much
money
each
business
partner
gets
for
a
special
product
can
be
configured
in
5
different
ways:
 1. FIXED
ONLY:
only
fixed
charge
is
taken
(value
of
shared)
 2. SHARED_ONLY:
only
shared
charge
is
taken
(value
of
fixed)
 3. FIXED_AND_SHARED:
both
‐
fixed
and
shared
‐
is
taken,
as
a
sum
(e.g.
in
case
that
100$
plus
10%
is
 configured
and
the
price
is
1000$
then
the
interest
is
200$).
 4. MAX_FIXED_OR_SHARED:
the
maximum
of
fixed
or
shared
(the
maximum
value
is
taken;
e.g.
“10%
 but
not
more
as
100$”).
 5. MIN_FIXED_OR_SHARED:
 the
 minimum
 of
 fixed
 or
 shared
 (the
 minimum
 value
 is
 taken;
 e.g.
 “10%
 but
at
least
100$”).
 Billing and invoicing of business partners for B2B transactions: • First
you
have
to
give
a
percentage
indicating
how
much
you
demand
to
receive
from
the
entire
revenue,
e.g.
 97
%.
 • Now
you
configure
your
business
partner
and
its
percentage
indicating
how
much
he
gets
from
the
revenue
as
 transaction
fee,
e.g.
2
%
Commission.
 • Further
business
partners
can
be
defined,
like
the
billing
engine
operator
or
other
PSP
operators,
e.g.
1
%.

 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-46 3.6 Application log This chapter describes the application log entry entity and the component functionality in detail. 3.6.1 Application log entry entity Each application log entry has a unique message identity, which is the text identity. This text will be read out from a property file, at the time when the administrator reads the log entries. The message parameters are stored in an encoded format. In addition each log entry has a severity (Information, Warning or Error) set. 3.6.2 log@MAXXO functionality The Java API links to this service: org.alturos.components.applog.ApplicationLogInterfaceGUI The application log component provides following functionality: • • Log activity entries: Creates a log entry and stores it in the database. Search log entries: Searches for application log entries matching the specified search criteria: • • • • • • Action Component From Date To Date Severity Levels Locale If one search criteria is not null it will be “AND” concatenated. 3.6.3 audit@MAXXO functionality With MAXXO version 2.17 all actions modifying the system entities are historised. The audit log table archives all operations which modify the attributes of an entity and who modified them => by the administrator or by a call center assistant. The logging can be activated or deactivated. Per C(R)UD method following attributes in the archive table are stored: • • • • User ID (the user which modifies the entity) Modification time (the timestamp) Operation (Create, Update, Delete) Attribute changes (the attributes which were changed by the modification operation). www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-47 Additionally the application log service will provide a search method, which allows finding log entries by using some search criteria. The search method allows a system administrator to track changes on entities (e.g., for finding user errors, etc.). Supported search criteria: • • • • User ID (the user which modifies the entity) Operation (Insert, Update, Delete) Entity name (the name of the entity class) Entity ID (the unique id) All criterias can be optional and combined with "AND" if they are provided. If no criterias are specified, all entries will be returned – therefore it's necessary to support paged reading to support the huge amounts of found records. Another feature is the support of audit trailing, which means that all relevant business events need to be logged so that future reports and analytics can be applied on this data. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 3-48 4 Roadmap for future requirements 4.1 New services / features 4.1.1 Social networking Social
networking
websites
(e.g.
XING,
facebook)
function
like
an
online
community
of
Internet
users.

Depending
on
 the
 website
 in
 question,
 many
 of
 these
 online
 community
 members
 share
 a
 common
interest
 such
 as
hobbies,
 religion,
or
politics.

With
the
planned
social
network
feature
in
the
future
MAXXO
releases,
social
networking
will
be
 enabled.
This
socializing
will
allow
reading
the
profile
pages
of
other
members
and
possibly

contacting
them
or
see
 their
activities
etc.


 Making
friends
 is
just
one
of
the
many
benefits
to
online
social
networking.
Another
 great
benefit
 is
the
 diversity
 because
the
Internet
gives
individuals
from
all
around
the
world
access
to
social
networking
sites.

 4.1.2 Reporting service In future releases of the MAXXO software several reporting functionalities are planned to be provided. Following reports will be implemented: • Audit log report o o o • Get number of logins per user List all actions taken by user List all services used by user Report to get number of registered users The report functionality will be realised with the JasperSoft reporting engine. The report design can be done with the iReport tool. 4.1.3 User history In next MAXXO releases all users related activities could be logged. The service would be notified whenever a user activity takes place. It creates a log entry describing the activity and affected data. Activities that would be logged: • • • • User status change (created, activated, etc.) User profile change (all updates to the user data) Password change (change password by user, reset password by admin) User payments www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 4-49 • • • Number of logins (successful, failed) Portal ownership (activation, deactivation) Change of outstanding actions (credit card expiry, leaving without warning, number of failed logins, etc.) Additionally the administrator will have the possibility to execute reports based on the logged user activities. There will be 2 possibilities for searching: • • Action related - search all user-activities which have performed the specified action User related - return all activities for the specified user 4.1.4 Transaction monitoring A potential feature will be the implementation of a transaction monitor. With this service it would be possible to monitor running actions, stop and/or restart them and so on. Additionally this feature provides some system operating figures like performance, throughput and memory resp. processor load. 4.1.5 Export / import of portal groups It is very often the case that an administrator has to configure a set of the same data on different server instances. Therefore it would ease this administration effort by providing an interface for exporting a configuration set of a sample portal group. When exporting the configuration data it will be stored in a defined XML file on a specified location. The administrator then can pick up this export file to import it afterwards on any other initial preconfigured MAXXO instance. 4.1.6 Risk check API For the user registration and the user’s scoring it is planned to have a defined procedure how to filter dubious users and to constrain their authorizations. There are two possibilities how to check if the user is on a black list or not. • • Ask the payment service provider (PSP) Query the user’s bank institute directly In case of a listed user each portal can set its own limits of the configuration for this user. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 4-50 4.2 Extension of existing services / components 4.2.1 Messaging service extension The message types used in message@MAXXO will be extended with various communication channels, like SMS, FAX, internal mailbox and some others. In addition digital signatures will be used by programs or users to verify and confirm the identity of someone and to confirm that data resp. messages have not been manipulated. They would ensure by means of verification and validation that the user is who he/she claims to be. Digital certificates ensure data integrity and informs the user that the message or transaction has not been accidentally or maliciously altered. This is done cryptographically. Additionally digital certificates ensure confidentiality and ensure that authorized intended recipients can only read messages. Digital certificates also verify date and time so that senders or recipients cannot dispute if the message was actually sent or received. It will be possible to sign a message by using a digital signature to ensure the senders identity and dataintegrity. The private key (used for signing) must be kept confidential (only the message-sender knows it) and must not be stored on the server (in a database). The public key(s) must be distributed to the message receivers so they can verify the identity of the message sender. The distribution of public keys can be implemented by sending them as mail-attachments. The private keys used for digital signatures must be stored in a trusted store (e.g. encrypted in a database) and they must be (should be) verified by a trust center (e.g. VeriSign). Key Management: Using digital signatures for messages requires a complete infrastructure for key management because you have to • • • • import the keys from a trust center store them in a trusted store validate the keys before each usage (because they can have timed out or blocked) handle the end of the validity for the keys (because they are only valid for a specific time period), e.g. by sending notifications to an administrator before the deadline is reached • update or delete the keys The digital signatures are only required for messages which are sent by the portal-user (technical user, which sends notifications), e.g. for sending payment-notifications from the billing engine to the users. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 4-51 They are limited to messages of type email. Sign and encrypt messages: The JavaMail-Crypto-API extension and a S/MIME or OpenPGP provider (which supports the required encryption algorithm) are needed to sign the emails. Additionally the "Unlimited Strength Jurisdiction Policy Files" are needed for the used JDK because the standard-crypto-support restricts the length of your crypto-keys due to import control restrictions. For keys with 1024bits length or more (PGP uses a standard key size of 2048) those JAR files must be installed. The public and private keys are created e.g. by using PGP which allows to store the public keys in a global repository so everyone can verify the public key against this repository to ensure the identity of the message sender. The internal implementation will create just a request that is sent to a JMS message queue to decouple the messaging service from the internal implementation. The mailbox-component is responsible for listening to this queue and storing the message in the user's mailbox. 4.3 Voting for requirements The task will be to prioritise all new services and extensions of services listed above. For assistance to decide which of these services are more important than others it is suggested to provide a voting feature on the MAXXO product web page. The goal is to set up a community of people to have an impact on the further development of the MAXXO software. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 4-52 5 Used technology The MAXXO application is based on J2EE / Java technologies. This provides a state of the art programming environment. It has the benefit to be platform independent and offers a lot of open source frameworks that can be used to improve quality and development costs. We use J2SE 5.0 as the virtual machine, the JBoss application server runs in. Most of the new language features of Java 5 are used. Currently we use JBoss 4.2.1 (with EJB3 support) that comes with Tomcat as servlet engine. For the development and operation of the MAXXO software product following standards, frameworks and software products are used in version 2.1.0. 5.1 Used standards Component Platform Standard Java5 / Java6 Version 5.0 / 6.0 Link http://java.sun.com Server-Side Architecture EJB3 3.0 http://java.sun.com/products/ejb 5.2 Used frameworks Component Java / J2EE Application Frontend (AJAX) Webservice (SOAP) Persistence Layer Messaging (JMS) Logging Google Web Toolkit (GWT) Apache CXF Hibernate Apache ActiveMQ Apache Log4J Apache Commons Logging 2.0.1 3.2.1 4.1.1 1.2 1.1.0 http://incubator.apache.org/cxf http://www.hibernate.org http://activemq.apache.org http://logging.apache.org http://commons.apache.org/logging 1.5 http://code.google.com/webtoolkit/ Framework Spring Version 2.3 Link http://www.springframework.org www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 5-53 Reporting Engine Report Designer JasperReports JasperSoft iReport 2.0.3 1.3.0 http://jasperforge.org/sf/projects/jaspe rreports http://www.jasperforge.org/jaspersoft/ opensource/business_intelligence/irepor t Templating Engine Apache Velocity 1.5 http://velocity.apache.org 5.3 Used software Component Java Virtual Machine Application Server Database Software J2SE JBoss MySQL Version 5.0 4.2.1 5.0 Link http://java.sun.com/j2se http://www.jboss.org/products/jbossas http://www.mysql.com www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 5-54 6 System architecture Figure 7: MAXXO System Architecture www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-55 6.1 System overview 6.1.1 RMI / SOAP communication The communication between the several portals (with the admin call center application) and the MAXXO’s platform component services is done via Java RMI/IIOP or HTTP (SOAP). For invoking the Portal API interfaces we use the webservice SOAP over HTTP(s) protocol to exchange information in a decentralized, distributed environment. For invoking the GUI API we use the same generated interfaces (with the same interface declarations) for Java RMI/IIOP and since version 2.1.0 also for SOAP. So the different session beans deployed in MAXXO are used with both protocols. This enables MAXXO to be embedded also in non Java environments only. So MAXXO can be used together with .NET, PHP or any other technologies. 6.1.2 Payment system interface A main requirement for MAXXO is to encapsulate a real payment service provider (i.e. Heidelpay) in an abstract way so that additional payment service providers (from other brokers) could be added in the future. An external PSP broker needs to be integrated into the abstract architecture. The overall design is based on two patterns: The Bridge Pattern: this pattern defines a set of interfaces each real implementation must adhere to. • The Abstract Factory Pattern: a factory provides real implementations for the real payment system implementations. For a general discussion of the two patters look at: http://en.wikipedia.org/wiki/Bridge_pattern http://en.wikipedia.org/wiki/Abstract_factory Together the two patterns form the basic structure to support the future extension for multiple payment system implementations. As with any pattern there are some tradeoffs: Since the top-level interfaces must be quite general it is sometimes not easy to use all advanced features of an underlying implementation. The interfaces only describe common behaviour and especially for handling errors and exceptions there is the need to provide also some form of access to information from the underlying implementation. • www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-56 Figure 8: Sequence diagram of payment system The above sequence diagram shows the creation of a real payment system implementation. The manager is instantiated and its open method is called with the class of the Payment System implementation (in this example the HpPaymentSystem class). The chosen payment system initialises itself (i.e. establish the required factory). After that the manager sets the properties into the new instance to provide the required configuration data. The only information that depends on the payment system implementation is the values of the payment system properties and the class of the payment system implementation. The PaymentSystemProperties class holds simple name value pairs within a map structure and provides therefore a simple and generic way to pass the required configuration parameters to the real payment service provider. The user of the payment system is therefore no longer bound to a real implementation (i.e. the Payment System Broker may change or there may be different brokers in use at the same time). Results are specific to the real Payment System implementations. Therefore a structure is needed that makes it possible to define common results in an independent manner. But also detail information provided by the Payment System implementation must be available. Therefore there is a distinction between a status (represented by codes) and results. Each result provides one ore more different types of status values. Each status value provides access to its codes. And each code has the capability to deliver the native codes and descriptions as received from the implemented payment system. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-57 So the different common codes (for example: TransactionCompletionCode.SUCCESS, TransactionCompletionCode.VALIDATION_ERROR,...) are defined at a logical level and the native codes and descriptions are always available. The native codes and descriptions are of great value for accounting, logging and error detection purposes. Therefore the results with all the detail structures are also available in the exception classes. The general rules are: • A PaymentRuntimeException is thrown if a technical problem is found within the Payment System Implementation. • A PaymentException is thrown if a business problem is found within the Payment System Implementation. • • The exceptions include the result of the failed operation. The result information is also available for transaction calls that work as expected by the getLastTransactionResult() method. This result may be used for accounting purposes. • There is a special query structure (represented by the QueryResult class) that is used to return result records and the query result. 6.1.3 Callbacks via event service It is often useful for the MAXXO application to react to certain events that occur inside the persistence mechanism. This allows the implementation of certain kinds of generic functionality, and extension of built-in functionality. The EJB3 specification provides two related mechanisms for this purpose. A method of the entity may be designated as a callback method to receive notification of a particular entity life cycle event. Callbacks methods are annotated by a callback annotation. Sometimes in MAXXO an entity listener class is used instead of the callback methods defined directly inside the entity class. An entity listener is a stateless class with a no-arg constructor. An entity listener is defined by annotating the entity class with the @EntityListeners annotation. The same callback method or entity listener method can be annotated with more than one callback annotation. A callback method can raise a RuntimeException. The current transaction, if any, must be rolled back. The following callbacks are defined: www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-58 Type @PrePersist Description Executed before the entity manager persist operation is actually executed or cascaded. This call is synchronous with the persist operation. @PreRemove Executed before the entity manager remove operation is actually executed or cascaded. This call is synchronous with the remove operation. @PostPersist Executed after the entity manager persist operation is actually executed or cascaded. This call is invoked after the database INSERT is executed. @PostRemove Executed after the entity manager remove operation is actually executed or cascaded. This call is synchronous with the remove operation. @PreUpdate @PostUpdate @PostLoad Executed before the database UPDATE operation. Executed after the database UPDATE operation. Executed after an entity has been loaded into the current persistence context or an entity has been refreshed. Table 4: Callbacks 6.1.4 Admin GUI interface The admin GUI in MAXXO is implemented with the Google webtool kit (GWT/EXT) which is a common AJAX technology based on the Model-View-Controller Framework. The administration portal application accesses the MAXXO system via Java RMI. Java RMI enables the programmer to create distributed Java technology-based to Java technology-based applications, in which the methods of remote Java objects can be invoked from other Java virtual machines, possibly on different hosts. RMI uses object serialization to marshal and unmarshal parameters and does not truncate types, supporting true object-oriented polymorphism. 6.2 Business / service layer 6.2.1 Metadata-based validation with Hibernate Validating input data has often been a troublesome part of enterprise Java applications, Hibernate meets our validation needs though. Hibernate offers a validation framework that allows a developer to specify validation requirements at the application model layer via annotations, and then leveraged those annotations in other application layers as well to generate the required validator. While validation in some of those layers is handled by Hibernate automatically, other layers, such as the view, can process www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-59 the model's validation-related annotations to generate, for instance, validator in the view, such as JavaScript-based validation. Since the database scheme can be generated from the Hibernate annotations, the correct database schema will ensure that no invalid data can be entered – for instance, by not accepting null values, or by limiting field sizes to a specified length. We need Hibernate validations for all our DTO’s, so no custom validation is needed. Note that necessary restrictions are realized in our Java implementation code and NOT in the WSDL specification. In the generated Request- and Response-Beans out of the WSDL specification the restrictions are checked via annotations. In case of a restriction violation a proper ValidationException is thrown. 6.2.2 Stateless services All services implemented in MAXXO are stateless. Stateless session beans are session beans that are designed to not require the preservation of state within the EJB that is specific to a particular EJB client. This does not imply that the EJB does not actually maintain any state within its fields or associated objects. However, it does imply that the state it maintains is not required to be accessed or utilized for a specific EJB client later. This also implies that the state is not important for access by another client later. 6.2.3 EJB 3.0 interceptor The EJB 3.0 specification defines the ability to apply custom made interceptors to the business methods of our session and message driven beans (and of course to the JBoss @Service and @Consumer beans). EJB 3.0 interceptors take the form of methods annotated with the @javax.ejb.AroundInvoke annotation. We have to distinguish between class and method-level interceptors that can be bound to a bean or a bean's method using annotations or xml. Default interceptors can only be bound via xml. A Default interceptor is an interceptor that is invoked whenever a business method is invoked on any bean within the deployment. In MAXXO we use EJB3 interceptors as a central functionality for following components: • • • • Request Validation Exception Handling Logging and Response Time Measurements 6.2.4 SSO – The single sign-on In MAXXO the single sign-on is a method of access control that enables a user to authenticate once and www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-60 gain access to the resources of multiple portals. In a homogeneous IT infrastructure or at least where a single user entity authentication scheme exists or where a user database is centralized, single sign-on is a visible benefit. All users in this infrastructure would have a single set of authentication credentials. All information processing systems can use such a centralised database for user authentication and authorization, which in turn means single sign-on has been achieved organization-wide. In MAXXO we use SSO on https basis. 6.3 Persistence layer The EJB3 specification recognizes the interest and the success of the transparent object/relationalmapping paradigm. The EJB3 specification standardizes the basic APIs and the metadata needed for any object/relational persistence mechanism. Hibernate EntityManager implements the programming interfaces and lifecycle rules as defined by the EJB3 persistence specification. Together with Hibernate Annotations, this wrapper implements a complete (and standalone) EJB3 persistence solution on top of the mature Hibernate core. In MAXXO a combination of all three together, annotations without EJB3 programming interfaces and lifecycle, or even pure native Hibernate, depending on the business and technical needs is used. In some cases it is possible to fall back to Hibernate native APIs, or if required, even to native JDBC and SQL. 6.3.1 Generic functionality MAXXO uses generic functionality in DAO interceptors and filters for following components: • • • • Client Capability Dynamic Mandatory Fields Delete Mechanism and so on The interceptor interface provides callbacks from the session to the application allowing the application to inspect and/or manipulate properties of a persistent object before it is saved, updated, deleted or loaded. 6.3.2 Hibernate Filters A Hibernate filter is a global, named, parameterized filter that may be enabled or disabled for a particular Hibernate session. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-61 The client filter is used to implement the client capability of our system. It passes to every select, executed to the database, the possible visible client ids. So we only see what we are allowed to. Look at the “multi-client capability” chapter for more detail. 6.3.3 DAO layer In MAXXO Hibernate is wrapped with a generic DAO layer. It has the job to encapsulate data retrieval, creation and removal. There is one DAO per entity, but the creation of a DAO is rather simple, because all of them extends a generic hibernate DAO interface which offers common DAO methods that are most of the time sufficient. 6.3.4 Database schema The database scheme is generated out from the object model. 6.4 Cross section functionality 6.4.1 Exception handling Exception handling is a programming language construct to handle the occurrence of some condition that changes the normal flow of execution. The condition is called an exception. Exceptions are normally recommended to be used only for signalling error (exceptional) conditions. In MAXXO we have a set of Business Exceptions defined, which are part of the business logic. A BusinessException denotes a Business case, where the client is able to react on this exception, e.g. the client passes an invalid id to the MAXXO application. A TechnicalException denotes a case where something happens what should not happen while using the MAXXO application normally. In this case it makes no sense to give the client detailed information. A RuntimeException can be thrown in different parts in the MAXXO application code or used libraries. This case is comparable with a TechnicalException. If any Exception is thrown a rollback will be performed. 6.4.2 Multi-client capability MAXXO is a multi-client capable system, which means that different users have different views on the data. It is solved in a generic way with help of filter mechanism. Because of this generic multi-client capability, an application developer does not need to care about the data visibility. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-62 6.4.3 Transactions Transaction support is a key feature in any enterprise middleware. It guarantees the integrity of the system even in case of random network or hardware failures. EJB 3.0 makes it very easy to declare transaction properties for any method in any POJO class using annotations. In fact, transactions tie entity beans and session beans. For the MAXXO application mainly one transaction is used per one method call. 6.4.4 Locking and isolation level The default locking system in EJB3 is mostly based on optimistic locking (i.e., using a version column to check any concurrency issues). EJB3 has defined an additional mechanism to increase the concurrency guaranties. For that a lock on a given entity (and it's associated entities if LOCK is cascaded) through the lock(Object entity) method is applied. Depending on the concurrency guaranties there a two kind of lock mode: • • LockMode.READ prevents dirty-reads and non-repeatable read on a given entity. LockMode.WRITE prevents dirty-reads and non-repeatable read on a given entity and force an increase of the version number if any. In MAXXO mainly optimistic locking is used, but very rarely also pessimistic locking is needed. The easiest isolation level to use would have been SERIALIZABLE, but this would bring a performance reduction and is not really necessary. So the isolation level in use for MAXXO is READ_COMMITTED. In this case data records retrieved by a query are not prevented from modification by some other transaction. Non-repeatable reads may occur, meaning data retrieved in a SELECT statement may be modified by some other transaction when it commits. In this isolation level, read locks are acquired on selected data but they are released immediately whereas write locks are released at the end of the transaction. 6.4.5 Logging Logging is a mundane but important topic in any software application and it is very useful to log information. However there are many logging implementations out there, and a software cannot impose the use of a particular one on the overall application that the software is a part of. In MAXXO the Apache commons-logging and log4j framework is used. 6.4.5.1 Trace logging MAXXO provides configurable tracing capabilities that can aid in problem determination. Unlike message logging, trace logging (or tracing) is not enabled by default. Trace data is intended primarily for www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-63 MAXXO and might be requested as part of diagnosing a reported problem. However, experienced product administrators can use trace data to diagnose and correct problems in the MAXXO environment. Tracing is best suited to situations where a problem is easily reproduced, is short-lived in duration, and can be produced without significant trace generation from other system activity. Note that enabling tracing can adversely affect the performance of the MAXXO product and its associated products and applications. For trace logging MAXXO logs into a proper log file in the file system. 6.4.5.2 Application logging Additionally it's important in MAXXO that the application maintains “application level” logs in database to extract a higher-level meaning. For that reason the MAXXO application keeps a trail of important activities that we might want to review while troubleshooting or conducting forensic analysis. Please note that it is inadvisable to keep sensitive business information itself in these database logs, as administrators have access to these logs for troubleshooting. 6.4.6 Statistics and management The architecture of using MBeans in MAXXO offers the possibility of surfacing server information so that an administrator can monitor the server's status. So a server can tap into a cluster of servers and extract information from specific MAXXO servers in order to fetch data or even alter their state. This will be especially useful in the case someone has to monitor a large number of MAXXO servers. 6.4.7 Asynchronous functionality In order to fulfil the asynchronous functionality in MAXXO the Quartz framework is integrated. Quartz is a full-featured, open source job scheduling system that can be integrated with, or used along side virtually any J2EE or J2SE application - from the smallest stand-alone application to the largest ecommerce system. Quartz can be used to create simple or complex schedules for executing tens, hundreds, or even tens-ofthousands of jobs; jobs whose tasks are defined as standard Java components or EJBs. The Quartz Scheduler includes many enterprise-class features, such as JTA transactions and clustering. In MAXXO we have several Quartz timers configured for asynchronous functionality like • • • Billing Process Removal of old application logging data and some others… www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-64 6.4.8 Configuration over database The application configuration of MAXXO is mainly done over some database tables with useful defaults. 6.4.9 Reporting JasperReports is one of the world’s most popular open-source Java reporting library. It can be easily embedded into any Java application to deliver sophisticated print or web reporting. It can also be used to create output to files for further processing in applications like Excel. In MAXXO we use JasperReports for generating invoices. 6.5 Testing framework To ensure a high code quality the MAXXO’s software developers and testers are using the JUnit framework to write their test cases. JUnit is one of the oldest and most popular testing frameworks available for Java development. Because of its early adoption, most Java developers are probably familiar with it. There are numerous extensions available for JUnit to allow for testing just about any component of a system from XML files to JavaScript. A basic JUnit test case extends junit.framework.TestCase and can be bundled together into a suite using a junit.framework.TestSuite instance. This allows the test developer(s) to bundle together similar tests. The TestCase class provides some basic methods for building a system of unit tests including the assert methods which provide the actual testing and results mechanism. 6.5.1 Simple unit test To test standalone code parts that have no dependency to the database or application server, normal JUnit tests are used. 6.5.2 Business test It offers the functionality to test business code with the database without application server. With annotations it is possible to define things like the initial data set, transaction behaviour, user, client, and so on. The benefit is to develop business code much faster using this test method, than deploying it to the application server. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-65 6.5.3 Container test In this case also a dataset and other configurations via annotation are done. The unit test case is executed as java application, but after setting up the database the test case is then delegated to be run on the server side. In this scenario we need a running application server with a deploid ear file. The benefit here is that a developer can use the application server infrastructure and test code in the destination environment. 6.5.4 Webservice test This test case represents real scenarios where a client makes SOAP calls to the application server and the developer can make asserts concerning the response. 6.5.5 Load test Load tests are running with Apache JMeter plug-ins to load test functional behaviour and measure performance. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 6-66 7 Quality 7.1 Performance It is essential that all layers of the MAXXO software can be configured optimally in order to ensure good performance and scalability. Optimally configuring and tuning the various tiers of the software, including the data server and the middle-tier services, such as the JVM, the application server (JBoss), the database (MySQL) and JMS (ActiveMQ) help ensure optimal performance for the users and the key business flows. 7.2 Benchmarks In the reference chapter you will find more information on the performance and scalability of the MAXXO software including benchmark publication reports. The used testing framework is Apache JMeter where a client is used for executing stress tests using JMeter-scripts. The JMeter-scripts contain Java-requests for access MAXXO Java methods. Further the scripts execute JDBC-requests for managing the MySQL database during the test. 7.3 Scalability Careful planning and development is necessary to make a truly scalable application. For us it is important to rigorously and regularly test our software for scalability problems to be able to identify major workloads and mitigate bottlenecks that can impede the scalability of the MAXXO application. When the MAXXO software does not meet our performance requirements, we analyze data from the test results to identify bottlenecks in the system and to hypothesize a cause. Additionally the architecture of the MAXXO software is designed to be fully clusterable. Therefore MAXXO is built on Sun's Java EE technology, and deploys on the JBoss/Tomcat platform. These are mature and robust open source platforms. JBoss offers the clustering, fail-over, load balancing, and distributed deployment features required to deploy large scalable enterprise applications such as MAXXO. You can easily cluster application/web servers to increase throughput without any change to MAXXO's code. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 7-67 7.4 Availability The MAXXO software architecture is designed to meet the availability, manageability, performance and security requirements for mission-critical internet applications. One reason to guarantee a high availability is that the MAXXO’s software architecture is as simple as possible but designed for a maximum of flexibility and expandability. The developer work conform with the SUN code-guideline standard. 7.5 Software stability 7.5.1 Continuous integration In the software development of MAXXO our team members are used to integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including heavy unit testing) to detect integration errors as quickly as possible. We find that this approach leads to significantly reduced integration problems and allows our team to develop cohesive software more rapidly. 7.5.2 Code guidelines We use code conventions for the Java programming language recommended by SUN. The SUN code convention document contains the standard conventions for filenames, file organization, indentation, comments, declarations, statements, white space, naming conventions and programming practices. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 7-68 8 References 8.1 Benchmark Test runs can be found under: https://chilliext.alturos.com/confluence/display/MAXXO/Test-Runs 8.1.1 Testenvironment Server Hardware A
 development‐machine
 HP
 Compaq
 dc5700
 Microtower
 Intel(R)
 Core(TM)2
 CPU
 4300
 @
 1.80GHz,
 1,79GHz,
 2,99
 GB
of
RAM,
Physical
Address
Extension.
 Software name jBoss instance 1 jBoss instance 2 MySQL description Version 4.2.1GA Version 4.2.1GA Version 5.0.27 The 2 jBoss instances are running clustered (excepting the SOAP-Tests). Client Hardware A development-machine Dell Optiplex GXS270 Intel(R) Pentium(R) 4 CPU 2.80GHz, 2,79GHz, 1,00 GB RAM Software name jBoss jMeter description Version 4.2.1GA Version 2.3 8.1.2 Test Runs create Onetime Product (USER_GUI.createOneTimeProduct) Protocol RMI RMI RMI Threads 1 50 100 Ramp-Up (sec) 0 5 5 Loops 1000 400 200 Samples 1.000 20000 20000 Average 45 361 849 Median 47 359 703 90% Line 62 672 1781 Error % 0 0 0 Throughput (sec) 19,6 118,6 110,9 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 8-69 create Subscription Product (USER_GUI.createSubscriptionProduct) Protocol RMI RMI RMI RMI Threads 1 50 100 125 Ramp-Up (sec) 0 5 5 5 Loops 1000 400 200 160 Samples 1000 20000 20000 20000 Average 39 405 815 1096 Median 32 406 734 829 90% Line 47 750 1062 1953 Error % 0 0 0 0 Throughput (sec) 22,1 109,3 111,9 105,0 get product by id ( USER_PORTAL.getProduct) Protocol RMI RMI RMI Threads 1 50 100 Ramp-Up (sec) 0 5 5 Loops 1000 400 200 Samples 1000 20000 20000 Average 12 236 483 Median 15 156 468 90% Line 16 485 578 Error % 0 0 0 Throughput (sec) 65,3 196,7 192,1 find products for the specific searchcriteria ( USER_PORTAL.findProducts) Protocol RMI RMI RMI RMI RMI RMI RMI RMI RMI RMI RMI RMI RMI RMI RMI RMI RMI Threads 1 1 50 50 100 100 1 50 100 1 50 100 1 50 100 1 50 Ramp-Up (sec) 0 0 5 5 5 5 0 5 5 0 5 5 0 5 5 0 5 Loops 1000 1000 400 400 200 200 1000 400 200 1000 400 200 1000 400 200 1000 400 Samples 1000 1000 20000 20000 20000 20000 1000 20000 20000 1000 20000 20000 1000 20000 20000 1000 20000 Average 28 21 403 437 854 833 18 410 845 18 433 895 22 439 934 21 409 Median 31 16 391 407 797 610 16 406 781 16 390 828 16 250 797 16 375 90% Line 32 32 828 891 1672 1875 31 828 984 31 890 1047 32 906 1875 31 844 Error % 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Throughput (sec) 29,0 36,0 112,6 105,6 109,1 110,0 41,9 111,0 109,5 42,0 111,4 101,6 36,2 109,4 97,6 36,0 112,5 find order for the specific searchcriteria ( USER_PORTAL.findOrders) Protocol RMI RMI RMI Threads 1 50 70 Ramp-Up (sec) 0 5 5 Loops 1000 200 150 Samples 1000 10000 10500 Average 60 1304 1762 Median 62 1250 1594 90% Line 78 2656 3625 Error % 0 0 0 Throughput (sec) 15,9 37,0 37,5 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 8-70 get invoice by id ( USER_PORTAL.getInvoiceById) Protocol RMI RMI RMI Threads 1 50 70 Ramp-Up (sec) 0 5 5 Loops 1000 400 285 Samples 1000 20000 19950 Average 39 1029 1221 Median 46 938 1063 90% Line 47 2078 2687 Error % 0 0 0 Throughput (sec) 23,3 46,8 54,9 find invoices for the specific searchcriteria ( USER_PORTAL.findInvoices) Protocol RMI RMI RMI Threads 1 50 60 Ramp-Up (sec) 0 5 5 Loops 1000 200 170 Samples 1000 10000 10200 Average 41 1195 1384 Median 46 1125 1188 90% Line 47 2406 2578 Error % 0 0 0 Throughput (sec) 22,9 40,3 41,3 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 8-71 Appendix 9.1 Technical background for triggering the billing process Overview The billing process is intended to process orders periodically and generate invoices. After invoices are generated the auto-payment could be triggered, however the auto-payment could be triggered independently as well. As soon as the authorization is given and the billing date has been reached, the billing process iterates through all portal groups using the pessimistic locking over the portal group's billing process entry for the duration of a process. This way, no other process is able to interfere. Within a portal group, the billing process iterates through all active or locked users. Each user is processed in a new transaction so that a failure by a single user does not interrupt the whole process and other users can be processed. Within each of these transactions, the billing process collects all orders, generates a new invoice if needed, which will include the old one, if it was not yet properly balanced. Authorization The billing process could start only if all portals are authorized (once or permanent). In order to change the authorization way each portal within a portal group must call BillingServiceInterfacePortal.updateBillingProcessConfig(org.alturos.components. billing.dto.request.UpdateBillingProcessConfigPortalRequest). The billing process receives the following authorization status: • • • PERMANENT: if all portals set PERMANENT; ONCE: if at least one portal set ONCE and the rest is set to ONCE or PERMANENT; PENDING: if at least one portal set PENDING; The billing process authorization is checked after each portal's configuration update. The change of the authorization does not change the portal's authorizations, e.g. if a global authorization was PERMANENT, portal1 has PERMANENT and portal2 sets PENDING, the global authorization changes to PENDING, but portal1 still has PERMANENT. If portal2 sets it to ONCE, the global authorization changes to ONCE too. Note: For newly created portals and portal groups the authorization is always initialized with PENDING. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 8-72 Billing Date The billing date is a formal date, from which a new billing process run has to be started. This date is the next day of month, which is configured by the property BILLING_DAY_OF_MONTH. E.g., if today is the 26.07.2007 and the BILLING_DAY_OF_MONTH = 1, the next billing date will be the 01.08.2007. If the BILLING_DAY_OF_MONTH has a value, which exceeds the maximal day of month in this month, e.g. 30 in February, then the maximal day of a month will be used instead, e.g. 28 instead of 30.The time-frame between the current billing date and one day before the next billing date builds a so-called "billing period", e.g. [01.07.2007 - 31.07.2007]. Trigger For starting a billing process periodically a CronService is used. By default the trigger fires daily at the 03:00. The trigger performs practically the same call as this method does. Workflow: PortalGroup level When this workflow is started the billing process iterates over all the portal groups and checks the start conditions, i.e. the authorization and billing date. If preconditions allow, the billing process attempts to acquire a lock for this portal group, which prevents processing this group concurrently, change the portal billing process configuration, create manual invoices, etc. If a lock could not be obtained, the group processing is skipped until the next trigger, else, if a lock is acquired successfully, the billing process iterates over all active or locked users within a portal group. Each user is processed within a new transaction (see next section for details). After all users are processed, the billing process calculates the next billing process date, sets the billing process status and releases the lock. Workflow: User level The billing process collects all active orders of a user. If a user has no active orders, this user will be skipped, otherwise a new invoice is being created. If there is an invoice associated with a user, which is not properly balanced, it will be included into the new invoice, i.e. new invoice takes last one as included, the last invoice takes the new one as delegated, and the new invoice's balance is initialized as following: newInvoice.actualBalance = newInvoice.balance = lastInvoice.actualBalance - lastInvoice.total The balance of the new invoice will never change further, since it is intended to indicate the user's balance at the moment of this invoice creation. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 8-73 The actual balance is supposed to be changed by the payment. Note: The invoice is properly balanced if and only if the actual balance is equal to the total. At first, the billing process selects all the subscription orders, which duration (activeSince to activeUntil) intersects with the current billing period. Currently only subscription orders, which use the products with interval MONTHLY are supported. A new invoice line is generated from the order line, inheriting such attributes as description, product, quantity, price, etc. If a subscription order does not fully fits the billing period, e.g. activeSince is greater as period start, or a subscription order was not billed for the last billing period(s), the price is adjusted using following formula: (price / daysOfInterval) * days(max(activeSince, lastInvoice.periodEndDay + 1, activatedDate), min(processPeriodEnd, activeUntil)) where: • • • price - regular subscription price per interval; daysOfInterval - formal amount of days in interval, i.e. 30 for MONTHLY; days(startDate, endDate) - function that calculates the length of the given time-frame in days including boundaries; • • • activeSince and activeUntil - subscription duration boundaries; activedDate - is a date of the last activation of the order, i.e. by the activate order method; lastInvoice.periodEndDay - end of the last invoice period for this subscription order – usually (lastInvoice.periodEndDay + 1) points to the same date as the current period start; • processPeriodEnd – the current billing process period end; Then billing process selects all the purchase orders, where the purchase date fits into the current billing period. There are several processing variants for purchasing an order: • • NEXT_BILLING_PROCESS - the order is processed unconditionally; NEXT_SUBSCRIPTION - the order is processed only if at least one subscription order for a current user has been processed in this billing process run, but if no subscription order is being processed, this purchase order remains unfinished. Generally, one order line from a purchase order results in one invoice line, however, if more orders reference the same product using the same price it is possible that an order lines will stack into a single invoice line dependent on a product stacking mode: • • NEVER: Never stack products from different orders; STACK_AS_EARLIEST: Stack products with the same price using the earliest purchase date and its description; www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 8-74 • STACK_AS_LATEST: Stack products with the same price using the latest purchase date and its description; Then the billing process gathers all credit vouchers from the previously processed and accepted orders. For each voucher an invoice voucher line is created. All vouchers are added to the invoice's vouchers balance as following: newInvoice.vouchersBalance = lastInvoice.vouchersBalance + Σvouchers Example Let say there are following products with DEFAULT tax rates: • • • • Subscription1 for price 20 EUR Product1 for price 10 EUR Product2 for price -10 EUR and Voucher1 for 5 EUR. Let say user Test is a consumer from Austria, thus default tax-rate is 20%. Then the user has following orders: • • SOrder: 1x Subscription1 from 16.MM.YYYY until forever; POrder: 1x Product1, 2x Product2 and Voucher1; Let say for the last invoice with a 50 EUR total in whatever reason the consumer Test has paid only 30 EUR. In the next billing process 20 EUR are outstanding. The billing process starts at 01.MM.YYYY and the billing period is from 01.MM.YYYY to 30.MM.YYYY. The processing for the user Test would take the following steps: 1. A new invoice is created with: actualBalance = balance = 30 - 50 = -20; vouchersBalance = 5; Old invoice is marked as included. 2. An SOrder is found. The price is adjusted to (20 / 30) * days(16.MM.YYYY, 30.MM.YYYY) = 2/3 * 15 = 10; A new invoice line is created: Subscription1 1x 10EUR = 10EUR, from 16.MM.YYYY to 30.MM.YYYY 3. POrder is found. • • • A new invoice line is created: Product1, 1x 10EUR = 10EUR; A new invoice line is created: Product2, 2x -10EUR = -20EUR; A new voucher line is created: Voucher1 5EUR; the voucherBalance is adjusted: 10 + 5 = 15EUR www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 8-75 VATs and invoice totals The invoice totals is calculated as following: Σpositives - ΣusableVouchers + Σnegatives where: • • Σpositives - a sum of all invoice lines amounts, which reference to products with a positive price; ΣusableVouchers - a sum of vouchers usable in this invoice; it is taken from the vouchers balance with following restrictions: o o since the credit vouchers are never paid out, the sum of the usable vouchers never exceeds the Σpositives; since the voucher’s balance is never negative, the sum never exceeds the vouchers balance; Note: The voucher price is a net price, but the voucher’s amount is subtracted from the net total before taxing, thus, the gross total gets reduced proportionally. Note: By having multiple tax rates involved within an invoice, at first the invoice lines with products of the first tax rate in enumeration are reduced by the vouchers, then as they are reduced to zero, the invoice lines of the next tax rate and so on. • Σnegatives - a sum of all invoice lines amounts, which reference to products with a negative price; note that this is never positive; The calculation of VATs and invoice totals depends on the invoice calculation mode: • GATHER_GROSS_PRICES: Recommended if the invoice template shows only gross prices in the invoice lines. In this mode VAT and gross price are calculated for each invoice line, then net prices, gross prices and VATs are summarized in sub-totals grouped by the tax rate. • GATHER_NET_PRICES: Recommended if the invoice template shows only net prices in the invoice lines. In this mode all net prices are summarized in sub-totals grouped by the tax rate, then for each sub-total the VAT and the gross total are calculated. Finally, the sum of all sub-totals makes the net total and the gross total of the invoice. Whereby the taxing depends on the amount's signum, i.e. if positive, it is taxed according to the VAT tax-rates, which is taken from the product definition, if negative, it could be taxed as well using the same tax rate, but only if the user's commerce type allows it. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 8-76 Note: in case when the invoice contains positive and negative invoice lines, and due to commerce type negative are not taxed, the totals could seem confusing, because the VAT line in this case is done for the positive part only. Example Continuing the previous example we have: • • • net Σpositives = 10 + 10 = 20 ΣusableVouchers = 15 net Σnegatives = -20 We have only a single sub-total for 20% VAT, lets show how the invoice totals are calculated assuming different configurations: VAT/mode with VAT GATHER_NET_PRICES net total = (20 - 15) -20 = -15; VAT = -15 * 20% = -3; gross total = -15 -3 = -18; vouchers balance = 0 net total = (20 - 15) -20 = -15; VAT = (20 - 15) * 20% = 1; gross total = -15 + 1 = -14; vouchers balance = 0 GATHER_GROSS_PRICES net total = (20 - 15) -20 = -15; VAT = (20 - 15) * 20% -20 * 20% = 1 -4 = -3; gross total = 6 -24 = -18; vouchers balance = 0 net total = (20 - 15) -20 = -15; VAT = (20 - 15) * 20% -20 * 0% = 1 -0 = 1; gross total = 6 -20 = -14; vouchers balance = 0 Without VAT Table 5: Net and gross prices Payment overview However logically payment is not a part of the billing process, practically it could be useful to make some overview, considering it just as a next step of invoice's life-cycle. Usually a payment is created by the auto-payment process, which takes an invoice as input, creates a request to the payment system for a new payment, which amount will balance the given invoice, and then assigns the created payment with the invoice. If the payment is successful, the payment processor updates the invoice's actual balance. Usually an invoice gets balanced, but if not, or if a payment is failed, the invoice remains unbalanced/unpaid until the next auto-payment run, which could try to fix the payment or until the next billing process, which will include it into the next invoice. www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 8-77 9 Table of Figures Figure 1: portal@MAXXO Object Model...........................................................................3-22 Figure 2: profile@MAXXO Object Model ..........................................................................3-25 Figure 3: User Lifecycle Status ......................................................................................3-30 Figure 4: Mail Sending Process via JMS System ...................................................................3-35 Figure 5: billing@MAXXO Object Model...........................................................................3-39 Figure 6: Billing System Entities.....................................................................................3-43 Figure 7: MAXXO System Architecture............................................................................6-55 Figure 8: Sequence diagram of payment system .................................................................6-57 www.alturos-group.com/alturos/solutions/maxxo.html office@alturos.com 9-78