PL 012.pdf

TRA04.02 – Web Services

Version 0.5 12/10/2019

Prepared by:

South Carolina Department of Health and Human Services (SCDHHS)

Enterprise Services (ES)

PL 012

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

Table of Contents

1. Introduction

2. Web Services in the MES

2.1. Application / Business Services

2.2. Common / Component Services

2.3. Data Services

3. Web Services Concepts

3.1. Web Service Characteristics

3.2. Web Service Elements and Communications Architecture

3.2.1. Consumer and Provider

3.2.2. Web Application Servers

3.2.3. Message-Oriented Middleware (MOM)

3.3. Types of Web Services – SOAP vs. REST

3.3.1. Simple Object Access Protocol (SOAP) Form

3.3.2. Representational State Transfer (REST) Form

3.3.3. SOAP vs. REST Web Services in the MES

4. Web Service Standards

5. Web Service Process Flow

5.1. Request Message

5.2. Web Service Security

5.3. Message Transformation

5.4. Request Validation

5.5. Message Processing

5.6. Response Message

5.7. Response Validation

5.8. Post Processing Activities

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

5.9. Error Handling

5.10. Process Logging

6. Web Service Payload Structure

6.1. Request Structure

6.2. Response Structure

7. Usage of Web Services in MES

7.1. Use Case 1: Portal Requests Member Information from the Integration Hub

7.2. Use Case 2: Integration Hub Requests Member Information from the EDS

7.3. Use Case 3: Data Changes in the Source Systems

8. Appendices

8.1. Acronyms

8.2. Referenced Documents

Table of Figures Figure 1. High-level depiction of web services

Figure 2. Web services in the MES

Figure 3. Web service understanding

Figure 4. Web application server (WAS) architecture

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

Figure 6 Web service process flow

Figure 7. Use case 1: portal requests member information from the integration hub

Figure 8. Use case 3: MEDS delta loads: MEDS to integration hub to EDS

Table of Tables Table 1. Web service characteristics

Table 2. Features of SOAP-based web services https://schhs.sharepoint.com/teams/INTHub/ES/Standards/TRA04.02%20-%20Web%20Services.docx#_Toc487479706 https://schhs.sharepoint.com/teams/INTHub/ES/Standards/TRA04.02%20-%20Web%20Services.docx#_Toc487479707 https://schhs.sharepoint.com/teams/INTHub/ES/Standards/TRA04.02%20-%20Web%20Services.docx#_Toc487479708 https://schhs.sharepoint.com/teams/INTHub/ES/Standards/TRA04.02%20-%20Web%20Services.docx#_Toc487479711

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

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

Table 4. Features of REST-based web services

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

Table 6. Common web services standards

Table 7 Web services authentication requirements

Table 8. Web services log elements

Table of Code Examples Code example 1. Request message of REST service hosted by the integration hub

Code example 2. Response message of REST service hosted by the integration hub

Code example 3. Portal requests member details from integration hub

Code example 4. Integration hub sends member information to portal

Code example 5. Integration hub request to EDS

Code example 6. EDS response to the integration hub

Code example 7. Source systems request to the Integration hub

Code example 8. Integration hub to EDS message

Code example 9. EDS response to integration hub

Code example 10. Integration hub response to source system

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

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

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

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

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

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

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 41

1. Introduction 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.

Figure 1. High-level depiction of web services

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

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

2.1. 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.

2.2. 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.

2.3. Data Services

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

Figure 2. Web services in the MES

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

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.

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

• Web service characteristics

• Web service architecture

• Types of services

• Web services implementation standards

3.1. 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

Characteristics Description

Autonomous Web services provide specific, autonomous, functionality to the consumer.

Being autonomous allows the development, testing, integration, and maintenance of web services independent from the rest of the application in which it is used. Autonomy also allows a web service to follow its own configuration management, version control, and release management path.

Reusable A service-oriented architecture is built upon the premise that reusable components are developed and integrated into technology solutions. Web services are implemented with a focus on reusability, providing system functionality consistently, and greatly reducing maintenance cost.

Loose coupling Loose coupling is an approach to interconnect system or network components so that the components depend on each other in the least extent possible.

Replacing components in a loosely coupled system with alternative

12/10/2019 SCDHHS - Confidential Page 9 of 41

Characteristics Description 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.

Synchronous or asynchronous functionality

