PL 004 TRA WEB SERVICES.docx

TRA04.02 Web services

TRA04.02 – Web Services Version 0.5 07/10/2017

Prepared by:

South Carolina Department of Health and Human Services (SCDHHS) Enterprise Services (ES)

Table of Contents

Table of Figures

Table of Tables

Table of Code Examples

Table of Standards

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.

IntroductionFigure 1. High-level depiction of web services

A web service is a function that programs can access via the web using either Hypertext Transfer Protocol (HTTP) or HTTP over Transport Layer Security (HTTPS). Web services form a critical part of a service-oriented architecture (SOA), exposing reusable system functionality in the form of component interfaces. A web application server (WAS) can expose web services directly or by leveraging a message-oriented middleware (MOM) technology, such as an enterprise service bus (ESB). The South Carolina Department of Health and Human Services (SCDHHS) Medicaid Enterprise System (MES) exposes business functionality for consumption by trading partners and system functionality for consumption by the MES. Section 5.Web Service Process Flow details the web services process conceptualized in Figure 1. High-level depiction of web services.

Industry standards define rules for web services and provide a common approach for defining, publishing, and consuming web services. Web services support interoperable machine-to-machine interaction over an Internet Protocol (IP) network through a set of open standards based. See Section 4.Web Service Standards for more about the most widely used web service standards and concepts. The web services description, expressed in the Web Services Description Language (WSDL), describes the rules for communication between the web services consumer (e.g., the trading partner) and the web services provider (e.g., the MES). The description includes message formats, datatypes, transport protocols, and transport serialization formats. Section 3.2. Web Service Elements and Communications Architecture provides additional information about web service concepts.

Section 3.3.Types of Web Services – SOAP vs. REST, describes two standard forms —Representational State Transfer (REST) and Simple Object Access Protocol (SOAP)—of web services, identifies unique features of each form, and compares each in terms of usability in the MES.

The information in this supplement document applies to all web services in the MES. See the TRA06 – Technology products portfolio (TPP) supplement for the technologies approved for use in the MES.

Web Services in the MESFigure 2. Web services in the MES

The MES uses a SOA with system functionality implemented into loosely coupled components and subsystems. The MES integration hub provides a central integration point for web services, messaging, and exchanges of files. Figure 2. Web services in the MES highlights integration points that might use web services.

SCDHHS categorizes web services into three broad groups of similar functions when designing the business architecture:

Application / business services Common / component services Data services Application / Business Services Application services (also referred to as business services) include services that form the core functionality of a system. Application services implement business functions end-users notice, for example, enroll provider, process claim, determine eligibility, etc.

Application services can be utilized inside the MES or exposed to external applications for consumption.

Common / Component Services Common services (also referred to as component services) perform activities that help developers perform routine functions in a consistent and reusable fashion. Examples of common services include configuration activities, such as process logging, error handling, sending emails, etc.

Common services are predominantly utilized inside the MES and are not exposed to external applications for consumption.

Data Services Data services provide a service-interface to database(s) and expose the typical CRUD (create, read, update, delete) functions.

For example, the Enterprise Data System (EDS) framework holds the data of all MES business entities, such as member, provider, eligibility, claims, etc. Data services perform operations on the core business entities of the EDS such as Retrieve Member Details, Create New Member, and Update Member Address. See the TRA05 --The EDS Framework supplement for more information about the data architecture and data flow.

Web Services Concepts This section describes the following web services concepts:

· Web service characteristics

· Web service architecture

· Types of services

· Web services implementation standards Web Service Characteristics Table 1. Web service characteristics describes web services inherent characteristics that guide the design and implementation of SOA-based enterprise applications.

Table 1. Web service characteristics

Replacing components in a loosely coupled system with alternative implementations of the service, results in minimal or no code deployments on the consumer side.

Components in a loosely coupled system are less constrained to the same platform, language, operating system, or build environment.

Asynchronous service execution does not provide an immediate response to a query. Asynchronous services include services where execution may require a significant amount of time to process the request. The advantage of asynchronous service is that the client can invoke a service and then execute other functions in parallel.

