Synergy My Account Design_3

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

MY ACCOUNT APPLICATION DESIGN

Version 1.0

DOCUMENT CONTROL

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

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

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

MY ACCOUNT APPLICATION DESIGN

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

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

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


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


3

APPLICATION OVERVIEW

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.


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


5

Architectural Strategies

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


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


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


8

Use Cases

Overview

The following is an overview of the functionality within MY ACCOUNT.


9

Register User

The following diagrams provide the sequence of interactions between

objects involved in registering a web user in MY ACCOUNT.


10

User Login

CLIENT SIDE PROCESSING


11

GRAILS SIDE PROCESSING

Aut

hent

icat

e()

<<SO

AP>

> lo

gonW

S

Use

r det

ails

Logo

nOp(

)

MY

AC

CO

UN

T C

lient

SD: M

Y AC

CO

UN

T LO

GIN

G

RAI

LS

<<co

ntro

ller>

> Lo

ginC

ontr

olle

r <<

serv

ice>

> Se

ssio

n

/rest

/ses

sion

/logi

n

Logi

n(us

erID

,Pw

d)

Logi

n(C

olum

busT

oken

)

<<SH

IRO

>>

Subj

ect

<<SH

IRO

>>

Col

umbu

s R

ealm

<<SO

AP>

> U

serL

ogon

WS

<<SO

AP>

> B

usin

essP

artn

erW

S

Cal

l SAP

Sim

ple

Acc

ount

- Atta

ched

Web

user

Aut

hent

icat

ed

Web

user

getA

ssig

nedA

ccou

nts

getA

ssig

nedA

ccou

nts(

)

Arra

y(ac

coun

ts)

Cal

l SAP

Acc

ount

s

getB

usP

artn

er

getB

usP

artn

er

Cal

lSA

P A

rray(

acco

unts

) P

artn

ers

JSO

N R

espo

nse


12

System Architecture

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

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


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


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)


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


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


18

Development Environment

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


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


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/


21

Application Deployment

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


22

Both the server and client builds require that the developer's proxy

credentials are set correctly in the following locations:

\\Profiles\$USERID\.m2\settings.xml \\Profiles\$USERID\.grails\ProxySettings.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:[email protected]:8080/ set HTTPS_PROXY=http://$USERID:[email protected]: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

Synergy My Account Design_3

Documents

Transcript of Synergy My Account Design_3