Chapter - 2 : Communication Protocols

This chapter discusses the available communication protocols available for data transmission between sending and receiving systems. Two methods will be made available for all processes.

• Web services over HTTPS
• Secure FTP

Web Services

OIDG web-services have the following characteristics:

• Client services are synchronous, one-way, with an acknowledgment response.
• Outbound processing resulting from the client request happens at a later time and results are logged.
  

  

• Outbound business service calls to host company systems are also synchronous and one-way.
• All web-services follow WS-Security standards for the authentication of SOAP messages where user and password are presented in the SOAP header and are authenticated for access to the service.

OIDG exposed web-services

Name	WSDL	Type
IDXClientWebServices		Synchronous Message “String” payload type for the WSDL

Creating SOAP Messages

SOAP Overview

SOAP (Simple Object Access Protocol) is an XML-based language used for the transport of structured information from a requester to a provider. A SOAP message is sent from the requesting application to an ISP Interface Web Service. A SOAP response message including the outcome is then returned to the requester. Proper authentication information must be included in the security portion of the header. The body, explained in detail later in this document, simply consists of the message, as defined by the service’s WSDL.

WSDL

WSDL (Web Service Definition Language) is an XML-based language used to describe Web Services. In the case of the OIDG, the WSDL for each available Web Service defines the message format, data type, and transport protocols that should be used between the requester and the provider.

Web Service Security

OIDG adheres to the WS-Security standards for the authentication of SOAP messages. The standards, as developed by the OASIS Open committee, can be referenced here Webservice security standards. As per this approach, consuming applications need to send the User name token as part of the SOAP security header along with the SOAP request.

The <wsse:UsernameToken> element is used to include the authentication information. The username and password are specified inside of the <wsse:Username>, and <wsse:Password> elements, respectively. The WSS specification for the UsernameToken node can be found here WSS <wsse:UsernameToken> Specification.

Here is a sample SOAP header showing the <wsse:UsernameToken> being used.

TLS 1.2 is required as the method of encryption for all OIDG SOAP messages.

SOAP fault usage for reporting errors

The SOAP specification defines a standard fault mechanism for reporting errors related to both the SOAP Header and Body. The SOAP specification defines standard high-level SOAP fault codes that can be refined to report specific errors.

In this implementation SOAP faults are considered for exception reporting and are used when it is not possible nor appropriate to send a normal service response or because the service request could not be processed for various reasons (e.g. syntax error in the service messages, congestion, failure in the authentication process).

Sample Soap Fault messages:

Success Acknowledgment

Schema Validation Failure

Business Rules Validation Failure

File Transfer

• Each client using sFTP should be assigned its own FTP folder.
• Folder permissions are provisioned by the hosting company.
• Files placed in FTP folders should be PGP encrypted and digitally signed by the client company to protect the file contents and to guarantee its integrity. A digital signature serves as a checksum and a non-repudiation device.
• The schedule for file transfers is to be determined between the client and host companies.

A successful integration between the client company and the company hosting OIDG will need to follow the following guidelines:

• Each client company should have their own FTP account and local folders.
• Each client company folder structure should include Inbound and Outbound top-level folders to more easily separate files coming from the client and those coming from the host.
• All transactions in a batch request need to be of the same transaction type. In other words, a batch request should not mix Policy Migration with Policy Synchronization or Premium Payment transaction types.

File Protection

We recommend use of encryption to protect all files on disk. OIDG supports asymmetric PGP encryption/decryption and, if enabled, will expect all files to be encrypted that it reads and writes to disk. Request files submitted by client companies are expected to be encrypted with the receiving company’s public key. OIDG can then decrypt the message with the receiving company’s private key.

In addition to protecting the contents of the file, you can also guarantee the integrity of the received file by validating its digital signature. The digital signature is created by the sender using their own private key. OIDG can then validate the signature by decrypting with the sender’s public key. This guarantees that the message has not been altered during transit and that it came from the sender. Decryption will not be successful otherwise.

Batch Processing

OIDG provides an infrastructure for batch processing of insurance transactions. Batch processing is only available with file-based submissions. Typically, client companies will place one or more zip files in a folder that has been configured specifically for them and for a specific request transaction type. A client specific schedule will also have been configured to read from this folder location. Any zip or XML file found will cause the creation and processing of a batch processing job in OIDG.

A batch request is expected to be one or more request files. Once the scheduler instructs OIDG to go interrogate a folder, batch requests are created the following ways:

• A zip file found in the folder becomes a batch request
• Multiple zip files found in the folder become multiple batch requests
• XML files found in the folder are grouped together to become a single batch request

