Configuring Cloud API access to third-party data

Configuring the ClaimContact roles that provide unfiltered access

For some resource access strategies and resources, the ClaimContact roles that provide unfiltered access are declared in a ClaimContact role yaml file. To modify the roles that provide unfiltered access, add or remove roles from this file. To deploy the changes, you must restart the server.

Configuring the fields that a caller is restricted to

The accessiblefields.yaml files define the types for which access can be filtered. Each type specifies additional edit and view restrictions imposed on users with filtered access.

• Fields that the user can view or edit must be listed explicitly.
• If the caller cannot view or edit any fields on the resource, an empty list ([ ]) must be specified.

The accessiblefields.yaml files are configurable. You can add and remove types and fields as needed to suit your implementation. To deploy the changes:

• If you are in development mode, the file will hotswap a few seconds after it is saved.
• If you are in production mode, you must restart the server.

Types of custom "third-party data" entities

There are different categories of custom entities that can store third-party information. The following descriptions make use of the term "API parent". When you generate endpoints for a custom entity, one of the REST endpoint generator prompts is "What is the resource name of the parent?" The resource you specify is the resource's API parent. For example, given the endpoint path /claims/{claimId}/trip-incident/{incidentId}/trip-segments/{segmentId}

• The API parent of TripIncident is Claim

• The API parent of TripSegment is TripIncident

There are different categories of custom "third-party data" entities:

• Custom incident type

  • This is a custom entity that is defined in the data model as a subtype of Incident

  • For example, PetIncident_Ext, which is a subtype of Incident used for a custom pet insurance product

• Custom entity whose API parent is Claim

  • This is a custom entity whose endpoint path defines Claim (/claim) as the parent

  • For example, FaultAssessment_Ext, which stores information about who caused the loss and has an endpoint path of /claims/{claimId}/fault-assessments-ext

• Custom entity whose API parent is ClaimContact or an incident type

  • This is a custom entity whose endpoint path defines ClaimContact (/contact) or one of the incident types as the parent

  • For example, Towable_Ext, which stores information about an object towed by a vehicle whose API parent is VehicleIncident and has an endpoint path of /claims/{claimId}/vehicle-incident/{vehicleIncidentId}/towables-ext

Configuration steps

To configure additional accessible fields filters for a custom third-party data entity, you must do the following:

1. Generate endpoints for the custom entity

2. Configure an additional accessible fields filter

3. Configure the accessible fields in the accessiblefields.yaml file

Step 1: Generate endpoints for the custom entity

First, you must generate endpoints for the custom entity using the REST endpoint generator. For more information, see Generating endpoints for custom entities.

Step 2: Configure an additional accessible fields filter

Next, you must add an additional accessible fields filter to the appropriate resource access extension file. You must also configure any related logic used by your additional accessible fields filter expression.

To define the filter itself, edit the appropriate resource access extension file. For example, to configure the producerCodes resource access strategy, edit the producerCodes_ext-1.0.yaml file.

In the appropriate resource access extension file, add a section that defines the custom type and a viewAndEdit expression. The expression can be defined in two ways.

Setting the filter to a Gosu expression

The expression can be a Gosu expression that returns null or a string.

• If the expression returns null, no additional restrictions are placed on access to the given resource.

• If the expression returns a string, Cloud API looks in the integration > roles > additionalaccessiblefieldsfilters directory for a file that starts with the returned string and ends with accessiblefields.yaml. It then adds any additional restrictions defined in that file.

You can use the base configuration's hasProducerPrivilegedAccessOnClaimContact or hasProducerPrivilegedAccessOnIncident methods.

ClaimContact:
 ...
 additionalAccessibleFieldsFilter:
   viewAndEdit: "user.hasProducerPrivilegedAccessOnClaimContact(resource) ? null : \"restricted\""

PetIncident_Ext:
 ...
 additionalAccessibleFieldsFilter:
   viewAndEdit: "user.hasProducerPrivilegedAccessOnIncident(resource) ? null : \"restricted\""

You can use this expression as is. Alternatively, you can write your own method. It can use the following symbols:

• user - The AuthorizedUser that Cloud API retrieved from the calling token

• resource - The instance of the resource to be evaluated

Note that you also need to configure any logic called by the additional accessible fields filter expression. For example, the base configuration's hasProducerPrivilegedAccessOnClaimContact or hasProducerPrivilegedAccessOnIncident methods check for ClaimContact roles listed in ProducerAccessibleRoles.yaml. If you are using one of these methods, you may need to modify the list of roles in that file.

Setting the filter to __inherit

You can also set the filter to __inherit. This means that the custom resource type inherits any additional accessible fields logic defined by its API parent.

Towable_Ext:
 ...
 additionalAccessibleFieldsFilter:
   viewAndEdit: __inherit

Step 3: Configure the accessible fields in the accessiblefields.yaml file

Finally, in restricted.accessiblefields.yaml, add the new type to the accessibleFields section. Add both an edit: and view: subsection and specify the fields that are available when a caller has restricted access.

• You can specify both fields directly on the resource (such as id) and child fields (such as incidentOwner.type).

• To specify no fields, use an empty list ([ ]).

ClaimCenter throws a runtime exception if any of the following occur:

• A type has an additional accessible fields filter expression, but the type is not listed in the accessiblefields.yaml file.

• A type with a viewAndEdit additional accessible fields filter expression is listed in the accessiblefields.yaml file, but it does not have both edit and view subsections.

