Medicare Online and ECLIPSE Web Services
Services Australia (referred to as the Agency from now on) developed Medicare Online claiming and Electronic Claim Lodgement and Information Processing Service Environment (ECLIPSE) in collaboration with the health care industry, the medical software industry and public and private hospitals.
The Oracle Insurance Gateway supports ECLIPSE Web Services and the accompanying PRODA organisational authentication model to send and receive Web Service requests or responses to and from the Agency.
Private Health Insurer Responsibilities
The following are Private Health Insurer (PHI) responsibilities that are not supported by the system:
-
Redirect requests from the Agency to Oracle Health Insurance Agent.
-
Registration of the Software Instance and obtaining and securely storing the Device Activation Code (DAC) that is needed to activate it.
-
Upon successful activation, PRODA maintains a valid time period for a Software Instance or Device, the Device expiry period. The agency disables the Software Instance after that period. The PHI is responsible for managing Device expiry using the PRODA website. Send a GET request to the Oracle Insurance Gateway’s
/eclipse/expirytimes
resource to retrieve the latest Device and Key expiry times that the system received from the Agency. If the Software Instance is not activated the GET request results in errorOIG-AUEC-002: Software Instance not activated, operation cannot be completed
. See the ECLIPSE documentation for the format and time zone for Device and Key expiry times. -
For a number of use cases the Agency relies on e-mail exchange, for example around ping requests. The Oracle Insurance Gateway does not support automated processing of e-mails from the Agency.
Enabling ECLIPSE Support
The Oracle Insurance Gateway enables ECLIPSE capabilities as part of its Australian Localizations.
Activating the Oracle Insurance Gateway Software Instance
A Software Instance, or a Device, that supports ECLIPSE Web Services must be registered and activated. Follow the Agency’s instructions to register the Software Instance.
Processing an Oracle Insurance Gateway Exchange that sends a request to an Agency service using an inactive Software Instance
results in error OIG-GATE-019
and fails the Exchange.
Pre-requisites for activating the Software Instance:
-
Run the Oracle Insurance Gateway Software Instance with Australian Localizations enabled
-
Set values for the following system properties:
Oracle Insurance Gateway System Property Description ohi.integration.australia.eclipse.si.activation.url
ECLIPSE Software Instance Activation URL. The specified value requires a placeholder
device_name
. At runtime, the system replaces the placeholder with the value of system propertyohi.integration.australia.eclipse.device.name
.ohi.integration.australia.eclipse.organization.identifier
Organization Identifier defined at registration time. Passed as
orgId
value in the payload of the Software Instance activation request and as HTTP Headerdhs-auditId
.ohi.integration.australia.eclipse.device.name
Device name as given or used during device registration. The system uses the value to construct the Software Instance Activation URL. Besides, the same value appears as HTTP Header
dhs-subjectId
and in the payload as value for attributekid
.ohi.integration.australia.eclipse.token.header.audit.id.type
The class of audit user specified, the value appears as HTTP Header
dhs-auditIdType
. Default value:http://humanservices.gov.au/PRODA/org
.ohi.integration.australia.eclipse.token.header.subject.id.type
The class of the subject, that is, as listed in HTTP Header
dhs-subjectId
. The value appears as HTTP Headerdhs-subjectIdType
. Default value:http://humanservices.gov.au/PRODA/device
.
To activate the Software Instance, send a PUT request to the Oracle Insurance Gateway HTTP API resource /eclipse/activate
with the following payload:
{ "deviceActivationCode" : "Device_Activation_Code_Value" }
If the Software Instance is already activated then the system returns error OIG-AUEC-003: Software Instance already activated
.
If a Device Activation Code is not provided then the system returns error OIG-AUEC-007: Device Activation Code is needed to activate the Software Instance
.
The Oracle Insurance Gateway does not store the Device Activation Code.
If transmitting the Public Key to the Agency succeeds, and the response received from the Agency indicates that the Software Instance is now activated then the system returns an HTTP 200 OK response containing the Device & Key expiry times it received from the Agency.
If the system encounters an error activating the Software Instance then it returns an HTTP 422 response with error OIG-AUEC-004: Software Instance activation failed, error: {error_detail}
.
To remove the existing Key Pair and re-activate the Software Instance using a newly generated Key Pair, send a PUT request to the Oracle Insurance Gateway HTTP API resource /eclipse/activate
with the following payload:
{ "deviceActivationCode" : "Device_Activation_Code", "force" : true }
Retrieving an Access Token at Startup for an Activated Software Instance
After activating the Software Instance at startup the system detects the Key Pair in the Key Store. Using the Key it retrieves a token in order to get up-to-date Device and Key expiry times.
Set values for the following system properties:
Oracle Insurance Gateway System Property | Description |
---|---|
|
The endpoint URL for retrieving tokens. |
|
Used by the system to retrieve a Service Provider specific access token. |
|
Used by the system to retrieve a Service Provider specific access token.
The JWT Assertion requires use of a |
|
Used by the system to retrieve a Service Provider specific access token.
The JWT Assertion requires use of a |
|
Used by the system to retrieve a Service Provider specific access token.
The JWT Assertion requires use of a |
|
Client identifier as provided during software registration. |
|
Name of the Software Instance |
See the ECLIPSE documentation for the values of system properties ohi.integration.australia.eclipse.service.provider.<REST Client ID>
and ohi.integration.australia.eclipse.service.provider.<REST Client ID>.audience
.
Refreshing the Device Key
The system checks if the existing Device or Key has expired or is about to expire.
If either the Device or Key has expired then the system de-activates the Software Instance by removing any Key Pair from the Key Store. The Agency does not accept requests from a Software Instance that is not activated. An authorised person at the PHI must regenerate a new Device Activation Code and re-activate the Software Instance.
Every 5 minutes the system monitors Key expiry and automatically refreshes the Software Instance Key before the current Key expires.
System property ohi.integration.australia.eclipse.key.expiry.time.margin
defines the margin (in seconds) that the system takes into account before the existing Key actually expires.
The default value is 3600 seconds.
According to the ECLIPSE documentation, the time zone for Device and Key expiry times is Australia or Sydney
.
If that ever changes, use system property ohi.integration.australia.eclipse.expiry.times.timezone
to adjust that default value accordingly.
If the existing Key is about to expire, the Oracle Insurance Gateway generates a new Key Pair and sends the Public Key part of it to the Agency. The moment the Agency accepts the new Key the Oracle Insurance Gateway removes any access tokens that were obtained using the expired Key Pair and uses the new Key Pair for obtaining PRODA access tokens.
To refresh the device key, make sure to set values for the following system properties:
Oracle Insurance Gateway System Property | Description |
---|---|
|
ECLIPSE Refresh Device Key URL.
The specified value requires placeholders |
|
Organization Identifier defined at registration time.
Passed as HTTP Header |
|
Device name as given / used during device registration.
The system uses the value to construct the Refresh Key URL.
Besides, the same value appears as HTTP Header |
|
The class of audit user specified, the value appears as HTTP Header |
|
The class of the subject, that is, as listed in HTTP Header |
|
Used by the system to retrieve the Service Provider specific access token for sending the request. |
|
Used by the system to retrieve the Service Provider specific access token for sending the request. |
Redirect Inbound Requests from the Agency to Oracle Health Insurance Agent
The PHI is responsible for redirecting inbound requests from the Agency to the Oracle Health Insurance Agent. Oracle Health Insurance Agent forwards these requests to Oracle Insurance Gateway. Pre-requisites for forwarding requests to the Oracle Insurance Gateway:
-
The PRODA access token is valid.
-
The Oracle Insurance Gateway Software Instance is activated.
To verify that the Oracle Insurance Gateway Software Instance is activated Oracle Health Insurance Agent sends a GET request to the Oracle Insurance Gateway’s /eclipse/healthcheck
resource.
Any ECLIPSE request the PHI receives from the Agency has an Authorization HTTP header carrying a PRODA access token. As the Oracle Insurance Gateway SaaS service only accepts requests with an Oracle IDCS access token it does not accept these requests. That is why Oracle Health Insurance Agent acts as proxy server: it receives all ECLIPSE requests from the Agency and validates PRODA access tokens.
If the PRODA access token is valid then Oracle Health Insurance Agent forwards the request to Oracle Insurance Gateway, replacing the PRODA access token with an Oracle IDCS access token in the process. Oracle Health Insurance Agent blocks awaiting a response from the Oracle Insurance Gateway Exchange that processes the request and returns the response to the Agency.
The following diagram shows the steps in processing an inbound ECLIPSE Web Services request:

Validating PRODA access tokens
Oracle Health Insurance Agent validates the PRODA access token using the JWK Set that is made available via PRODA’s JWK Set Endpoint. PRODA’s JWK Set is compliant with the RFC 7517 specification.
PRODA’s JWK Set URL is available from its OpenID Configuration using a “Well-Known URI” (as defined in RFC 5785). The OpenID Configuration also exposes the "issuer" URI.
The following table defines the PRODA access token aspects Oracle Health Insurance Agent validates:
Aspect | Explanation | Rule | Oracle Health Insurance Agent Configuration |
---|---|---|---|
Signature |
Validate the access token’s signature |
The access token must be signed with a signature that is published in PRODA’s JWK Set |
Property |
Subject |
`sub`claim of the access token |
Must have a value |
Not applicable |
Issuer |
|
Environment-specific, static value |
Property |
Audience |
|
Static value, either "PRODA.UNATTENDED.B2B" or "PRODA.ATTENDED.B2B" |
Property |
Issued at |
|
Must be in the past |
Not applicable |
Expiry |
|
Must be in the future |
Not applicable |
To bypass PRODA access token validation, and have Oracle Health Insurance Agent accept all inbound requests it receives on the /eclipse
resource regardless of the value of the Authorization header, set property agent.eclipse.validateAccessToken
to false.
Mapping Oracle Health Insurance Agent Requests to Oracle Insurance Gateway Exchanges
Redirect Agency requests to the /eclipse
resource of Oracle Health Insurance Agent.
Oracle Health Insurance Agent maps ECLIPSE request URLs to the Oracle Insurance Gateway Exchange API as follows:
/eclipse/<web_service_path>
→ /api/exchanges/integration/<integration_code>
For example, for the ECLIPSE Web Service path /mcp/onlineeligibilitycheck/hhf/v1
(Online Eligibility Check - Agency to Health Fund) Oracle Health Insurance Agent assumes an Oracle Insurance Gateway
Integration with code onlineeligibilitycheck
to be configured:
/eclipse/mcp/onlineeligibilitycheck/hhf/v1
→ /api/exchanges/integration/onlineeligibilitycheck
For Oracle Health Insurance Agent to determine the Integration code from the Web Service path use the following properties:
Oracle Health Insurance Agent Property | Explanation |
---|---|
|
Optional, comma-separated list of resource path segments that will be excluded when determining the name of the Oracle Insurance Gateway Integration code that the inbound request must be mapped to.
For example, if path |
|
Optional prefix that the system applies to the Oracle Insurance Gateway Integration code.
For example, if path |
If ECLIPSE Web Service paths are changed while redirecting the requests to Oracle Health Insurance Agent then Oracle Health Insurance Agent configuration needs to be adjusted accordingly. |
See the ECLIPSE documentation for an overview of all ECLIPSE Web Services paths.
Returning Responses That Adhere to the Specifications of the Agency
For inbound, synchronous request - response message exchanges, the Agency expects either an HTTP 200 OK response or an HTTP 400 Bad Request response (with appropriate errors).
Constructing the payload for messages the system sends to the Agency is the responsibility of the Oracle Insurance Gateway Integration developer.
Define a Custom Step as the last step of the Integration to create the JSON payload that adheres to the specifications of the Agency. The Custom Step must reference a Dynamic Logic function that returns the JSON payload.
Oracle Health Insurance Agent expects Oracle Insurance Gateway Exchanges to accompany the payload that needs to be returned to the Agency with a result
indicator that instructs Oracle Health Insurance Agent how to respond.
For example, as a result of the following response that an Oracle Insurance Gateway Exchange returns to Oracle Health Insurance Agent:
{ "result" : "success", "payload" : { "status" : "SUCCESS" } }
Oracle Health Insurance Agent sends an HTTP 200 OK response to the Agency with the following payload:
{ "status" : "SUCCESS" }
Similarly, as a result of the following response that an Oracle Insurance Gateway Exchange returns to Oracle Health Insurance Agent in case of validation failures:
{ "result" : "failure", "payload" : { json_failure_payload } }
Agent sends an HTTP 400 Bad Request response to the Agency with the json_failure_payload
.
Oracle Health Insurance Agent passes the response payloads it received from Oracle Insurance Gateway Exchange verbatim, without inspecting or modifying the payload. |
Exceptions in Processing Inbound Requests
In the following cases:
-
the PRODA access token is invalid
-
the Oracle Insurance Gateway Software Instance is not activated
-
an exception is encountered processing the Oracle Insurance Gateway Exchange resulting in Oracle Insurance Gateway returning a response other than in the HTTP 200 family
-
the Oracle Insurance Gateway Exchange does not complete in time resulting in a timeout
-
the Oracle Insurance Gateway Exchange results in a response with a payload that Oracle Health Insurance Agent cannot process
Oracle Health Insurance Agent returns an HTTP 400 Bad Request response with the following sample payload (as specified in document TECH_SIS_PHI_06 - PHI OUTBOUND Common Rules Supplement.pdf
):
{ "highestSeverity": "Error", "serviceMessage": [ { "code": "3040", "severity": "Error", "reason": "Health Fund system unavailable." } ] }
The values for the respective labels are specified using the following Oracle Health Insurance Agent properties:
Oracle Health Insurance Agent Property | Value in the Sample Payload |
---|---|
|
Error |
|
3040 |
|
Error |
|
Health Fund system unavailable. |
If the Oracle Insurance Gateway Exchange results in a response with a payload that cannot be processed by Oracle Health Insurance Agent, then Oracle Health Insurance Agent replaces the reason
in the response message with the value of Oracle Health Insurance Agent property agent.eclipse.gatewayErrorReason
.
Receiving Ping Requests from the Agency
The Agency periodically sends ping requests.
Ping requests must be redirected to Oracle Health Insurance Agent’s /eclipseping
resource.
If it receives a ping request, Oracle Health Insurance Agent sends a GET request to the Oracle Insurance Gateway’s /eclipse/healthcheck
resource.
The Oracle Insurance Gateway returns an HTTP 200 OK response with the following JSON payload:
{ "activated": true|false }
If the Oracle Insurance Gateway Software Instance was successfully activated and is ready to handle ECLIPSE web service requests the value for the activated
attribute is true
.
In that case Oracle Health Insurance Agent returns the following response to the Agency:
{ "pingTest": [ { "name": "name as provided in the agency's ping request", "available": true }] }
Otherwise, if the Oracle Insurance Gateway Software Instance is not activated and, thus, is not ready to handle ECLIPSE web service requests then Oracle Health Insurance Agent returns the following response to the Agency:
{ "pingTest": [ { "name": "name as provided in the agency's ping request", "available": false }] }
Configure Oracle Insurance Gateway Integrations for Sending Outbound Requests to the Agency
Prerequisites for Oracle Insurance Gateway Integrations for sending ECLIPSE web service requests to the Agency:
-
Define a Delivery Integration Step with a REST Destination.
-
Set value
PRODA
as Authentication Feature for the Delivery Step. If that is set then the Oracle Insurance Gateway makes sure the Authorization header has a (Service Provider specific) PRODA access token when sending the REST request. Note that the system determines the REST Client ID for each Delivery Step from destination code. Thus, there is a separate REST Client ID per rest destination configured. For example, if the rest destination code is 'EclipseDestination' for a delivery step, then the REST Client ID for that Integration Step is 'EclipseDestination'. -
As PRODA access tokens are Service Provider specific, set the following system properties for every Delivery Step that sends a request to the Agency to make sure that the system determines the correct Service Provider and Service Provider Audience for retrieving the PRODA access token:
-
ohi.integration.australia.eclipse.service.provider.<REST Client ID>
-
ohi.integration.australia.eclipse.service.provider.<REST Client ID>.audience
-
-
Register required HTTP headers as Exchange Properties prior to invoking the request. See the ECLIPSE documentation for an overview of the HTTP headers.
If a value for the following HTTP headers is not set at the moment the system sends the request to the Agency then the Oracle Insurance Gateway applies default values for these:
HTTP Header | Default Value |
---|---|
|
|
|
|
|
|
Sending Ping Requests to the Agency
Send a GET request to the Oracle Insurance Gateway’s /eclipse/pingagency
resource for sending a ping request to the Agency.
Prerequisites for pinging the Agency:
-
The Oracle Insurance Gateway Software Instance is activated. If the Oracle Insurance Gateway Software Instance is not activated then invoking this request results in error
OIG-AUEC-002: Software Instance not activated, operation cannot be completed
. -
Values are specified for the pinging system properties
Oracle Insurance Gateway System Property Description ohi.integration.australia.eclipse.ping.request.url
Contains the Agency’s ping resource URL
ohi.integration.australia.eclipse.ping.header.audit.id
The ‘dhs-auditId’ value is the unique Location Id (Minor ID) for the source agency who is sending the ‘Web Service Request’ while pinging agency.
(DEFAULT VALUE : WEB00001)ohi.integration.australia.eclipse.ping.header.audit.id.type
The ‘dhs-auditIdType’ value represents the class of audit user specified. If supplied will always be Location Id.
(DEFAULT VALUE : "Location Id")ohi.integration.australia.eclipse.ping.header.subject.id
The "dhs-subjectId" value represents class of subject user(id) specified while pinging agency.
(DEFAULT VALUE :WEB00001)ohi.integration.australia.eclipse.ping.header.subject.id.type
The "dhs-subjectIdType" value represents class of the subject(type) while retrieving token.
(DEFAULT VALUE : "Fund Location Id")ohi.integration.australia.eclipse.ping.header.product.id
The ‘dhs-productId’ value represents the latest application version used to submit the ‘Web Service Request’.
(DEFAULT VALUE : "ECLIPSE API V1.0")ohi.integration.australia.eclipse.ping.header.location.id
The ‘dhs-locationId’ value represents the class of the location(id) while retreiving token also used in the dhs-correlationId.
(DEFAULT ID : "WEB00001")ohi.integration.australia.eclipse.ping.header.ibm.client.id
The value represents x-ibm-client-id used while pinging agency.
(DEFAULT VALUE : "http://humanservices.gov.au/PRODA/org") -
Values are specified for service provider system properties
Oracle Insurance Gateway System Property Description ohi.integration.australia.eclipse.service.provider.EclipsePingClient
Used by the system to retrieve the Service Provider specific access token for sending the request
ohi.integration.australia.eclipse.service.provider.EclipsePingClient.audience
Used by the system to retrieve the Service Provider specific access token for sending the request
If a value for any of the required system properties is not defined then the system returns an HTTP 422 response with error OIG-AUEC-001
, specifying the property for which a value is not set.
If all pre-requisites are met then the Oracle Insurance Gateway Software Instance sends a request with the following payload to the Agency:
{ "pingTest": [ { "name": "TEST_AVAILABILITY" }] }
If the Agency’s resource responds with an HTTP 200 OK response then the Oracle Insurance Gateway returns the response payload to the client verbatim, otherwise it returns error OIG-AUEC-006: Ping Request Failed
.