Attachment 5 EOHHS Secretariat Application Reference Manual~1.pdf

Commonwealth of Massachusetts Executive Office of Health and Human Services

EOHHS Technology Office Secretariat Application Reference Manual

Version 3.3

EOHHS Technology Office Version: 3.3

Secretariat Application Reference Manual Date: Nov 20, 2017

Revision History

Revision Date Description

1.0 02-Feb-14 Initial Revision

1.1 24-Oct-14 Updated based on revised standards and guidelines.

1.2 10-Nov-14 Updated Cloud Computing, SOA and CI guidelines

1.3 11-Nov-14 Updated Configuration Management

1.4 12-Nov-14 Updated EDM section

1.5 19-Nov-14 Incorporated the Architecture Team’s review comments

1.6 24-Nov-14 Added Governance section

1.7 26-Nov-14 Updated AIMS section

1.8 01-Dec-14 Updated the Address Validation Gateway Service, GIS, HIWay, MLS and Project Management sections

1.9 08-Dec-14 Updated the Information layer and Data security sections

2.0 07-Jan-2015 Updated MDM and HIWay sections.

2.1 07-Jan-2015 Updated Information Layer sections

2.2 17-Feb-2015 Improve Readability of some sections, Add model Data Dictionary Appendix C

2.3 02-Apr-2015

• Replaced the Governance Model Job-Aid with MassForge Link of the worksheet.

• Updated sections 4 and 8 with review comments

• Updated sections 5.5.1 – 5.5.3

• Made numerous typographical and grammatical corrections and adjustments

2.4 15-Apr-2015 Removed Cloud section (2.9.5) and inserted new VG4 Logicworks section (10.4)

3.0 30-Jun-2015 Modifications throughout many SARM sections.

3.2 31-Oct-2016 Updated versions for tools, identity federation & cloud

3.3 20-Nov-2017 Added WS Security Policy standards

Table of Contents

1. INTRODUCTION

1.1 Business Objectives

1.2 Information Technology Objectives

1.3 How this document is organized

1.4 Intended Audience

2. ARCHITECTURE

2.1 Overview

2.2 Key Design Principles

2.2.1 Think business process/service, not system/application

2.2.2 Prefer composition over inheritance

2.2.3 Adopt model-driven architecture

2.2.4 Define domain frameworks

2.2.5 Use hybrid approach for legacy application management

2.2.6 Separation of Concerns (SoC)

2.2.7 Design to achieve the best Quality of Service (QoS)

2.2.8 Build for collaboration

2.2.9 Adopt open and standards-based design

2.2.10 Treat data as a shared asset

2.2.11 Secure information

2.3 Technology Governance

2.4 Quality of Service

2.5 Access

2.5.1 XML Gateway

2.5.2 Portal Gateway

2.5.2.1 Accessibility

2.5.2.2 Usability

2.5.2.3 Security Context

2.6 Business process/composite Services

2.6.1 Service categorization

2.6.2 Service Granularity

2.6.3 Services Reusability

2.6.4 Service Orchestration

2.6.5 Service Versioning

2.7 Integration

2.7.1 Registry and repository

2.7.2 Enterprise Service Bus

2.7.3 Message Queue

2.8 Information

2.8.1 Data Format and Interoperability

2.8.2 Logical Data Modeling

2.8.3 Physical Database Design

2.8.4 Data Administration/Management

3. SECURITY

3.1 Identity and Access Management (functions)

3.2 Authentication

3.2.1 Enterprise Authorization

3.2.2 Application Authorization

3.3 Data Masking

3.4 Auditing and Logging

3.5 Application Intrusion Prevention

3.6 Security of Data at Rest and in Transit

3.7 Web Services Security

3.7.1 Transport security

3.7.2 Message-level security

3.7.3 How does it work?

3.8 Technology Standards

3.9 Federal Security Standards

4. TECHNOLOGY

4.1 Presentation Tier

4.1.1 Cascading Style Sheets (CSS)

4.1.2 Supported Browsers

4.1.3 JavaScript

4.1.4 Ajax

4.1.5 ActiveX Controls & Applets

4.1.6 Web Application Frameworks

4.1.7 Portal

4.2 Services Tier

4.2.1 Spring Framework

4.2.2 Services Framework

4.2.3 XML Data Binding

4.2.4 Service Integration

4.2.4.1 Oracle Service Bus

4.2.4.2 Rhapsody Integration Engine

4.2.4.3 IBM Data Power XML Gateway

4.2.4.4 Oracle SOA Suite

4.2.5 Persistence Framework

4.2.6 Workflow Engine

4.2.7 Job Schedulers

4.2.8 Logging and Logging services

4.3 Database Tier

4.3.1 Database Server

4.4 Reports

4.4.1 Reporting within Application

4.4.2 Reporting outside the Application

5. ENTERPRISE SERVICES

5.1 Access and Identity Management Services (AIMS)

5.1.1 Business Value:

5.1.2 Service Offerings:

5.1.3 Security Standards:

5.1.4 Technology Stack:

5.1.5 Identity Federation

5.1.6 Integration Guidelines:

5.2 Enterprise Document Management (EDM)

5.2.1 Business Value:

5.2.2 Service Offerings:

5.2.3 Technical Stack:

5.3 Member Locator Service (MLS)

5.3.1 Business Value

5.3.2 Service Offerings

5.4 HIway Service Suite

5.4.1 Business Value

5.4.2 Service Offerings

5.4.3 Integration Guidelines:

5.5 XML Gateway

5.5.1 XML Gateway Implementation:

5.5.2 Business Values:

5.5.3 Service Offerings:

5.5.4 Service NOT Offered:

5.5.5 Technology Stack:

5.5.6 Integration Guidelines:

5.6 Application Monitoring

5.6.1 Business Value

5.6.2 Service Offerings

5.6.3 Technology Stack

5.7 Address Verification

5.7.1 Business Value:

5.7.2 Service Offerings:

5.7.3 Service NOT Offered:

5.7.4 Technology Stack:

5.7.5 Integration Guidelines:

5.8 Geographical Information Services (GIS)

5.8.1 Business Value:

5.8.2 Service Offerings:

5.8.2.1 Web Service

5.8.2.2 Data Service:

5.8.3 Standard/Compliance

5.9 Quality Assurance Services

5.9.1 Business Value:

5.9.2 Service Offerings:

5.9.3 Service NOT Offered:

5.9.4 Technology Stack

5.10 Backup and Recovery

5.10.1 Business Value:

5.10.2 Service Offerings:

6. APPLICATION DEVELOPMENT

6.1 New Project Request

7. REQUIREMENTS MANAGEMENT

7.1 Overview

7.2 Requirements Gathering

7.3 Requirements Documentation

7.4 Requirements Traceability

8. DEVELOPMENT

8.1 Integrated Development Environment

8.2 XML Editor

8.3 Build Tool

8.4 Unit Testing

8.4.1 Java

8.4.2 Web Services

8.4.3 File Transfers

8.4.4 HIPAA Transactions

8.4.5 Web Page Inspection and Debugging

8.4.6 TCP/IP Monitor

8.4.7 HTTP Debugging

8.5 Code Quality

9. TESTING

9.1 Functional Testing

9.1.1 Test/Code Coverage Analysis

9.1.2 Acceptance Tests

9.2 Regression Testing

9.2.1 Web application

9.3 Accessibility Testing

9.3.1 ADA Compliance

9.3.2 Screen Reader

9.3.3 Color Contrast Testing

9.3.4 Database

9.3.5 Web Services

9.4 Performance Testing

9.5 Vulnerability Testing

9.6 Defect Tracking

9.7 Performance Monitoring

9.7.1 Application Monitoring

9.7.2 DB Monitoring

9.8 Browser compatibility

9.8.1 Supported Browsers

10. ENVIRONMENT

10.1 Application Categories

10.1.1 Enterprise Applications

10.1.2 Standard Applications

10.1.3 Application Integrations

10.2 Application Environments

10.3 Virtual Gateway

10.4 Virtual Data Center – VG4 Cloud Environment

10.4.1 Improved Hardware and Software (VG 4 Migration Project)

10.4.2 VG4 Physical and Virtual Equipment

11. RELEASE MANAGEMENT

11.1 Business Value

11.2 Service Offerings

11.3 Service NOT Offered

11.4 Technology Stack

12. CONFIGURATION MANAGEMENT

12.1 Source Control Tool

12.1.1 Main Branches

12.1.2 Supporting Branches

12.1.3 Source Control Process

12.2 Continuous Integration

13. CHANGE/RISK/ISSUE MANAGEMENT

14. CLOUD BEST PRACTICES

14.1 Cloud Design Principles

14.1.1 Scalability

14.1.2 Loose Coupling

14.1.3 Services, Not Servers

14.1.4 Databases

14.1.5 Removing Single Points of Failure

14.1.6 Optimize for Cost

14.1.7 Caching

14.2 Security

14.2.1 Cloud Security

14.2.2 Network Security

14.2.3 Identity and Access

14.2.4 Data Protection

14.2.5 Data Privacy

14.2.6 Threat Defense

14.2.7 Compliance and Certifications

15. APPENDIX A - FREQUENTLY ASKED QUESTIONS (FAQ)

16. APPENDIX B - TEMPLATES

17. APPENDIX C - DATA DICTIONARY

18. APPENDIX D - LOGICAL DATA MODELING

19. APPENDIX E – PHYSICAL DATABASE DESIGN

20. APPENDIX F – DATA ADMINISTRATION

20.1 Attribute Data Content, Type, and Size

20.2 Miscellaneous Issues with Data Types, Lengths, and Formats for various types of Data

21. APPENDIX G – CLOUD SLA

22. APPENDIX H – EHS WS SECURITY SERVICE POLICY

1. Introduction

Information Technology (IT) strategic key initiatives mandate an infrastructure based on Cloud Computing, Service Oriented Architecture (SOA) model, and consolidation of IT services at 3 organizational levels: Commonwealth, Secretariat, and Agency. It is to be a flexible infrastructure providing the foundation to fulfill the objectives listed in following sections of this document. By allowing the agencies to follow architectural/technology standards defined in this document and reuse enterprise shared resources/services within EHS, it promotes effective delivery of the EHS applications and eliminates incompatibility within the agencies.

Purpose