name: restricted
accessibleFields:
 ...
 PetIncident_Ext:
   edit: []
   view:
   - type
   - name

For custom incident types, be aware that the REST endpoint generator does add an additional accessible fields filter, but it does not add the type to the restricted.accessiblefields.yaml file. For custom incident types, you must add the type to the restricted.accessiblefields.yaml file (or remove the additional accessible fields filter). Otherwise, ClaimCenter throws an error any time you attempt to access the custom incident type.

Query-backed collections

The default behavior for sorting and filtering behavior for query-backed collections is that the Cloud API allows you to sort and filter on a field only if the field is available to all callers. This means that the field you want to use for sorting or filtering is available for the collection type in every accessiblefields.yaml file.

name: restricted
accessibleFields:
 ClaimContact:
   edit: []
   view:
   - id
   - firstName
   - lastName

The lastName field is available to all callers, even to callers with additional accessible field restrictions, so you can sort and filter on lastName.

However, primaryPhone isn't available to callers with additional accessible field restrictions, so those callers who can't view primaryPhone values can't sort or filter on primaryPhone.

You can use an access.yaml file, such as contactAuthorizationIds_core-1.0.access.yaml, to list the specific additional accessible fields source files you want to make available for the element resource, rather than checking all such files.

Here is an example of this specific listing of additional accessible fields files:

resources:
    ClaimContact:
        permissions:
            ...
        additionalAccessibleFieldsFilter:
            viewAndEdit: "..."
            queryBackedCollectionFiles:
            - privileged // privileged.accessiblefields.yaml must exist
            - restricted // restricted.accessiblefields.yaml must exist

The Cloud API will only use the files listed here when it's determining whether a field is sortable or filterable for the query-backed collection. If no files are specified here, the Cloud API will check all additional accessible field files to determine which are allowed.

When you specify additional accessible fields this way, ensure the following:

• The referenced accessiblefields.yaml file exists.
• You are not using __inherit as a value for viewAndEdit.

There is also validation that checks whether each individual element result in the viewAndEdit expression is one of the items from the queryBackedCollectionFiles config - otherwise, it will cause a RuntimeConfigurationException.

Stream-backed collections

When a collection is stream-backed, Cloud API lets you sort and filter on all sortable and filterable fields. However, if a field on a given resource is restricted to the caller, Cloud API treats the field's value as if it were null for the purpose of sorting and filtering.

name: restricted
accessibleFields:
 ...
 ClaimContact:
   edit: []
   view:
   - id
   - firstName
   - lastName
 ...

Finally, suppose there are four ClaimContacts in a collection:

• Ray Newton (the insured); primary phone: 111-1111

• Karen Egerston (the producer); primary phone: 333-3333

• Sue Thompson (driver of a third-party vehicle); primary phone: 222-2222

• Virginia Green (passenger in the third-party vehicle); primary phone: 444-4444

Andy Applegate is a claims adjuster who is not bound by additional accessible fields filters. If Andy sorts the collection based on primaryPhone, Andy will see this:

1. Ray Newton; primary phone: 111-1111

2. Sue Thompson; primary phone: 222-2222

3. Karen Egerston; primary phone: 333-3333

4. Virginia Green; primary phone: 444-4444

Karen Egerston is a producer who is bound by additional accessible fields filters and cannot view primaryPhone on third-party contacts. If Karen sorts the collection based on primary phone, Karen will see this:

1. Sue Thompson; primary phone: (null)

2. Virginia Green; primary phone: (null)

3. Ray Newton; primary phone: 111-1111

4. Karen Egerston; primary phone: 333-3333

Note that the Sue Thompson and Virginia Green ClaimContacts have been sorted as if their primary phone values were null.

This behavior exists because the entire stream-backed collection is loaded into memory at one time. Thus, Cloud API knows which members of the collection are restricted by an additional accessible fields filter before it starts to build the response. It can permit sorting and filtering on the field, and it simply obfuscates the restricted information by treating it as null.

The resource access extension file

<CollectionResourceType>:
  additionalAccessibleFieldsFilter:
    create: <expression>

The expression must return null or a string.

• If the expression returns null, no additional restrictions are placed on the fields that can be specified when POSTing an instance of the given type.

• If the expression returns a string, Cloud API looks in the integration > roles > additionalaccessiblefieldsfilters directory for a file that starts with the returned string and ends with accessiblefields.yaml. It then restricts the POST from specifying any fields not defined in that file.

The expression can make use of the following symbols:

• user - The AuthorizedUser that Cloud API retrieved from the calling token

• resource - The instance of the resource to be evaluated

• data - The data envelope of the request payload.

The accessiblefields.yaml file

The accessiblefields.yaml file must specify the type. The type must have an edit property that defines the fields the caller cannot specify in the POST. If the caller cannot edit any fields on the resource, an empty list ([ ]) is specified. (Note that if the type must also have a view property if the resource access extension file specifies a viewAndEdit expression for that type.)

Configuring service request access by service

In the base configuration, every type of service is listed in ExternallyVisibleServices.yaml. Therefore, there are no service requests which a producer cannot access.

If you add a custom service to ClaimCenter and you want contacts and producers with the appropriate permission to be able to access service requests with this service, then you must add this service to ExternallyVisibleServices.yaml.

If there is a type of service that you never want to make accessible to contacts and producers, such as something related to fraud investigation, you can deny access by omitting that service type from ExternallyVisibleServices.yaml.