How the producerCodes strategy manages access

Cloud API for BillingCenter implements third-party data access for producer codes using the following:

  • The getRestProducerCodeAuth... methods in the ContactAuthorizationIdsRestV1Enhancement enhancement
  • The IRestProducerCodeAuthorizationPlugin plugin
  • The RestV1ExternalProducerCodeAuthHelperPlugin plugin
  • The accessiblefields.yaml files

The getRestProducerCodeAuth… methods

ProducerCodeAuthRestV1Enhancement is a Gosu enhancement for the AuthorizedUser entity. It has a number of methods whose names start with "getRestProducerCodeAuth". Each method determines access for a specific set of resources.

For example:
  • The getRestProducerCodeAuthRootAccess method determines access to root resources, such as payment plans.
  • The getRestProducerCodeAuthProducerAccess method determines access to producer resources, such as agency bill payments.
  • The getRestProducerCodeAuthAgencyDisbursementsAccess method determines access to AgencyBillDisbursement resources.
When BillingCenter receives a call from a user using the producerCodes resource access strategy, it first calls the appropriate method in this enhancement. The methods return a subclass of AuthAccess objects. There are two types of return values for these methods:
  • The method could return an ProducerCodeRestrictedAccess object.
    • The fields available to the caller on the target resources are restricted. The fields the caller can access are specified in the producercoderestricted.accessiblefields.yaml file.
  • The method could return an UnfilteredAccess object.
    • The caller is not restricted by any third-party data filters. (The caller can access any resource and any field as specified by their API roles and any restrictions imposed by all callers using the producerCodes resource access strategy.)
  • The method could return an NoAccess object.
    • The caller has no access to the resource.

The IRestProducerCodeAuthorizationPlugin plugin

The IRestProducerCodeAuthorizationPlugin defines methods which allow you to customize authorization logic for producer code resource access.

The plugin implements the IRestProducerCodeAuthorizationPlugin interface. This interface has the following methods:

  • getAuthorizedProducerCodesQuery(AuthorizedUser user) - Returns the query to retrieve the producer codes the given user has access to.
  • getAuthorizedProducerCodes(AuthorizedUser user) - Returns a map of the producer code strings and producer codes the user has access to.
  • getRestProducerCodeAuthRootAccess(AuthorizedUser user) - Returns the root access object for the user when they are authorized with at least one producer code.
  • getRestProducerCodeAuthPolicyPeriodAccess(AuthorizedUser user, PolicyPeriod policyPeriod) - Returns the access object for the given user and policy period. In the base configuration implementation of this method, the user can access a policy period if:
    • A provided producer code can access an active PolicyCommission on the policyPeriod
    • A producer code has an active item commission on any charge on the policy period
    • A producer code has an inactive item commission with a commissionAmount that is greater than 0 on any charges on the policy period
  • getRestProducerCodeAuthChargeAccess(AuthorizedUser user, Charge charge) - Returns an access object for the given user and charge. See Producer code access by resource for an overview of how charge access is determined in the base configuration.

The RestV1ExternalProducerCodeAuthHelperPlugin

The RestV1ExternalProducerCodeAuthHelperPlugin defines methods to map producer code strings to producer codes and to handle parameters.

This plugin implements the RestV1ExternalProducerCodeAuthHelperPlugin interface. This interface defines the following methods:
  • getProducerCodeMapByCodes(Set<String> codes)
  • setParameters(Map params)

The getProducerCodeMapByCodes method accepts a set of strings and returns a map of those strings and their corresponding producer codes.

In the base configuration implementation of the plugin, BillingCenter expects each of the strings to map exactly to the Code value on one of the ProducerCode entities in the BillingCenter database. If there are any strings that match more than one producer code or that do not match a producer code, BillingCenter throws an error for the call.

To avoid errors, Guidewire recommends that producer codes be unique in the BillingCenter database. However, if there are producer codes in the BillingCenter database that are not unique, the plugin can be configured to accept different values as strings and map them to the producer codes.

For example, you can configure producer code access to send the IDs of producer codes in the bc_producerCodes claim rather than the code strings. Then you can create a custom implementation of the getProducerCodeMapByCodes method which maps the set of producer code IDs to producer code entities in the database.

The setParameters method accepts a map of parameters as set in the plugin registry item. In the default implementation of RestV1ExternalProducerCodeAuthHelperPlugin, it sets the cache size of the producer codes it queries for to 100.

The accessiblefields.yaml files

An accessiblefields.yaml file is a file that lists the fields a user can access when an additional accessible fields filter grants them filtered access to a resource. All accessiblefields.yaml files are stored in the integration > roles > additionalaccessiblefieldsfilters directory. They all have names that end in "accessiblefields.yaml". For contact authorization id access, the relevant files are accountprimarypayer.accessiblefields.yaml and invoiceitempayer.accessiblefields.yaml. For producer code access, the relevant file is producercoderestricted.accessiblefields.yaml.

Each file contains an accessibleFields section with a list of resource types. For each type, there is an edit and view section. Each section lists the fields that a user can edit or view when restricted by the filter. If a user cannot edit or view any fields, then the section lists "[]".

For example, the following is a portion of the accountprimarypayer.accessiblefields.yaml file.
name: accountprimarypayer
accessibleFields:
 AccountContact:
   edit: []
   view:
   - displayName
   - id
   - primaryPayer
   - roles
 ...

For a given user and AccountContact, if the user is restricted to the accountprimarypayer accessible fields filter, then:

  • The user cannot edit any fields.
  • The user can view only the displayName, id, primaryPayer, and roles fields.

Example logic flow for determining access

Suppose that there is a BillingCenter account with one policy with one policy period with id bc:101. There is one producer earning commission on the policy period with producer code bc:101ProdCode.

There are two callers that are attempting to access the policy period bc:101 in BillingCenter using the GET /billing/v1/accounts endpoint. They are both using the producer codes resource access strategy.

  • The first caller's JWT includes the producer code bc:101ProdCode, which earns commission on the policy period.
  • The second caller's JWT does not include the producer code that earns commission on the policy period.

When BillingCenter receives a request for the account, it first calls the producerCodes_ext-1.0.access.yaml file, which in turn calls the producerCodes_core-1.0.access.yaml file. This file calls the getRestProducerCodeAuthAccountAccess method in the ProducerCodeAuthRestV1Enhancement enhancement. This method calls getRestProducerCodeAuthPolicyPeriodAccess for each policy period on the account. This method handles processes such as:

  • Validating the user's producer codes
    • If a user's producer code does not match an existing producer's producer code in the database, BillingCenter throws an error.
  • Mapping the user's producer codes to producer codes in the database
    • It calls the IRestProducerCodeAuthorizationPlugin, which calls the RestV1ExternalProducerCodeAuthHelperPlugin to produce the map of producer code strings and producer codes.
  • Checking if there are any charges on the policy period on which the provided producer codes earn commission

If there are any policy periods on which at least one provided producer code earns commission, BillingCenter grants access to the account. It grants access by returning a ProducerCodeRestrictedAccess object where viewAccess is true. Otherwise, it returns a NoAuthAccess object.

  • For the first caller, a ProducerCodeRestrictedAccess where viewAccess is true is returned.
  • For the second caller, a NoAuthAccess object is returned.

As a result of the returned values, BillingCenter grants the first caller restricted access to view the account, and the second caller gets no access to the account.