![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)](https://image.slidesharecdn.com/bc9c00d9-bf7e-421e-8428-013b29410bec-150724014118-lva1-app6892/85/Synergy-My-Account-Design_3-20-320.jpg)
Synergy My Account Design_3
- 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