Web Service Elements and Communications Architecture This section describes the architecture of web service communications, as depicted in Figure 3. Web service understanding.Figure 3. Web service understanding

Consumer and Provider Web services communication involves two parties—the client/consumer and the server/provider.

The consumer (client) initiates the communication by sending a request message to the provider using Hypertext Transfer Protocol (HTTP), the application protocol used to distribute information on the web. The consumer does not maintain knowledge of the service definition or implementation. The consumer only needs to know how to connect to the service and the parameters required to execute the functionality.

A provider (server) of the service exposes particular functionality to consumers. The provider, in its native code base, implements the functionality of the service and defines input and output parameters for the service. The provider responds to the consumer request message by processing the request and sending a response.

Web Application Servers The computer system on the provider side of the web service, the web application server (WAS), processes the request sent by the consumer. The WAS houses the native code of the business logic that needs to be executed for a particular service. The WAS consists of two components—the web server and the application server. The web server provides the endpoint location for the service and interacts with the client. The application server runs the code and provides the content.

Figure 4. Web application server (WAS) architecture Figure 4. Web application server (WAS) architecture illustrates the WAS architecture, and the following steps to process a consumer request.

The consumer initiates the communication by sending a request to the provider.

On the provider side, the web server receives the request, extracts the input parameters, and transforms the request into a database request format using the input parameters.

The WAS receives the results from the database.

The WAS then sends the response to the service consumer in the format prescribed by the service description.

Message-Oriented Middleware (MOM) Message-oriented middleware (MOM) is an optional functional component of the web services architecture. A MOM brokers and mediates communication between the consumer and the provider. A MOM is particularly useful in a dynamic business environment where processes, technologies, and services tend to change frequently. The MOM provides a level of abstraction to calling services by shielding the physical implementation of reusable components.

TRA04.02-S1. The ESB coordinates all web service interactions.

In the MES, all web service interactions are coordinated by the ESB. See the TRA04.01 – Enterprise Service Bus (ESB) supplement for information about the ESB functions, standards, and operations in the MES. Figure 5. Web service architecture with message-oriented middleware (MOM) illustrates a web services architecture that includes a MOM. The communications steps include:

1. The consumer sends the message to the middleware.

1. The middleware sends the message to the provider.

1. The provider sends a response back to the middleware.

1. The middleware sends the message back to the consumer.

Figure 5. Web service architecture with message-oriented middleware (MOM)

Types of Web Services – SOAP vs. REST Typically, developers implement web services using either the Simple Object Access Protocol (SOAP) or the Representational State Transfer (REST) architecture pattern. Both SOAP and REST use HTTP to transport messages between the consumer and the provider; the major distinction lies in the message format. This section introduces each of these forms, highlights unique features of each, and compares the usability of each in the MES.

Simple Object Access Protocol (SOAP) Form SOAP, as specified at http://www.w3.org/TR/soap/, is a protocol specification for exchanging structured Extensible Markup Language (XML) (and only XML) information between a SOAP sender and SOAP receiver in the implementation of web services. The Web Service Definition Language (WSDL) describes the operations offered by SOAP services. WSDL is an XML language for syntactically defining interfaces. Services using SOAP-based messaging and WSDL-based definition have been widely implemented for a long time.

A full set of SOAP-based features would be beyond the scope of this supplemental document. Table 2. Features of SOAP-based web services lists a subset of SOAP-based web service features.

Table 2. Features of SOAP-based web services

WS-Security: This standard defines some ‘enterprise level’ security features and allows identity through intermediaries beyond point-to-point—Secure Socket Layer (SSL).

WS-Atomic Transactions: This protocol defines the ACID (Atomicity, Consistency, Isolation, and Durability) transactions.

Using SOAP web services in the enterprise must be considered against the advantages and disadvantages listed in Table 3. Advantages and disadvantages of SOAP-based web services.

Table 3. Advantages and disadvantages of SOAP-based web services

Very powerful.

