Extract Integration Point
Introduction
This integration point enables the Oracle Health Insurance application to perform bulk data extraction. It exposes APIs to submit and monitor extract process. Submit API accepts an extract configuration and triggers an asynchronous process. After the process completes, the configured destination receives a notification.
Extract Configuration
Data required to be extracted is defined by an extract configuration. As a part of the configuration, it is possible to provide the row selection criteria, property selection, any linked data that is not directly part of the resource itself.
-
resourceName: The root resource for extraction, For example, policies, ctrclaims. -
q: The query string for the root resource. This provides the row selection criteria and follows the Query API semantics. -
fields: The basic and reference field properties selection for the root resource, with the fields configuration it is possible to include or exclude properties. Refer below examples. -
expand: The subResource property selection criteria for the root resource. To make configuration less verbose, it is possible to use 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
Extract process generates a DataFileSet with multiple files. Each file contains an array of records and each record is a representation of a row selected by the root resource query criteria including all the linked resources for the row selection.
Default Row Payload
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:
| 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 |
Influence Row Payload
Fields or expand parameters can influence the default presentation. Use expand to control the subResource and use fields to control the basic and reference properties.
Include Sub Resources Using Expand
| 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 |
Include DynamicData
expand also influences the dynamicData.
| 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 |
Include or Exclude Properties Using Fields
The fields parameter can be used to control properties to be included in the resource representation. There is no way to explicitly exclude properties that work together with include. By including any basic property on certain level, other basic properties can be excluded.
| 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 |
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 root resource and linked resource is the right side expression. The grammar 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 does not support joining on dynamic fields. |
Example: Simple Expression
The extract is on claims and is required to fetch 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.
Example: Complex Expression
The extract is on policies and is required to fetch 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
Extract process supports the notification mechanism. A notification key can be provided during the extract submission process. Notification step skips in the absence of notification key. A notification can be sent out to the configured endpoint, by providing a notification key after the extract process completes successfully or unsuccessfully.
Use ohi.extract.<0>.notification.endpoint to configure notification endpoints. Where <0> must be replaced with the notification key defined on the extract.
The configured endpoint url should 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.
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 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.
Monitor 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.
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.