Extract Integration Point

Introduction

This integration point enables bulk data extraction out of Oracle Health Insurance applications. It exposes operations to submit and monitor the extract process.

The submit operation accepts an extract configuration and starts an asynchronous process to extract the information. Upon completion of the extract, the configured destination receives a notification.

Extract Configuration

An extract configuration specifies the criteria of the to-be extracted information. This includes row selection criteria, property selection, and any linked data that is not directly part of the resource itself.

The extract configuration comprises the following parameters:

  • resourceName: The root resource for extraction. Examples are policies and ctrclaims.

  • q: The query string for the root resource. It specifies the row selection criteria following the Query API syntax.

  • fields: The basic and reference field properties selection for the root resource. This controls which attributes are included in the extract.

  • expand: The subResource property selection criteria for the root resource. This parameter supports shorthand keys dynamicData, rootDynamicData, and subResources to include certain type of data. Refer below examples.

  • linkedResources: Allows including extra resources in the extract that are not part of root resource. For example, calculation results along with policies. This is a list of linkedResource configuration to extract multiple resources along with the root resource. Configuration related to linked resource is similar to the root resource.

    • resourceName: The linked resource name.

    • join: Linked resource join criteria with the root resource. Only supports subset of Query API operators. Refer below examples.

    • q: Other selection criteria for the linked resource.

    • fields: The basic and reference type properties selection for the root resource.

    • expand: subResource properties selection criteria for the linked resource.

Extract Payload

The extract process generates a DataFileSet with multiple files. Each file contains an array of records. Each record is a representation of a row selected by the root resource query criteria including all the linked resources for the row selection.

The payload for each selected row contains the root resource and the properties of all the linked resources. The resource properties can be found in the View Objects page. Object properties in Oracle Health Insurance can have different data types. Each datatype has a different representation which is defined in the section Property Representation (GET).

The property name of an object property matches the name in the View Objects page. For fixed properties, just use the name. For dynamic properties, use Field Usage Name.

The default representation of a resource includes the following elements:

Table 1. Extract Payload
Element Included?

Basic Properties (single value)

Yes

Reference Properties (single value)

No

Dynamic Record (single value)

No

Sub resources

No

Basic Properties (multi value)

Yes

Reference Properties (multi value)

No

Dynamic Record (multi value)

No

Basic Properties (time valid)

No

Reference Properties (time valid)

No

Dynamic Record (time valid)

No

The fields and expand parameters control the inclusion information in the payload, i.e., in addition to the default representation.

The Expand Parameter

The expand parameter controls the inclusion of sub resources.

Consider the following examples:

Table 2. The Expand Parameter
expand value claimLine included? claimLineDiagnosis included? claimDiagnosis included? claimPendReason included? claimLinePendReason included?

not specified

No

No

No

No

No

claimLineList

Yes

No

No

No

No

claimLineList.claimDiagnosesList

Yes

No

Yes

No

No

subResources

Yes

No

Yes

Yes

No

claimLineList.subResources

Yes

Yes

No

No

Yes

The expand parameter also controls the inclusion of dynamic records and dynamic fields as sub resources, collectively referred to as dynamicData.

Table 3. Consider the Following Examples
expand value claim dynamicData included? claimLine dynamicData included? claimDiagnosis dynamic data included? brand dynamicData included? claimLinePendReason dynamicData included?

not specified

No

No

No

No

No

rootDynamicData

Yes

No

No

No

No

subResources

Yes

Yes

Yes

No

No

dynamicData

Yes

Yes[1]

Yes[1]

No

Yes[1]

brand.dynamicData

No

No

No

Yes

No

claimLineList.subResources

No

Yes

No

No

Yes

claimLineList.dynamicData

No

Yes

No

No

No

When the representation includes dynamic data in the form of dynamic records, each dynamic record representation includes a GUID field.

The Fields Parameter

The fields parameter controls which additional properties are included in the resource representation.

Consider the following examples:

Table 4. Fields Parameter
Fields Value Claim Included? ServicedMember Included? servicedMember.addressList included? claimLineList included?

not specified

All the properties specified in default representation

No

No

No

code and id

Only code and id included

No

No

No

servicedMember

Default representation + servicedMember reference property

Default representation properties for servicedMember

No

No

servicedMember.addressList

Default representation + servicedMember reference property

Default representation properties for servicedMember
addressList sub resource

Default representation for all the addresses.

No

claimLineList.id and claimLineList.code

All the properties specified in default representation

No

No

Only code and id included for all the claimLines

Joining Linked Resources

As a convention the left side expression is the root resource and the linked resource is the right side expression. The syntax used for the join criteria is as follows.

join := expression
expression := [[(]simple_expression | complex_expression[)]]
simple_expression := field_name.operator(linked_resource_name.field_name)
operator := eq | neq
field_name := attribute[(+)]?[.field_name]* -- for joins
complex_expression := expression.complex_operator.expression
complex_operator := and | or
Join expressions on dynamic fields are not supported.

In the following example, the extract is on claims and fetches ctrClaims along with it as linkedResources. The join between ctrClaim and claim is on code. Hence, the join criteria is a simple expression.

