Configuring financial calculations access

Cloud API supports the ability to retrieve financial calculations for a claim. This includes the following endpoints:

GET /claim/v1/claims/{claimId}/financial-calculations
- This identifies the list of financial calculation expressions a given caller can access on a given claim

POST /claim/v1/claims/{claimId}/financial-calculations/{expression}/get-amount
- This retrieves the result of a given financial expression, either with or without filters

For more information on how to use these endpoints, see the Cloud API Consumer Guide.

Cloud API also supports the following configurations for these endpoints:

Exposing base configuration ClaimCenter calculations that are not exposure in the base configuration of Cloud API
Exposing custom calculations
Configuring restrictions to specific financial calculation expressions and filters

This topic discusses how to configure restrictions to specific financial calculation expressions and filters. For information on how to expose new calculations to the Financial Calculations endpoints, see Exposing financial calculations.

Overview of financial calculations access

As is the case with any endpoint, you can control which callers have access to the /financial-calculations endpoint through endpoint access. You can also control which callers can access a given claim through resource access.

However, once a caller has access to a given claim and the /financial-calculations/{expression}/get-amount endpoint, you may not want to give them the ability to perform every type of financial calculation on any of the claim's transactions. For example, you may have the following requirements:

An insured can see total payments for a claim, but not access reserve information.
A third-party claimant can see total payments only for exposures where they are claimant for the exposure.

To enforce these types of requirements, Cloud API supports additional logic to restrict financial calculations access.

Types of restrictions

The following table summarizes the ways in which you can restrict access to the functionality of the /get-amount endpoint.


Restriction	Example	More Information
Grant access to one or more specific financial expressions	You can grant access to the `TotalPayments` expression to insureds, but prevent them from using any other expression.	Granting access to financial expressions
Restrict access to a particular transaction filter	You can prevent insureds from using the `recoveryCategory` filter.	Defining filter access
Require a particular transaction filter	You can require that claimants must filter by exposure when using the `TotalPayments` expression.	Defining filter access
Limit the values that can be used for a particular transaction filter	You can require that when insureds filter transactions based on CostType, they can specify only `claimcost`.	Defining filter access


Restriction	Example	More Information
Grant access to one or more specific financial expressions	You can grant access to the `TotalPayments` expression to insureds, but prevent them from using any other expression.	Granting access to financial expressions
Restrict access to a particular transaction filter	You can prevent insureds from using the `recoveryCategory` filter.	Defining filter access
Require a particular transaction filter	You can require that claimants must filter by exposure when using the `TotalPayments` expression.	Defining filter access
Limit the values that can be used for a particular transaction filter	You can require that when insureds filter transactions based on CostType, they can specify only `claimcost`.	Defining filter access

These restrictions can be used individually or in combination. For example, you could specify that claimants only have access to transactions for TotalPayments for exposure and only where the CostType is claimcost.

Granting access to financial expressions

You can grant access to specific financial expressions based on the caller's resource access strategy. For example, you can specify:

Callers using internal access have access to all financial expressions.
Callers using contactAuthorizationIds access have access to TotalPayments only.

For a given resource access strategy, access to financial expressions is defined in up to two files:

The core access.yaml file
The extension access.yaml file

Access is defined in the view permission of the FinancialCalculation element resource.

To provide access to all financial expressions, set view to true
To provide access to a set of financial expressions, write a Gosu expression that returns true if the resource element name is one of the allowed expressions.

For example, the internal_core-1.0.access.yaml file has the following:

FinancialCalculation:
  permissions:
    view: __inherit
    edit: __inherit
    get-amount: __inherit

This means that if an internal caller can view the claim, they can use all financial calculations expressions on that claim.

On the other hand, the contactAuthorizationIds_core-1.0.access.yaml file has the following:

FinancialCalculation:
  permissions:
    view: 
    - __inherit
    - "resource.Element.Name == \"TotalPayments\""
    edit: false
    get-amount: true

This means that a contactAuthorizationIds caller can use ("view") only the TotalPayments expression (and any other expressions inherited from the parent).

Configuring access to financial expressions

To configure access to financial expressions, add the new logic to the appropriate access extension file.

For example, suppose you added the following to the contactAuthorizationIds_ext-1.0.access.yaml file:

FinancialCalculation:
  permissions:
    view: 
    - __inherit
    - {\"TotalPayments\",\"FuturePayments\"}.contains(resource.Element.Name)

This means that a contactAuthorizationIds caller can use ("view") the TotalPayments expression and the FuturePayments expression (and any other expressions inherited from the parent).

Defining filter access

Filter access is defined in the FinancialCalculationConfig.yaml file. The high-level syntax for this file is as follows:

FinancialCalculationConfig:
  <resourceAccessStrategy>:
    <filter>:
      required: <GosuExpression>
      values: <GosuExpression>

<resourceAccessStrategy>

For a caller to have access to financial calculations, the caller must be using a resource access strategy that is listed in the FinancialCalculationConfig.yaml file. If the caller's resource access strategy is not listed in this file, then the caller has no access to financial calculations.

For example, suppose the FinancialCalculationConfig.yaml file has the following contents:

FinancialCalculationConfig:
  contactAuthorizationIds:
    ...
  internal:
    ...
  service:
    ...

This means that:

Callers using the contactAuthorizationIds, internal, or service resource access strategy can access financial calculations (subject to additional logic defined for that access strategy).
Callers using any other resource access strategy (such as gwabuid) cannot access financial calculations.

For a given resource access strategy, if the access.yaml file allows a user to access one or more financial expressions, but FinancialCalculationConfig.yaml does not contain a mapping for that strategy, this is considered a configuration error. At runtime, Cloud API returns a 500 error.

<filter>

Within each resource access strategy, you must list the filters that callers of this strategy have access to. The legal values are:

claimLevel
exposure
costType
costCategory
reservingCurrency
recoveryCategory

If a filter is not listed, callers using that strategy cannot filter transactions using that filter.

For example, suppose the FinancialCalculationConfig.yaml file has the following contents:

FinancialCalculationConfig:
  contactAuthorizationIds: 
    exposure: 
    costType: 
    costCategory: 
  internal:
    claimLevel:
    exposure:
    costType:
    costCategory:
    reservingCurrency:
    recoveryCategory:
  ...

This means that:

Callers using the contactAuthorizationIds strategy can filter only by exposure, costType, and costCategory.
Callers using the internal strategy can use any filter.

required and values

A given filter can have a required expression and/or a values expression.

required

The required expression defines whether the filter is required. It is a Gosu expression that must resolve to a Boolean value.

If it resolves to true, then the filter must be included in calls to /get-amount. In other words, if it resolves to true, the caller cannot inherently view all transactions. They must specify the given filter.
If it resolves to false, then the filter can be omitted.

If no expression is specified, the expression returns false.

For example, suppose you have the following:

   contactAuthorizationIds:
    exposure:
      required: "!user.hasPrivilegedRoleOnClaim(claim)"

This means that callers using the contactAuthorizationIds strategy must specify an exposure filter if they do not have a privileged role on the claim. (In other words, contacts who are not privileged must restrict their financial calculations to a specific exposure.)

values

The values expression identifies the set of allowed values for a filter. It is a Gosu expression that must resolve to a List as follows:

claimLevel - the expression must return a List of Booleans, usually with a single element of true or false.
exposure - the expression must return a List of ids corresponding to one or more exposures.
all other filters - the expression must return a List of valid typecode values for the filter

If no expression is specified, the expression returns null.

If the expression returns null, all values are considered legal.

If the expression returns an empty string, no values are considered legal. (In other words, the filter cannot be specified for this caller on this claim.)

For example, suppose you have the following:

   contactAuthorizationIds:
    costCategory:
      values: "{\"autoglass\",\"autoparts\",\"body\",\"towing\"}"

This means that callers using the contactAuthorizationIds strategy is not required to specify a CostCategory. However, if they do, they can filter only on autoglass, autoparts, body, or towing.

Specifying required and values

You can specify both expressions. This is typically done to specify that callers who meet a given criteria must include this filter and must limit the filter to a subset of possible values.

For example, suppose you have the following:

FinancialCalculationConfig:
  contactAuthorizationIds:
    costType:
      required: "true"
      values: "{\"claimcost\"}"

This means that callers using the contactAuthorizationIds strategy can execute financial calculations for ClaimCost transactions only. (In other words, the caller must specify the costType filter and can set it only to claimcost.)

Available symbols

For both required and values, the expressions can use the following symbols:

user - the AuthorizedUser making the request
expression - the name of the financial expression being requested
claim - the relevant claim

Base configuration restrictions

The base configuration includes the following restrictions:

Internal users and services can access all financial calculations.
External users using the contactAuthorizationIDs resource access strategy can access only the TotalPayments expression, and only when filtering by a costType of claimcost. Broadly speaking:
- An insured can see total claimcost payments for the claim without further restrictions.
- A claimant who is not an insured can see total claimcost payments only for the exposures where they are the claimant.
External users using any other resource access strategy (such as producers and vendors) cannot access any financial calculations.