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 arepolicies
andctrclaims
. -
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:
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:
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.
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:
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 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.
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.
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.