DISQ Overview

DISQ provides a simple, more comprehensive interaction model that requires no configuration. DISQ surfaces all of the data and associated operations in a consistent and flexible manner, facilitating any kind of service interaction.

While OIPA provides flexible services with AsFile and ExposedComputation, these services are difficult to understand, configure, and interact with. There is no formal XML schema that defines the input and output parameters for most web services. The payloads typically consist of a single string, which can be any kind of structured xml data.

In contrast, DISQ provides a formal XML schema which describes the data and operations that it exposes. DISQ requires no configuration in order for it to function, beyond normal configuration in the existing system. With a simple introduction to the DISQ model, one can easily understand how to make any request into OIPA.

Request Model

DISQ consists of a single Service Endpoint, with a flexible Request model which allows several operations to be invoked dynamically. A DISQ Request consists of the following parts:

Header - provides a loose bucket of properties that can help influence the overall processing of the DISQ request.
Context - identifies the resource that the DISQ request applies to. Context is a fundamental problem with OIPA because most times external systems do not know the OIPA unique identifier (i.e. GUID) of the resource they want to access. So the system requires a different method of "looking up" the resource to work with. The Context section of the DISQ request solves this problem by allowing the caller to specify any combination of fields to uniquely identify the context for the Action.
Action - identifies the operation to be performed within the context specified.
ResponseFormat - identifies the information to be returned as a result of the action being performed.

The contents of the request are dictated by the Action being executed. It is important to understand the usage models surrounding each Action in order to understand the appropriate Context and Response

In the DISQ request sample above, we can see the following:

The Header defines a Message ID and a Timestamp. These are supported in the standard DISQ Schema, and are typically used in SOA middleware.
The Context defines the company that the client belongs to; in this case the caller is identifying the Holding Company as the context for this request.
The Action being requested is to Get a Client with the last name Hyatt.
The ResponseFormat is defined as Default. In the case of a Get action, the default response will be to return the fixed fields for the requested entity.

From a Query standpoint, it helps to read the request as follows:

Get me a Client with the Last Name 'Hyatt' that belongs to the Company named 'Holding Company'

Context

Context is one of the most important aspects to DISQ. Without holding the internal OIPA identifiers, external systems need some method of identifying the unique resource to use when executing an Action. The Context section is the DISQ means of identifying that resource.

Actions

Actions are the means of specifying the operation that is to be performed against the Context. The list of Actions that are available will grow overtime. At the time of this writing, the following Actions are expected:

Create
Get
Find

At the time of this writing, Create is supported only for Client, Get is supported for Client and Policy, Find is supported for Client, Address, Policy, Role, Segment, BenefitSplit, Withholding and Allocation.

Get Action denotes the retrieval of a single, unique resource in the system. The Get action will always return a single element. If more than one resource happens to be found, an exception will be thrown.

Find Action denotes the retrieval of multiple instances of the same source type, all instances of that type that match the search criteria will be found. Find is also different than Get in that it allows you to specify more than one data element as the action. When more than one element of the same name is specified, the result of the data retrieval is to do a UNION of the results of processing each element individually. For example, if you want to find all clients with a last name of "Smith" who live in Boston OR Bedford, you could execute the following:

<Find>
    <Client>
        <LastName>Smith</LastName>
        <Addresses>
            <Address>
                <City>Boston</City>
            </Address>
            <Address>
                <City>Bedford</City>
            </Address>
        </Addresses>
    </Client>
</Find>

Response Format

The ResponseFormat section allows the caller to specify what to include in the Response from the DISQ Request. There are a few elements in the ResponseFormat:

ResponseType - can be Default, Acknowledge, or Custom. Default is the behavior if the Response Format element is omitted from the request.

Default - the default response type is to return the subject of the action itself, and only the fixed fields. If dynamic fields are required, then the caller must specify a Custom response type.
Acknowledge - a simple success or failure will be returned from the call
Custom - the caller specifies what information is to be returned.

The example below is for a Get Client action. The Custom format indicates that the caller is requesting certain information to be returned. By specifying an empty Fields tag inside the Client tag, the caller is indicating to return dynamic fields. By specifying an empty Addresses tag inside the Client tag, the caller is indicating to return all addresses for the client.

<ResponseFormat>
    <ResponseType>Custom</ResponseType>
    <Client>
        <Fields/>
        <Addresses/>
    </Client>
</ResponseFormat>

Responses

The Responses are returned from the execution of a DISQ Request can contain any OIPA type defined in the oipa schema. Typically, these will be the entities that are the subject of the action being requested. For example, for Get Client, a Client element will be returned. This section highlights an example response.

Example: Get Client request with a Default response type.

DISQ Request