Extensible via the WS* standards to support, for example:

Identity through intermediaries Atomic transactions Stateful processing Complex request coordination in a single request The power of SOAP also makes it very complex, especially when implementing stateful processing and request coordination.

Supports development of stateful web services, maintaining context across several requests.

Well-structured and supported by a set of rigorous standards.

Representational State Transfer (REST) Form Whereas SOAP is a protocol, REST is an architectural pattern that focuses on designing resources, similar to the concepts of objects in object-oriented design. Data and functionality are both considered resources, and both are accessed using Uniform Resource Identifiers (URIs) and the HTTP verbs normally used for working with the required objects or resources (GET, POST, PUT, and DELETE). In a REST web service, requests made to a resource’s URI elicits a response that may be in XML, Hypertext Markup Language (HTML), JSON, or other formats capable of transport via HTTP.

A full set of REST-based features would be beyond the scope of this supplemental document. Table 4. Features of REST-based web services lists some features of using REST-based services.

Table 4. Features of REST-based web services

Using REST web services in the enterprise must be considered against the advantages and disadvantages presented in Table 5. Advantages and disadvantages of REST-based web services.

Table 5. Advantages and disadvantages of REST-based web services

Supports cacheable reads, improving system performance.

SOAP vs. REST Web Services in the MES Although REST services are preferred and encouraged for the MES, SCDHHS will support both SOAP and REST web services under the appropriate conditions. SCDHHS will standardize using REST services within the MES for most web service interfaces.

Develop REST services in scenarios where the following apply:

Read-caching will improve system performance, as in the case of data services.

Performance will be negatively impacted by XML parsing.

Flexible data representation is required (multiple formats).

Maintaining a state of information from one request to another is not required.

Service-functionality can be expressed as simple CRUD operations on data resources.

Develop SOAP-based services in the following scenarios:

Enterprise-level security requires pass-through authentication along several intermediaries.

Service-functionality is expressed as a series of activities to accomplish the desired outcome.

Coordination between several services is required to accomplish the desired outcome.

Clients require a formal service contract and the rigid specification that the WSDL provides.

Web Service Standards Web service communications are based on a set of industry standards. Service-oriented architecture is a style of application programming where components are offered as service, through a communication protocol over the network. Web services implement the service-oriented architecture in web applications. This section provides a brief overview of some of the most widely used standards and concepts.

TRA04.02-S2. Web services will use only XML or JSON language formats.

SCDHHS uses following language formats for web services:

· Extensible Markup Language (XML) is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. XML is the predominant message format web service transactions.

· JavaScript Object Notation (JSON) is a lightly structured data-interchange format that consists of attribute-value pairs and is easy for both humans and machines to read and write. The JSON format is syntactically identical to the code for creating JavaScript objects.

TRA04.02-S3. Web services communication are based on HTTP or JMS transport protocols.

Web services use following transport protocols:

· Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, information systems. It is a generic, stateless, protocol, which can be used for many tasks beyond its use for hypertext. In the context of web services, this protocol is used for transmission of machine-readable text formats like XML and JSON over the internet.

· Java Message Service is a Java application program interface (API) that allows applications to create, send, receive, and read messages. Messages (or messaging), as earlier defined in this document, is a means of communication between two software components. In the context of web services, JMS is another method/ transport protocol to send messages across providers and consumers of service. Using SOAP over HTTP messaging may not be sufficient because HTTP does not guarantee message delivery and JMS provides a more reliable and scalable messaging mechanism.

TRA04.02-S4. Web services are implemented in REST and/or SOAP data exchange protocols.

Web services use following data exchange protocols:

· Representational State Transfer (REST) is an architectural style for web applications and is primarily used to build simple, efficient, web services. REST uses HTTP for data communication. All service calls point to a URI resource, which is the fundamental concept of REST. A resource is an object with a type, associated data, relationships to other resources, and a set of methods. These resources are accessed by a common interface using HTTP standard methods, PUT, GET, POST, and DELETE.

