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.
Operations
This specific API supports the following operations
|
|
|
|
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
orctrclaims
. -
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
: ThesubResource
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 on 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:
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 includes data from subresources.
Consider the following examples:
expand value | claimLine included? | claimLineDiagnosis included? | claimDiagnosis included? | claimPendReason included? | claimLinePendReason included? |
---|---|---|---|---|---|
not specified |
No |
No |
No |
No |
No |
|
Yes |
No |
No |
No |
No |
|
Yes |
No |
Yes |
No |
No |
|
Yes |
No |
Yes |
Yes |
No |
|
Yes |
Yes |
No |
No |
Yes |
The expand
parameter includes 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 |
|
Yes |
No |
No |
No |
No |
|
Yes |
Yes |
Yes |
No |
No |
|
Yes |
Yes [1] |
Yes[1] |
No |
Yes[1] |
|
No |
No |
No |
Yes |
No |
|
No |
Yes |
No |
No |
Yes |
|
No |
Yes |
No |
No |
No |
When the representation includes dynamic data in the form of dynamic records or flex codes, each dynamic record or flex code 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:
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 |
Default representation properties for servicedMember |
No |
No |
servicedMember.addressList |
Includes the default representation and a |
Default representation properties for servicedMember |
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 different. 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 that 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 the 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, the same as a credential key.
Authorization
A user authorization configuration protects access to this integration point. The relevant access restriction is the 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.
For example, where all claims with a person
as a linked resource are 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.
Response Message
The system returns the following response message along with a 200 status for a successful extraction process.
{
"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"
}
]
}
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.