<DisqRequest>
    <Header>
        <MessageId>671B973D-2AC7-4572-8E23-202FF4C5AB64</MessageId>
        <Timestamp>2012-09-19T17:00:30.496-04:00</Timestamp>
    </Header>
    <Context>
        <Company>
            <CompanyName>Holding Company</CompanyName>
        </Company>
    </Context>
    <Get>
        <Client>
            <ClientGuid>0872C75B-B50F-47E1-B439-BA3DC3BBF88A</ClientGuid>
        </Client>
    </Get>
    <ResponseFormat>
        <ResponseType>Default</ResponseType>
    </ResponseFormat>
</DisqRequest>

DISQ Response

<Client>
    <FirstName>Deb</FirstName>
    <LastName>Hyatt</LastName>
    <TaxId>123412345</TaxId>
    <ClientGuid>0872C75B-B50F-47E1-B439-BA3DC3BBF88A</ClientGuid>
    <DateOfBirth>1976-01-01T00:00:00-05:00</DateOfBirth>
    <UpdatedGmt>2009-06-02T16:49:10-04:00</UpdatedGmt>
    <MiddleInitial/>
    <Sex>02</Sex>
    <TypeCode>02</TypeCode>
    <LegalResidenceCountryCode>US</LegalResidenceCountryCode>
    <MaritalStatus>00</MaritalStatus>
    <EntityTypeCode>CLIENT</EntityTypeCode>
</Client>

Complete Request & Response Xml Schema for DISQ

<xs:schema elementFormDefault="qualified" version="1.0" targetNamespace="http://xmlns.oracle.com/insurance/oipa" xmlns="http://xmlns.oracle.com/insurance/oipa" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:import namespace="http://xmlns.oracle.com/insurance/oipa" schemaLocation="http://localhost:8080/PASJava/DisqService?xsd=2"/>
    <xs:element name="Create">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="actionType">
                    <xs:sequence/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name="DisqRequest">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="Header" minOccurs="0">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="MessageId" type="xs:string" minOccurs="0"/>
                            <xs:element name="Timestamp" type="xs:dateTime" minOccurs="0"/>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
                <xs:element name="Context" minOccurs="0">
                    <xs:complexType>
                        <xs:choice>
                            <xs:element ref="Client"/>
                            <xs:element ref="Address"/>
                            <xs:element ref="Company"/>
                            <xs:element ref="Plan"/>
                        </xs:choice>
                    </xs:complexType>
                </xs:element>
                <xs:choice>
                    <xs:element ref="Get"/>
                    <xs:element ref="Create"/>
                    <xs:element ref="Find"/>
                </xs:choice>
                <xs:element name="ResponseFormat" minOccurs="0">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="ResponseType" type="responseType" minOccurs="0"/>
                            <xs:choice>
                                <xs:element ref="Client"/>
                                <xs:element ref="Address"/>
                                <xs:element ref="Company"/>
                                <xs:element ref="Plan"/>
                            </xs:choice>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="DisqResponse">
        <xs:complexType>
            <xs:sequence>
                <xs:choice minOccurs="0" maxOccurs="unbounded">
                    <xs:element ref="Client"/>
                    <xs:element ref="Address"/>
                    <xs:element ref="Company"/>
                    <xs:element ref="Plan"/>
                </xs:choice>
                <xs:element name="Success" type="xs:boolean"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="Find">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="actionType">
                    <xs:sequence/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name="Get">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="actionType">
                    <xs:sequence/>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:complexType name="actionType" abstract="true">
        <xs:sequence>
            <xs:choice minOccurs="0" maxOccurs="unbounded">
                <xs:element ref="Client"/>
                <xs:element ref="Address"/>
                <xs:element ref="Company"/>
                <xs:element ref="Plan"/>
            </xs:choice>
        </xs:sequence>
    </xs:complexType>
    <xs:simpleType name="responseType">
        <xs:restriction base="xs:string">
            <xs:enumeration value="Default"/>
            <xs:enumeration value="Custom"/>
            <xs:enumeration value="Acknowledge"/>
        </xs:restriction>
    </xs:simpleType>
