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.

Response

When creating the consumption successfully, HTTP status code '201: Created' is returned. Additionally, the response will set a HTTP Location header to point to the generic HTTP API representation of the created consumption.

Authorization

The IP is protected by "writeconsumptiononline IP" access restriction.

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.

Authorization

The IP is protected by "writeconsumptionbatch IP" access restriction.

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/or transactionEndDateTime 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 the transactionEndDateTime is specified, then all consumptions up-to the end period will be returned
- if no transactionEndDateTime is specified and only the transactionStartDateTime is specified, then all consumption from the start period will be returned
If both limitCodes and a combination or both of the transactionStartDateTime and transactionEndDateTime 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:

Table 1. Reversed Consumption
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:

Table 2. Transaction Period: February 01, 2010 to April 01, 2010
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:

Table 3. Transaction Period: March 01, 2010 to April 01, 2010
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:

Table 4. Transaction Period: February 01, 2010 to March 01, 2010
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.

Authorization

The IP is protected by "readconsumptionbatch IP" access restriction.

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.

Authorization

The IP is protected by access restriction of type HTTP API "limitconsumptions API" .

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:

Table 5. 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.

1. when a consumption created for a limit, that acts as sub limit to other limit(s). The sub limit setup specifies if the sub limit consumption counts per product or across products in context of the composite limit