Batch processing goes as follows:

• The configured client (ISP) schedule determines when request file processing will start.
• Zips will be processed concurrently in OIDG as soon as a process thread is available.
• Each zip becomes a batch request in OIDG. When OIDG creates a batch request it will send a batch start message to configured outbound service endpoints.
• Batches are created and processed concurrently in OIDG. Because of this concurrency, the order in which batches are processed cannot be guaranteed.
• Each policy in a batch is taken through ACORD schema validation then business rules validation and finally through a transaction specific outbound workflow. Transaction types are describe in the Insurance Processes section of this document.
• Policies are processed concurrently. Because of this concurrency, the order in which policies are processed cannot be guaranteed. Each policy that is processed is submitted to configured outbound service endpoints.
• Once OIDG reaches the end of the zip file, the corresponding batch in OIDG is closed. When OIDG reaches the end of a batch request it will send a batch end message to configured outbound service endpoints.

OIPA Data Intake Integration for Outbound Batch Processing

OIDG provides offers out of the box integration with Oracle Insurance Policy Administration (OIPA). Batch processing with an integrated OIDG / OIPA deployment would typically mean that OIPA’s Data Intake transport would be used since this provides the best performance. This integration mechanism is configured in OIDG via the AdminView GUI. As described above, each OIDG client would have its own FTP folder for requests and a corresponding schedule for processing requests placed in that folder. Each zip file placed in the request folder is treated as an independent batch request. Batch submissions to OIPA are handled as described below:

• When OIDG creates a batch internally it also initializes a batch submission in OIPA. This means a new batch is created on the OIPA Data Intake queue. Batches are created concurrently in OIDG and OIPA. Because of this concurrency, the order in which batches are processed cannot be guaranteed.
• Each policy in a batch processed by OIDG goes through a transaction specific outbound workflow which might include an OIPA Data Intake queue submission, depending on routing rules for the transaction and state of the policy. Policies are processed concurrently. Because of this concurrency, the order in which policies are submitted to OIPA cannot be guaranteed.
• Once OIDG reaches the end of and closes a batch request, it also puts and end of batch message on the OIPA Data Intake queue and tells OIPA it can begin processing the batch. OIPA will only start processing the batch when it receives this message and if it is not already processing a batch for the same client company.
• Multiple batches for the same client company will be processed sequentially in OIPA.
• Multiple batches for different client companies will be processed concurrently in OIPA.

Error Handling and Notifications

There are two ways to send (or transmit) requests to the OIDG, web services and FTP. Errors can occur in either transmission type or are reported back to the user, but via different mechanisms. OIDG does not provide any UI to clients for monitoring errors so they are either reported real-time as SOAP faults or written to files. Two levels of validation are done. The first is a check against the ACORD AML schema. The second is a check against the input data rules for the particular transaction being executed. If either of these fail, the request is rejected.

The following error types are reported by OIDG:

• XMLSchemaError - Request payload failed ACORD AML schema validation
• BusinessRuleValidationError – Request payload failed business rules validation
• CommunicationError - Outbound service connection error
• BusinessServiceError - PII processing or outbound service request failure
• ApplicationError - Internal OIDG communication or general runtime error

Web service transmissions are processed real-time and the corresponding request validations are processed real-time. When a validation fails during web service processing a SOAP fault is thrown. The web service caller will have to catch and process the SOAP fault. The errors are also logged in OIDG’s database for later system-level error reporting. If no failures occur during validation, an acknowledgement is sent back to the caller.

FTP transmissions are file-based and are processed asynchronously as batch requests. When errors occur during FTP processing, they are logged. Once the FTP request processing has completed, a report file can be generated for that request and placed into the configured error folder for the client company that initiated the request.

System administrators will be able to see all errors for all client companies via OIDG’s Quick View UI. They will also be able to configure the system to generate error reports similar to those sent to the client’s error folders. Error files are generated per batch. Errors that have occurred during the batch are put into a report XML file and written to disk in a configurable location.

The following XSD describes the format of the error report and notification XMLs. Samples are also provided below.

Sample Error Report XML

Result Notification

At the end of batch file processing, OIDG can call web services and/or send emails to report batch status information. There are two kinds of notifications: results notification, typically sent to the host, and validation notification, typically sent to the client. Detail error reports can be generated on the local file system or be sent to an FTP destination. Notification endpoints (web service URLs, emails addresses, report file location, FTP path) are configured using the AdminView application.

Sample Results Summary Notification

Sample Validation Summary Notification