You are here:
InsClaimItemService:calculateCoverages
Use this service to calculate the coverage amount and adjusted amount for a claim line item. These amounts are used as payment amount when the claims adjuster pays the claim line item.
The service considers applicable deductibles, copays, coinsurance, and out-of-pocket maximums when creating adjustments.
This service evaluates the Coverage Calculation Formula if one's defined on the coverage spec.
Method: calculateCoverages
How It Works
The service uses object interface
field names as default input and output for common fields in both Vlocity
(ClaimLineItem__c) and Salesforce FSC
(ClaimCoveragePaymentDetail) data models.
This service works differently depending on whether a Coverage Calculation Formula exists on the coverage spec.
When there's no Coverage Calculation Formula present, this service:
-
Uses the following information to get the claim record, the associated policy record, and attribute values for both the claim and the policy.
-
claimId -
claimCoverageId -
claimItemId(if available) -
claimAmount
-
-
Calls the InsPolicyTermsService: process service.
This service calculates all insured obligation amounts (copay/coinsurance, deductible, and out-of-pocket max) and returns this data.
-
Subtracts the insured obligation amounts from the claim amount, if one or more insured obligation amounts exist.
-
Returns the output including the final adjusted amount and child claim items (if any).
When a Coverage Calculation Formula exists on the coverage spec, this service:
-
Uses the following information to get the claim record, the associated policy record, and attribute values for both the claim and the policy.
-
claimId -
claimCoverageId -
claimItemId(if available) -
claimAmount
-
-
Compiles the following objects (including AttributeSelectedValues <productcode.key>) to make them available to the Coverage Calculation Formula on the coverage spec:
-
Claim
-
Policy
-
PolicyCoverage
-
InsuredParty
-
InsuredItem
-
InvolvedInjury
-
InvolvedProperty
-
-
Runs the Coverage Calculation Formula.
-
Calls the InsPolicyTermsService: process service.
This service calculates all insured obligation amounts (copay/coinsurance, deductible, and out-of-pocket max) and returns this data.
-
Subtracts the insured obligation amounts from the claim amount, if one or more insured obligation amounts exist.
-
Returns the output including the final adjusted amount and child claim items (if any).
Remote Options
Option |
Description |
|---|---|
|
Required. The Id of the claim that the service calculates the coverage amount for. |
|
Optional. Use this option when you're updating an existing claim line item with recalculated coverage and adjusted amounts. |
|
Required. The Id of the coverage the service calculates an amount for. |
|
Required. JSON of possible additional input for use in the coverage formulas, to be saved in the claim line item record (if saveLineItem is true). It must have the following inputs:
|
This option uses the interface field names described in this table in the input and output
for common fields in Vlocity ClaimLineItem__c and Salesforce FSC
ClaimCoveragePaymentDetail data models:
User Interface Field Name |
Common Fields in Vlocity |
|---|---|
|
Use for |
|
Use for |
|
Use for |
|
Use for |
|
Use for |
|
Use for |
|
Use for |
|
Use for |
|
Use for |
|
Use for |
|
Use for |
For fields not listed here, use the fully qualified name of the field.
Attributes prefixed with ClaimLineItem that have the claim line item's API are saved to the claim line item that is created.
Input JSON and Output JSON
If out-of-the-box methods of determining the adjusted amount for a payment detail meet your business needs, you can skip this section. But if you want to adjust payment detail amounts in ways that aren’t supported out of the box, this section is for you.
Typically, these out-of-the-box use cases are for scenarios not covered by power attribute classes, such as:
-
Conditional deductibles, where two deductibles exist on the same coverage spec. For example, Deductible A applies to a fire damage loss, and Deductible B applies to a flood damage loss. You want the system to determine which deductible to apply to the payment detail at runtime.
-
Copay/Coinsurance order of operations. For example, coinsurance and copay both exist on the same coverage spec, and you want to apply the coinsurance before applying the copay on a payment detail.
-
Calculation of a payout amount for a benefit type. For example, for a Wellness Visit benefit type, you want the system to calculate a $50 amount for the payment detail.
After you understand InsClaimItemService: calculateCoverages
output JSON format, you can implement power attribute-like behavior to calculate
payout amounts and adjustments without having an underlying power attribute
class.
Before we get ahead of ourselves, let’s use a simple example to illustrate the
output JSON expected to be returned by InsClaimItemService:
calculateCoverages. Consider a straightforward use case supported by the
out-of-the-box Deductible power attribute class.
Example: $5,000 claimed amount on a policy with a $1,000 deductible
Here’s the input JSON for InsClaimItemService:
calculateCoverages.
{
"claimId": "01t000000000000001",
"claimCoverageId": "01t000000000000002",
"claimItemId": "01t000000000000003",
"additionalInput": {
"ClaimLineItem.claimAmount": 5000
"ClaimLineItem.description": "first party claim payment"
"ClaimLineItem.recipientId": "01t000000000000004"
}
}Here’s the output JSON returned by InsClaimItemService:
calculateCoverages.
{
"claimItem": {
"adjustedAmount": 4000 // loss item adjusted amount
},
"claimLineItemAdjustment": {
"attributeClass": "Deductible", // policy terms attribute class
"adjustedAmount": 1000, // policy terms tracking entry postedAmount
"assetTermId": "a6ERN00000000dg2AA", // policy terms id
"remainingAmount": 0 // policy terms tracking entry remainingAmount
}
}Here’s how user interactions on the Financials tab invoke services, how
InsClaimItemService: calculateCoverages gets data, and what happens
to the data afterwards.
-
(1) On the Financials tab of a claim, a user clicks New Loss Item and enters a $5,000 claim amount. Pressing Tab to advance from Claim Amount to the next field invokes
InsClaimItemService: calculateCoverages. In this example, the JSON output returned fromInsClaimItemService: calculateCoveragesincludes these values.-
claimLineItem: adjustedAmountThe amount paid to the payee after the deductible is subtracted from the claim amount: $5,000-$1,000=$4,000. This value is presented back to the user in the Adjusted Amount field on the New Loss Item form. -
claimLineItemAdjustment:adjustedAmountThe amount of the adjustment to the claim coverage payment detail, in this case the $1,000 deductible subtracted from the claim amount. -
claimLineItemAdjustment:attributeClassThe reason why the amount to be issued to the payee differs from the claimed amount. In our example, the claimed amount is decreased by $1,000 because a $1,000 deductible applies (attributeClass = Deductible). -
claimLineItemAdjustment:assetTermIdThe policy term for which a policy term tracking entry is created. In our example, it’s the ID of the Deductible policy term. -
claimLineItemAdjustment:remainingAmountThe amount to set in the policy term tracking entry, in this case $0 because there’s no deductible remaining after this transaction.
-
-
(2) Clicking Add to save the new loss item invokes
InsClaimItemService: add, which uses returned JSON output fromInsClaimItemService: calculateCoveragesto persist data to ClaimCoveragePaymentDetail, ClaimCoveragePaymentAdjustment, and InsurancePolicyTermTrackingEntry records. (TheInsClaimItemService: updateservice works similarly.) Each record includes values related to our example:-
The ClaimCoveragePaymentDetail record has a ClaimCoveragePaymentDetail.ClaimedAmount of $5,000 and a ClaimCoveragePaymentDetail.AdjustedAmount of $4,000.
-
The ClaimCoveragePaymentAdjustment record has a ClaimCoveragePaymentAdjustment.AdjustedReason of Deductible and a ClaimCoveragePaymentAdjustment.AdjustedAmount of $1,000.
-
The InsurancePolicyTermTrackingEntry record has an InsurancePolicyTermTrackingEntry.PostedAmount of $1,000 and an InsurancePolicyTermTrackingEntry.RemainingAmount of $0.
-
With an understanding of the basic structure of output JSON, you can set up a more advanced use case by introducing logic into the Coverage Calculation Formula in a coverage spec.
Example: On the Details tab of a coverage spec, you enter a Coverage
Calculation Formula like this, using the same ClaimLineItem syntax used for
additionalInput.
InvokeIP('ClaimCoverage_ClaimCoverageFormula', , INPUT('claimId', ClaimLineItem.claimId) INPUT('benefitType', ClaimLineItem.benefitType), INPUT('quantityCount', ClaimLineItem.unitCount), 'result')
At runtime, this formula calls an integration procedure called ClaimCoverage_ClaimCoverageFormula. This integration procedure expects inputs for claimId, benefitType, and quantityCount, as shown in this sample input JSON for testing the integration procedure:
{
"claimId": "a2b4W000007W2pQQAS",
"benefitType": "Ambulance - Air",
"quantityCount": "1",
}The Coverage Calculation Formula specifies that output JSON for the
ClaimCoverage_ClaimCoverageFormula integration procedure is in a node called
result. As long as the JSON structure in that result
node conforms to the expected InsClaimItemService: calculateCoverages
output JSON format, the system behaves exactly as if it’s using an underlying
power attribute class: displaying the Adjusted Amount to the
user and persisting data to ClaimCoveragePaymentDetail,
ClaimCoveragePaymentAdjustment, and InsurancePolicyTermTrackingEntry records after
the Add button is clicked.
In this output JSON example of a $50 payout for a Wellness Visit, the
result node causes InsClaimItemService: add to perform
an insert of 50 into ClaimCoveragePaymentDetail.AdjustedAmount.
{
"result": {
"claimLineItem": {
"adjustedAmount": "50"
}
},
}Here are some tips for configuring your calculation.
-
If your use case involves existing power attribute classes, you can use
InsurancePolicyTerms: getCurrentStandingsto determine how much remains on a policy term before applying an adjustment. This step allows you to apply the correct adjustment and pass back the appropriate assetTermId. In these use cases, configure the JSON structure returned by your integration procedure to include both the claimLineItem and claimLineItemAdjustment nodes.In the claimLineItemAdjustment node, make sure to:
-
Include assetTermId.
-
Include attributeClass.
The
InsClaimItemService: addservice needs both of these values to determine how to create the insurance policy term tracking entry record for that specific power attribute on the policy. For example, a coverage spec with a conditional deductible has two Deductible power attributes: Deductible A for fire and Deductible B for flood. The integration procedure within the Coverage Calculation formula can useInsurancePolicyTerms: getCurrentStandingsto determine that Deductible A for this policy is $1,000 and Deductible B is $500. Then, based on the cause of loss for this claim, the integration procedure can figure out which deductible to apply. When returning the output JSON, make sure to return the correct assetTermId based on which deductible was applied. -
-
Some use cases don’t involve the out-of-the-box power attribute classes but still require an adjustment to be made to the payment detail. For example, when a provider bills more than a negotiated rate, you need a ClaimCoveragePaymentAdjustment record to explain why the adjusted payment amount is less than the claimed amount. In these use cases, configure the JSON structure returned by your integration procedure to include both the claimLineItem and claimLineItemAdjustment nodes.
In the claimLineItemAdjustment node:
-
Leave out assetTermId because there’s no power attribute class defining this adjustment.
-
Include attributeClass as the adjustment reason (for example, “Overbilling Adjustment”).
The
InsClaimItemService: addservice uses the attributeClass string to populate the ClaimCoveragePaymentDetail.AdjustedReason field even though there’s no related attributeClass. -
-
If a use case involves a payout amount for a benefit type, there’s no discrepancy between claimed and adjusted amounts. For example, a flat rate of $100/day applies to hospital stays. In these cases, leave the entire claimLineItemAdjustment node out of your JSON.