Synchronous service execution provides an immediate response to a query. In this situation, the client waits until the server sends back the response message. The advantage of synchronous services is that the client application knows the status of the web service operation in a very short time.

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.

3.2. Web Service Elements and Communications Architecture

This section describes the architecture of web service communications, as depicted in Figure 3.

Web service understanding.

3.2.1. 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

Figure 3. Web service understanding

12/10/2019 SCDHHS - Confidential Page 10 of 41 processing the request and sending a response.

3.2.2. 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.

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

2. 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.

3. The WAS receives the results from the database.

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

3.2.3. 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

12/10/2019 SCDHHS - Confidential Page 11 of 41 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.

2. The middleware sends the message to the provider.

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

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

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

3.3. 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.

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

3.3.1. 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

Feature Description

Well-defined and structured

The WSDL contains and describes the common set of rules to define the messages, bindings, operations, and location of the web service. WSDL allows for definition automation with certain development languages.

XML messaging SOAP relies exclusively on XML to provide messaging services.

Supports stateful context

HTTP messaging is stateless, treating every request as an independent transaction that is unrelated to any previous request. SOAP can be used to implement stateful transactions where context is maintained between requests.

Extensible Significant level of extensibility in the form of WS* standards. Examples include:

• 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.

http://www.w3.org/TR/soap/

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

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

Advantages Disadvantages

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.

Interface is described in WSDL, enabling automated service definition with certain development languages.

SOAP message processing consumes more bandwidth and resources. The XML message format is more verbose than JavaScript Object Notation (JSON), and parses slower than JSON.

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

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

3.3.2. 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.

12/10/2019 SCDHHS - Confidential Page 14 of 41

Table 4. Features of REST-based web services

Feature Description

Resource oriented

REST services offer a resource-oriented interface. These resources can be pictures, video files, web pages, business information, or anything that can be represented in a computer-based system. The REST service will provide access to these resources.

Utilizes HTTP verbs

CRUD (create, read, update, and delete) operations on resources are implemented by simple HTTP verbs (GET, POST, PUT, DELETE)

Stateless RESTful web services are completely stateless. The client is responsible for passing context to server. The web services treat each request independently, and do not need to maintain the client’s previous interaction variables, which simplifies the web services design.

Cacheable REST reads are cacheable. RESTful web services can implicitly or explicitly, define themselves as cacheable. Well-managed caching of responses could partially or completely eliminate redundant client–server interactions, improving scalability and performance.

Self-describing Unlike SOAP-based web services, REST does not need a WSDL to describe the REST web services interface. The REST service consumer relies on the provider to document the service interface and message format.

Efficient RESTful web services request and response messages are very brief and readable when compared to SOAP messages. The request and response messages are not wrapped in verbose XML envelopes.

Flexible data representation

REST services are not bound to the XML (or any other) format. REST services can produce output in JSON, XML, X-12, comma-separated values (CSV), TEXT, or other formats capable of transport via HTTP.

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.

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

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

Advantages Disadvantages

Flexible data representation allows more than just XML.

Security is strictly point-to-point and can only be accomplished via HTTPS.

Efficient messaging allows smaller message formats than verbose XML.

REST services are typically not accompanied by WSDL, requiring the service provider to share additional documentation with the consumer.

Very simple, since it uses HTTP verbs. Does not support built-in retry logic for messaging.

Supports cacheable reads, improving system performance.

3.3.3. 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.

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

4. 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.

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

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:

o A header element with message identification elements o A body element with a request and response information o 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.

http://www.w3.org/ http://www.oasis-ws-i.org/

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

Table 6. Common web services standards

Group Standards

Business processes WS-BPEL WS-Business Activity

Management WS-Management WS-Management Catalog WS-ResourceTransfer

Reliability WS-ReliableMessaging WS-Reliability WS-RM Policy Assertion

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

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

Description and discovery WSDL

Messaging WS-Addressing WS-Notification WS-BaseNotification WS-Topics WS-BrokeredNotification

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

5. 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).

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

Figure 6 Web service process flow

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

5.1. 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.

5.2. 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

Requirement Description

Access control and identity management

Web services operating in MES adhere to the standards outlined in the TRA01.02 – Access Control and Identity Management supplement.

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

Requirement Description

Database standards All general data security requirements that apply to the databases apply to web services.

Authentication The web service provider utilizes an identity provider authenticator to verify that the users of the web service are who they claim to be.

Authorization The web service provider grants access to the services and data based on the privileges defined for the user.