</xs:schema>
<xs:schema elementFormDefault="qualified" version="1.0" targetNamespace="http://xmlns.oracle.com/insurance/oipa" xmlns="http://xmlns.oracle.com/insurance/oipa" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="Address">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="oipaType">
                    <xs:sequence>
                        <xs:element name="Line1" type="xs:string" minOccurs="0"/>
                        <xs:element name="Line2" type="xs:string" minOccurs="0"/>
                        <xs:element name="Line3" type="xs:string" minOccurs="0"/>
                        <xs:element name="Line4" type="xs:string" minOccurs="0"/>
                        <xs:element name="Line5" type="xs:string" minOccurs="0"/>
                        <xs:element name="Line6" type="xs:string" minOccurs="0"/>
                        <xs:element name="City" type="xs:string" minOccurs="0"/>
                        <xs:element name="StateCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="PostalId" type="xs:string" minOccurs="0"/>
                        <xs:element name="AddressRoleGuid" type="xs:string" minOccurs="0"/>
                        <xs:element name="AddressRoleCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="AddressGuid" type="xs:string" minOccurs="0"/>
                        <xs:element name="DefaultFlag" type="xs:string" minOccurs="0"/>
                        <xs:element name="EmailCorrespondenceFlag" type="xs:string" minOccurs="0"/>
                        <xs:element name="EffectiveDate" type="xs:dateTime" minOccurs="0"/>
                        <xs:element name="ExpirationDate" type="xs:dateTime" minOccurs="0"/>
                        <xs:element name="RegionCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="MunicipalityCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="CountryCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="Email" type="xs:string" minOccurs="0"/>
                        <xs:element name="PhoneNumber" type="xs:string" minOccurs="0"/>
                        <xs:element name="FaxNumber" type="xs:string" minOccurs="0"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name="Client">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="oipaType">
                    <xs:sequence>
                        <xs:element name="FirstName" type="xs:string" minOccurs="0"/>
                        <xs:element name="LastName" type="xs:string" minOccurs="0"/>
                        <xs:element name="TaxId" type="xs:string" minOccurs="0"/>
                        <xs:element name="ClientGuid" type="xs:string" minOccurs="0"/>
                        <xs:element name="DateOfBirth" type="xs:dateTime" minOccurs="0"/>
                        <xs:element name="DateOfDeath" type="xs:dateTime" minOccurs="0"/>
                        <xs:element name="UpdatedGmt" type="xs:dateTime" minOccurs="0"/>
                        <xs:element name="CompanyName" type="xs:string" minOccurs="0"/>
                        <xs:element name="Email" type="xs:string" minOccurs="0"/>
                        <xs:element name="MiddleInitial" type="xs:string" minOccurs="0"/>
                        <xs:element name="Prefix" type="xs:string" minOccurs="0"/>
                        <xs:element name="Sex" type="xs:string" minOccurs="0"/>
                        <xs:element name="Suffix" type="xs:string" minOccurs="0"/>
                        <xs:element name="TypeCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="LegalResidenceCountryCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="AlternateName1" type="xs:string" minOccurs="0"/>
                        <xs:element name="AlternateName2" type="xs:string" minOccurs="0"/>
                        <xs:element name="AlternateName3" type="xs:string" minOccurs="0"/>
                        <xs:element name="AlternateName4" type="xs:string" minOccurs="0"/>
                        <xs:element name="AlternateName5" type="xs:string" minOccurs="0"/>
                        <xs:element name="AdditionalPrefix" type="xs:string" minOccurs="0"/>
                        <xs:element name="AdditionalSuffix" type="xs:string" minOccurs="0"/>
                        <xs:element name="TaxIDType" type="xs:string" minOccurs="0"/>
                        <xs:element name="Title" type="xs:string" minOccurs="0"/>
                        <xs:element name="MaritalStatus" type="xs:string" minOccurs="0"/>
                        <xs:element name="BirthCountryCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="CitizenshipCountryCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="BirthRegionCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="PrimaryPhone" type="xs:string" minOccurs="0"/>
                        <xs:element name="TextField1" type="xs:string" minOccurs="0"/>
                        <xs:element name="TextField2" type="xs:string" minOccurs="0"/>
                        <xs:element name="CheckBox1" type="xs:string" minOccurs="0"/>
                        <xs:element name="CheckBox2" type="xs:string" minOccurs="0"/>
                        <xs:element name="Radio1" type="xs:string" minOccurs="0"/>
                        <xs:element name="Radio2" type="xs:string" minOccurs="0"/>
                        <xs:element name="Combo1" type="xs:string" minOccurs="0"/>
                        <xs:element name="Combo2" type="xs:string" minOccurs="0"/>
                        <xs:element name="EntityTypeCode" type="xs:string" minOccurs="0"/>
                        <xs:element name="Date1" type="xs:dateTime" minOccurs="0"/>
                        <xs:element name="Date2" type="xs:dateTime" minOccurs="0"/>
                        <xs:element name="Addresses" minOccurs="0">
                            <xs:complexType>
                                <xs:sequence>
                                    <xs:element ref="Address" minOccurs="0" maxOccurs="unbounded"/>
                                </xs:sequence>
                            </xs:complexType>
                        </xs:element>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name="Company">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="oipaType">
                    <xs:sequence>
                        <xs:element name="CompanyName" type="xs:string" minOccurs="0"/>
                        <xs:element name="CompanyGuid" type="xs:string" minOccurs="0"/>
                        <xs:element ref="Client"/>
                        <xs:element ref="Plan"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:element name="Fields">
        <xs:complexType>
            <xs:sequence>
                <xs:any processContents="lax" namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="Plan">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="oipaType">
                    <xs:sequence>
                        <xs:element name="PlanName" type="xs:string" minOccurs="0"/>
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
    <xs:complexType name="oipaType" abstract="true">
        <xs:sequence>
            <xs:element ref="Fields"/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>