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 error OIG-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 property ohi.integration.australia.eclipse.device.name. Sample value: https://some.host.gov.au/context_root/api/b2b/v1/devices/device_name/jwk.
  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 Header dhs-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 attribute kid.
  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 Header dhs-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
ohi.integration.australia.eclipse.token.url	The endpoint URL for retrieving tokens.
ohi.integration.australia.eclipse.service.provider.DefaultEclipseClient	Used by the system to retrieve a Service Provider specific access token.
ohi.integration.australia.eclipse.jwt.assertion.sub	Used by the system to retrieve a Service Provider specific access token. The JWT Assertion requires use of a sub claim and the system needs this system properties to determine the value of that claim. The value is usually the same as the software instance or device name.
ohi.integration.australia.eclipse.jwt.assertion.aud	Used by the system to retrieve a Service Provider specific access token. The JWT Assertion requires use of a aud claim and the system needs this system properties to determine the value of that claim. Default value: https://proda.humanservices.gov.au.
ohi.integration.australia.eclipse.service.provider.DefaultEclipseClient.audience	Used by the system to retrieve a Service Provider specific access token. The JWT Assertion requires use of a token.aud claim and the system needs these system properties to determine the value of that claim.
ohi.integration.australia.eclipse.client.identifier	Client identifier as provided during software registration.
ohi.integration.australia.eclipse.softwareinstance.name	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
ohi.integration.australia.eclipse.refresh.key.url	ECLIPSE Refresh Device Key URL. The specified value requires placeholders org_id and device_name. At runtime, the system replaces the placeholders with the values of system properties ohi.integration.australia.eclipse.organization.identifier and ohi.integration.australia.eclipse.device.name respectively. Sample value: https://some.host.gov.au/context_root/api/b2b/v1/orgs/org_id/devices/device_name/jwk.
ohi.integration.australia.eclipse.organization.identifier	Organization Identifier defined at registration time. Passed as HTTP Header dhs-auditId.
ohi.integration.australia.eclipse.device.name	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 dhs-subjectId and in the payload as value for attribute kid.
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 Header dhs-subjectIdType. Default value: http://humanservices.gov.au/PRODA/device.
ohi.integration.australia.eclipse.service.provider.EclipseKeyExpiryClient	Used by the system to retrieve the Service Provider specific access token for sending the request.
ohi.integration.australia.eclipse.service.provider.EclipseKeyExpiryClient.audience	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 agent.eclipse.jwkSetURL (URL). Retrieve the value from PRODA’s environment-specific OpenID Configuration.
Subject	`sub`claim of the access token	Must have a value	Not applicable
Issuer	iss claim of the access token	Environment-specific, static value	Property agent.eclipse.issuerURI (URI). Retrieve the value from PRODA’s environment-specific OpenID Configuration.
Audience	aud claim of the access token	Static value, either "PRODA.UNATTENDED.B2B" or "PRODA.ATTENDED.B2B"	Property agent.eclipse.clientId
Issued at	iat claim of the access token	Must be in the past	Not applicable
Expiry	exp claim of the access token	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
agent.eclipse.excludePathSegments	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 /mcp/onlineeligibilitycheck/hhf/v1 must result in Oracle Insurance Gateway Integration code onlineeligibilitycheck then set mcp,hhf,v1 as value.
agent.eclipse.integrationPrefix	Optional prefix that the system applies to the Oracle Insurance Gateway Integration code. For example, if path /mcp/onlineeligibilitycheck/hhf/v1 must result in Oracle Insurance Gateway Integration code eclipseonlineeligibilitycheck then set eclipse as value (and set mcp,hhf,v1 as value for property agent.eclipse.excludePathSegments).

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
agent.eclipse.errorHighestSeverity	Error
agent.eclipse.errorCode	3040
agent.eclipse.errorSeverity	Error
agent.eclipse.errorReason	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
dhs-productId	oig-<release_version>
dhs-messageId	urn:uuid:<generated_UUID_value>
dhs-correlationId	urn:uuid:<generated_UUID_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.