This document (the Secretariat Application Reference Manual (SARM) provides guidance on the standards, technologies, and tools to be utilized at the secretariat level during application development and maintenance for the Executive Office of Health and Human Service s (EOHHS). It a lso provides guidelines for application architecture to ensure that individual projects conform to the overall architectural vision for EOHHS and is based on a blueprint for standard, open, reusable, and service -oriented services. This document is intended to be used across the enterprise within EOHHS to ensure that every initiative across the enterprise achieves consistently high quality.

The Enterprise Technical Reference Manual (ETRM) published by Massachusetts Information Technology Division (ITD/Mass IT) represents the standards that all organizations are expected to adhere to within the Commonwealth. This document supplements the ETRM, inheriting anything in it and expanding and providing more details as necessary. If your business requirements cannot be met by the technologies and policies listed in this document, then the EOHHS Chief Technology Office should be consulted prior to a project architecture review.

http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/it-policies-standards-and-procedures/ent-pols-and-stnds/ent-architecture/etrm-v-5-1/

The SARM should also serve as a guide for procuring tools to be used for EOHHS IT projects.

1.1 Business Objectives

It is critical that the Information Systems (IS) organization provides all EOHHS sponsors / users with the ability to:

• Access business information faster, more economically, more securely, and more easily

• Respond to changing business and legislative environment

• Accommodate organizational restructuring

• Accommodate business growth and expansion

• Rapidly expose business services to interested parties

• Control the cost of business processes and IS development

• Accommodate existing information technology assets (legacy systems)

• Allow for cost-effective retirement of outdated systems

• Maintain quality and accuracy of information

1.2 Information Technology Objectives

In addition to always keeping the business objectives in focus, the following information technology objectives also need to be addressed:

http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/it-policies-standards-and-procedures/ent-pols-and-stnds/ent-architecture/etrm-v-5-1/ http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/it-policies-standards-and-procedures/ent-pols-and-stnds/ent-architecture/etrm-v-5-1/

• Consolidate development tools and technologies

• Improve reliability, modularity, extensibility, scalability and stability of existing and new systems

• Establish technical guidance by promoting best practices and standards

• Exploit new network computing architectures, particularly those based on Web Services standards so that future evolution of the architecture is supported

• Use packaged applications (COTS) where appropriate

• Replace obsolete and outdated technologies

• Provide integration mechanisms for non-conformant legacy systems

• Provide a repository of reusable software components that can be leveraged in projects within

EOHHS

• Provide integration mechanism for existing system to promote the concept of se rvice -oriented architecture

• Provide security requirements in order to protect the EOHHS infrastructure from unauthorized access

• Provide solutions that are based on open-standards and vendor independent implementations of those standards and specifications

• Use Open-Source Software where appropriate

• Establish a process for defining standards

• Adhere to Commonwealth IT Standards and Policies, as noted above – reference ETRM

1.3 How this document is organized

This document consists of the following sections:

Architecture – the architectural design principles and guidelines for all phases of application development by EOHHS agencies

Security – the guidelines for the Implementation and Deployment phases of the applications developed by the agencies and their vendors.

Technology – the guidelines for the Implementation and Deployment phases of the applica tions developed by the agencies

Enterprise Services – the shared and standard services available at the secre tariat level that shall be leveraged by the business services and applications developed by the agencies

Project Management – the methodology and collaboration tools for supporting the project management activities across the enterprise

Requirement Management – the methodology and collaboration tools for supporting requirements management across the enterprise

Development – the processes, best practices, and tools to be used during the development phase of applications

Testing – the types of tests to be executed and available tools for testing to ensure the quality of the applications during the testing phase of application development/maintenance

Environment – the information for categorizing the applications and choosing the correct environments for the application

Release Management – the guidelines for managing software releases

Configuration Management – the software configuration management process to be followed and the available tools for supporting the process

Change/Risk/Issue Management – the guidelines for managing project risk s, change requests, and related issues.

1.4 Intended Audience

This document is intended for the following audience:

• Business and IT leaders, who need to start and manage business/IT strategy across the enterprise

• Enterprise Architects, who need to define standards, processes, and design patterns and identify new technology, and ensure implementation compliance.

• Project Team Members, who need to map dependencies and develop a timeline that meets the business expectations

• Vendors that provide solutions in compliance with the standards defined in this document.

• Standards and Legal Teams, which need to review and understand how the applications leverage technology and standards to meet their objectives.

• Procurement Team that procures the IT tools and technologies.

2. Architecture

Due to our organizationally and functionally distributed business environment, The EOHHS architecture team recommends that the EOHHS application development teams follow the Service Oriented Architecture (SOA) design approach as a standard.

SOA:

• Allows seamless integration of the multitude of legacy applications in EOHHS and a consistent way to meet the quality of service (QoS) requirements.

• It provides building blocks for combining simple services from state, federal and partner applications into fully featured, value-added services and achieves integration and rapid development of new business offerings.

• The location-independent and functionally-decoupled attributes of a service-oriented architecture will allow flexibility in how applications are deployed.

2.1 Overview

This section presents the key design principles and guidelines for designing software architecture within EOHHS computing environment. The diagram illustrated here is a conceptual view of EOHHS specific application architecture developed using Service-Oriented Architecture (SOA) principles.

Access q XML Schema Validation q Transformation Services q HTML Presentation q Content Management q Portal Services

Business Process/Composite Services

Vertical Services

Intake Eligibility

Integration

ESB/

Message Queue

Web service Registry

Routing

Applications

Information

Q u ality O f Service Layer (Secu rity, M an agem en t & M o n ito rin

g) G o ve rn an ce

XML Gateway Portal Gateway

Contracts

Claims Processing

Treatment Planning

Transformations (XML, HL7, HIPAA, etc.)

MMIS MA-21

State

Applications

EIM-ESM

Federal Applications

Data Format/ Interoperability

Data Modeling Data Security

En terp rise Sh ared

Services

Horizontal Services

Business Rule Adapters

Mediation Domain Value

Map

Process Orchestration

Data Management

2.2 Key Design Principles

2.2.1 Think business process/service, not system/application

Orient service development around business processes so that it is possible to execute these proce sses from the business models directly through a process engine and also measure, monitor and administe r processes dynamically

2.2.2 Prefer composition over inheritance.

Wherever possible, consider composition over inheritance, particularly to improve functionality reuse.

Inheritance increases the dependency between parent and child classes, thereby limiting the reuse of child classes.

2.2.3 Adopt model-driven architecture

Insulate application architecture from the underlying technology platform by utilizing a model-driven architecture.

2.2.4 Define domain frameworks

Adopt domain frameworks so that new features can be added by using a fe w new components with minimal changes to existing code

2.2.5 Use hybrid approach for legacy application management

Adopt a hybrid approach for legacy application management involv ing both componentization and encapsulation of existing functionality, and integration of conformant systems and services.

2.2.6 Separation of Concerns (SoC)

Separate the application into distinct components with a minimum of overlap and that may operate independently. The benefit of this approach is that change to one feature or functionality for one component is independent of others

2.2.7 Design to achieve the best Quality of Service (QoS)

Use workload models, based on multiple factors, to scale systems to meet present and anticipated Quality of Service (QoS or Service Level) requirements.

2.2.8 Build for collaboration

Adopt technologies to facilitate inter-enterprise collaboration and process automation.

2.2.9 Adopt open and standards-based design

Adopt process and service standards to harmonize processes of the business domain and stre amline interactions

2.2.10 Treat data as a shared asset

Adopt technologies that allow data to be shared consistently across the enterprise, with relevant users having access to the data necessary to perform their duties

2.2.11 Secure information

Implement security measures to protect information at the network, container, and service (code) levels in order to provide for the Confidentiality, Integrity, and Availability of the data.

2.3 Technology Governance

EOHHS uses a number of software and hardware products including three different types of load balancers, multiple XML gateways, application servers, web servers, database servers, document management systems, messaging systems, enterprise service bus, different monitoring products, and various application development technologies and their associated frameworks. Given the many components mentioned, a governance framework is specified to help EOHHS support current IT systems and upcoming future IT solutions required by state and federal mandates.

Governance can be defined as the processes that assure that the appropriate policies, standards and guidelines are followed in the enterprise. It defines the chain of responsibility, authority, and communication, as well as the measurement and control mechanisms to enable people to carry out t heir roles and responsibilities in predictable manner.

There are several governance categories for an enterprise IT:

• Information Technology (IT) Governance – The processes that ensure effective and efficient use of IT solutions to enable an organization to achieve its goals

• Enterprise Architecture (EA) Governance - Ensures that projects apply prescriptive guidance provided by the EA process.

• SOA Governance - Is specifically focused on an organization’s SOA, namely Service Lifecycle , Service Metadata and Composite applications.

For purposes of immediate needs of EOHHS, we will focus on SOA Governance with a future aim to revisit the IT Governance and EA Governance aspects of governance later.

Our focus on SOA Governance addresses the following concerns

• Service registration

• Service versioning

• Service ownership

• Service funding

• Service modeling

• Service discovery and access

• Deployment of services and composite applications

• Security for services

• Processes and procedures to support service publishing and service validation

• Documenting the approach to support service lifecycle management and service reuse

• Verify that running services are the approved versions

• Define mechanism to manage SLAs for services

• Provide a mechanism to enable runtime service look-up

There are many factors to consider when defining the SOA governance plan, a comprehensive approach to implement effective SOA governance should:

• Accommodate all related EOHHS Requirements,

• Define a governance model that the EOHHS will accept and support.

• Leverage tooling to make governance operational and automated if possible or have a manual governance operational process and (or) method,

• Define various governance functions based on best practices, processes, principles, policies

• Provide a documented methodology that can be well communicated in the enterprise, i.e.

provide effective documentation to allow the whole enterprise to understand, communicate, and practice.

After initial assessment we came to a conclusion that managing service lifecycle maximizes the SOA governance value and the following governance model was created with an aim of initially executing part of this model manually to gauge its effectiveness for EOHHS.

As part of the above SOA Governance Model, a job-aid was created. Input will be applied in a spreadsheet to support this model.

Reference https://tools.hhs.state.ma.us/sf/sfmain/do/go/doc82124 https://tools.hhs.state.ma.us/sf/sfmain/do/go/doc82124

2.4 Quality of Service

Application Quality attributes are the overall factors that affect the run-time behavior, system design, and user experience for an application, and which have the potential for application wide impact across layers and tiers. Some of these attributes are related to the overall system design, while others are specific to run time, design time, or user centric issues. The extent to which the application possesses the desired combination of quality attributes, such as usability, performance, reliability, and security, indicates the success of the design and the overall quality of the software application. When designing for quality attributes, consider the following guidelines:

• Quality attributes are system properties, separate from the core functionality of the system.

• Identify key quality attributes required for your application during the design phase

• There are two types of Quality attributes: attributes that are measurable at run time

(performance, scalability etc.), and others that are measured through inspection only (reusability, extensibility etc.). Testing the applications for quality attributes and acceptance criteria for those attributes should be planned with this in mind.

• Analyze the tradeoffs between various quality attributes and work to achieve those that are most appropriate for your application

Depending on a project’s requirements, the design effort must consider all of the quality attributes listed below.

Quality Attribute

Description

Performance Ability to deliver results (throughput or bandwidth) within the least response time (latency)

Scalability Ability to cater to greater demands imposed upon the system (e.g.: support increased number of users, products) without affecting any of the other QoS parameters

Reliability Ability to function with the least occurrence of failure

Availability Ability to maximize the time when the system is available for use

Security Ability to authenticate and authorize users to provide secure access to the system in a traceable (auditable) manner

Manageability Ability to monitor and configure systems easily and detect operational characteristics related to performance and failures (remotely).

Maintainability Ability to modify the system easily, with the minimum amount of work or rework over the life cycle of the application

Extensibility Ability to make significant enhancements or changes easily.

Usability Ability to allow users to use and navigate the system easily.

Serviceability Ability to be repaired or updated easily and rapidly without affecting reliability or availability of the system.

Reusability Ability to use individual components or services in the building of unrelated modules or services

Interoperability Ability of components to work with each other regardless of their underlying platform.

2.5 Access

Client requests to access EOHHS applications and services should use either the Portal Gateway or the XML gateway. This section discusses these gateways and provides guidelines to use them.

2.5.1 XML Gateway

The XML gateway controls access to EOHHS services and data based on customizable roles and privileges, and aligns business and IT with dynamic control of se rvice level management, routing, security and performance. It provides denial of service protection, SOAP message validation; XML threat protection and XML file size validation.

XML Gateways ideally should:

1. Be purpose built platforms packaged as a tamper-proof appliance/syste m that provides high security and exceptional performance.

2. Be based on configuration driven development so they can fulfill speed-to-market use cases.

3. Simplify, secure and accelerate SOA assets development.

4. Provide xml and cryptographic acceleration at wire speed without compromised security.

For service offerings, technology stack and integration guidelines re fer to the XML Gateway under Enterprise Services section of this document.

2.5.2 Portal Gateway

The user interface portals are the client’s access to the business process composite services, util ize the enterprise content management services, and render data in HTML formats. These portals are used by the employees, agency application users and general public users. This section of this document discusses the design guidelines for developing user interface portals.

2.5.2.1 Accessibility

Below listed are some of the web accessibility best practices.

User interfaces should:

• Add introduction text contents to inform users of screen readers about the controls and tasks available in the web site.

• Add a title bar and title text for every UI zone

• Add text labels above or to the left of every control including textbox, dropdown list etc. for the convenience of screen reader.

• Add a label to every icon/image that represents an object.

• Add a colon ':' at the end of the label's text string to identify the control.

2.5.2.1.1 Web Accessibility standards

Reference: http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/tech-guidance/accessibility-guidance/web-accessibility/web-accessibility-standards.html for Web Accessibility standards defined by MassIT for further details http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/tech-guidance/accessibility-guidance/web-accessibility/web-accessibility-standards.html http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/tech-guidance/accessibility-guidance/web-accessibility/web-accessibility-standards.html

2.5.2.1.2 Audit for Web Accessibility

guidance/accessibility-guidance/web-accessibility/auditing-for-web-accessibility for auditing requirements for web accessibility.

2.5.2.1.3 Content for Web Accessibility

guidance/accessibility-guidance/web-accessibility/resources for introductory sources for creating accessible web content, Word documents, Excel documents, and PDFs.

2.5.2.2 Usability

User interfaces should:

• Have a consistent look and feel

• Have self-guiding navigation

• Be transparent to user by providing feedbacks on user’s action

• Avoid repeated requests for the same information

• Inform the user of the purpose of the fields

• Prefill default values for the forms and fields wherever possible

• Protect users from errors

• Guide users to the field that causes the error

• Perform tasks efficiently with a minimal number of user interactions.

2.5.2.3 Security Context

Security considerations include:

• Users should have single identity to access all the EOHHS applications

• Fine-grained UI field level access should prevent users from performing unauthorized tasks

• Mask sensitive information

• Restrict access to sensitive information based on user’s role

• Audit access to sensitive information

2.6 Business process/composite Services

2.6.1 Service categorization

Business Services encapsulate the high-level business functionality and offe r these capabilities to the users and other services. In the EOHHS architecture, services are categorized as Ve rtical Service s and Horizontal Services. The distinction is made depending on the scope of the service. A horizontal service is a micro-service that performs a specific fine grained functionality, where as a Vertical service represents a “macro-service” that performs coarse grained functionality by combining the functionalities of other fine-grained services.

http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/tech-guidance/accessibility-guidance/web-accessibility/auditing-for-web-accessibility http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/tech-guidance/accessibility-guidance/web-accessibility/auditing-for-web-accessibility http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/tech-guidance/accessibility-guidance/web-accessibility/resources http://www.mass.gov/anf/research-and-tech/policies-legal-and-technical-guidance/tech-guidance/accessibility-guidance/web-accessibility/resources

Horizontal Services – shouldn’t be exposed to the end-users directly. Rather, they should be used to encapsulate common functionality that may be present and utilized across different v ertica l business services. Hence, horizontal service are not “owned” by a specific business unit but instead are shared by many organizations. Examples include: Decision Services (Business Rules), Adapters (for integrating different endpoints), and Mediation Services (take care of data transformations) are a few examples of the horizontal services.

Vertical Services - Vertical business services should encapsulate core, high-level business functionality such as Contracts and Credentialing, Claims Processing, Eligibility, Enrolment and Service Delivery that are offered by the various organizational units within EOHHS.

2.6.2 Service Granularity

The Design team should use the following guidelines while deciding the granularity of a business service

• Granularity should be derived from or relate to a business function

• A business service should be defined to include sufficient scope and functionality to provide the business some value on its own.

• A business service should be defined narrow enough or focused in scope to accommodate future changes without adversely affecting other components or services.

• A fine-grained Service architecture relies on multiple fine-grained service ca lls that may offer slower performance. In order to provide better performance, consider utilizing coarse-g rained services that are comprised of multiple fine grained services.

• Consider the possibility of future changes to the underlying implementation. In general, businesses benefit from using coarse-grained facades or patterns to hide the fine-grained services beneath them. The goal is to insulate services from changes to the underlying implementation by designing them at a level of granularity that will allow for future expansion with little impact to the clients.

2.6.3 Services Reusability

Factors to consider related to reusability.

• Service should be stateless to enable it reusable. Retaining state-related data should not extend beyond a request/response on a service. Holding the state beyond the call context will affect the scalability, availability and reusability of the service since the state management will consume more resources.

• Apply design standards to make each service potentially reusable, which may result in the application being better able to accommodate future requirements with less development effort.

• Shared components/Services must be written as standalone elements that perform a task while hiding complexity.

2.6.4 Service Orchestration

During the requirements and analysis phase, the team should capture all requirements in the form of business processes that includes business rules and policies. This enables re use of them in both the business processes level and services level. A BPM tool suite provides a tool for the business analyst (For example, Oracle BPA Suite) to capture requirements, and a tool for service orchestration modeling for the architect (For example, JDeveloper with BPM extension). The service orchestration modeling tool enables the architect to develop the service orchestration or flow model for each business service or activity. Most of these tools either generate the code or create metadata for executing the logic.

Best practices for service orchestration modeling and composition include:

• Leverage the BPM tool for service orchestration modeling

• Adopt open-standards (such as BPMN) based tools for modeling and orchestration

• For better Business/IT alignment, Business analysts should be responsible for business process modeling and architects should be responsible for service orchestration modeling

• Upload all service orchestration models to the SOA repository to avoid duplicating the artefacts.

• Map each service to business activities. This is called service orchestration, and it is the lowest level of the business process.

• Architects should define the service, implementation, properties, interfaces, and bindings based on their Service Component Architecture / SCA standard. The development team should follow this service model for developing and modifying the service.

• Identify which business rules could be externalized and which could be built inside code for better performance. A rules engine should be used to interpret the rules accurately based on the runtime rule parameters.

• Identify, define, and monitor the performance of the business process services, and review their Key Performance Indicators (KPI).

2.6.5 Service Versioning

Versioning can mean different things in SOA: artifacts versioning (the usage of a versioning control system to store and manage your software artifacts), or runtime versioning (to put a different label on services that behave differently). While the two are not completely disconnected, each type of version number may be incremented independently. This section focuses on runtime versioning.

A best-practice is to include the version number in the contracts (WSDL) and message schema XSD. A good way to achieve this is to include version numbers in your namespace s. The W3C also uses this approach in the namespaces of XSLT, XSD, and so on.

• Don’t change the version number when you fix a bug during which the contract and interface will not change.

• Consider overwriting the default service version for short-lived and fully automated services if the contract and interface are backwards compatible.

• Define a versioning scheme. For example, 5.2.1, in which 5 stands for major releases, 2 for minor releases, and 1 for bug fixes.

2.7 Integration

2.7.1 Registry and repository

EOHHS has a number of services that are integrated to provide business value. It is usually impossib le for a given individual to have complete knowledge of the entire service landscape and dependencies. A registry and repository, accessible across the enterprise, should be used to publish those services with information to allow an application to utilize those services. A registry is basically a listing of all serv ice s and their key characteristics, while a repository stores important physical service artifacts such as WSDLs, XSDs, SLAs, and so on. Stakeholders can use a registry and repository to gain insight into available services and how to utilize them.

Here are some pointers on the service information that should be documented when starting an SOA initiative:

• Organize the information by service type: For example, vertical business service, and horizontal services.

• Document dependencies between services: what other services invoke a particular service? O n what other services does that service rely?

• For every service, list service name, owner, version, state (identified, in development, in production, deprecated, etc.), and description.

• For automated services, add the associated WSDLs, XSDs, and endpoint locations for e very environment.

2.7.2 Enterprise Service Bus

Enterprise Service Bus is a framework used for connectivity between service providers and requesters in an SOA that supports virtualization and management of service interactions between communicating participants.

• Location Transparency - The ESB identifies messages and routes them between interacting services. These services need not know the location of other participants in the communication.

Additional service providers to ESB can be added dynamically and messages could be routed to them without disrupting the requestors.

• Communication protocol - The ESB enables messages to flow across different end-points using transport protocols.

• Message Transformation - Requesters and providers of a service may not necessarily communicate using the same message format. The ESB can reconcile differences by transforming the messages from the requester to the form expected by the provider.

The EOHHS Architecture Team limits the choice of integration tools to Oracle Service Bus and Rhapsody.

• Oracle Service Bus should be used for simple pass-through-messaging integrations use the routing service to integrate with the services offered by internal/external Virtual Gateway and Agency applications.

• Rhapsody should be used for integrations that need transformation of messages, e.g. from HL7, and HIPAA formats to XML format and vice versa.

Use of an ESB in EOHHS should be considered when three or more applications/services are integrated.

The rest of this section lists design guidelines to be followed:

• The integration infrastructure must be accessible by all EOHHS applications within the enterprise , and by partners that need to share information with EOHHS applications.

• Consider reducing multiple numbers of integration tools/technologies, point-to-point interfaces, and data manipulation methods. This will reduce tight coupling between applications, and infrastructure and support complexities at the enterprise level.

• Consider reusing existing services always as a possible first solution and consider making the existing services available across the enterprise to reduce the duplication of services.

• Follow the enterprise security guidelines while integrating with external partners. Service run-time policies should be enforced wherever possible.

• Promote vertical and horizontal scalability to maintain the performance requirements during increased workload and during increased number of applications connected through the ESB.

Configure and control the maximum number of concurrent calls to protect the integrated applications from spikes in load.

• Consider using Message Header to send/receive routing instruction so that routing instruction is separated from message payload and payload is not tightly coupled with ESB.

• Transformation rules are common to multiple integrations, should be stored in a central registry, and should be exposed as a re-usable service.

2.7.3 Message Queue

• Consider using Message Queues for all asynchronous and parallel message proce ssing needs during the integration

• Always assign a dead letter queue to the queue manager to catch undelivered-messages that are not sent due to network or destination issues.

• Use JMS standard for promoting enterprise wide application portability.

• Build only essential data in the message with optimal message size and length to maintain performance of the application that processes the messages.

• Message persistence reduces performance and hence use Message persistence for essentia l data only

• Wherever possible, applications should be designed to read queue messages sequentially inste ad of reading by message attribute or correlation identifiers since queue manager will otherwise have to search all messages that will reduce application performance.

• Configure Message channels with disconnect interval so that they can go inactive when not-in-use to improve the performance

• Consider using standard based SOAP/JMS protocol for communication

2.8 Information

Every EOHHS application (whether developed internally or acquired) should be based on a data model created by following industry standard practices for logical data modeling and an effectiv e physica l database design utilizing standard de-normalization practices, as appropriate. All data formats, names, and lengths/precisions should be compliant with industry standard “data administration” practices. (See section 2.8.1 regarding data format and interoperability) The deliverables should include:

• A logical data model (refined at least to the third normal form – 3NF) reflecting real world objects as well as any relationships and attributes that are needed for the application processing. The documentation should consist of:

o Entity Relationship (ER) diagrams depicting the entities and relations pertinent to the application o Data Dictionary providing “meaningful” definitions and descriptions of the data that would allow other teams and outside organizations to understand what the data is and the various formats, relationships, and other details as described elsewhere in the sections / appendices on logical data modeling, physical database design, and data administration principles

• A database that performs efficiently and that should require only a minimum of changes to adapt to future changes to the underlying logical data model. It is understood that performance tuning may require de-normalization to achieve the best over-all throughput for the application, but such deviations from the logical data model should be kept to a minimum to avoid complications when applying future data model modifications.

Scope of applicability of the following guidelines

• Turnkey / COTS (common of the shelf) software that is to be used as-is. If legally feasible, before any “application” purchase, we should be provided with documentation of the data model on which the application’s database has been created (ER diagrams, data dictionaries, etc. ). Such documentation should be used in evaluating competitive products. Generic toolsets (spreadsheets, word processors, etc.) would be exempt from this requirement.

• MOTS (modified off the shelf) software adjusted for our needs. Data modeling is critical to ensure that all modifications will allow the application to accommodate our user group’s current requirements and be ready to accept possible future enhancements. The goal is to provide a robust and resilient data model that will be stable as the application is enhanced in the future and that is independent of the physical infrastructure (servers, operating system, database software, etc.).

Other considerations when purchasing, designing, or modifying an application

At the earliest possible point during project development, identify all data security requirements for the application’s data to allow the data model and database to accommodate those requirements from the start rather than re-working the model later. Identify all “sensitive” application data classifications - PII, PCI, PHI, FTI (Federal Tax Info), Domestic Violence, IIHI (Individually Identifiable Health Information), etc. More granular mapping of these classifications may be required for precise control of data when some elements must have shared access by a broader user group that lack s acce ss authorization for sensitive data classes.

Also, any regulatory or mandatory data encryption requirements should be i dentified at this time – encryption of data at rest (on the disk files), in motion (over the network), or both.

Auditing requirements for application processing and/or data should also be developed at the earliest possible point during a project to allow for the best design solution for tracking audit data. Audit data should include details on who can access such data and where, when, and how the data is to be used.

It is expected that ANY changes to an existing logical and physical database must b e coo rdinated / scheduled with all stakeholders (including both internal users as well as external organizations) b efore being implemented. This includes changes of Column Names, Data Types, Sizes, and/or Precisions.

Possible affected system components that will require related modifications include:

• Inputs (Screens, Input File Formats, SQL Queries (applications, ad -hoc, scripts, ODBC, etc. ), Interfaces from other systems, etc.)

• Outputs (Screens, Reports, SQL Queries (applications, ad-hoc, scripts, ODBC, etc. ), Output File Formats, Interfaces to other systems, etc.)

• Processing Code Changes both for the application being modified and any interfacing applications (whether internal or external to our organization).

• Existing Data Conversions – including both that application’s database as well as data in other databases that must be synchronized with the modified application database.

• Infrastructure may require capacity upgrades of disk space , machine CPU and memory, and network bandwidths – all of which may require significant lead time for purchases and implementations. Changes may affect all platforms from development through production.

• Documentation Changes

• Training for users and other teams.

2.8.1 Data Format and Interoperability

Consider the definition of interoperability as defined by one organization in the health industry – the Healthcare Information and Management Systems Society (HIMSS) website states:

Interoperability describes the extent to which systems and devices can exchange data, and interpret that shared data. For two systems to be interoperable, they must be able to exchange data and subsequently present that data such that it can be understood by a user.

The focus should be on two aspects, the success of the transfer or exchange of data , and the g reater challenge, ensuring that all parties will be able to correctly interpret or understand what the exchanged data means

To see a more detailed definition you may reference:

http://www.himss.org/files/FileDownloads/HIMSS%20Interoperability%20Definition%20FINAL.pdf http://www.himss.org/files/FileDownloads/HIMSS%20Interoperability%20Definition%20FINAL.pdf

For EOHHS / VG purposes, design decisions should give priority to utilizing industry standard data formats, over-riding those standards only when absolutely necessary (e.g. for local deviations from the standards). Some industry standard formats may be found on the web documents of g overnmental organizations, professional groups, and commercial applications documentation. Use of standard data formats will improve the interoperability of our data when other organizations are required to provide data to us or extract data from EOHHS / VG databases.

2.8.2 Logical Data Modeling

As noted in a Wikipedia reference - There are a number of benefits resulting from using a logica l data model:

• It promotes a better, cross-team understanding of business data elements and re quirements, increasing data re-use and sharing.

• It minimizes data redundancy (reducing data & business transaction inconsiste ncy), decre ases development and maintenance time and cost (by eliminating redundant data access which reduces coding).

• It establishes a consistent naming scheme (avoiding multiple names for the same data) which reduces confusion and trial and error ad-hoc and application SQL query development).

