1. S Y N E R G Y T & D B U S I N E S S P A R T N E R S H I P
MYACCOUNTAPPLICATIONDESIGN
Version1.0
2. DOCUMENTCONTROL
Author and Custodianship
Author/Title: Martin O’Donnell – Technical writer
Custodian/Title: T&T Business Partnership
Approval list
When this document is updated, the following people/teams must sign
off the final document and any updates. This document can be signed
off when requirements meet expectations and the compliance
coordinator confirms the regulatory impacts.
Name/Group Position/title Date
Amit Kumar
Dave Newman
Distribution list
When this document is updated, the following people/teams must be
notified and be granted access to the updated version (incl.
Regulatory).
Name/Group Position/title
Amit Kumar
Dave Newman
3. Reference Documents
DMS Title Description Author
3480178 OPD for My
Account
Outlines the architecture for the
existing My Account application.
Amit Kumar
3479084 PCI DSS
Compliance
Rregistration and payment
protocols used to facilitate bill
payment using BPoint.
George
Pimatti
3462939 BPoint API Payment API for BPoint Comm.
Bank
Document version history
Version Date Description Author
1 draft 1 24/11/2014 Initial complete draft Martin O’Donnell
4. M Y A C C O U N T A P P L I C A T I O N D E S I G N
T
MYACCOUNTAPPLICATIONDESIGN
DOCUMENT
CONTROL
................................................................................................
i
Author
and
Custodianship
...................................................................................................
i
Approval
list
.........................................................................................................................
i
Distribution
list
....................................................................................................................
i
Reference
Documents
.........................................................................................................
i
Document
version
history
...................................................................................................
i
INTRODUCTION
...........................................................................................................
1
In
Scope
..........................................................................................................................
1
Out
of
Scope
...................................................................................................................
1
APPLICATION
OVERVIEW
........................................................................................
3
Architectural
Strategies
............................................................................................
5
Two-‐way
Data
Binding
...................................................................................................
5
Use
Cases
........................................................................................................................
8
Overview
............................................................................................................................
8
Register
User
......................................................................................................................
9
User
Login
.........................................................................................................................
10
System
Architecture
................................................................................................
12
Overview
..........................................................................................................................
12
SAP
SOAP
SERVICES
..........................................................................................................
14
Other
Databases
...............................................................................................................
15
Development
Environment
..................................................................................
18
Source
Code
Repositories
.................................................................................................
18
Development
Tools
..........................................................................................................
20
Application
Deployment
........................................................................................
21
GRAILS
..........................................................................................................................
21
GULP
.............................................................................................................................
21
List
of
GRAILS
Controllers
.....................................................................................
23
Public
REST
API
.................................................................................................................
23
Authenticated
REST
API
....................................................................................................
24
List
of
GRAIL
Services
.............................................................................................
25
List
of
Client
Services
..............................................................................................
27
List
of
Forms
..............................................................................................................
31
List
of
SOAP
Services
...............................................................................................
33
5. M Y A C C O U N T A P P L I C A T I O N D E S I G N
T
List
of
ORACLE
Tables
.............................................................................................
36
JavaScript
Libraries
.................................................................................................
40
FormsEngine.js
.................................................................................................................
40
Other
Libraries
..................................................................................................................
46
6. M Y A C C O U N T A P P L I C A T I O N D E S I G N
1
INTRODUCTION
This document describes the elements that are integrated into the design
of the MY ACCOUNT application for the purpose of illustrating the
principal functions and components of the application.
This document is designed to be a companion for the Operational Process
Document (DMS 3480178) that was developed for the existing My Account
application. The new application
The proposed audience for this document are those persons involved in
the support and future development of this application including:
• Application Support Personnel
• Application Developers
• Application Designers
• Development Managers
• Solution Architects
In Scope
The following areas comprise the descriptive scope set by this document.
• Design elements and approach of the MY ACCOUNT web client
• Design elements and approach of the MY ACCOUNT web server.
• Configuration elements of the MY ACCOUNT web application
• Deployment elements of the MY ACCOUNT web application
• Interface mechanisms between MY ACCOUNT web application and
SAP, BPOINT and Lotus Notes
• Design of the MMA Address Search
Out of Scope
The following associated areas may be referenced in this document but are
not described here in.
• Design functionality related to SAP
• Design functionality related to Oracle DBMS.
• Design functionality related to BPOINT
• Design functionality related to Lotus Notes
.
PURPOSE
OF THIS
DOCUMENT
AUDIENCE
SCOPE
7. M Y A C C O U N T A P P L I C A T I O N D E S I G N
2
This document includes explanations of design methodologies and
principals that require a broad understanding of web application
development. While this document does provide some information on
these principals and methodologies it does so only in support of providing
context to the design of the MY ACCOUNT application and should not be
construed as a comprehensive explanation of the nuances of each design
element. It is recommended that the reader pursue other more
authoritative sources should extra information be required to facilitate a
clearer understanding of any principal or methodology mentioned in this
document.
It is also assumed that the reader has a general understanding of the
Unified Modelling Language (UML) that has been used to diagrammatically
represent the associations and relationships of design elements in the My
Account application.
ASSUMPTIONS
8. M Y A C C O U N T A P P L I C A T I O N D E S I G N
3
APPLICATIONOVERVIEW
MY ACCOUNT is a stand-alone web application that is designed to be a
replacement for the legacy My Account component integrated into the
Synergy corporate website. MY ACCOUNT offers a secure environment in
which Synergy customers can view and update their account details, pay
their bill and apply for other services provided by Synergy.
MY ACCOUNT has been designed to achieve the following objectives:
• To be easily differentiated from the Synergy corporate web site.
• Present a contemporary look and feel.
• Provide a seamless web experience. The application should appear
as native as possible with limited translation processing.
• Provide Synergy customers with the same functionality as the legacy
My Account.
• Environment neutral. The application is required to deployed to any
networked environment without having to be customised to that
environment.
The main objective in developing the MY ACCOUNT client was to provide
the user with an online experience that closely resembles a desktop
application. The main feature of such applications is the fluid operation of
the user interface (UI). Any transitions between displays are handled locally
therefore there is little if any pause between data handling and the
associated display of that data to the user. This contrasts against
traditional web applications that that rely on server side processing to
perform the bulk of the UI operations.
9. M Y A C C O U N T A P P L I C A T I O N D E S I G N
4
The user experience of such applications is dependent on the speed at
which the server supplies pages to the user’s browser. This speed can
degrade markedly if there is a poor connection between server and
browser detrimentally impacting on the use of the application. To provide
a more fluid user experience and drastically speed up the application, MY
ACCOUNT has adopted a more dynamic approach that uncouples the UI
processing from the server and hands it to the local browser.
Unlike traditional web applications that have multiple static pages as part
of the UI, MY ACCOUNT has adopted the more dynamic single page
application (SPA) approach using the AngularJS framework. This approach
provides the following advantages over the traditional web development:
• A single HTML template can be used to dynamically present
information to the user instead of employing multiple static pages.
• The application state is held on the client browser rather than the
server, meaning that the majority of data is loaded once. This limits
calls to the server to those necessary to retrieve user data rather
than DOM updates.
The main feature of the SPA approach is that a single HTML template can
be used to show information to the user. This template is divided into
segments with each segment assigned a controller. When the page needs
to be updated with new information, rather than update the whole page,
only the segment associated with the new information is updated.
This approach is not natively support on browsers but is implemented
using an extension of JavaScript called AngularJS.
The application server-side management design takes an agnostic
approach in that it is not strictly configured to any one environment but
rather presents a common configuration across any environment. The key
to achieving this design is to employ RESTful requests to and from the
server and client. However SOAP will still be required for exchanging data
with SAP so the REST calls that originate from the MY ACCOUNT client
need to be repackaged into SOAP and vice versa.
SINGLE PAGE
APPLICATION
RESTFUL
SERVER
10. M Y A C C O U N T A P P L I C A T I O N D E S I G N
5
ArchitecturalStrategies
AngularJS provides a client side model-view-controller (MVC) architecture
alongside a library of components commonly employed in rich Internet
applications. The framework adapts and extends standard HTML to
present dynamic content through two-way data binding allowing for
automatic synchronisation of models and views.
Two-way Data Binding
Fig 99: Traditional single way data binding
Traditional MVC frameworks bind data by merging the HTML template and
the model components into a view. This means that any changes to either
the model or sections of the view require the repeat of the merger to
reflect the changes. Consequently, the application developer must
manually manage this merger in the application.
Fig 99: AngularJS Two Way Data Binding
The AngularJS approach is to regard the view as a simple projection of the
model. Rather than merge the template and model together, AngularJS
enhances the traditional HTML mark-up on the template with custom
attributes that are compiled on the browser. During compilation these
ANGULARJS
FRAMEWORK
11. M Y A C C O U N T A P P L I C A T I O N D E S I G N
6
attributes as interpreted as directives to bind input and output parts of the
page to the model. Essentially, the AngularJS compiler traverses the HTML
on the template and attaches specific behaviours to elements of the DOM
“as directed”. These behaviours include event listeners that trigger a
reparsing of the template when either the model or view is update.
The result is a “live” view of the model that dynamically updates in
response to any changes. This approach places the model as the single
source of truth for the application state and places the responsibility for
managing the view into the hands of the AngularJS framework via the
browser rather than the application developer who is left to concentrate on
coding the business logic.
The two way binding is managed by the scope, an object that provides
specific data and methods to maintain a specific view. In AngularJS the
controller, rather than directly updating the model, as per the traditional
MVC architecture, initialises and augments the Scope with methods to
control the behaviour of the view. The view is updated when the section of
the template associated HTML page is
Fig 99: The use of Scope in two-way binding.
SCOPES
12. M Y A C C O U N T A P P L I C A T I O N D E S I G N
7
Representational state transfer (REST) provides a simpler mechanism for
linking networked machines based on HTTP rather than SOAP. REST
handles all CRUD (Create/Read/Update/Delete) operations as HTTP
requests. Since all platforms provide ubiquitous support for HTTP, data
can be handled through the native functionality of the browser rather than
having to formulate a SOAP envelope.
HTTP//…/apps/rest/accountAuth
Example of a RESTful service call
The REST API developed under the GRAILS MVC framework manages the
handling of REST calls from the MY ACCOUNT client.
GRAILS provides an acentric environment that does not require specific
configuration but instead uses a set of inherit conventions to impose a
standard configuration on any GRAILS-based application. This removes the
onus on the developer to define the configuration within the application in
favour of adopting a framework standard. All environment-specific
properties, such as hosts and passwords are stored on the GLASSFISH
server.
The Forms Engine is a JavaScript library that provides a platform for
implementing multi-page web forms that run inside the My Account client.
A key feature of the engine is its ability to process forms as separate sub-
flows within the engine. This allows forms to be modularized providing the
ability to create a single sequence of inputs from a collection of common
templates. The engine also supports the use of the browser’s back button
and the switching between forms.
REST
GRAILS
FRAMEWORK
FORMS
ENGINE
13. M Y A C C O U N T A P P L I C A T I O N D E S I G N
8
Use Cases
Overview
The following is an overview of the functionality within MY ACCOUNT.
14. M Y A C C O U N T A P P L I C A T I O N D E S I G N
9
Register User
The following diagrams provide the sequence of interactions between
objects involved in registering a web user in MY ACCOUNT.
15. M Y A C C O U N T A P P L I C A T I O N D E S I G N
10
User Login
CLIENT SIDE
PROCESSING
16. M Y A C C O U N T A P P L I C A T I O N D E S I G N
11
GRAILS SIDE
PROCESSING
Authenticate()
<<SOAP>>
logonWS
Userdetails
LogonOp()
MYACCOUNT
Client
SD:MYACCOUNTLOGIN
GRAILS
<<controller>>
LoginController
<<service>>
Session
/rest/session/login
Login(userID,Pwd)
Login(ColumbusTok
en)
<<SHIRO>>
Subject
<<SHIRO>>
ColumbusRealm
<<SOAP>>
UserLogonW
S
<<SOAP>>
BusinessPartnerWS
CallSAP
SimpleAccount
-AttachedWebuser
Authenticated
Webuser
getAssignedAccounts
getAssignedAccounts()
Array(accounts)
CallSAP
Accounts
getBusPartner
getBusPartner
CallS
AP
Array(accounts)
Partners
JSONResponse
17. M Y A C C O U N T A P P L I C A T I O N D E S I G N
12
SystemArchitecture
Overview
The MY ACCOUNT Application Client is a client-side MVC architecture
hosting an Internet rich, single page application. The application is
designed to be a self-service portal for Synergy customers giving them
access to conduct online services and enquiries related to their energy
account.
The MY ACCOUNT application server is responsible for managing backend
data services and persistence. All core business processes are
implemented using this interface, except for payments, whereby the
requirement for PCI compliance mandates that credit card information be
sent directly to the payment provider.
MY ACCOUNT
APPLICATION
CLIENT
MY ACCOUNT
APPLICATION
SERVER
18. M A N A G I N G T H E M A T C H I N G R U L E S
13
The MY ACCOUNT server is hosted on the GLASSFISH application server
managed under a GRAILS web application framework to provide a REST
like server environment. Built according to the MVC paradigm, GRAILS
employs controllers and services to interpret and co-ordinate
communication requests between the MY ACCOUNT client and various
databases in the Synergy network including SAP and BPOINT through the
GLASSFISH server via a JSON API.
BPOINT an external merchant receivables solution managed by the
Commonwealth Bank Group to facilitate customer payments and direct
debits. All MY ACCOUNT customer financial transactions are conducted
directly with this service in accordance with PCI compliance requirements.
For information related to BPoint and associated connections see the
following documents:
• DMS 3479084 - PCI DSS Compliance
• DMS 3462939 - BPoint Payment Connector API
SAP Netweaver is used to facilitate the exchange information between the
SAP database and external applications. In this case it is the connection
point between MY ACCOUNT and the customer account and usage data
held in SAP CRM and ISU.
Stores non-core business information relevant to the MY ACCOUNT
application.
All automated emails sent by MY ACCOUNT to its users are made through
the SMTP interface provided by the LOTUS NOTES mail server.
Grails comes bundled with its own ORM mapping system: GORM (Grails
Object-Relation Mapping). Under this system, the entity classes are simple
stored in grails-app/domainfolder and Grails uses Convention over
Configuration (along with some inline static declarations) to calculate the
mappings. Grails will actually build an entire database based on the Entity
classes present - in fact when run in development mode, Grails creates and
destroys an in-memory database each time it is run.
More detailed information related to the MY ACCOUNT system architecture
can be found in the Operational Process Document (DMS# 3480178)
GLASSFISH
BPOINT
SAP
NETWEAVER
ORACLE
RDBMS
LOTUS
NOTES
GRAILS
GORM
19. M A N A G I N G T H E M A T C H I N G R U L E S
14
SAP SOAP SERVICES
My Account connects to SAP over Netweaver SOAP -based web services.
There are 2 distinct SOAP engines:
• Netweaver Java: older web services that were written when the
originals My Account first launched.
• Netweaver PI: A newer framework that basically promotes
underlying SAP Function modules to SOAP interfaces. All new SAP
web services are implemented in Netweaver PI.
To connect to the SOAP-based Web Services, we use the Apache CXF Client
Plugin (Apache CXF is an open source web services framework)
See the Table of SOAP services for a complete list of SOAP services used by
MY ACCOUNT.
Setting Up a web service involves the following steps:
1. The WSDL is placed under the docs/ folder, which as the root level
of the Grails project
2. Configuring the web service is a matter of creating a set of
assignments using standard Grails Configuration instead a
configuration block called cxf.client
MY ACCOUNT uses the convention of storing web service configuration in
one of the following areas, which is imported into the main Grails
configuration during startup:
• grails-app/conf/wsclient/BPointWebServices.groovy The
BPoint SOAP web service is configured here.
• grails-
app/conf/wsclient/SapNetweaverWebServices.groovy SAP
Netweaver web services are configured here.
• grails-app/conf/wsclient/SapPiWebServices.groovy. SAP PI
web services are configured here
SETUP
20. M A N A G I N G T H E M A T C H I N G R U L E S
15
Sample configuration block:
cxf {
client {
def piRequestContext = [
(javax.xml.ws.BindingProvider.USERNAME_PROPERTY):
"USERNAME",
(javax.xml.ws.BindingProvider.PASSWORD_PROPERTY):
"PASSWORD"]
superDuperWS { // the web service will be injected into
Grails Controllers/Services using this name
wsdl = "docs/SuperDuper.wsdl" // the wsdl location of the
web service within the project
namespace = "synergy.apps.wsclient.superduper" // java
client stubs will be located in this package
bindingFile = "grails-app/conf/wsclient/binding.xml" //
binding file mainly to ensure Date types are converted
correctly
outputDir = "src/java"
allowChunking = true
clientInterface =
synergy.apps.wsclient.superduper.SuperDuperService // the fully
qualified Java class name of the generated client stub
serviceEndpointAddress =
"${synergy.pi.baseurl}/XISOAPAdapter/..." // location of the
web service: IMPORTANT must use ${synergy.pi.baseurl} which
changes with environment
requestContext = piRequestContext
}
... more web service definitions
}
}
Other Databases
My Account connects to SAP over SOAP for most primary purposes.
However, there are some ancillary My Account functions, such as the
Energy Saving Tips tool for which the backing data is not held in SAP.
There are 2 such databases:
• Oracle – which holds all configuration and user data for ancillary
functions in GRID and My Account.
• Apache SOLR - a local search oriented database to support uses
cases that require fast searching (e.g. Address Lookup)
21. M A N A G I N G T H E M A T C H I N G R U L E S
16
The Oracle Connection Pool is actually configured in Glassfish and
provided to the application through JNDI. The connection is registered
under this JNDI name: jdbc/Echannel. All tables are held in the
ECHANNELShema.
The following databases are used:
• Glassfish dev - SYNDEV60
• Glassfish test - SYNTST40
• Glassfish preproduction - SYNUAT42
• Glassfisg production - SYNPRD20
Apache SOLR is a search-oriented database that works by simply matching
documents to search criteria. Apache SOLR is divided into a set of
schemas; each schema holds documents of the same type. We have 4
schemas:
• grid - provides text based searching to support document searches
performed on the GRID website
• premise_address - supports single line address search for
premises
• postal_address_file - supports single line address search for postal
addresses (australia wide, including PO Boxes)
• energy_saving_tips - used as a tip recommendation engine by
matching the house profile of a user (appliances and house
features) against the house profile of a tip
For the grid schema, the data is updated when an administrator uploads
new content into GRID from Red Dot.
For the premise_address and postal_address_fileschemas, EChannel
Support updates the data manually from time to time on an ad-hoc basis.
The scripts for uploading the data are held in Subversion under the
echannel-search project.
For the energy_saving_tips schemas, the data is updated when an
administrator uses the energy saving tips admin tool to modify tips
(https://172.21.252.34:8181/apps/admin/energyToolboxAdmin/). The
current procedure is that after the business has updated the tips, Echannel
support would then login to each production server and clicks the link to
Re-index the search engine.
ORACLE
APACHE
SOLR
22. M A N A G I N G T H E M A T C H I N G R U L E S
17
Super Users are authenticated using LDAP (Synergy's main user
permissions database is LDAP). The following environment specific
properties must be set on the Glassfish server to enable LDAP connection:
ldap.url // connection url.
ldap.security.principal // connection username.
ldap.security.credentials // connection password
ldap.search.context // 'dc=synergy,dc=dmz'
ldap.group.prefix=''// either 'dev', 'test', 'uat' or 'prod'.
LDAP
23. M A N A G I N G T H E M A T C H I N G R U L E S
18
DevelopmentEnvironment
Source Code Repositories
The repository all the source code is held in subversion at the
following location:
http://subversion.synergy.int/synergy/synergydevsrc/SynergyRetailWeb/
Each repository is associated with a Synergy project. Two
repositories directly associated with the MY ACCOUNT application:
• synergy-apps
• myaccount-client
In addition there are other projects not directly associated with MY
ACCOUNT but is referenced by the application:
• echannel-search
GENERAL
LOCATION
24. M A N A G I N G T H E M A T C H I N G R U L E S
19
MY ACCOUNT has two repository projects at this location:
Synergy-apps Contains the Grails/REST server
components that runs as a web application
on Glassfish
Myaccount-client Contains the AngularJS componentts
Each project contains the following subdirectories:
/trunk Contains the production code. Each trunk relates to
s specific version of the application.
/branches Contains folders representing projects in
development. Developers only commit code to
branches.
/tags Used as a repository for adhoc code that has yet to
be committed to a project.
This repository contains source code for the Apache SOLR search
engine and has the following structure:
/dev Contains scripts for running Apache SOLR on a
developer machine.
/home . This folder gets copied to C:/GridSearch as part
of the search engine install.
/upload_script Scripts that upload the search indices for the
premise search and postal address file.
/solr.war Deployment file to Glassfish server. Content root
is “solr”.
This stores code for non-project assets and has the following
structure:
/database Resources to allow Glassfish t connect to the
Oracle RDBMS
/glassfish Glassfish environment properties.
MY
ACCOUNT
ECHANNEL-SEARCH
(APACHE SOLR
SEARCH)
ECHANNEL-
ENVIRONMENT
25. M A N A G I N G T H E M A T C H I N G R U L E S
20
/properties Glassfish environment properties.
/scripts Contains readme.txt holding information on
/glassfish and /properties.
Development Tools
No specific tools are required to develop MY ACCOUNT however It is
recommeded that IntelliJ IDEA by JetBrains be used. The ;latest version of
this application can be downloaded at the following location
www.jetbrains.com/idea/
26. M Y A C C O U N T A P P L I C A T I O N D E S I G N
21
ApplicationDeployment
The MY ACCOUNT application is deployed in two parts – the server and the
client.
MY ACCOUNT is designed to be a single page static web application so the
longest delay encountered by the user should occur when the client and
associated data is initially deployed to the browser. Consequently, any
deployment of the client will need to be optimized to minimize this delay
as much as possible. This requires the adoption of minification to
streamline the size of the deployment, minimising the number of files
involved.
When account data is first loaded, a maximum of 10-web service calls to
separate PI web services may be required. The MY ACCOUNT Server
utilizes the GRAILS Async capability to perform these tasks concurrently.
Calls for temporal data are structured in such a way that only incremental
data is requested when the user increased their date range.
GRAILS
The MY ACCOUNT Server is deployed as a standard J2EE web application in
Glassfish under the GRAILS web application framework. GRAILS provides
an acentric development environment without the developer needing to
know any configuration related to the environment. All environment-
specific properties, such as hosts and passwords are stored on the
GLASSFISH server.
The result of this build is a web application archive (WAR) file that is
opened on the host server.
GULP
GULP is an automated system builder that is use to build and optimize
the deployment of the MY ACCOUNT client including:
• Minification of Apps/Libs
• Angular optimisation
• Combining of HTML files
• Running LESS to create the CSS
The resulting WAR file is zipped and handed to TCS.
APPROACH
COMPONENTS
27. M Y A C C O U N T A P P L I C A T I O N D E S I G N
22
Both the server and client builds require that the developer's proxy
credentials are set correctly in the following locations:
Profiles$USERID.m2settings.xml
Profiles$USERID.grailsProxySettings.groovy
C:Users$USERID.npmrc
Additionally, to configure the proxy when running NPM, the proxy
credentials must be configured at the command line:
set
HTTP_PROXY=http://$USERID:$PASSWORD@pandora.synergy.i
nt:8080/
set
HTTPS_PROXY=http://$USERID:$PASSWORD@pandora.synergy.
int:8080/
Building My Account client
Before the My Account client can be built, the following commands must
be run (these just download the required packages for npm and bower)
npm install
bower install
Note that during the bower install, you maybe prompted to select which
version of a package to download (likely AngularJS and JQuery). Make sure
you select the current production versions.
• To perform a server build (creates dist/myaccount.zip)
gulp serverbuild
• To perform a dev build: (creates a runnable dev build under the
dist/ folder)
gulp devbuild
• To perform a dev build and stay in sync so that updates are
automatically deployed:
gulp devwatch
Building Synergy-Apps
Use the following command:
grails war
APPLICATION
BUILD