ODOT Default Web Application Architecture

Filename:ODOT Web Application Architecture.doc Version: 8.0 Author: Michael Jordan Last Modified: 11/16/2017 Project Site: Document Summary:

Prepared by the ODOT Division of Information Technology (DoIT)

The Ohio Department of Transportation (ODOT) Division of Information Technology

[Document Header]

[Version], [Date] 1

Contents 1 Introduction ......................................................................................................................... 3

1.1 About This Document ..................................................................................................... 3 1.2 Document Location ......................................................................................................... 3

2 Architecture ......................................................................................................................... 4 2.1 A Layered Approach ....................................................................................................... 4

2.1.1 User Interface Layer ............................................................................................... 4 2.1.2 Domain Layer ......................................................................................................... 4 2.1.3 Service Layer .......................................................................................................... 5

3 Technologies ....................................................................................................................... 6 3.1 Microsoft .NET Platform.................................................................................................. 6

3.1.1 C# ........................................................................................................................... 6 3.1.2 ASP.NET ................................................................................................................ 6

3.2 AJAX ............................................................................................................................... 6 3.3 Third Party Libraries ....................................................................................................... 7

3.3.1 Bing Maps API ........................................................................................................ 7 3.3.2 Spring.NET – Lightweight Dependency Injection API ............................................ 7 3.3.3 ExtJs ....................................................................................................................... 7 3.3.4 log4net .................................................................................................................... 8

4 Visual Studio Projects ........................................................................................................ 8 5 How To ................................................................................................................................. 9

5.1 How to use the AdoTemplate in Spring.Net to perform database queries and transactions .............................................................................................................................. 9 5.2 How to create a Visual Studio Project template automatically using the batch program9

[Document Header]

[Version], [Date] 2

Document History Version Date Author Description 1.0 12/28/2007 Michael Jordan Initial Version 2.0 7/17/2008 Michael Jordan Removed references to the NHibernate OR mapping

framework. 3.0 6/17/2010 Michael Jordan Updated the version references of the ExtJS and Spring

libraries to current 4.0 11/4/2011 Michael Jordan Removed some additional NHibernate references. Added

additional text related to rich JavaScript business objects. Corrected some spelling issues.

5.0 10/18/2013 Michael Jordan Updated to reflect use of .Net 4.0 Updated to reflect use of ExtJs 4.X Updated to reflect use of Html5 Update Virtual Earth to Bing Maps

6 07/01/2013 Michael Jordan Updated to include both ExtJs 4.x and 5.x 7 004/27/2017 Michael Jordan Updated ExtJs 5.x and referencing SQL Server as

preferred backend database 8 11/16/2017 Michael Jordan Updated document location section

Added Technology Constraints and Appendix sections Added Architecture Justifications section Updated Ajax and ASP.Net verbiage in the Technologies section Added support for stored procedures Added Security Authentication and Authorization section

[Document Header]

[Version], [Date] 3

1 Introduction 1.1 About This Document

The purpose of this document is to describe the default architecture used in development web applications at the Ohio Department of Transportation. Many of these same concepts apply to client/server based application development as well.

1.2 Document Location The latest version of this document is available from the following site. The following table provides the website and folder location of the document.

Application Site http://portal.dot.state.oh.us/Divisions/DoIT/SoftProd/client/Software%20Development%20Practices

Document Folder http://portal.dot.state.oh.us/Divisions/DoIT/SoftProd/client/Software%20Development%20Practices/Forms/AllItems.aspx

Filename ODOT Web Application Architecture.doc

[Document Header]

[Version], [Date] 4

2 Architecture 2.1 A Layered Approach

The default architectural approach used at ODOT for web applications involves a standard 3-tiered model for partitioning application logic. The three primary layers are User Interface Layer, Domain Layer, and Service Layer. The implementation of these various layers uses the C# programming language from the Microsoft .NET platform. The use of well-defined application layers allows applications to be modified and extended without necessarily requiring significant code re-rewrites. For example by having the data access logic located in the Service layers it makes it possible to replace the implementation without necessarily requiring any changes to the user interface. The following sections provide a brief description of these application layers and an indication of the type of application logic that should be implemented within each.

