Configuring access to third-party data
An additional accessible fields filter is a set of if/else logic that controls a user's access to third-party data. It consists of an expression in a resource access file that evaluates the business relationship the user has with a given resource. This evaluation may add restrictions that limit the user's access to only the fields that do not contain third-party data.
Configuring access to base configuration entities
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.
Configuring access for custom entities
If you create a custom entity that stores third-party information, and you want to restrict access to this information, you can add new additional accessible fields filters for the custom entity.
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
isClaim
-
The API parent of
TripSegment
isTripIncident
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 ofIncident
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:
-
Generate endpoints for the custom entity
-
Configure an additional accessible fields filter
-
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 REST endpoint generator overview.
Note that there are additional considerations for custom incidents. For more information, see Incidents and risk units: Implementation overview.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
directory for a file that starts with the returned string and ends withaccessiblefields.yaml
. It then adds any additional restrictions defined in that file.
You can use the base configuration's
hasProducerPrivilegedAccessOnClaimContact
or
hasProducerPrivilegedAccessOnIncident
methods.
additionalAccessibleFieldsFilter
expression is:ClaimContact:
...
additionalAccessibleFieldsFilter:
viewAndEdit: "user.hasProducerPrivilegedAccessOnClaimContact(resource) ? null : \"restricted\""
PetIncident_Ext
. The REST endpoint generator adds the
following to the producerCodes_ext-1.0.yaml
file: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
- TheAuthorizedUser
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
. It has an API parent of
VehicleIncident
, and you want it to use the same logic as the
additional accessible field filter parent for VehicleIncident. To do this, add the
following to the producerCodes_ext-1.0.yaml
file:Towable_Ext:
...
additionalAccessibleFieldsFilter:
viewAndEdit: __inherit
__inherit
option is
not needed for custom incident types, as this is added automatically by the REST
endpoint generator. It is not needed for custom entities whose API parent is
Claim
, as Claim
has no additional accessible
fields filter logic to inherit. Therefore, the __inherit
option is
meaningful only for third-party data entities that are API children of ClaimContact or
an incident type.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 asincidentOwner.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 theaccessiblefields.yaml
file, but it does not have bothedit
andview
subsections.
PetIncident_Ext
to only
the type
and name
fields, add the following to
restricted.accessiblefields.yaml.
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.
Sorting and filtering on accessible fields
Within a collection, a field can be sortable, which means that the collection is ordered based on the values of that field. A field can also be filterable, which means that the collection members can be filtered based on the field's value.
However, with additional accessible fields filters, a sortable or filterable
field may not always be available to the caller. For example, suppose a claim has four
ClaimContacts: the insured, the producer, and two-third party contacts. Suppose that
primaryPhone
is sortable and filterable, but it is also restricted
so that the producer cannot access primaryPhone
for the third-party
contacts. Sorting and filtering on primaryPhone
could expose
information about those values that the caller should not be allowed to see. What
happens if the producer attempts to sort or filter on primaryPhone
?
The behavior depends upon whether the collection is query-backed or stream-backed.
Query-backed collections
When a collection is query-backed, Cloud API lets you sort and filter on a field only
if the field is available to all callers. In other words, every reference to the
collection type in every accessiblefields.yaml
file must specify
that access to the field is always allowed. If access to the field is not granted to
all callers, then sorting and filtering is not allowed on that field.
ClaimContacts
collection is
query-backed and that lastName
and primaryPhone
are sortable and filterable. Also, the
restricted.accessiblefields.yaml
file specifies the
following:name: restricted
accessibleFields:
...
ClaimContact:
edit: []
view:
- id
- firstName
- lastName
...
lastName
is available to all callers, even to callers with
additional accessible field restrictions. Therefore, sorts and filters on
lastName
are allowed.
primaryPhone
is not available to all callers. Those with
additional accessible fields restrictions cannot see this field. Therefore, sorts
and filters on primaryPhone
are not allowed, even for callers with
no additional accessible fields restrictions.
This behavior exists because a query-backed collection is not loaded into memory all at once. Rather, the collection is loaded one page at a time. Cloud API begins to build the response before it has loaded every page of the collection. Cloud API cannot know whether any member of the collection will be restricted by an additional accessible fields filter. Therefore, because there could be a member of the collection that requires restricted access, it cannot allow access to sorting and filtering on that field.
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.
ClaimContacts
collection is
stream-backed and that lastName
and primaryPhone
are sortable and filterable. Also, the
restricted.accessiblefields.yaml
file specifies the
following: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 he sorts the collection based on
primaryPhone
, he will see this:
-
Ray Newton; primary phone: 111-1111
-
Sue Thompson; primary phone: 222-2222
-
Karen Egerston; primary phone: 333-3333
-
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
she sorts the collection based on primary phone, she will see this:
-
Sue Thompson; primary phone: (null)
-
Virginia Green; primary phone: (null)
-
Ray Newton; primary phone: 111-1111
-
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.
Filtering fields in a POST
It is possible to add an additional accessible fields filter that restricts which fields can be specified when POSTing a given type of resource. However, there are no instances of this in the base configuration.
The resource access extension file
Activities
. The type must
have an additionalAccessibleFieldsFilter
property with a
create
sub-property. The syntax for this
is:<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
directory for a file that starts with the returned string and ends withaccessiblefields.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.)
Restricting access to service requests based on its services
Every service request has an array of one or more services
. Contacts and
producers can view a given service request only if every service in the
services
array has been allowlisted in the
ExternallyVisibleServices.yaml
file. If a service request has at
least one service that is not listed in the
ExternallyVisibleServices.yaml
file, then no contact or producer
can view that request.
ExternallyVisibleServices.yaml
file contained
only the following rows:visibleServices:
- autoappraise
- autoinsprepair
- autoinsprepairbody
- autoinsprepairglass
Then suppose you have the following service requests.
- Service request 1
- Services:
autoappraise
,autoinsrepairglass
- Services:
- Service request 2
- Services:
autoappraise
,autoinsrepairaudio
- Services:
For the first service request, every service is listed in
ExternallyVisibleServices.yaml
. Therefore, this service request is
accessible to contacts and producers (assuming they have the other permissions needed to
access it).
For the second service request, the autoinsrepairaudio
service is not
listed in ExternallyVisibleServices.yaml
. Therefore, this service
request is not accessible to contacts and producers (regardless of any other
permissions).
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
.