PL 010.pdf

TRA04.01 – Enterprise Service Bus (ESB)

Version 0.11 12/10/2019

Prepared by:

South Carolina Department of Health and Human Services (SCDHHS)

Enterprise Services (ES)

PL 010

12/10/2019 SCDHHS - Confidential Page 2 of 36

Table of Contents

1. Introduction

2. ESB in the MES Architecture

3. ESB Functions

3.1. Provide Virtual Endpoints

3.2. Route Requests

3.3. Transform Messages

3.4. Translate Protocols

4. Integrating Services (Composite Services)

4.1. The Component-Oriented Approach

4.1.1. Pipeline Patterns

4.1.2. Content-Based Router Patterns

4.1.3. Dispatcher Patterns

4.1.4. Scatter-Gather Patterns

4.2. Service Orchestration

5. ESB-Related Standards

6. ESB Adapters and Connectors

7. ESB Operations and Management

7.1. Authentication and Authorization

7.2. High Availability and Load Balancing

7.3. Auditing

7.4. Process Logging

7.5. Exception Handling

7.5.1. Mediation Exceptions

7.5.2. Endpoint Exceptions

7.5.3. Error-Handling Tasks

8. ESB Use Cases

12/10/2019 SCDHHS - Confidential Page 3 of 36

8.1. Retrieve Data from Multiple Sources

8.2. Update Member Address from Portal

8.3. SOAP/HTTP to SQL

8.4. File/FTP to Web Service

8.5. SOAP/HTTP to SOAP/JMS

8.6. File/FTP to SQL

9. Appendices

9.1. Acronyms

9.2. Referenced documents

Table of Figures Figure 1. ESB in the MES architecture

Figure 2. Role of the ESB in the MES

Figure 3. ESB virtual endpoint architecture

Figure 4. ESB one-to-one and one-to-many message routing associations

Figure 5. ESB message format conversion

Figure 6. ESB protocol translation

Figure 7. Pipeline Enterprise Integration Pattern

Figure 8. Dispatcher Enterprise Integration Pattern

Figure 9. ESB service orchestration

Figure 10. ESB distribution service

Figure 11. Mediation exceptions in ESB

Figure 12. Endpoint exceptions

Figure 13. Retrieve member data use case

Figure 14. Retrieve member documents from OnBase use case

Figure 15. Update member address from portal use case

Figure 16. SOAP/HTTP to SQL use case file://dhhs-fsredir/users/rbg24678/Documents/07%20-%20Standards/TRA04.01%20-%20Enterprise%20service%20bus%20(ESB).docx#_Toc489303550 file://dhhs-fsredir/users/rbg24678/Documents/07%20-%20Standards/TRA04.01%20-%20Enterprise%20service%20bus%20(ESB).docx#_Toc489303551 file://dhhs-fsredir/users/rbg24678/Documents/07%20-%20Standards/TRA04.01%20-%20Enterprise%20service%20bus%20(ESB).docx#_Toc489303556 file://dhhs-fsredir/users/rbg24678/Documents/07%20-%20Standards/TRA04.01%20-%20Enterprise%20service%20bus%20(ESB).docx#_Toc489303557 file://dhhs-fsredir/users/rbg24678/Documents/07%20-%20Standards/TRA04.01%20-%20Enterprise%20service%20bus%20(ESB).docx#_Toc489303564

12/10/2019 SCDHHS - Confidential Page 4 of 36

Figure 17. File/FTP to web service use case

Figure 18. SOAP/HTTP to SOAP/JMS use case

Figure 19. File/FTP to SQL use case

Table of Tables Table 1. Technologies for which the ESB has adapters and connectors

Table 2. Examples of ESB log file contents

Table of Code Examples Code example 1. Request the ESB routes based on content

Code example 2. ESB logic for content-based routing

Code example 3. Translated XML messaging formats

Code example 4. XML message converted to JSON format

Table of Standards TRA04.01-S1. The ESB will serve as infrastructure to the integration hub

TRA04.01-S2. All enterprise services may expose both a REST and SOAP interface

TRA04.01-S3. The SCDHHS ITIL framework will govern all enterprise services

TRA04.01-S4. The service level agreement will dictate the ESB service commitment

TRA04.01-S5. The ESB adheres to TRA01.02 – Access Control and Identity Management

TRA04.01-S6. The ESB application maintains availability per the SLA

TRA04.01-S7. The ESB process logs conform to the TRA01.02 – Access Control and Identity Management supplement

TRA04.01-S8. The ESB will handle mediation and endpoint errors gracefully

TRA04.01-S9. ESB services will contain design considerations for error-handling

TRA04.01-S10. Composite services maintain transactional atomicity

12/10/2019 SCDHHS - Confidential Page 5 of 36

SCDHHS expressly restricts the distribution of this document to include only those SCDHHS staff, SCDHHS processing environment contractors, or any entity given explicit access to this document with SCDHHS executive or management approval.

Intended audience

The SCDHHS Technical Reference Architecture (TRA) audience includes SCDHHS staff, trading partners, and third-party vendors who will be implementing, integrating, managing, or operating the SCDHHS Medicaid Enterprise System (MES). The SCDHHS TRA provides the reference model by which technologies and components of the SCDHHS MES will be measured for development and implementation.