· Simple Object Access Protocol (SOAP) defines an XML-based format that applications use to communicate with each other. SOAP is similar to Remote Procedure Call (RPC) used in Java. The wide range of disparate systems in the web requires that applications support a common data encoding protocol and message format to communicate with each other. SOAP is a standard for encoding messages in XML that invoke functions in other applications. SOAP provides an envelope around an XML document that identifies it as a SOAP message. The SOAP message contains:

· A header element with message identification elements

· A body element with a request and response information

· A fault element containing status and error information.

TRA04.02-S5. Web services use WSDL for Web Service Description.

Web Service Description Language is a document, written in XML, used to describe the web service. WSDL describes the complete contract for application communication. The service consumer, by reading the WSDL (either manually or using integrated development tools), can understand the message formats, operations supported, and service destinations (network address) of the web service. WSDL specifies where and what should be sent as a request and what can be expected as a response. Though WSDL is not necessary for defining every web service, it is required for SOAP messaging.

In addition to the standards of implementing web services described above, other specifications are maintained and supported by various standards bodies and entities, such as the World Wide Web Consortium (W3C) (http://www.w3.org/) and Advancing Open Standards for the Information Society (OASIS) (http://www.oasis-ws-i.org/). The websites for these organizations contain information related to the latest developments in the web service standards.

Enterprise software vendors chose to adopt these web services standards. It is not practical to list out all the web service standards in this document. However, Table 6. Common web services standards lists some of the most common web services standards that all vendors of web service based applications (e.g. IBM and ORACLE) abide by.

Table 6. Common web services standards

WS-Business Activity

WS-Management Catalog WS-ResourceTransfer

WS-Reliability WS-RM Policy Assertion

WS-Business Process Execution Language (BPEL) WS-Business Activity WS-Atomic Transaction WS-Coordination WS-Discovery

WS-Security WS-Secure Conversation WS-Trust WS-Policy WS-Privacy

WS-Notification WS-BaseNotification WS-Topics WS-BrokeredNotification

Web Service Process Flow This section describes the series of discrete steps that take place during the execution of web services (shown in Figure 6 Web service process flow). Figure 6 Web service process flow

The steps include:

Request message Web service security Message transformation Request validation Message processing Response message Response validation Post-processing activities Process logging Error handling

Request Message The request message is the message sent by the consumer/client to the provider of the web service.

While the format of a SOAP-based request message differs from REST-based requests, a request message essentially contains information regarding the service function or the resource (data and/or functionality) being requested and the parameters of the service.

Web Service Security Due to the nature of its loosely coupled connections and open standards, web services are vulnerable to access by unintended clients, with potentially malicious intentions. Therefore, the request message needs authentication by the provider to ensure that the request message came from a legitimate source.

The security vulnerabilities of web services warrant an additional layer of processing to ensure security of these services. Table 7 Web services authentication requirements describes security requirements and high-level methodology in ensuring security.

Table 7 Web services authentication requirements

Message Transformation The ESB exposes services to consumers in the form of proxy services. Proxy services ensures appropriate authentication obscure and coordinate application- and data services to accomplish its task. The MES supports both SOAP and REST proxy services, but prefer REST for application- and data services. The ESB can transform the incoming request from SOAP/XML to the appropriate REST requests and data format, if required.

Request Validation The smooth functioning of web services depends on the exchange of request and response messages that exactly match the format described in the service contract or the WSDL.

The provider incorporates functionality in the web service to validate the request message to ensure:

· The request message asks for a valid function/method.

· The request message contains all the data elements necessary to process this request.

Broadly, validations make sure that the messages follow the schema, that all required data elements arrived in the request, and that the data elements belong to the datatype defined by the WSDL.

Validations occur before beginning the processing to avoid potentially costly run-time errors during request processing.

Message Processing During message processing—the core of the execution of the web services—the web service performs its intended function, using the parameters received in the request message. Message processing could vary from something as simple as providing configuration settings to a very complex set of business processes, requiring several other web services to be called.

Response Message The response message is the message sent by provider to the consumer in response to the request message. Depending on the kind of request, the response message could a collection of data elements requested by the consumer or could simply be an acknowledgement of the request message.

Request messages and response messages adhere to the web service description.

Response Validation Similar to the WAS validation of the request message, the consumer validates the response message to make sure that the response message is in the expected format and that data in the response message can be used for the post-transaction activities.

Examples of routine validations include:

· Design time validations ensure that:

· The provider sends a valid response.

· The response message is a valid SOAP message with mandatory SOAP envelope, header, and body.

· The response contains a SOAP fault element if an error occurred, and does not contain an element if no error occurred.

· The response contains WS-Security headers and tokens.

· The response contains WS-Addressing headers.

· Run time validations verify:

· The response message contains an error element.

· That the message contains all required elements.

· That required elements are not empty.

· That each data element is of the valid data type.

Post Processing Activities Post processing activity refers to the functions that the client/consumer performs with the data received in the web service response. In other words, this refers to how the consumer uses the data received in the response message.

This activity depends on the context of the web services call, and may vary in every situation. Typically, one of the following activities uses the received information:

· Display the data in the user interface

· Create or update consumer database records using the data requested

· Conditionally execute more business logic

· Pass this data onto another web service

Error Handling In the web services ecosystem, both the provider and the consumer must handle errors.

Error handling on the provider side involves sending appropriate error messages back to the client/consumer to communicate the exact nature of the error so the consumer can perform appropriate actions.

Error handling on the consumer side involves parsing the response message for the error, notifying other modules of the failure, and then ensuring smooth execution of code until a logical end.

Two types of errors may occur in web services—system-level, and business-level errors.

· System-level exceptions represent failures of run-time software components, hardware, and network communication protocols that are part of the service implementation at provider side. These errors represent failures that are not related to the business logic or data that is being executed, for example, a relational database management system (RDBMS) server crashes, and web service cannot process the request message because the application server cannot allocate a Java Database Connectivity (JDBC) connection. In the event of a system-level error, the web service captures the error, logs it, and sends it along to the consumer. For example, a proxy service receives a request message from the consumer; the proxy service then invokes a composite web service. If, for some reason, the composite service does not respond in time, the proxy service receives a system-level error message (e.g., http 404 or 408). The proxy service captures, extracts, and logs the error message. The proxy service then passes the error message back to the consumer of the service.

· Business level errors represent failures that the service raises in response to violations in business logic or data, for example, a request message represents a request to process a claim and the requesting provider is not eligible for such a claim.

Process Logging Both the consumer and provider applications maintain a record of all web service interactions in the form of a process log. These process logs can take different shapes and forms, such as log files, log tables, and non-relational (NoSQL) documents. Administrators of the consumer and provider applications should have the ability to set the log level, the level of detail to be included in the logs. For web service logs, Table 8. Web services log elements describes the data that can be captured as part of process logs.

Table 8. Web services log elements

(Optional: Required in the event of an error)

Maintaining web services logs helps detect configuration errors, validate the request and response messages, and analyze error responses.

Web Service Payload Structure A web service message payload is the most essential part of the message that one application sends to the other. In the MES, all message payloads follow a common structure. This common structure is a standard for the minimum necessary data elements required for successful communication between two parties. All the data elements in the message fall into one of the following categories of elements. Some of these elements are mandatory while some are not.

Examples: memberId=USR57889 or ZipCode=28227

· Sort specification—the indicator of how the response results should be sorted (based on element).

· Limit—the indicator of how many data records a service should return in each call.

· Offset—the indicator of the serial number at which the results start in a query.

· Record count—the indicator of the number of total record meeting the conditions of the query elements.

Example: Sort=DOB:asc,offset=50,limit=26 returns a set of 25 records, starting from the 51st record of the query results that were sorted by ‘date of birth’ in ascending order.

This group of elements is not mandatory. These elements appear in response messages only in the event of an exception.

Any message will be either a request message or a response message. The following section describes the standard structures of the request and response message payloads. The identity tokens were omitted from these examples, since they will take up several pages of content. For more information about identity tokens, please refer to standard supplement TRA01.02 – Access control and identity management.

Request Structure A request message payload shall contain data elements in the following structure:

Identity elements Query filter elements Pagination elements The ESB exposes services to consumers in the form of proxy services. Proxy services ensures appropriate authentication obscure and coordinate application- and data services to accomplish its task. The MES supports both SOAP and REST proxy services, but encourage REST for application- and data services. A common feature of proxy services is to capture the identity provided in the request header and add identityContext information (see below) to the message body of application- and data services. The identityContext contain the unique identifier of the calling user and all augmented claims information. Please refer to the TRA01.02 – Access Control and Identity Management supplement for additional information on access control and identity management.

Code example 1. Request message of REST service hosted by the integration hub shows an example of a request message of REST service hosted by the integration hub.

Code example 1. Request message of REST service hosted by the integration hub “identity”: {“uniqueId”: “mlm0947”, “claims”: [{“Role”: “CaseWorker”}, {“Organization”: “Acme Medical”}] “request”: { “operation”: “findDocuments”, “query”: { “ssn”: “199199199” “sort”: { “dob”: “asc”, “age”: “dsc” “pagination”: { "page": 4, "limit": 25

Response Structure The response message payload contains the following data elements:

Identity elements Pagination elements Response elements Error elements Code example 2. Response message of REST service hosted by the integration hub provides an example of a response message of REST service hosted by the integration hub Code example 2. Response message of REST service hosted by the integration hub “identity”: {“uniqueId”: “mlm0947”, “claims”: [{“Role”: “CaseWorker”}, {“Organization”: “Acme Medical”}] "sort": { "dob": "asc", "age": "dsc" "pagination": { "page": 4, "limit": 25 "response": { "pagination": { "recordCount": "225", "page": 4, "limit": 25 "data": [ "documentId": 6239440, "documentName": "MEDS - Curam Application - HH# 001094396 Year 2015 - Receipt Date Status- COMPLETE", "type": "pdf", "HH#/AppID": 1094396, "Primary SSN": "199199199", "Case Date": 1431057600000, "Last Name": "Test", "First Name": "Smoker", "Claim Type": "FI", "Year": "2015", "Curam App Reference ID": "1368325", "WFStatus": "COMPLETE", "Import Source": "CURAM ONLINE" "documentId": 6239441, "documentName": "MEDS - Curam Application - HH# 001094396 Year 2015 - Receipt Date Status- COMPLETE", "type": "pdf", "HH#/AppID": 1094396, "Primary SSN": "199199199", "Case Date": 1431057600000, "Last Name": "Test", "First Name": "Smoker", "Claim Type": "FI", "Year": "2015", "Curam App Reference ID": "1368325", "WFStatus": "COMPLETE", "Import Source": "CURAM ONLINE" "errors": [ "errorCode": "ERR-2343", "errorDescription": "Error Desc", "errorLevel": "INFO/WARN/ERROR" Usage of Web Services in MES The loosely connected, but highly integrated, applications in the MES rely on web services to share data and application functionality. This section illustrates the following use cases when web services are used in the MES:

· Portal requests member information from the integration hub

· Integration hub requests member information from the EDS

· Updates to MEDS are sent from MEDS to the integration hub and then to EDS Use Case 1: Portal Requests Member Information from the Integration Hub The Portal provides the user interface for users, such as members and providers, to see and interact with their data. Users can potentially perform functions such as updating member address info, submitting claims, approving payments, etc.

The portal application makes web service calls to the integration hub, to retrieve and update data according to its designed purpose. For example, when the user first logs in, the portal makes a call to the integration hub to invoke the authentication service. When the user retrieves their profile information, the portal makes a call to the integration hub to invoke the service that provides member profile information.

In the web service communication between the portal and integration hub (shown in Figure 7. Use case 1: portal requests member information from the integration hub), the portal invokes the service by sending a request message in the format defined in the WSD. The portal sends the unique Member ID as an input parameter, and asks for the details of the member whose Member ID matches the input.

In response, the integration hub sends a message containing the profile data of the member whose Member ID matches the input. The format of the request and response messages look different based on whether the service is implemented in REST or SOAP.

Figure 7. Use case 1: portal requests member information from the integration hub For this web service communication to take place, the integration hub (service provider) development team creates web services using the REST architecture. The integration hub team communicates the details of this service using design documents and sample messages to the portal (service consumer) team.

In Code example 3. Portal requests member details from integration hub, the portal makes a RESTful service call to the integration hub to request member information Code example 3. Portal requests member details from integration hub http://hostedlocation/PortalRestService/rawMmis?queryname=MEMBER&queryvalue=987654321&transform=transIntoArray&collection=PORTALSERVICES Code example 4. Integration hub sends member information to portal, shows the response that the integration hub will send back to the portal, containing the requested member details.

Code example 4. Integration hub sends member information to portal “memberId”: “987654321”, “firstName”: “MYLES”, “middleName”: “K”, “lastName”: “MCMILLIAN”, “dateOfBirth”: “2012-01-02T05:00:00.000Z”, “socialSecurityNumber”: “123456789”, “gender”: “M”, “modifiedBy”: “bob”, “modifiedDate”: “10/27/2016 Use Case 2: Integration Hub Requests Member Information from the EDS The integration hub exposes web services via the ESB for consumption. Some web services will be exposed only internally to SCDHHS and will be used mainly for integrating reusable components to perform system functions. These internal services also provide administrative functions such as process logging, error logging, email, etc.

As illustrated in Figure 7. Use case 1: portal requests member information from the integration hub, data services can be implemented to interact with the business entities in the NoSQL database. These data services can be exposed via the integration hub to both internal applications as well as external trading partners. Examples of these services would implement functions such as “Update Member Address”, “Retrieve Member Eligibility History”, or “Verify Provider”.

Some NoSQL technologies provide the capability to expose these business functions as RESTful services directly from the database. This example considers such a NoSQL database.

Below are some sample request and response JSON messages exchanged between the Integration hub and the EDS. For this web service communication to take place, the EDS development team creates REST web services and a WADL document. The EDS team communicates the details of this service using a WADL document to the integration hub (service consumer) team.

In Code example 5. Integration hub request to EDS, the integration hub makes a RESTful service call to the EDS to request member information Code example 5. Integration hub request to EDS http://hostedlocation/EDS/EDS?queryname=MEMBER&queryvalue=9876543 Code example 6. EDS response to the integration hub shows the response that the EDS will send back to the integration hub, containing the requested member details.

Code example 6. EDS response to the integration hub "MemberData": {

"MBR_NUM_MEMBER_ID": "9876543",

"MBR_NAM_FIRST": "JOHN",

"MBR_NAM_LAST": "WAYNE",

"MBR_DTE_BIRTH": "2004-01-01",

"MBR_CDE_RACE": "01",

"MBR_CDE_SEX": "M",

"MBR_CDE_SSN_VALID": "V",

"MBR_CDE_SOUNDEX": "H4200B4500",

"MBR_NUM_SSCN": "111111111C2",

"MBR_NUM_SSN": "2222222222",

"MBR_IND_RRN": "N",

"MBR_IND_SSCN": "Y",

"MBR_CDE_ANSWER": "SF1",

"MBR_CDE_TTR_AGE": "A24",

"MBR_TMS_TTR_LSTUPD": "2013-02-02 01:05:02.681970",

"SOURCE": "MEDS"

Use Case 3: Data Changes in the Source Systems In the MES, records created or updated in a source system (e.g., MEDS or Cúram) are propagated to the EDS in a number of ways such as ETL, batch files or web services. In this use case, the source systems use web services to update the integration hub, which in turn will update the No SQL database in EDS.

In the use case illustrated in Figure 8. Use case 3: MEDS delta loads: MEDS to integration hub to EDS, the source systems send a web service request to the integration hub with the list of all newly created or updated records.