Claim Callout Integration Point
This Integration Point implements the execution of claim callout rules. While a claim is processed, claim callout rules may be triggered. The purpose of the claim callout integration point is to call out, that is, send messages, to external systems and to receive and handle the associated responses.
Callout Rules are described in configuration:process-rules/claim-callout-rules.adoc. The text below only describes technical details of the Claim Callout Integration Point.
Design Choices
-
The request headers includes correlationId for asynchronous call outs. Oracle Health Insurance expects this information back in the response header when the asynchronous response is received.
-
To handle response messages for asynchronous callouts, this Integration Point features one listening endpoint. This endpoint can be consumed by external components to deliver the response messages to asynchronous callouts. This endpoint is protected by access grant 'claimscalloutasync IP'. The endpoint supports three paths:
-
/custom - to handle response messages of a custom format. These responses will be processed using the "Response Logic" specified in the callout definition.
-
/claimsupdate - to handle response messages that adhere to the Claims Update IP (HTTP). The callout rule response mechanism (implemented by the Claim Callout Integration Point) will process such responses as 'regular' Claims Update IP requests (also see "Additional Notes" below).
-
/claimsupdate/submit. The same as the one above. After updating the claim, the claim is submitted as well.
-
Illustrations
Synchronous Messaging
In synchronous messaging the same HTTP connection is used for sending the request (1) and receiving the response (2):
-
The request message (1) is created with the "Request Logic" specified in the callout definition and sent to the external component.
-
If the request message was created and delivered successfully, the request sent timestamp is logged in the claim callout history.
-
The response message (2) is received, stored and processed by executing the 'Response Logic' of the callout definition (if defined). The response received timestamp is logged in the claim callout history. This will be the same as the request sent timestamp, because the callout is synchronous.
![Claim Callout Integration Point](configuration:process-rules/call_out_sync.png)
Asynchronous Messaging
In asynchronous messaging separate HTTP connections are used for sending the request message and for receiving the response message:
-
The request message (1) is created with the "Request Logic" specified in the callout definition and sent tot the external component.
-
If the request message was created and delivered successfully, the request sent timestamp is logged in the claim callout history.
-
This request message gets a technical response (2) which indicates that the request is being processed by the external component. This response includes only a HTTP status code; any message content is disregarded as that should be included in the asynchronous response message via the separate HTTP connection.
-
The asynchronous response message (3) is received, stored and processed. The response received timestamp is logged in the claim callout history. Depending on the path to which the response is sent, one of the following happens:
-
The response with a custom format is processed by executing the "Response Logic" of the callout definition.
-
The response is passed to the Claims Update IP (HTTP) and processed like regular Claims Update IP requests (also see additional notes below).
-
The response is passed to the Claims Update IP (HTTP) and processed like regular Claims Update IP requests (also see additional notes below) and submitted as well.
-
-
The response (4) to the asynchronous response message (3) contains the response message described below.
![Claim Callout Integration Point](configuration:process-rules/call_out_async.png)
Request Message
The request message that is sent to the external component (arrow 1 in both pictures above) may be of any JSON/XML-form as created in dynamic logic (the "Request Logic"). Additionally, the dynamic logic may specify a request header map. When specified, the values are set as request headers of the call out event.
Depicted below is an example request message to a DRG-grouper component using a synchronous callout. The creation of this message, including the encapsulating element <synchronousCalloutRequest>, would have to be coded in dynamic logic (the "Request Logic"):
<synchronousCalloutRequest> <claim> <claimCode>CLAIM12345</claimCode> <fields> <field name="grouperType" value="APR"/> <field name="grouperVersion" value="30"/> </fields> </claim> </synchronousCalloutRequest>
Synchronous Response Message
The synchronous response (arrow 2 in the synchronous scenario) is a custom XML/JSON-message.[1] The entire response message is fed to the "Response Logic" (if defined).
Example:
<synchronousCalloutResponse> <claim code='CLAIM123'> <attendingProvider>123456</attendingProvider> <locationProvider>345678</locationProvider> <operatingProvider>098765</operatingProvider> <referralProvider>567895</referralProvider> </claim> </synchronousCalloutResponse>
Asynchronous Response Message
The asynchronous response (arrow 3 above) should either be a Claims Update IP message with correlation information or be a custom XML/JSON-message [1]. In case of a custom response, the entire response message is fed to the "Response Logic".
Example (custom XML-message):
<asynchronousCalloutResponse> <claim code='CLAIM123'> <attendingProvider>123456</attendingProvider> <locationProvider>345678</locationProvider> <operatingProvider>098765</operatingProvider> <referralProvider>567895</referralProvider> </claim> </asynchronousCalloutResponse>
Asynchronous Response Response Message
Please refer to the 'Response Messages' section in the HTTP API Integration Points part of the Common Features book for more details.
Error Messages
The following error messages that are specific to this Integration Point may be returned in the Asynchronous Response Response Message:
Code | Sev | Message |
---|---|---|
CLA-IP-CALL-001 |
Fatal |
Callout Response with correlation id {0} is already received |
CLA-IP-CALL-002 |
Fatal |
Callout Request with correlation id {0} could not be found |
CLA-IP-CALL-007 |
Fatal |
Callout Request with correlation id {0} has already timed out |
Notes:
-
CLA-IP-CALL-001 is raised when an asynchronous response contains correlation information that refers to a request message for which a response was already received earlier.
-
CLA-IP-CALL-002 is raised when an asynchronous response contains correlation information for which the correlating request message cannot be found. I.e. when the response message refers to a request message that does not exist.
-
CLA-IP-CALL-007 is raised when an asynchronous response is received after the request has timed out. In this case an error task for the time out is already displayed in the UI page "View Technical Errors" (Operations menu). This task needs to be reprocessed to re-execute the callout from the start.
Additional Notes
Note the following applies:
-
When responding to a callout rule, the Claims Update IP request message is directed at the endpoint of the Callout Rule IP, instead of at the endpoint of the Claims Update IP.
-
When responding to a callout rule, the Claims Update IP request message contains correlation information in the request header to match the message to a callout rule which is pending response.
-
When responding to a callout rule, the response to a Claims Update IP request message will be an Asynchronous Response Message (see above), i.e. not a Claims Update IP request message. Errors raised in processing of the Claim Update IP request message are not sent back to the external component. The concerned error message(s) will however be displayed in the UI page "View Technical Errors" (Operations menu), as details of the technical error that is displayed there in that case.
-
The requestHeaders bind variable of the dynamic logic function callout definition be use to specify request headers to be set for REST based call out events. For details refer to Dynamic Logic guide.