This document uses the terms “service consumers” and “service providers”. In the context of Medicaid operations, the terms “service providers” or “providers” typically describes vendors who provide medical services to members. However, in the context of the ESB, and the associated web services, the terms “web service providers”, “service providers”, or “providers” interchangeably refer to a component that exposes system functionality via an interface managed by the ESB.

12/10/2019 SCDHHS - Confidential Page 6 of 36

1. Introduction The South Carolina Medicaid Enterprise System (MES) is implemented in a service-oriented architecture (SOA), which integrates system functionality in loosely coupled components. The enterprise service bus (ESB), a message-oriented middleware (MOM) solution, acts as the MES backbone, enabling components of disparate functionalities and technology platforms to communicate with each other. The ESB exposes and coordinates the functionality of the loosely coupled components as enterprise services, and performs functions, such as routing messages, transforming message formats, transforming message structures, and translating transport protocols.

This Technical Reference Architecture (TRA) supplement defines the role of the ESB in the MES and identifies the ESB features, common standards, and use cases.

2. ESB in the MES Architecture In the MES architecture, the integration hub integrates all of the enterprise applications and components using communication technologies, such as web services, messaging, and files exchanges.

The core of the integration hub—the ESB—connects to each distributed component in the MES and exposes (makes available) the functionality of these components throughout the MES.

Figure 1. ESB in the MES architecture highlights the integration points where the ESB facilitates loose coupling of MES components.

In addition to connecting distributed components in the MES, the ESB also connects to middleware applications within the integration hub. For example, the managed file transfer (MFT) application monitors Secure File Transfer Protocol (SFTP) locations and securely transfers files to the ESB.

Figure 1. ESB in the MES architecture

12/10/2019 SCDHHS - Confidential Page 7 of 36

As mentioned previously, the ESB exposes and coordinates the functionality of the loosely coupled components as enterprise services. A component can provide services and consume other services. For example, Centers for Medicare and Medicaid Services (CMS) can consume web services hosted by the ESB to exchange member account information and the CMS can provide web services used to determine constituent eligibility.

A component couples to the ESB using one or more connections. For example:

• The portal connects to the ESB using web services.

• The ESB connects to a legacy application using a database adapter/Structured Query

Language (SQL) adapter.

• The MFT application connects to the ESB using File Transfer Protocol (FTP) and web services.

Figure 2. Role of the ESB in the MES shows the connections and the ESB functions that facilitate the communication between the MES components, trading partner applications, and other applications, which can connect directly to the ESB or to other integration hub components, such as MFT and the extract, transform, and load (ETL) application. The TRA04. The Integration

Figure 2. Role of the ESB in the MES

12/10/2019 SCDHHS - Confidential Page 8 of 36

Hub supplement describes the types of services external partners can consume. The ESB functions are described in Section 3.

ESB Functions, Section 5. ESB-Related Standards, and Section 7. ESB Operations and Management.

3. ESB Functions The ESB enables the MES components to consume functionality implemented in services while being oblivious of the technical details of the components involved. As far as any particular component is concerned, it is exchanging messages only with the ESB, as if the ESB itself was the provider/consumer of the services.

The ESB also helps bridge the gaps between the provider and consumer in terms of connectivity and messaging format requirements. The ESB performs core functions at the message level to implement service transparency, and thus achieves a service-oriented architecture. The core functions include:

• Providing virtual endpoints

• Routing requests

• Transforming messages

• Translating protocols

• Orchestrating services

The rest of this section illustrates the core ESB functions using an example where a web service consumer (a trading partner) sends a message with member information to a web service provider that maintains member information (an MES component). The trading partner is the message source; the MES component is the message destination.

3.1. Provide Virtual Endpoints

The ESB provides virtual service endpoints (proxies) to service consumers and providers as shown in Figure 3. ESB virtual endpoint architecture. That is, the web service consumer makes a request of the virtualized destination (proxy) provided by the ESB. The ESB sends the request to the service provider. The service provider sends a response to the virtual endpoint (provided by the ESB) for the consumer, and the ESB sends the response to the consumer.

One benefit of virtual endpoints is that it avoids point-to-point integrations. For example, if a web service provider needs to change the physical service endpoint address or code, developers only need to update the ESB; web service consumers do not need to make a

12/10/2019 SCDHHS - Confidential Page 9 of 36 corresponding change. Likewise, if a service consumer changes the physical service endpoint address or code, service providers do not need to make the corresponding change.

Figure 3. ESB virtual endpoint architecture

3.2. Route Requests

When the service consumer sends a request to the ESB, the consumer identifies the operation to perform and the data elements required to fulfill the operation. When the ESB has a one-to-one association between the service provider’s virtual endpoint and real endpoint, the ESB routes the message to that service provider destination.

However, sometimes the ESB has a one-to-many association between the virtual endpoint and specific provider endpoints. When the ESB has multiple destinations for the same virtual endpoint, the ESB determines where to route the request based on the following:

• Message content (described in the rest of this section).

• Load balancing algorithms when the providers offer the same services (described in

Section 7.2. High Availability and Load Balancing).

• A sequence determined when setting up the composite service (described in Section

4.2. Orchestrate Services).

Content-based routing allows the ESB to forward a message to a particular service endpoint depending on the message content. Figure 4. ESB one-to-one and one-to-many message routing associations shows the consumer invoking a service that creates data entities, such as member, provider, and employee. When the service consumer invokes the createObjects service, the consumer embeds the criteria for forwarding the request in the message body or the message header. The ESB parses the message content and routes the message to the appropriate service. In the Figure 4. ESB one-to-one and one-to-many message routing associations, if the content is:

• Member-related, the ESB routes the message to the MemberCreate service.

12/10/2019 SCDHHS - Confidential Page 10 of 36

• Provider-related, the ESB routes the message to the ProviderCreate service.

• Employee-related, the ESB routes the message to the EmployeeCreate service.

Figure 4. ESB one-to-one and one-to-many message routing associations

Code example 1. Request the ESB routes based on content provides an example of a request message that the ESB parses for the data element Person Type, and then, based on the Person Type value, the ESB invokes an operation.

Code example 1. Request the ESB routes based on content http://,domainname>/ESB/createObjects "request" : { "operation”: "write", "payload”:

"Person Type”: “Provider” "First Name": "John", "Last Name": "Doe", "DOB": "1/1/1966", "SSN": 112233445, "Addr1": "123 Main st", "Addr2": "unit 4", "City": "columbia", "State": "SC", "Zip": 33333

12/10/2019 SCDHHS - Confidential Page 11 of 36

Code example 2. ESB logic for content-based routing shows the ESB routing logic.

Code example 2. ESB logic for content-based routing xmlns="http:// http://,domainname>/ESB/Route"> <route> <from uri="seda:createObjects"/> <choice> <when> <xpath>Person Type = 'Member'</xpath> <to uri="seda:MemberCreate"/> </when> <when> <xpath>Person Type = 'Provider'</xpath> <to uri="seda:ProviderCreate"/> </when <when> <xpath>Person Type = 'Employee'</xpath> <to uri="seda:EmployeeCreate"/> </when> <otherwise> <to uri="seda:DefaultCreate"/> </otherwise> </choice> </route>

3.3. Transform Messages

Frequently, the messaging formats of the consumer and provider differ, and the provider cannot process the message in the client’s native format. For example, if the consumer can only send a message in eXtensible Markup Language (XML) format and the provider can only process JavaScript Object Notation (JSON) formatted messages, the provider cannot process the message.

The ESB converts the message from source/consumer format to destination/provider format in-transit (the transformation is not persisted).

Code example 3. Translated XML messaging formats shows an XML message converted into another XML format where different XML tags enclose the data elements. Code example 4. XML message converted to JSON format shows a message formatted in XML and its conversion to JSON format.

12/10/2019 SCDHHS - Confidential Page 12 of 36

Code example 3. Translated XML messaging formats

ORIGINAL XML MESSAGE

<?xml version="1.0" encoding="UTF-8" ?> <member> <memberId>8781394960</memberId> <firstName>MYLES</firstName> <middleName>K</middleName> <lastName>MCMILLIAN</lastName> <dateOfBirth>2012-01-28T05:00:00.000Z</dateOfBirth> <socialSecurityNumber>xxxxxxxx</socialSecurityNumber> <gender>M</gender> <modifiedBy>liferay</modifiedBy> <modifiedDate>10/27/2016</modifiedDate>

<SOURCE>UI</SOURCE>

</member>

TRANSLATED XML FORMAT

<memberInfo> <memId>8781394960</ memId > <fName>MYLES</fName> <mName>K</ mName > <lName>MCMILLIAN</lName>

<DOB>2012-01-28T05:00:00.000Z</ DOB >

<SSNr>xxxxxxxx</ SSNr > <gen>M</gen> <lastModifiedBy>liferay</lastModifiedBy> <lastModDate>10/27/2016</ lastModDate > <src>UI</src> </memberinfo>

Code example 4. XML message converted to JSON format

ORIGINAL XML MESSAGE

<member> <memberId>8781394960</memberId> <firstName>MYLES</firstName> <middleName>K</middleName> <lastName>MCMILLIAN</lastName> <dateOfBirth>2012-01-28T05:00:00.000Z</dateOfBirth> <socialSecurityNumber>xxxxxxxx</socialSecurityNumber> <gender>M</gender> <modifiedBy>liferay</modifiedBy> <modifiedDate>10/27/2016</modifiedDate>

<SOURCE>UI</SOURCE>

</member>

MESSAGE CONVERTED INTO JSON FORMAT