2.1.1 User Interface Layer This layer contains code that is specific to the user interface interactions (i.e. responding to user event, button clicks, click on links, form submission, etc). For web application this logic will be implemented in C# as ASP.Net MVC Controllers returning Json data in response to AJAX calls from the client. When server side view logic is necessary then the system can leverage either the ASPX or (preferably) the Razor view engines. For the most part though, all view logic will be implemented using the ExtJs JavaScript framework and the server side controllers would be APIs returning Json/XML data in response to AJAX calls. Use of the ExtJs (5.x) JavaScript user interface library is required for consistency in user interface development as well as for the rich set of user interface components offer by this library. The structure of the ExtJs JavaScript files should follow the Application Architecture recommended by the ExtJs vendor: http://docs.sencha.com/extjs/5.1/application_architecture/application_architecture.html Use of Web 2.0 style development techniques (i.e. AJAX based requests) to provide dynamic client side functionality is encouraged where appropriate. This is accomplished by using the AJAX libraries built into the ExtJs JavaScript framework. Note: One caveat to this is when building a feature rich JavaScript application it may be necessary for performance reasons to build a rich client side domain model in JavaScript. In this case these JavaScript classes would be considered an extension of the Domain layer as indicated below and could contain business logic that runs client side in the browser.

2.1.2 Domain Layer This is a Visual Studio class library project that compiles to a DLL called ODOT.<app name>.Domain.dll. The core of the application requirements will be modeled as Domain objects. Domain objects are C# classes that represent the key business concepts within the application (i.e. Users, Projects, Purchase Orders, Coordinates, etc.). This layer contains the primary business logic of the application (calculations, relationships among domain

[Document Header]

[Version], [Date] 5