Reference (http://en.wikipedia.org/wiki/Logical_data_model#Modeling_benefits)

The consequences of utilizing a poor logical data model for applications may include:

• Increased disk processing when inserting, updating, deleting, or reporting/displaying data (some data model / physical database design impacts may result in extreme increases of I/O counts by factor of 10:1, 100:1, or more)

• Inconsistent values stored for some data details when stored in multiple places

• Inconsistent data types, resulting in:

o Difficult or impossible comparisons between two or more columns or records o Unexpected sorting results for screens and reports o Unexpected limitations of what data the application can accommodate for future enhancements (inadequate number of occurrences of some data, data lengths that require truncation of real life data values, etc.)

• Incorrectly defined keys, which require major data content updates whenever a change in data value must occur in a primary key column.

Data Dictionaries, one deliverable of the data modeling process, should include meaningful definitions of all application entities, attributes and relationships. Desirable details should include

• attribute domain details including: data types, lengths, precisions, null -ability (NULL, NOT NULL), default values, value constraints (format patterns and/or discreet lists of values),

• Entity and attribute constraints (e.g. referential integrity, unique keys, domains for attributes, etc.),

• How the data should be used, the various data stewards/owners, data retention rules, data encoding, etc.

• Mapping of data against the appropriate data classes (security or otherwise) applicable to the attribute (restricted classes such as HIPAA, PCI, etc.)

See the data dictionary model in Appendix C providing a proto-type for application data dictionaries for

EOHHS.

We request that you comply with the principles found in data modeling textbooks or the primer on data modeling found at: Data Modeling 101 at http://www.agiledata.org/essays/dataModeling101.html http://en.wikipedia.org/wiki/Logical_data_model#Modeling_benefits http://www.agiledata.org/essays/dataModeling101.html

2.8.3 Physical Database Design

Please refer to section 18, Appendix E – Physical Database Design for guidelines.

Tasks and end-products of…