Confidentiality The web service provider protects the privacy requirements of the data being sent and received.

Integrity, non-repudiation

The web service provider makes sure that a message remains unaltered during transit.

Transport Layer Security (TLS)

Adding system processing at the transport level of security secures the communications channel between applications. An example of a transport-level security protocol is Secure Socket Layer (SSL), also known as Transport Layer Security (TLS). TLS is the Internet Engineering Task Force (IETF) standardized version of SSL. Essentially, this protocol creates a level of trust between the two parties involved.

In the case of MES, implementing this protocol ensures the integration hub automatically authenticates all service requests from the portal.

Message level Message-level security ensures encapsulation of user credentials and claims in every message using the WS-Security specification to secure messages. The credentials are passed the first time when the client sends a request message and the server provides a security token.

Subsequent transactions contain the security token, enabling continuous authorization validation.

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

5.3. 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.

5.4. 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.

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

5.5. 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.

5.6. 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.

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

5.7. 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:

o The provider sends a valid response.

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

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

o The response contains WS-Security headers and tokens.

o The response contains WS-Addressing headers.

• Run time validations verify:

o The response message contains an error element.

o That the message contains all required elements.

o That required elements are not empty.

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

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

5.8. 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

5.9. 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

12/10/2019 SCDHHS - Confidential Page 26 of 41 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.

5.10. 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

Log Item Description logType The type of the log file or table containing error, warning, information, success or failure data. Examples include: ‘PROCESS_LOG’, ‘ERROR_LOG’, ‘RECOVERY_LOG’

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

Log Item Description processName The name of the process being executed processId The identity of the process being executed purpose The purpose of the process being executed applicationName The name of the requesting application, for example, ESB, Portal timestamp The date and time when the message is logged

Service Name The name of the web service

Service Location The address and port of the web service endpoint

RequestMessage The XML or JSON message sent as part of the request

ResponseMessage The XML or JSON message that was received as part of the response consumerSystem The name of the application sending the request message

ProviderSystem The name of the application receiving the request message and sending the response message

Environment The environment where the processes are running, for example, DEV, QA, PROD

UserId The user who is currently logged in and on whose behest the processes are being executed

(Optional: Required in the event of an error)

ErrorCode The code of the error

ErrorDescription The description of the error

ErrorMessage The message as is received from the service provider

ErrorSeverity The severity of the error, for example, HIGH, MEDIUM, LOW

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

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

6. 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.

Element Description

Identity elements Identity elements help the web service identify the consumer of the service. Some of the information that forms these elements includes user ID, SAML tokens or OAuth tokens. This group of elements is mandatory.

Query elements Query elements help the web service determine the subset of data to perform the operation. For example, for a query operation, these elements determine the subset of data that has to be returned to the consumer. For an update operation, these elements help determine the records in the database these updates have to be applied on. This group of elements is mandatory.

Examples: memberId=USR57889 or ZipCode=28227

Pagination elements Pagination elements help the web service further narrow the results of the query elements to be returned to the consumer. All web services in MES include a default mechanism to deal with large amounts of response data. Data will always be paginated in batches unless pagination is specifically disabled. Pagination prevents runaway queries and inadvertently passing large amounts of data over the network. This group of elements is not mandatory. They may not be required in web services where the response is a small record set.

Data elements that implement the pagination process include:

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

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

Element Description

• 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.

Response data elements

Response data elements form the core set of data returned by the provider. The data returned by the web service follows the rules set forth by the identity, query, and pagination elements. This group of elements is mandatory.

Exception/error elements

In the event of any exception or error, the response message shall include exception/error elements. The minimum set of data elements are code and description.

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.

6.1. Request Structure

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

• Identity elements

• Query filter elements

• Pagination elements

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

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

6.2. Response Structure

The response message payload contains the following data elements:

• Identity elements

• Pagination elements

• Response elements

• Error elements

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

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", 12/10/2019 SCDHHS - Confidential Page 32 of 41

"Year": "2015", "Curam App Reference ID": "1368325", "WFStatus": "COMPLETE", "Import Source": "CURAM ONLINE" "errors": [ "errorCode": "ERR-2343", "errorDescription": "Error Desc", "errorLevel": "INFO/WARN/ERROR"

7. 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

7.1. 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.

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

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=PORTALSE

RVICES

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”: “33bob”, “modifiedDate”: “10/27/2016

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

7.2. 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.