code.eq("code")

Right side refers to ctrClaims linkedResource and left side refers to claims root resource.

In the following example, the extract is on policies and fetches all other versions of policies as linkedResources. The join between policies and policies versions is on gid and both ids are not the same. Hence, the join criteria is a complex expression.

gid.eq("gid").and.id.neq("id")

Right side refers to policies as linkedResource to fetch the versions and left side refers to policies root resource where it is the last version.

Extract Notification

The extract process makes use of the generic notification mechanism. A notification key can be provided during the extract submission process.

The notification is sent out to the configured endpoint, by providing a notification key after the extract process completes successfully or unsuccessfully.

Set the property ohi.extract.<0>.notification.endpoint to configure notification endpoints. <0> is replaced with the notification key defined on the extract.

The configured endpoint url has to accept the POST requests.

Gateway extract requests use gateway as the notification key. It points to the Notification Integration Point in the Gateway.

Notifications use JSON as the default media type. Configure alternative media types via the rest client’s media type properties. Configure the media type of the notification by setting property ohi.service.{0}.media.type in which placeholder {0} should be replaced with the notification key defined on the extract.

Use the following message for notification:

{
    "status": "",
    "correlationId": "",
    "links": [
        {
            "rel": "file",
            "href": "href="http://host:port/contextroot/datafilesets/{datafilesetcode}/datafiles/{datafilecode}/data",
        }
    ]
}

Authentication

The extract notification supports different authentication types for the notification clients, the default value is BasicAuthentication. ohi.service.{0}.client.authentication property can be used to set the authentication feature, {0} should be replaced with the notification key on the extract, use the same notification key for credentialKey.

Authorization

The extracts IP access restriction protects this integration point.

API Conversation and Interaction

This integration point uses Long-Running Operations Through REST API conversation style. This section provides a complete example of a single extract conversation.

This example covers the use case of extracting all claims with person as linked resource, and use claimLine serviced member for join criteria. Extract payload includes all the claim and claimline sub resources and for person linked resource all the sub resources for the person. Extract notification will be sent to the configured endpoint with gateway notification key.

Submit API accepts an optional correlationId header. To match the request and notification message, External systems use the header. Extract stores the header and later includes it as a part of the notification message.

Starting the Extract Process

To start the extract process, use the POST method to submit following request to /extracts.

Request

header - correlationId: 123
{
   "notificationKey": "gateway",
   "resourceName": "claims",
   "expand": "subResources|claimLineList.subResources",
   "linkedResources": [
    {
       "resourceName": "persons",
       "join": "claimLineList.servicedMember.code.eq("code")",
       "expand": "subResources"
    }
   ]
}

Response

201
Content-Type: application/vnd.oracle.insurance.resource+json
Vary: Accept,Accept-Encoding,Accept-Language,Origin
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-OHI-APP-ID: ALI
X-OHI-APP-VERSION: 6.0.0
X-XSS-Protection: 1; mode=block
Location: http://host:port/api/generic/extracts/12324

The system responds with HTTP 201 (Created) and a location header for the extract.

Monitoring the Extract Process

A monitor link from the starting response can be used for monitoring the extract process. The following request can be used to get the extract status.

Request

GET /extracts/1

Response

200
{
    "notificationKey": "gateway",
    "status": "InProcess",
    "links": [
        {
            "href": "http://hostname:port/contextroot/api/activities/{id}",
            "rel": "operator",
            "httpMethod": "GET"
        },
        {
            "href": "http://hostname:port/contextroot/api/extracts/{id}",
            "rel": "monitor",
            "httpMethod": "GET"
        }
    ]
}

The payload containing links and status of the extract returns with a 200 response. If the extract process fails, additional links operator:restart, operator:messages will be included in the response. If the same request as above is used in failure scenario the response looks like below:

{
    "notificationKey": "gateway",
    "status": "TechnicalError",
    "links": [
        {
            "href": "http://host:port/contextroot/api/activities/234",
            "rel": "operator",
            "httpMethod": "GET"
        },
        {
            "href": "http://host:port/contextroot/api/activities/234/recover",
            "rel": "operator:restart",
            "httpMethod": "POST"
        },
        {
            "href": "http://host:port/contextroot/api/activities/234/messages",
            "rel": "operator:messages",
            "httpMethod": "GET"
        },
        {
            "href": "http://host:port/contextroot/api/extracts/1",
            "rel": "monitor",
            "httpMethod": "GET"
        }
    ]
}

Completion of Extract Process

After the extract process completes, the configured endpoint receives notification. The location header link returned in the first step can be used to get the extract results.

GET on location header link returns following response:

{
    "notificationKey": "gateway",
    "status": "Success",
    "links": [
        {
            "href": "http://host:port/contextroot/api/activities/2572368306",
            "rel": "operator",
            "httpMethod": "GET"
        },
        {
            "href": "http://host:port/contextroot/api/datafilesets/EXT12302",
            "rel": "file",
            "httpMethod": "GET"
        }
    ]
}

Response contains a link to datafileset, this link can be used to download the extract results.

1. Dynamic data is only included, if the sub resource itself is included.