"member": { "memberId": "8781394960", "firstName": "MYLES", "middleName": "K", "lastName": "MCMILLIAN", "dateOfBirth": "2012-01-28T05:00:00.000Z" "socialSecurityNumber": "xxxxxxxx", "gender": "M", "modifiedBy": "liferay", "modifiedDate": "10/27/2016", "SOURCE": "UI"

Figure 5. ESB message format conversion shows the ESB receiving a Simple Object Access Protocol (SOAP) request message in an XML format and converting it to a Representational state transfer (REST) message in JSON format. The ESB receives the response in JSON format and converts it to XML format before sending the response to the consumer.

Figure 5. ESB message format conversion

12/10/2019 SCDHHS - Confidential Page 13 of 36

The ESB also supports the following conversions:

• Electronic Data Interchange (EDI) to XML

• Flat file to XML

3.4. Translate Protocols

When setting up the integration, the consumer and provider do not need to make significant changes to their native code to support the integration because the ESB can translate protocols for them. In addition, changes to the consumer communication protocol do not require subsequent changes to the service provider; changes to the provider communication protocol do not require changes to the service consumer.

The ESB enables consumers and providers to choose a communication protocol based on factors, such as:

• Technological limitations of the source platform

• Requirements to leverage the existing code base

• Enterprise preferences or constraints.

In the example illustrated in Figure 6. ESB protocol translation, the consumer can only Figure 9.

ESB service orchestration communicate using web services, and the provider communicates in Java Database Connectivity (JDBC). In this situation, the ESB converts the protocol, taking messages from the consumer in web service format and sending/executing SQL commands to the provider using a database adapter. See Section 8.3. SOAP/HTTP to SQL, Section 8.4. File/FTP to Web Service, Section 8.5. SOAP/HTTP to SOAP/JMS, and Section 8.6. File/FTP to SQL for additional supported protocol translations.

Figure 6. ESB protocol translation

4. Integrating Services (Composite Services) Using distinct routing, translation, and transformation services to support the disparate MES data sources and consumers could violate the loose coupling concept of MES SOA. That is, one message routed from a provider to a consumer may require a different transformation than

12/10/2019 SCDHHS - Confidential Page 14 of 36 another message routed between the provider and consumer, while routing the same message to a different consumer may require different protocol. Instead of creating unique services with specific features to support each instance, the ESB offers integration, or composite services.

4.1. The Component-Oriented Approach

Components can perform a range of small, useful, flexible operations between a consumer and a service provider. Typically, component services implement Enterprise Integration Patterns (EIP) independent of the service descriptions (WSDL and others). Using the EIPs, developers combine business applications (consumers and service providers) into a composite service. EIP components include:

• Pipe patterns—a single event triggers a sequence of processing steps, each performing a specific function. The EIP component sequences the calls.

• Content based router patterns—the EIP component examines the message content and routes the message onto a different channel, based on data contained in the message.

• Message dispatcher patterns—the EIP component sends the message to a list of service providers (multipoint).

• Scatter gather patterns—the EIP component routes a request message to a number of service providers, and then aggregates the responses into a single response message.

4.1.1. Pipeline Patterns

A composite service using the pipeline pattern sequentially sends an incoming message to several services, as illustrated in Figure 7.

Pipeline Enterprise Integration Pattern. First, the composite service sends the message to the first consumer, and then the composite service sends the first consumer’s response to the second consumer. Continuing, the composite service sends the second consumer’s response to the next, and so on.

Figure 7. Pipeline Enterprise Integration Pattern

12/10/2019 SCDHHS - Confidential Page 15 of 36

A consumer always sends the same message structure to the pipeline composite service, which is a proxy to the real service. When the service needs to change, the composite service sends the consumer message first to an XSL transformation (to adapt the consumer's message to the new service format), then it sends it to the new version of the service.

4.1.2. Content-Based Router Patterns

Section 3.2. Route Requests describes the ESB function to route requests, including routing based on the message content. Section 4.1.1. Pipeline Patterns describes how the ESB can sequence the delivery of a message to many services. The content-based router EIP tests the name of the item in the message, and sends the message to the correct services. Because each service may define a different format, the ESB may have to perform different transformations before sending the message to the correct service. To accommodate this need, the content-based router pattern integrates routing services and pipeline patterns.

4.1.3. Dispatcher Patterns

Another composite service could dispatch a request to several services (multi point communication). For example, when the member eligibility system determines a member no longer qualifies for Medicaid benefits, multiple services need notification of that eligibility change. The composite service build on the dispatcher pattern integrates notification to all consumers, as shown in Figure 8. Dispatcher Enterprise Integration Pattern.

4.1.4. Scatter-Gather Patterns

The use case described in Section 8.1. Retrieve Data from Multiple Sources demonstrates a composite service that routes a request to multiple providers, and then, aggregates the responses into a single response message. In the use case, the user queries MES for a member’s details, and the SCDHHS portal displays all the available data, including links to documents in OnBase.

Figure 8. Dispatcher Enterprise Integration Pattern

12/10/2019 SCDHHS - Confidential Page 16 of 36

4.2. Service Orchestration

Trying to build complex composite services with a limited number of EIPs may result in scattered and over-designed configurations. With orchestration, the ESB coordinates and arranges multiple services exposed as a single aggregate service. Developers can combine loosely coupled services across different enterprise applications into a single composite service.

The ESB can then expose this composite service to applications to perform a series of different, but related functions in one request.

For example, illustrates how the ESB orchestrates services when a member applies for benefits.

The figure depicts the following sequence of events:

• The member enters all required information in a client browser (portal) and submits the application.

• The portal calls the EligibilityAndEnrollmentRequest service of the ESB and waits for a response.

• The ESB in turn, breaks the application data into smaller fragments and orchestrates the calling of each of the services (exposed by partner applications) that comprise the EligibilityAndEnrollmentRequest service. The services exposed by partner applications include:

1. Get member demographic information.

2. Get member household composition.

3. Get member eligibility history.

4. Get member supporting documentation.

5. Verify member income.

6. Determine member eligibility.

• The ESB returns a list of potential benefits for which the member is eligible and can be enrolled in to the client browser (portal).

12/10/2019 SCDHHS - Confidential Page 17 of 36

Figure 9. ESB service orchestration

5. ESB-Related Standards This section identifies standards that apply to the ESB component of the MES.

TRA04.01-S1. The ESB will serve as infrastructure to the integration hub.

All enterprise services will be exposed through the Integration hub. The ESB provides the infrastructure to the Integration hub and facilitates web services, ETL and MFT services.

Different business and data services across the enterprise will be exposed through the integration hub using the ESB.

Direct calls to services exposed through an application server are explicitly discouraged and require enterprise architecture approval with specific reasons why the integration hub and the ESB cannot be used.

TRA04.01-S2. All enterprise services may expose both a REST and SOAP interface.

Proxy services exposed through the ESB may expose both a REST and SOAP interface, according to the specifications outlined in the TRA04.02 - Web Services supplement.

TRA04.01-S3. The SCDHHS ITIL framework will govern all enterprise services.

12/10/2019 SCDHHS - Confidential Page 18 of 36

All enterprise services exposed outside SCDHHS via the ESB will managed within the Enterprise Service Catalog and configuration management database and delivered in alignment with SCDHHS ITIL Service Operations processes.

TRA04.01-S4. The service level agreement will dictate the ESB service commitment.

Service level agreements will be established for each business and data service according to the design of the service. Information technology (IT) service management tools use these services level agreements to monitor performance according to the SCDHHS IT Infrastructure Library (ITIL) policies.

6. ESB Adapters and Connectors To connect to applications built on diverse platforms with varied communication mechanisms, the ESB implements software components commonly referred to as adapters and connectors.

An adapter is a driver that enables the ESB to connect to various kinds of endpoints, such as databases, files servers, message queues, etc. A connector enables the ESB to interact with a third-party product functionality and data, for example, connectors allow the ESB to interact with the application programming interfaces (API) of services, such as SAP, LDAP, MQ series, etc.

The adapters and connectors provide the infrastructure to automate the integration of enterprise applications. Table 1. Technologies for which the ESB has adapters and connectors lists the technologies for which the MES ESB has adapters and connectors.

Table 1. Technologies for which the ESB has adapters and connectors

Technology Description

File/FTP The ESB supports receiving and sending files from and to data sources.

For inbound data, the ESB FTP adapter service reads data from a local or remote file system, transforms the file data into an XML / JSON message, and sends the message to the ESB for further processing.

For outbound data, the FTP adapter transforms the contents of an XML / JSON message to a text file, and writes the text file to a local or remote file system.

12/10/2019 SCDHHS - Confidential Page 19 of 36

Technology Description

SQL/database The ESB supports direct access to the database of a data source. The data source provides database access with appropriate rights to the ESB.

For inbound data, the ESB SQL adapter sends an XML / JSON message to the ESB when a SQL insert, update, or delete operation is performed against a database.

For outbound data, the SQL adapter transforms the contents of an XML / JSON message into a SQL insert, update, or delete operation on the target database.

JMS The ESB supports sending and receiving XML messages using Java Message Service (JMS) queues.

For inbound data, the ESB JMS adapter listens on a JMS destination (queue or a topic) and forwards incoming messages to the ESB.

For outbound data, the JMS adapter writes messages from ESB to a JMS queue.

HTTP The ESB supports sending and receiving XML/ JSON messages directly via an HTTP endpoint.

For inbound data, the ESB provides a web server address that connecting applications can send messages to (using GET, POST, UPDATE, DELETE methods). The web service receives the message and forwards it to the

ESB.

For outbound data, the web service writes messages to an HTTP endpoint.

SMTP/email The ESB supports sending emails over the Simple Mail Transfer Protocol

(SMTP).

The SMTP adapter subscribes to messages from the ESB, converts the messages into email messages, and sends them using the configured SMTP server. The adapter supports setting the body of the ESB messages as the subject, body, or attachment of the email. The adapter can also retrieve emails from the mail server.

12/10/2019 SCDHHS - Confidential Page 20 of 36

Technology Description

Custom third-party connectors

The ESB supports out-of-the-box connections with many industry-leading third-party applications.

Custom connectors support seamless connections with other commercial off-the-shelf (COTS) applications, such as SAP, PeopleSoft, etc. These adapters can directly connect to the business layers and data layers of third-party applications using prebuilt web services.

7. ESB Operations and Management The ESB does not expose operation and management features as services to components;

however, the following are critical for the successful implementation of the ESB in the MES:

• Authentication and authorization

• High availability and load balancing

• Process logging and error logging

• Exception handling

• Monitoring and tracking

7.1. Authentication and Authorization

TRA04.01-S5. The ESB adheres to TRA01.02 – Access Control and Identity Management.

The ESB supports open industry standards for ensuring the integrity and privacy of communications and ensuring that only authorized users can access the functions exposed by the ESB. The MES ESB adheres to the standards outlined in the TRA01.02 – Access Control and Identity Management supplement. The integration hub, which contains the ESB, also encapsulates the identity and access management (IAM) framework as an enterprise service.

7.2. High Availability and Load Balancing

TRA04.01-S6. The ESB application maintains availability per the SLA.

Components depend on the ESB to consume and provide services to the rest of the MES components. While the ability to connect with different application is one of the key strengths of an ESB, if the ESB becomes unavailable, the availability of all other components/applications is affected. Therefore, it is of upmost importance that the ESB application maintains availability per the SLA.

12/10/2019 SCDHHS - Confidential Page 21 of 36

Clustering is the key method to achieve high availability. Clustering refers to the practice of deploying additional components capable of taking over the responsibilities if one or more components fail. Instead of waiting for the failure to resolve, current transactions automatically transition from the failed component to the backup (often referred to as a failover node) until the failure is resolved.

The MES uses some services more heavily in the day-to-day business flow. For example, MES users create members throughout every day; however, users rarely update existing addresses.

Therefore, the MES frequently invokes createMember services and sporadically invokes updateAddress services.

To handle the volume of requests for heavily used services, the MES provides multiple instances—multiple service endpoints—and distributes service requests across the multiple instances to balance the workload. Figure 10. ESB distribution service illustrates how the ESB distributes service requests, routing them to various endpoints using built-in load balancing algorithms.

Figure 10. ESB distribution service

7.3. Auditing

Audit trails keep track of the changes and transactions occurring in the system. The MES ESB tracks:

• Configuration changes: The ESB provides an administrative console to view and access the history of configuration changes to the ESB application.

• Message flows: The ESB application creates persistent files of the messages that flow across the pipeline.

12/10/2019 SCDHHS - Confidential Page 22 of 36

• User sessions and account logins: The ESB application keeps track of the users who log into the application and stores their session details, such as the message exchanges and services consumed.

Audit trails also support the log/audit requirements of regulations such as, the Health Insurance Portability and Accountability (HIPAA) §164.308(a)(1)(ii)(D): Security Management Process to implement policies and procedures to prevent, detect, contain, and correct security violations, including, implementing procedures to regularly review records of information system activity.

7.4. Process Logging

The ESB generates logs that document events, such as access requests and errors. Logs provide audit trails for accountability and for technical diagnostics. The ESB application contains a mechanism to configure:

• The level of detail logged, which defines the amount of details stored in the log file/tables.

• The log format, such as tables, XML files, and text files.

TRA04.01-S7. The ESB process logs conform to the TRA01.02 – Access Control and Identity Management supplement.

Audit trails ensure that SCDHHS can trace actions on the MES back to the responsible individuals. The TRA01.02 – Access Control and Identity Management supplement addresses audit trail topics, such as determining:

• The minimum set of events and/or transactions that must be logged

• Data capture and storage requirements

• Review, reporting, and analysis requirements

• Log/audit data retention and archival requirements

Log files never contain protected information, such as protected health information (PHI).

Table 2. Examples of ESB log file contents provides examples of information captured in ESB log files .

Table 2. Examples of ESB log file contents

Category Description

Date and time The date and time the message was generated. This reflects the local time zone.

12/10/2019 SCDHHS - Confidential Page 23 of 36

Category Description

Organization ID The organization identification or a unique description for the originating component.

Instance ID The name of the ESB instance or server name to which the component that originated the message belongs.

Component ID The identification of the component that originated the message.

Message ID The identification that uniquely identifies the message within the component. The identification consists of a prefix that represents the component, followed by a dash, then a number.

Error message The text of the error message.

Error type The type of error message, for example, ERROR, WARNING, NOTIFICATION, TRACE, and UNKNOWN.

Error message level The error message level, represented by an integer value that qualifies the message type. Possible values are from 1 (highest severity) through 32 (lowest severity).

Network address The network address and name of the host where the message originated.

Process ID The identification of the process or execution unit associated with the message.

User ID Identification of the user whose execution context generated the message.

7.5. Exception Handling

The range of components connected to the ESB increases the complexity of error handling for the ESB. Errors can occur in the ESB internal application processing (mediation errors) and in remote applications to which the ESB connects (endpoint errors). The MES requires programmed routines to handle mediation and endpoint errors gracefully, without crashing the MES or its related components.

12/10/2019 SCDHHS - Confidential Page 24 of 36

TRA04.01-S8. The ESB will handle mediation and endpoint errors gracefully.

7.5.1. Mediation Exceptions

After the ESB receives a message, the ESB performs actions (such as formatting, protocol conversion, data mapping, etc.) on the message. See Section 3. ESB Functions for more information on these functions. Mediation exceptions are exceptions that occur at the ESB.

Examples of mediation errors at the message level include:

• Invalid data format of the input request to the proxy service, such as a malformed XML.

• Request message data not matching rules expected by the proxy business service, such as an invalid member type.

• A web service invocation returning a fault message defined on its Web Service Definition

Language (WSDL) interface, for example, the supplied memberId is invalid.

Figure 11. Mediation exceptions in ESB illustrates a mediation exception that occurs when the ESB identifies that the consumer request message contained an invalid XML structure and an invalid member type.

Figure 11. Mediation exceptions in ESB

7.5.2. Endpoint Exceptions

The ESB sends request messages to service-providing components on behalf of other components. These service providers may or may not handle potential errors gracefully.

Regardless of the nature of the error responses from these service providers, the ESB handles the error responses such that the component waiting on the response does not crash.

Endpoint error examples include:

• Web service invocation failure errors, such as an HTTP 404 status code response indicating that the target service is unavailable.

• Database-update-fail errors, indicating that the database manager is offline.

12/10/2019 SCDHHS - Confidential Page 25 of 36

Figure 12. Endpoint exceptions demonstrates endpoint exceptions where the exception occurs at the provider, and the provider sends the error response messages to the ESB. The ESB sends the same error message to the consumer, in a format the consumer understands.

Figure 12. Endpoint exceptions

7.5.3. Error-Handling Tasks

In general, depending on the requirements of the solution, the ESB error-handling process performs a combination of the following tasks:

• Retrying to invoke the service after a predefined time period for fixed number of times.

• Propagating/reporting an error back to service consumer.

• Tracing the error-causing data in a system log for diagnostic purposes.

• Emailing an administrator to report the specific errors.

• Logging an invalid service request in the log file or database tables.

TRA04.01-S9. ESB services will contain design considerations for error-handling.

The minimum set of data stored in the logs includes:

• Error code

• Error message

• Error detail

• Error-causing component

• Request message

• Response message

TRA04.01-S10. Composite services maintain transactional atomicity.

The ESB orchestrate service invokes multiple services that may insert/update database. Data is updated permanently only after all the services are successfully executed. If any service is

12/10/2019 SCDHHS - Confidential Page 26 of 36 failed, all these services data updates will be roll backed to the previously committed state and leave the system in a consistent state prior to failureMonitoring and Tracking

The ESB provides tools, such as administration web pages and application consoles to monitor, track, and manage the runtime parameters of all service instances. For instance, ESB administrators can:

• See request messages to the ESB proxy business services.

• See the status of service instances (processing, completed, error, or waiting).

• Use the ESB tools to manage and influence the completion of a service flow. For example, an administrator can resubmit a failed service request.

• Collect and view runtime statistical information about job sequences, proxy services, and service endpoints, which provides a simple but effective way of determining the runtime performance of the ESB.

• Use the collected statistical data to analyze network traffic patterns.

• Use the collected statistical data to estimate the service load and the rate of use.

8. ESB Use Cases This section provides the following examples of using the ESB:

• From the portal, retrieving member data from multiple sources

• Updating a member’s address from the portal

• SOAP/HTTP to SQL

• File/FTP to web service

• SOAP/HTTP to SOAP/JMS

• File/FTP to SQL

8.1. Retrieve Data from Multiple Sources

This use case demonstrates the flow of data and the function of the ESB when a user retrieves a member address in the portal. The user queries for a member’s details and the portal displays all the available data, which includes links to documents in OnBase. When the user clicks on the link, the portal displays the document. Figure 13. Retrieve member data use case illustrates the steps involved in querying member details from the portal.

12/10/2019 SCDHHS - Confidential Page 27 of 36

Figure 13. Retrieve member data use case

1. The user logs into the portal application, enters a member’s unique information, such as the MemberId or Social Security number (SSN), and submits the query for the member.

2. The portal sends a request message in REST/JSON format to the virtual endpoint provided by the ESB to invoke the GetMemberDetails proxy business service.

3. The ESB:

a. Receives the message.

b. Decides to use the RetrieveMemberInfo web service to execute the request.

c. Converts the input message sent by the portal into JSON format and sends the request message to the database using HTTP GET method.

4. The ESB routes the message to the EDS RetrieveMemberInfo service endpoint.

5. The ESB receives a JSON/XML response from the EDS.

6. The ESB:

a. Transforms the response message received from the EDS into a format defined by the GetMemberDetails proxy service.

b. Sends the web service response message to the portal in REST/JSON format.

7. The portal receives the response from the ESB, parses the response message, and displays the data, including links to the member’s document in the portal web page.

12/10/2019 SCDHHS - Confidential Page 28 of 36

Figure 14. Retrieve member documents from OnBase use case illustrates the steps involved in viewing the documents from OnBase.

Figure 14. Retrieve member documents from OnBase use case

1. The portal sends a web service request message in REST/JSON format to the virtual endpoint provided by the ESB.

2. This message invokes the GetOnbaseDocument proxy business service provided by the

ESB.

3. The ESB:

a. Receives the message.

b. Decides which web service corresponds to the GetOnbaseDocument proxy service.

a. Transforms the input message into a SOAP-based request message format.

b. Routes the message to the OnBase GetDocument service endpoint.

4. OnBase receives a SOAP request.

5. The ESB receives the SOAP response from OnBase.

6. The ESB transforms the response message received from OnBase into a format defined by the GetOnbaseDocument proxy service.

7. The portal receives the response from the ESB and displays the document in the portal.

8.2. Update Member Address from Portal

This use case demonstrates the flow of data and the function of the ESB when a user updates the member address in the portal. When the user saves the address in the portal, the backend service UpdatememberAddress validates the new address entered by the user, updates the EDS, and then updates all the systems of record, such as the Medicaid Eligibility Determination

12/10/2019 SCDHHS - Confidential Page 29 of 36

System (MEDS), MMIS, and Cúram.

Figure 15. Update member address from portal use case illustrates this use case.

1. The user logs into the portal application, updates the member address, and saves the updated address.

2. The portal application sends a request message in REST/JSON format to the proxy business service UpdateMemberAddress provided by the ESB.

3. This message invokes the proxy business service UpdateMemberAddress provided by the ESB.

4. The ESB receives the message and determines that executing this proxy service requires executing three separate business services described in steps 5 - 7.

5. The ESB invokes United States Postal Services (USPS) address validation web service, which includes:

a. Transforming the input message sent by portal into a SOAP XML request message format (as described in the USPS web service

WSDL).

b. Routing the message to the USPS address validation service endpoint.

c. Receiving a validation response from USPS address validation service.

6. The ESB invokes the EDS web service to update the address, which includes:

a. Transforming the input message sent by portal into a HTTP PUT method request message format.

b. Routing the message to the EDS update address service endpoint.

Figure 15. Update member address from portal use case

12/10/2019 SCDHHS - Confidential Page 30 of 36

c. Receiving the confirmation response from the EDS.

7. The ESB updates source systems using SQL, which includes:

a. Transforming the input message sent by portal into an SQL command.

b. Routing the SQL command to the source system databases.

8. The ESB sends address update confirmation to the portal.

8.3. SOAP/HTTP to SQL

Legacy applications may not be able to expose web interfaces to other applications in the enterprise, due to, for example, limitations in the platform technology or technical team.

However, the ESB can expose proxy services, which the MES components can invoke to communicate with the legacy system, as illustrated in Figure 16. SOAP/HTTP to SQL use case.

Figure 16. SOAP/HTTP to SQL use case

The service design phase includes the following:

1. The provider/target shares the following database connection parameters with the ESB:

database host, database name, port, service ID, and password. The ESB uses the SQL adapter to connect to the database.

2. The ESB creates a proxy CRUD (create, read, update, and delete) service layer on the database and generates a WSDL. The ESB uploads the WSDL into the registry of services.

The steps to execute the service include:

3. The consumer/source imports the WSDL into its native code base and uses it to communicate (send and receive web service messages) with the proxy business services.

4. The ESB uses the SQL adopter and JDBC connection to execute SQL statements in the target system.

12/10/2019 SCDHHS - Confidential Page 31 of 36

8.4. File/FTP to Web Service

ESB applications commonly perform transport translation for data synchronization across the enterprise. When a source cannot or does not invoke web services, the source component can generate a file of newly created or updated data. This data file is usually in text format. The ESB converts this text file into XML/JSON transit format, and invokes a web service provided by the destination/target.

Figure 17. File/FTP to web service use case and following text explains the steps involved in developing and executing a file/FTP-to-web service interface using the ESB.

Figure 17. File/FTP to web service use case

Steps to design the service include:

1. The source system shares the network location, name, format, and metadata of the file.

2. The target system exposes web services to create, read, update, and delete data entities in its database. The target system generates a WSDL and uploads it into the services registry. The ESB imports the WSDL and creates internal services to call the target system web services.

Steps to execute the service include:

3. The ESB monitors the network location for the arrival of the file.

4. As soon as the file becomes available, the ESB reads the data, converts it into XML, and uses it as payload to call the target system’s web service.

12/10/2019 SCDHHS - Confidential Page 32 of 36

8.5. SOAP/HTTP to SOAP/JMS

In this scenario, both the consumer and target applications are capable of creating SOAP-based web service messages. However, the target is a JMS-based endpoint while the source sends the request message through HTTP. The ESB facilitates the communication by creating an interface.

Figure 18. SOAP/HTTP to SOAP/JMS use case and the description below identify the steps involved in creating this interface.

Figure 18. SOAP/HTTP to SOAP/JMS use case

The design steps include:

1. The target system creates a web service and provides the following details to the ESB:

• WSDL

• JMS queue connection factory name

• JMS queue name

2. The ESB imports the WSDL and creates the internal services to call the target system’s web services. The ESB exposes these services by creating proxy web services with an HTTP-based endpoint and generates the WSDL. The ESB uploads the WSDL into the registry of services. The source system imports the WSDL into its native code base and uses it to call the proxy services.

The execution steps include:

3. The source system invokes the web service in XML/JSON format over HTTP.

4. The ESB receives the message, transforms it into a target application format, and drops it into the target inbound JMS queue.

5. The target application processes the message and places the response message back in the target outbound JMS queue.

6. The ESB receives the response message from the target outbound queue, transforms it to the source format, and sends it back to the source application using HTTP.

12/10/2019 SCDHHS - Confidential Page 33 of 36

8.6. File/FTP to SQL

In this use case, the source system creates a file of newly created and/or updated data. The ESB reads the data from the file and uses SQL to update the target database. Figure 19. File/FTP to SQL use case and the text below describe the steps involved in creating this interface.

Figure 19. File/FTP to SQL use case

The steps to design the service include:

1. The source shares the network location, name, format, and metadata of the file. The ESB uses its FTP adapter to connect and pool that network location.

2. The target shares the following database connection parameters with the ESB: database host, database name, port, service ID, and password. The ESB uses the SQL adapter to connect to the target database.

The steps to execute the service include:

3. The ESB monitors the network location for the arrival of the file.

4. When the source places the file in the file location, the ESB reads the data in the file and uses the data to create or update records in the target database using the database adapter and JDBC connections.

9. Appendices

9.1. Acronyms

Acronym Meaning

COTS Commercial off-the-shelf

12/10/2019 SCDHHS - Confidential Page 34 of 36

CRUD Create, read, update, and delete

ECM Enterprise content management

EDI Electronic Data Interchange

EDS Enterprise Data Services

ES Enterprise Services

ESB Enterprise service bus

ETL Extract, transfer, and load

FTP File Transfer Protocol

HIPAA Health Insurance Portability and Accountability Act

HTTP Hypertext Transfer Protocol

IAM Identity and access management

JDBC Java Database Connectivity

JMS Java Message Service

JSON JavaScript Object Notation

MEDS Medicaid Eligibility Determination System

MES Medicaid Enterprise System

MFT Managed File Transfer

MMIS Medicaid Management Information System

MOM Message-oriented middleware

NoSQL Non SQL, non-relational, or not only SQL

PHI Protected health information

12/10/2019 SCDHHS - Confidential Page 35 of 36

PKI Private key infrastructure

REST Representational state transfer

SCDHHS South Carolina Department of Health and Human Services

SFTP SSH File Transfer Protocol or Secure File…