Extract Integration Point

Introduction

This integration point enables bulk extraction of data. It submits and monitors the extraction process.

The submit request starts an extract configuration that begins an asynchronous process to extract data. Upon completion of the extraction process, a pre-configured endpoint receives a notification.

The Extract Configuration

The extract configuration specifies the criteria to extract data. This includes rows to select, properties, and any linked data not directly part of the resource itself.

The extract configuration comprises:

  • resourceName: The name of the root resource to extract data. For example, policies or ctrclaims.

  • q: The query string for the root resource. It specifies a criteria to select rows. This parameter works similar to the syntax of a query API.

  • fields: The basic and reference fields of a root resource to determine the data to include in the extraction process.

  • expand: The subResource of shorthand keys like dynamicData, rootDynamicData, and subResources to include in the extraction process.

  • linkedResources: Includes extra resources in the extract, not part of the root resource. For example, calculation results along with policies. It can include a list of linked resources of a root resource for the extraction process. The configuration to include a linked resource is similar to that for including a root resource.

    • resourceName: The linked resource name.

    • join: The join criteria to join a linked resource with a root resource. This parameter only supports a subset of query API parameters. Following is the list of parameters that this parameter allows:

    • q: Selects a criteria for the linked resource.

    • fields: Sets the basic and reference type properties of a root resource.

    • expand: Selects properties of a subresources of a linked resource for the extract request.

The Extract Payload

The extract request generates a data file set with multiple files. Each file contains an array of records. Each record is a representation of a row with the linked resources based on the query criteria set for a root resource.

The payload for each selected row contains the root resource and the properties of all the linked resources. The View Objects page contains the resource properties. Each object property has different data types. See Property Representation (GET) for the different representations of a data type.

The property name of an object property matches the name in the View Objects page. The property name works for the fixed properties. The Field Usage name works for dynamic properties.

The default representation for the extract request includes the following elements:

Table 1. Extract Payload
Element Data Type 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 determine the response that includes more information than the default representation.

The Expand Parameter

The expand parameter controls the inclusion of subresources.

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, like subresources or dynamicData.

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 determines the additional properties that return in a resource representation of the extract request.

Consider the following examples:

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

not specified

Displays all the properties in the default representation

No

No

No

code and id

Includes only code and id

No

No

No

servicedMember

Includes the default representation and a servicedMember reference property

Default representation properties for servicedMember

No

No

servicedMember.addressList

Includes the default representation and a servicedMember reference property

Default representation properties for servicedMember
addressList sub resource

Includes the default representation for all the addresses

No

claimLineList.id and claimLineList.code

Includes all the properties specified in the default representation

No

No

Only code and id included for all the claimLines

Join Linked Resources

For a join operation, the left side expression is for the root resource and the right side expression is for the linked resource. Following is a syntax used for the join criteria:

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
The join between the root and the linked resource is an outer join. The extract request does not include information about root resources that do not have a linked resource.

In the following example, the extract is on claims and fetches ctrClaims as a linked resource. The join between ctrClaim and claim is on code.

code.eq("code")

This is an example of a join criteria with a simple expression.

The right expression is for the ctrClaims linked resource and the left expression refers to the claims root resource.

The following example extracts data for policies and different versions of policies along with their linked resources. The join between policies and policies versions is on gid, both ids are not the same. Hence, the following join criteria is a complex expression:

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

The right expression refers to policies as a linked resource that fetches versions and the left expression refers to policies as a root resource and considers the latest version.

Notification

The extract request uses the generic notification. A notification key is sent during the submit step of the extract request.

The notification is sent to a pre-configured endpoint and the notification key helps determine whether the extraction process was a success or not.

The ohi.extract.{0}.notification.endpoint property configures the notification endpoint. Here, {0} is the notification key for the extract.

The configured endpoint accepts a POST request.

A data extraction on a gateway uses gateway as the notification key. The keyword directs the IP to the notification integration point in the gateway.

The notification uses JSON as the default media type. Alternative media types are configured through the REST client’s media type properties. The media type of the notification is set through the ohi.service.{0}.media.type property, where {0} is the notification key for the extract.

Following is an example of a notification:

{
    "status": "",
    "correlationId": "",
    "links": [
        {
            "rel": "file",
            "href": "http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafiles/{datafilecode}/data",
        }
    ]
}

Authentication

The extract notification supports different authentication types for the notification clients. The default value is the basic authentication. The ohi.service.{0}.client.authentication property uses the authentication feature, where {0} is the notification key on the extract, same as a credential key.

Authorization

A user authorization configuration protects access to this integration point. The relevant access restriction is extracts IP access restriction.

API Conversation and Interaction

This integration point is a Long-Running Operations Through REST. This section explains an example to extract a resource.

Let us take an example where all claims with a person as a linked resource is joined with a claimLine serviced member. The extract payload contains all the claim and claim line subresources and all the subresources of the person-linked resource. The extract notification is sent to the pre-configured endpoint with the gateway notification key.

The submit request accepts an optional correlationId header. An external system uses a header that matches the request and the notification message. The extraction process stores and includes the header as part of the notification message.

Starting the Extraction Process

A POST request to the /extracts resource starts the extraction process.

Request

Following is an example of the request payload:

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

Response

Following is an example of a response payload:

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://[hostName]:[portNumber]/[api-context-root]/extracts/12324

The application returns an HTTP 201 (Created) response with a location header for the data file set.

Monitoring the Extraction Process

A monitor link helps to monitor the extraction process.

Request

The following request returns the status of the extraction process:

GET /extracts/1

Response

Following is a response to the monitor request:

200
{
    "notificationKey": "gateway",
    "status": "InProcess",
    "links": [
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/activities/{id}",
            "rel": "operator",
            "httpMethod": "GET"
        },
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/extracts/{id}",
            "rel": "monitor",
            "httpMethod": "GET"
        }
    ]
}

The request returns a payload with links and status of the extraction process along with a 200 response. Additional links such as operator:restart and operator:messages are available in case of a failed extraction process. Following is an example of a payload that returns for a failed process:

{
    "notificationKey": "gateway",
    "status": "TechnicalError",
    "links": [
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/activities/234",
            "rel": "operator",
            "httpMethod": "GET"
        },
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/activities/234/recover",
            "rel": "operator:restart",
            "httpMethod": "POST"
        },
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/activities/234/messages",
            "rel": "operator:messages",
            "httpMethod": "GET"
        },
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/extracts/1",
            "rel": "monitor",
            "httpMethod": "GET"
        }
    ]
}

Completion of Extraction Process

The configured endpoint receives a notification after the completion of the extraction process. The location-header link returns the extracted results.

A GET request on the location-header link returns the following response:

{
    "notificationKey": "gateway",
    "status": "Success",
    "links": [
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/activities/2572368306",
            "rel": "operator",
            "httpMethod": "GET"
        },
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/datafilesets/EXT12302",
            "rel": "file",
            "httpMethod": "GET"
        }
    ]
}

The response contains a link to the data file set. The link downloads the extracted data.

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