Adjudication Counters Integration Point
The primary purpose of this integration point is:
-
To provide other adjudication engines with current adjudication limit counts.
-
Provide information that can be used to generate periodic counter statements.
-
Allow other adjudication engines to submit increments and decrements to adjudication limits.
-
Enable counters offsets. For example, migrate an account from another system onto Claims.
Consumption is an increment to a limit counter. Negative Consumption is a decrement to a limit counter.
Design Principles
External interfaces determine when to send request messages and what data they contain.
The service provided by the integration point described in this guide restricts to:
-
calendar year based limits
-
plan/subscription year based limits
-
annual limits
-
sliding window limits
-
lifetime limits
-
first claim based limits
This integration point does not access regime counters, authorization counters, case based adjudication limits, counters related to claims, and provider limits. The batch operations provided by the Counters Integration Point are examples of Long-Running Operations Through REST.
Write Limit Consumption Online
Request
The HTTP POST request to: http://[hostName]:[portNumber]/[api-context-root]/limitconsumptions enables external systems to write consumption on counters.
Write consumption request messages have the following structure:
{ "limitCode" : "", "familyCode" : "", "aggregationLevel" : "", "serviceDate" : "", "numberOfUnits" : "", "withdrawn" : "", "excludeFromCarryOver" : "", "providerGroupStatus" : "", "externalId" : "", "counterId":"", "startDate":"", "endDate":"", "description" : "", "transactionSourceCode" : "", "referenceCode" : "", "<insurableEntityType.usageName>" : { "code" : "", } "amount" : { "currency" : "", "value" : "" }, "provider" : { "code" : "", "flexCodeDefinitionCode" : "" } }
While processing write consumption request, instead of sending the transaction date-time (attribute of consumption), set it automatically to the current date and time.
If the request fails to specify an attribute required for processing that request, the response contains an explanatory message (see Error Messages).
Creating Consumption
Before creating any consumption, the system checks the request payload for the following:
-
Are all functional identifiers in the request payload known? (limit, insurable entity, aggregation level, provider, currency, and transaction source )
-
Does the request contain enough information to identify the applicable counter or counter period?
-
Does the request contain enough information to create the consumption? For example, a consumption can only be created if the correct value (amount, number, withdrawn indicator) based on the limit type (amount, number or service days) is available in the request.
If the answer to any of these questions is no, then the system returns an error message without processing the request.
The next step is to resolve the counter. When the counter id is specified, system considered the provided counter otherwise, the system selects the appropriate counter based on the limit code and insurable entity (for insurable entity level limits) or family code (for family level limits). If the counter does not exist, it is created based on the provided information.
Counters for insurable entity level limits get a reference to the provided person or object (insurable entity). The family code storage for family level limits happens on the counter without a reference to the provided person or object (if an insurable entity has been provided it will only be stored on the consumption. After the counter has been selected or created, the limit consumption should be created, and the applicable counter periods updated:
-
A limit consumption should be created for the selected or newly created counter, with the amount/qty, currency, service date, withdrawn indicator, exclude from carry over indicator, provider, aggregation level, insurable entity, provider group status, external id, description, transaction source and reference as specified in the request
-
The maximum amount or number or service days is unspecified (null) on external consumptions and external consumption always finalized (preliminary indicator unchecked and transaction date-time set)
-
If the currency code has not been provided for amount type limits, it is derived:
-
If the limit counter does not exist yet, or it exists without any limit counter periods, the consumption creation occurs with the default currency code
-
If a limit counter period that the consumption counts towards exists (based on the search as specified below), then current amount currency code of the counter period taken
-
For limit counter periods that count towards consumption and other limit counter periods that exist for an applicable counter, the counter period takes the amount currency of the most recent counter period.
-
-
-
The system searches for an applicable existing counter period for the limit. If the limit is a sub-limit to another limit, the system fetches the counter periods of all other (composite) limits towards which it counts; based on:
-
Service date, provider, aggregation level, currency and exclude from carry over indicator of the consumption
-
Start date, end date, carry over start date, other products carry over start date, provider, aggregation level, and current amount currency specified on the counter periods. Whether a consumption counts towards a counter period or not is determined by the following conditions:
-
Consumption with an unspecified provider counts towards counter periods of all providers
-
Consumption with a specified provider also counts towards counter periods with an unspecified provider (for limits that count across providers)
-
Consumption with an unspecified aggregation level counts towards counter periods of all aggregation levels
-
If both a carry over period, and other products carry over period are specified and the consumption falls in both periods, it still only counts once towards the counter period
-
-
Consumption with a specified aggregation level also counts towards counter periods with an unspecified aggregation level (for limits that count across products [1] )
-
Consumption that falls in the carry over period only counts towards the counter period if the aggregation level of the consumption is unspecified or if it matches the aggregation level of the counter period for limits that count per product aggregation level; for limits that count across products[1] all consumption (regardless of the aggregation level) that falls in the carry over period counts towards the counter period
-
Consumption that falls in other products carry over period only counts towards the counter period if the aggregation level of the consumption is unspecified or if it does not match the aggregation level of the counter period
-
Consumption only counts towards counter periods with the same currency (consumption currency matches counter period current amount currency)
-
-
-
If no applicable counter period exists, and the consumption is for an annual or calendar year limit with a renewal period of exactly one year, then the system immediately creates a new counter period. If a new counter period is created and the start and end date are provided in the request, the new counter period is created with the provided start and end date. Otherwise, no counter period is created. After a counter period either retrieved or created, then:
-
Update (if applicable) the current amount or number of units or service days on the retrieved counter periods
-
The maximum amount or number of units or service days does not update, since external consumption does not get evaluated against a maximum
-
-
The version on the counter increments by 1
-
Update counter periods of the composite limit, then its counter also updates by 1
-
Limits With a Carry Over Period
Writing consumption to a limit with a carry over period may result in a consumption that counts towards two different counter periods.
Considering the composite limit counter periods, if the limit to which the consumption has been written to is specified as a sub-limit.
If the attribute of excludeFromCarryOver in the request set to No
(or left unspecified) and the service date is within a carry over period, the consumption counts:
-
towards the counter period that captures the service date between its start and end date.
-
towards the counter period that captures the service date between its carry over start date, and the day prior to its start date.
Consider the following scenario. A 1-year calendar based limit is configures with a carry over period of two months. Currently, two counter periods exist:
-
the counter period for 2007 which has a carry over start date November 01, 2006, start date January 01, 2007, and end date December 31, 2007
-
the counter period for 2008 which has a carry over start date November 01, 2007, start date January 01, 2008, and end date December 31, 2008
A consumption request comes with the excludeFromCarryOver attribute set to No
and service date December 04, 2007.
This date is both in the carry over period of the 2008 counter period, and the period of the 2007 counter period.
As a result, the consumption counts towards both counter periods.
If a consumption request comes in with the excludeFromCarryOver attribute set to Yes
and service date December 04, 2007, the consumption only counts towards the 2007 counter period.
If the limit counts per product aggregation level, count only the consumption of the same (or unspecified) product aggregation level; if the limit counts across product aggregation levels count all consumption, regardless of product aggregation level.
The above specified behavior also applies to the Other Products Carry Over Period. Consumption of other (or unspecified) product aggregation levels during the carry over period, also counted for the next full period of the new product aggregation level; not counting consumption of the same product aggregation level.
![Two Consumptions](../_images/two-consumptions.gif)
Write Consumption Batch
Request
This request enables handling of multiple write consumption requests in one go. Since the volume of data can be quite extensive, the input for this process comes from a supposed data file set. For more information about how to create a data file set please refer to Data File Set Integration Point.
Consumption batch elements that are contained in the datafile(s) that are part of the input data file set have the following structure: in here the <consumptionList> is the root element of an individual datafile.
<consumptionList> <consumption elementId="" limitCode="" familyCode="" aggregationLevel="" serviceDate="" numberOfUnits="" withdrawn="" excludeFromCarryOver="" providerGroupStatus="" externalId="" description="" transactionSourceCode="" referenceCode=""> <amount currency=""> {value} </amount> <provider flexCodeDefinitionCode="" code=""/> </consumption> ... </consumptionList>
For more specifics of how to import individual consumption elements, see the previous description of Creating Consumption.
There is a required elementId
attribute in each request element, to allow for correlation between an error message and a specific consumption.
This information is a part of the data file set response that is produced during the write consumption batch process.
Assume that an input data file set containing at least one datafile with a structure as outlined above has been created. In order to initiate the consumption import process a HTTP POST request to: http://[hostName]:[portNumber]/[api-context-root]/writeconsumptionbatches has to be submitted. A write consumption batch (initiation) request contains the following structure:
{ "dataFileSetCode" : "..." }
The system responds with HTTP 201 (Created), and a location header for the write consumption batch.
It is also possible to submit the equivalent XML payload, contained in the root element: WriteConsumptionBatchInput.
In the above request the dataFileSetCode
refers to the data file set that contains the datafile(s) with consumption
records that need to be imported.
Response
As described in Long-Running Operations Through REST there are multiple ways in which one can get the response/result of this long-running operation. Typically, though one would opt for notification events.
For Write Consumption Batch a notification message can be sent out to a pre-configured endpoint.
The notification endpoint can be configured on ohi.activityprocessing.notification.endpoint.CONSUMPTION_IMPORT
or to
a more generic endpoint: ohi.activityprocessing.notification.endpoint
.
Configure the notification endpoint on the specific: CONSUMPTION_IMPORT, fetch all other properties based on CONSUMPTION_IMPORT or else using defaults. Similarly, configure the endpoint for the notification without the specific code, then fetch all other properties on a generic usecase code 'ActivityNotificationClient'. See section "Outbound RESTful Service Invocations" in Security Guide for the process and more properties. The notification message has the following or common structure:
<notification correlationId="" workId="{activityId}" status="">
<links>
<link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafile/{datafilecode}/data"/>
<link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafile/{datafilecode}/data"/>
...
</links>
</notification>
Effectively the data file set holds a reference of the result of the Write Consumption Batch.
In case one uses a polling approach to follow the progress and (or) performs collection queries
over writeconsumptionbatch
resources, for completed Write Consumption Batch operations the data file set link will be there.
For these one can get to the actual stream of data by using the Data File Set Integration Point operations.
As mentioned the data file set holds the result of the Write Consumption Batch operation. Every individual datafile has a generic structure:
<consumptionResponse> <resultMessages result="S"> <resultMessage code="GEN-FILE-006"> The total number of successfully processed records is \{0} </resultMessage> </resultMessages> <resultMessages result="F" elementId="{elementId}"> <resultMessage code="{error code}"> {error text} </resultMessage> </resultMessages> </consumptionResponse>
In this generic structure the message GEN-FILE-006 is used to inform about the number of records
(in this case consumption elements) that are successfully imported into the system.
If there are problems in importing (individual) consumption records those are also contained in the datafile.
A sample of the that is included in the description above.
These elements which failed importing, include the elementId
as a reference to the consumption element that
resulted in an error. Additionally, it also contains the {error code} and {error text} to further detail the
problem that the system detected.
Read Consumption Batch
With this operation the user has the ability to read consumptions that are contained by the system. This can be viewed as a consumption report. Because the volume of data returned can become quite extensive, the result of this process will be a datafile set.
Request
In order to initiate the consumption import process a HTTP POST request to: http://[hostName]:[portNumber]/[api-context-root]/readconsumptionbatches has to be submitted. A read consumption batch (initiation) request has the following structure
{ "limitCodes" : [ {code}, {code}, ... ], "transactionStartDateTime" : { "value" : "..." }, "transactionEndDateTime" : { "value" : "..." } }
It is possible to submit the equivalent XML payload, contained by the root element: ReadConsumptionBatchInput.
In this case the limitCodes
element becomes a container of limit codes, with each individual limit code contained by a <value>
element.
Retrieval of consumption details happens using the above specified selection criteria. All criteria are optional. Returned consumptions depend on what is specified in the request:
-
If only a list of
limitCodes
is specified, then all consumptions for the specified limits will be returned -
If only
transactionStartDateTime
and/ortransactionEndDateTime
are specified, then all consumptions with a transaction or reversal date-time in the specified period will be returned-
if no
transactionStartDateTime
is specified and only thetransactionEndDateTime
is specified, then all consumptions up-to the end period will be returned -
if no
transactionEndDateTime
is specified and only thetransactionStartDateTime
is specified, then all consumption from the start period will be returned
-
-
If both
limitCodes
and a combination or both of thetransactionStartDateTime
andtransactionEndDateTime
are specified, then consumptions matching all combined criteria will be returned -
If no specified criteria, all consumptions will be returned
-
No returns in case consumption for limits with the reference Case or Single Claim
-
The system responds with HTTP 201 (Created) and a location header for the read consumption batch.
-
Both the internal consumption, created due to claims processing, and the external consumption, created through this integration point will be returned
-
Only finalized consumption will be returned
Response
For Read Consumption Batch a notification message will be sent to a pre-configured endpoint.
Configure the endpoint to send notification using ohi.ReadConsumptionBatch.endpoint.request
.
If the endpoint requires Authentication, use the Authentication Use Case: ReadConsumptionBatch to set
authentication.
See section "Outbound RESTful Service Invocations" in the Security Guide for the process and more properties.
The notification message has the following or common structure:
<notification correlationId="" workId="{activityId}" status="">
<links>
<link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]datafilesets/{datafilesetcode}/datafile/{datafilecode}/data"/>
<link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafile/{datafilecode}/data"/>
...
</links>
</notification>
Effectively the data file set holds a reference of the result of the Read Consumption Batch.
In case one uses a polling approach to follow the progress and/or performs collection queries
over readconsumptionbatch
resources, for completed Read Consumption Batch operations the data file set link will be available.
For these one can get to the actual stream of data by using the Data File Set Integration Point operations.
The file
hypermedia link will be contained in the event as a convenience to allow direct datastream access to the Consumption Data File.
For more information about the actual data contained in the data file set, see the section about Consumption Data File.
Consumption Data File
The read consumption batch process creates a datafile contained in a data file set with the following structure:
<consumptionList> <consumption claimCode="" claimLineCode="" numberOfUnits="" maximumNumber="" maximumServiceDays="" withdrawn="" reversed="" excludeFromCarryOver="" serviceDate="" transactionDateTime="" aggregationLevel="" providerGroupStatus="" description="" referenceCode="" transactionSourceCode="" externalId="" reserved="" expirationDate="" subLimitCode=""> <amount currency=""> {value} </amount> <maximumAmount currencyCode=""> {value} </maximumAmount> <provider flexCodeDefinitionCode="" code=""/> <counter limitCode="" limitDescription="" familyCode=""> <counterPeriodList> <counterPeriod startDate="" endDate="" carryOverStartDate="" otherProductsCarryOverStartDate="" aggregationLevel="" maximumNumber="" maximumServiceDays="" currentNumber="" currentServiceDays=""> <maximumAmount currencyCode=""> {value} </maximumAmount> <currentAmount currencyCode=""> {value} </currentAmount> <provider flexCodeDefinitionCode="" code=""/> </counterPeriod> </counterPeriodList> </counter> </consumption> ... </consumptionList>
For every consumption the counter periods that the consumption counts towards are returned.
-
Consumption with an unspecified provider counts towards counter periods of all providers
-
Consumption with a specified provider also counts towards counter periods with an unspecified provider (for limits that count across providers)
-
Consumption with an unspecified aggregation level counts towards counter periods of all aggregation levels
-
Consumption with a specified aggregation level also counts towards counter periods with an unspecified aggregation level (for limits that count across products)
-
Consumption that falls in the carry over period only counts towards the counter period if the aggregation level of the consumption is unspecified or if it matches the aggregation level of the counter period for limits that count per product aggregation level; for limits that count across products all consumption (regardless of the aggregation level) that falls in the carry over period counts towards the counter period
-
Consumption that falls in the other products carry over period only counts towards the counter period if the aggregation level of the consumption is unspecified or if it does not match the aggregation level of the counter period
-
Consumption only counts towards counter periods with the same currency (consumption-currency matches counter period current amount currency)
-
If the read limit is a composite limit, then select consumptions of the sub-limits:
-
if they are not for the same claim line as the composite limit consumptions (that is, do not refer to the composite limit)
-
and have the same provider group status as specified in the sub-limit setup
-
a sub-limit consumption follows the same guidelines as specified above in determining whether it counts towards a counter period or not
-
when a composite limit counts per product, sub-limit configuration specifies if the sub-limit consumption counts for the same product or across product.
-
For a composite limit that counts per product, the sub-limit setup may apply specifies if the sub-limit consumption counts towards the same product or all products. When a sub-limit will be configured to count per product, the sub-limit consumption with aggregation level unspecified or if it matches the aggregation level of the counter period for the composite limit will count towards the counter period of the composite. For a sub-limit configured to count across products all consumption (regardless of the aggregation level) that falls in the counter period of the composite counts towards it.
-
-
When no consumptions exist based on the specified criteria the response contains an empty <consumptionList> element. When a consumption does not count towards any counter period the <counterPeriodList> element will not be returned for that consumption.
The return of reversed consumption, needs to be transformed from the table structure. For example, The following table represents storage of reversed consumption in the database:
Claim | Claim Line | Amount | Service Date | Transaction Date | Reversal Date |
---|---|---|---|---|---|
CL01 |
1 |
$ 100 |
Feb 15, 2010 |
Feb 25, 2010 |
Mar 31, 2010 |
If the requested transaction period is February 01, 2010, through April 01, 2010, then the response is:
Claim | Claim Line | Amount | Service Date | Transaction Date |
---|---|---|---|---|
CL01 |
1 |
$ 100 |
Feb 15, 2010 |
Feb 25, 2010 |
CL01 |
1 |
- $ 100 |
Feb 15, 2010 |
Mar 31, 2010 |
If the requested transaction period is March 01, 2010, through April 01, 2010, then the response is:
Claim | Claim Line | Amount | Service Date | Transaction Date |
---|---|---|---|---|
CL01 |
1 |
- $ 100 |
Feb 15, 2010 |
Mar 31, 2010 |
If the requested transaction period is February 01, 2010, through March 01, 2010, then the response is:
Claim | Claim Line | Amount | Service Date | Transaction Date |
---|---|---|---|---|
CL01 |
1 |
$ 100 |
Feb 15, 2010 |
Feb 25, 2010 |
After this transformation, order the consumptions by transaction date, ascending. This way, it is easiest to show the deltas. Also,show this way the external consumption perforce. Although not shown in the example, show the number of units with a minus sign as well in exactly the same way.
Read Consumption Online
This API returns the eligible consumption under the specified counter. It supports all limit types.
The response follows HTTP API consumption resource graph given by /generic/consumptions/definition. It is possible to influence resource representation by specifiy fields and expand (see Influence Resource Representation)
Request
The url for the API refers to the counter period or the counter.
POST : http://[hostName]:[portNumber]/[api-context-root]/generic/limitconsumptions/counter/\{id of the counter}/search
POST : http://[hostName]:[portNumber]/[api-context-root]/generic/limitconsumptions/counterperiod/\{id of the counter period}/search
Request body may specify the following additional Generic API attributes to influence resource representation
-
fields
-
expand
Response
List of all the eligible consumption that counts towards the counter or the counter period. The response structure is given by http://[hostName]:[portNumber]/[api-context-root]/generic/limitconsumptions/definition
The response can also contain generic response messages/codes. Please refer to Response Messages section for more details.
Whether a consumption counts towards a period or not depends on many factors like, type of limit, carry over period, other carry over period, sub limits, across product/provider settings. For details on how consumption count towards a counter period refer Adjudication Limits. |
Error Messages
The following situations cause a request message to fail:
-
The insurable entity (combination of code and type code) is unknown
-
The limit code is unknown
-
The provider (combination of code and flex code definition code) is unknown
-
The aggregation level is unknown
-
The start date-time is greater than the end date-time for the transaction period
In case of a request to write consumption, requirement of additional information depends on the configuration of the limit:
-
Recording consumption for an insurable entity based limit requires an insurable entity, but not specified for any insurable entity
-
Recording consumption for a family based limit requires a family code, but not specified for any family code
-
Recording consumption for an amount based limit, but not specified any amount
-
Recording consumption for a number based limit, but not specified the number of units
In case of a request to write consumption, in some situations it is not allowed to write consumption:
-
Recording consumption for a service days based limit, but also specifying an amount or a number
-
Recording consumption for an amount or number based limit, but also specifying withdrawal of the consumption
-
Recording consumption for a limit that is related to an adjudication case (the limit has reference case) or a claim (the limit has reference single claim)
The above specified situations result in the following error messages:
Code | Severity | Message |
---|---|---|
CLA-IP-LIMI-003 |
Fatal |
Limit code {code} is unknown |
CLA-IP-LIMI-006 |
Fatal |
Provider identified by code {code} and flex code definition code {code} is unknown |
CLA-IP-LIMI-011 |
Fatal |
Either amount or number should be specified unless the limit type is service days (in which case both amount and number should be left blank) |
CLA-IP-LIMI-012 |
Fatal |
Required insurable entity for insurable entity level limits |
CLA-IP-LIMI-013 |
Fatal |
Required family code for family level limits |
CLA-IP-LIMI-014 |
Fatal |
The provided value does not comply with limit type {type} |
CLA-IP-LIMI-018 |
Fatal |
It is not possible to write consumption to a limit related to an adjudication case or a claim |
CLA-IP-LIMI-024 |
Fatal |
Start date-time {start date-time} cannot be greater than the end date-time {end date-time} of the transaction period |
CLA-IP-LIMI-025 |
Fatal |
Withdrawn consumption only allowed if the limit type is service days |
CLA-IP-LIMI-026 |
Fatal |
Aggregation level {aggregation level} is unknown |
CLA-IP-LIMI-027 |
Fatal |
Insurable entity identified by code {code} and type {code} is unknown |
CLA-IP-LIMI-028 |
Fatal |
The counter is unknown |
CLA-IP-LIMI-029 |
Fatal |
When End date is specified, start date must be specified as well |
In addition, there is a possibility to return other messages not specific to the Counters Integration Point as well.
Please refer to Response Messages for more details.