entities, etc). The exception to this would be business logic that spans multiple objects within a given database transaction in which case that logic would be located in a Service Layer method that would coordinate the logic required among the various domain entities. The Domain Layer is generated in its own .NET Assembly/dll which will contain all the domain entities for the application as well as interface definitions for the service layers (implemented as C# interface classes). The implementation of the service interfaces will reside in the Server Layer Assembly. By decoupling the domain layer from the service assembly we can swap out different service implementation without affecting either the Domain Layer or the User Interface Layer.

2.1.3 Service Layer This is a Visual Studio class library project that compiles to a DLL called ODOT.<app name>.Service.dll. For ODOT web applications the Service Layer contains the transactional boundaries for the application and the data access logic (Create, Read, Update, and Delete logic). The Service Layer should be generated as its own .Net Assembly and it should provide an implementation of the service interfaces defined in the Domain Layer assembly. Most of the business logic of the application should be contains within the Domain entities and the service layer should defer to the domain entities where possible. The exception being when a business use case scenario requires coordination across multiple service interfaces within a single transaction. This type of business transaction would need to lie in the service layer itself. Note that the Service Layer implementation contains the data access logic for the application. This could involve accessing Web Services, FTP processes, flat file exchange, XML repositories, etc. Whatever the backend data sources is, this is the layer the logic should be implemented in

2.2 Security – Authentication and Authorization 2.2.1 Authentication

The application will use an ODOT web service (ODOT Authentication and Authorization Service a.k.a. OAAS) for forms based authentication of the Active Directory username/password credentials for both internal and external users (e.g. Non-ODOT). The underlying users and roles will be stored as Active Directory user accounts and Active Directory Groups respectively.

The application will use HTTPS protocol to secure the forms based web interface. The application will use an ODOT website for external user registration/account

creation (e.g. MYODOT). 2.2.2 Simple Role Based Authentication and Authorization

If the security requirements for the application can be satisfied using simple security roles (e.g. Admin, Guest, Editor) then Authorization would be handled as follows

Authentication will be performed the same as described in section 2.2.1 above using the OAAS web service. The service will return an XML structure that includes a text based list of the application specific roles for the authenticated user.

[Document Header]

[Version], [Date] 6

The application will use an ODOT website (Application Security Manager a.k.a. ASM) for administering user role based permissions. The underlying users and roles will be stored as Active Directory user accounts and Active Directory Groups respectively but the application will leverage this ASM application rather than implementing a custom interface to Active Directory. Using this application new roles can be created specific to this application and user can be added to these roles.

Internally the application roles will be AD groups and the users will be AD users added to these groups but the application will not be accessing the AD objects directly. Instead the application will use OAAS service to authenticate users and get list of their roles and user the ASM website as an administrative tool to manage user role membership.

2.2.3 Complex Authorization If the security requirements for the application cannot be satisfied with simple role

based security (e.g. user permissions are assigned to specific objects with the application that are created by the application) then Authentication would still be implemented as in 2.2.1, but the application would need to implement a custom Authorization mechanism that maps AD users to permissions with the application. The details of this will vary by application, but the users will still be represented by and authenticated as Active Directory user accounts using the OAAS webs service.

3 Technologies

3.1 Microsoft .NET Platform 3.1.1 C#

C# is the preferred language on the .NET platform. 3.1.2 ASP.NET

ASP.NET is the technology used to implement the web based User Interface Layer for all ODOT applications. The recommended approach is to use ASP.Net MVC framework that exposes Json/Xml service API endpoints (either RESTful or JSON-RPC style endpoints are preferred).

3.2 AJAX AJAX (Asynchronous JavaScript and XML), or Ajax, is a group of inter-related web development techniques used for creating interactive web applications. A primary characteristic is the increased responsiveness of web pages achieved by exchanging small amounts of data with the server "behind the scenes" so that the entire web page does not

[Document Header]

[Version], [Date] 7

have to be reloaded each time the user performs an action. This is intended to increase the web page's interactivity, speed, functionality, and usability. AJAX is asynchronous in that extra data is requested from the server and loaded in the background without interfering with the display and behavior of the existing page. JavaScript is the scripting language in which AJAX function calls are usually made. Data is retrieved using the XMLHttpRequest object that is available to scripting languages run in modern browsers. The preferred data exchange format is either JSON or XML unless specific business/technical requirements require a different format (e.g. binary image files, audio files, etc.) ODOT web applications should use the ExtJs AJAX library as opposed to other third party libraries unless specific business/technical requirements require otherwise.

3.3 Stored Procedures Applications may optionally use stored procedures for data access logic where applicable.

3.4 Third Party Libraries 3.4.1 Bing Maps API

The Bing Maps JavaScript API version 8 is the recommended API for web based mapping applications at ODOT. For more information on Bing Maps API see: http://www.bing.com/api/maps/sdkrelease/mapcontrol/isdk#loadMapAsync+JS

3.4.2 Spring.NET – Lightweight Dependency Injection API In order to simplify some of the plumbing code necessary to “glue” domain objects together and to provide declarative transaction management the application should be deployed using the lightweight Spring.NET AOP container. Spring.Net allows declarative configuration of transactions without needing to use specific begin/end transaction logic as well as simplifying the use of ADO.NET in application code. It acts as an AOP container that allows dependent services to be configured declaratively. For additional information on Spring.Net see: http://www.springframework.net/

3.4.3 ExtJs

ExtJs is a JavaScript based collection of user interface components that leverage dynamic JavaScript to deliver a rich responsive user interface to end users. The library provides common user interface components such as grids, trees, dialog boxes, etc. As well as dynamic web layout management that does not have to be hand coded by the developer. Use if this library is highly recommend for all but the simplest of web applications. For additional information on ExtJs see: http://docs.sencha.com/extjs/5.1.4/index.html

[Document Header]

[Version], [Date] 8

Note: ODOT currently uses the 5.x versions of ExtJs in all new web applications; however there are still many ODOT legacy systems that use the 3.x versions of this library.

3.4.4 log4net

Log4net is a tool to help the programmer output log statements to a variety of output targets. In case of problems with an application, it is helpful to enable logging so that the problem can be located. With log4net it is possible to enable logging at runtime without modifying the application binary. The log4net package is designed so that log statements can remain in shipped code without incurring a high performance cost. It follows that the speed of logging (or rather not logging) is crucial. At the same time, log output can be so voluminous that it quickly becomes overwhelming. One of the distinctive features of log4net is the notion of hierarchical loggers. Using these loggers it is possible to selectively control which log statements are output at arbitrary granularity. For more information on log4Net see: http://logging.apache.org/log4net/

4 Technology Constraints 4.1.1 Use of ORM libraries/frameworks is prohibited

Application shall NOT make use of any ORM framework (e.g. NHibernate, Entity Framework, LINQ-To-SQL, etc.). As an alternative, applications should use SQL APIs (e.g. Spring.Net data access using AdoTemplate wrapper) that leverage direct parameterized SQL for data access logic. For additional information see Architectural Justifications 7.1 Why is the use of ORM technology prohibited?

4.1.2 Use of ExtJS for implementation of UI is required See Architectural Justifications 7.2 Why Is ODOT strict on the use of the ExtJS JavaScript framework for user interface implementation as versus alternate technologies such as: angular, react, etc.?

5 Visual Studio Projects 5.1 Reference implementation of the ODOT Web Application

Architecture A reference implementation of the ODOT Web Application Architecture be found here: \\itcfs014\Common\Development\ in the HRManager.zip file. This file contains a Visual Studio project with all application tiers represented as well as the Visual Studio project structure and the integration of the ExtJs build process with the .Net web application build

[Document Header]

[Version], [Date] 9

process. The example is self-contained and should build and run on any machine with Visual Studio 2013 or higher installed.A

6 How To 6.1 How to use the AdoTemplate in Spring.Net to perform database

queries and transactions See the Spring.NET Reference.chm user reference documentation. See specifically Chapter 20. Data access using ADO.NET.

6.2 How to create a Visual Studio Project template automatically using the batch program

A batch file has been created that runs a PowerShell script that automatically generates a standard Visual Studio Project template using the third party libraries and code structure described in this document. The batch file is located at: \\itcfs014\Common\Development\Tools\Scripts\create-odot-webapp.bat Just pass in the name of the new application and it will create the directory structure and all the Visual Studio project structure files and library references.

7 Architectural Justifications 7.1 Why is the use of ORM technology prohibited?

Our past experience with ORM products has proven this to have a higher total cost of ownership for our in house development staff. Here are our primary reasons:

• We want the developers to keep their SQL skills fresh by “owning” the SQL logic and not hiding behind an abstraction layer.

• With an ORM you have to learn yet another query language that has no standard but is proprietary to the specific ORM.

• Each ORM product has significant differences so knowledge of one is almost useless when learning another one because they are just that different. Especially in how they perform.

• Troubleshooting developer implemented SQL with DBAs is much easier. They can just send the SQL statement to our DBAs and get back an optimal version. This is much harder with ORM products because they auto-generate the SQL

• Although it is easy to build basic Create/Read/Update/Delete functionality using ORM for simple logic. When it comes to more complex logic you tend to have to

[Document Header]

[Version], [Date] 10

hand write queries using the ORM specific query language. Which begs the question why didn’t we just do that in the first place using plain SQL.

• 100% of all the projects that our architects have seen implemented at ODOT both in .Net and Java have had additional delays, technical and performance issues related to the ORM portion specifically.

7.2 Why Is ODOT strict on the use of the ExtJS JavaScript framework for user interface implementation as versus alternate technologies such as: angular, react, etc.?

All web applications eventually have to choose some framework to use for building the user interface layer. To avoid ODOT inheriting a disparate collections of various frameworks we are choosing a specific flavor. The reasons are:

• Our developers have a lot of experience building with this UI technology. This will be invaluable when we take ownership to maintain the final code base for this product.

• With the ExtJs framework we get: Extensive, detailed, searchable and professionally designed documentation:

http://docs.sencha.com/extjs/5.1.0/ Built in UI widgets (Dialogs, Buttons, Forms, Windows, Trees, etc.) and

components with a consistent look and feel: http://examples.sencha.com/extjs/5.1.0/examples/kitchensink/

Lots of code examples: http://examples.sencha.com/extjs/5.1.0/examples/index.html

Ability to create a desktop like user experience from a browser: http://examples.sencha.com/extjs/5.1.0/examples/desktop/index.html http://examples.sencha.com/extjs/5.1.0/examples/feed-viewer/feed-

viewer.html?theme=classic Responsive design support:

http://examples.sencha.com/extjs/5.1.0/examples/responsive-app/index.html Mobile platform support: https://cdn.sencha.com/touch/sencha-touch-

2.4.1/examples/

8 Appendix 8.1 Application Security Manager (a.k.a. ASM)

This is website created internally at ODOT that is used as an administrative tool for managing user role based application permissions. The application provides a web based front end wrapper around ODOT’s Active Directory infrastructure and provides acts as a common user permission administration tool across internal ODOT applications.

[Document Header]

[Version], [Date] 11

8.2 MYODOT This is an external website (https://myodot.dot.state.oh.us/) used by ODOT to allow external users to create user credentials for use with various ODOT applications.

8.3 ODOT Application and Authentication Service (a.k.a. OAAS) This is an internal web service build by ODOT that provides an http service interface for authenticating Active Directory user accounts against ODOT’s Active Directory Infrastructure. Applications use this service to implement forms based authentication.

8.4 ODOT Active Directory Infrastructure This term refers to both the internal and external Active Directory Forests that compromise the ODOT Active Directory implementation. The internal AD forest is for internal AD network users and the external forest is for external user accounts. This is implemented as two separate AD forests with a one-way trust between the internal and external forests.