Tools for configuring foreign keys

When you configure a schema, you typically modify three files:

  • The schema extension file, which defines the structure of the property
  • The mapping extension file, which defines how data maps from the database to the property
  • The updater extension file, which defines how data maps from the property to the database

Schema configuration for foreign keys make use of several tools, one for each of these files:

  • The schema extension file references the SimpleReference schema
  • The mapping extension file references the ResourceReference mapper
  • The updater extension file references one of the value resolvers

In some cases, you may also need to explicitly define an URI Mapping.

The SimpleReference schema

The SimpleReference schema is a schema used to simplify how information from other resources is embedded in a schema. The SimpleReference schema has the following fields, which are common to all resources:

  • displayName
  • id
  • jsonPath
  • refid
  • type
  • uri

Whenever you add a foreign key property to a schema extension file, the property's definition uses the SimpleReference schema.

The ResourceReference mapper

The ResourceReference mapper is a mapper that maps information from an entity into the fields defined by the SimpleReference schema. Whenever you add a foreign key property to a mapping extension file, the property's mapper references the ResourceReference mapper.

Value resolvers

A value resolver is a class used in updaters to return the resource that a foreign key property points to. Within the context of a foreign key property:

  • The root (or the root resource) is the resource that has the foreign key property.
  • The resolved value is the resource that the foreign key points to.

For example, suppose the Activity resource has a foreign key field named AssignedUser that points to a User resource. In this case:

  • The root is Activity.
  • The resolved value is the User that Activity.AssignedUser points to.

The term resolving the reference refers to the act of determining the resource that the foreign key property points to.

When adding a foreign key property to an updater extension file, the property's updater references a value resolver.

Cloud API provides multiple value resolvers. Some of them are for a specific base configuration entity. Others provide more generic functionality. Some of them are abstract, in which case you must extend the value resolver for a specific type of entity. The following is a brief overview of each resolver. The following topics go into greater detail about when and how to use each resolver.

Entity-specific value resolvers

An entity-specific value resolver is a base configuration value resolver that resolves values for a specific type of base configuration entity. For example, the UserJsonValueResolver can be used for foreign key fields that point to instances of User.

You can find a list of entity-specific value resolvers in Studio by executing a Navigate -> File command (CTRL + SHIFT + N) and entering "valueresolver".

Be aware that some entity-specific value resolvers have special behaviors to enable specific Cloud API use cases. These behaviors may not be appropriate for custom foreign key properties. Whenever you use an entity-specific value resolver, Guidewire recommends testing the associated PATCH and POST behaviors thoroughly.

For more information on the use cases for entity-specific value resolvers, see Updater case 1: Root and resolved value have no common ancestor and Updater case 2: Root and resolved value have a common ancestor.

KeyableBeanJsonValueResolver

The KeyableBeanJsonValueResolver is a generic value resolver that can be used when either:

  • There is no entity-specific value resolver for the entity the foreign key references.
  • There is an entity-specific value resolver for the entity the foreign key references, but it has behaviors that are not appropriate for the custom foreign key.

The KeyableBeanJsonValueResolver is declared in the gw.rest.core.pl.framework.v1.refs package.

To use this resolver, the schema property for the foreign key must include a x-gw-extensions.resourceType field that identifies the type of resource the foreign key points to. For example, if you had a backupUser_Ext foreign key property on Activity that points to User, then the schema property declaration would be as follows:

    "Activity": {
      "properties": {
        "backupUser_Ext": {
          ...
          "x-gw-extensions": {
            "resourceType": "User"
          }
        }
      }

Also, in the updater, the path attribute must resolve to a KeyableBean.

By default, this updater supports both reference by id and refid. You can disable referencing by refid.

This resolver is final and cannot be subclassed. If you need a KeyableBean value resolver with behavior that can be subclassed, use AbstractKeyableBeanJsonValueResolver.

For more information on using the KeyableBeanJsonValueResolver, see Updater case 1: Root and resolved value have no common ancestor and Updater case 2: Root and resolved value have a common ancestor.

AbstractKeyableBeanJsonValueResolver

The AbstractKeyableBeanJsonValueResolver is also a generic value resolver. It is abstract and therefore is never used directly. But it can be extended, and the subclass resolver can apply to any entity.

Subclassing this resolver gives you the ability to specify "isEntityViewable logic". This logic can control access to an object based on business-specific conditions of the object. For example, this logic could mandate that a foreign key property to User can reference only users with the "Manager" role.

For more information on using the AbstractKeyableBeanJsonValueResolver, see Update case 3: Accessibility of resolved value is conditional.

CollectionBasedJsonValueResolver

Note: This value resolver is theoretically applicable in all applications. However, the primary use case for this value resolver occurs most often in PolicyCenter.

In some situations, the resolved value cannot be determined using id only. In these situations, the correct resolved value can be selected only by selecting a KeyableBean from a collection contained on some ancestor entity. The most common situation that this occurs is when resolving effdated entities.

For more information on using the CollectionBasedJsonValueResolver, see Update case 4: Resolved value cannot be easily resolved by id alone.

The URI Mapping

A URI mapping is an entry that defines, for a given resource type, the resource's URI and its parent. If a schema defines one or more foreign keys, the root resource needs an URI Mapping.

URI mappings exist for all base configuration resource types in Cloud API. URI mappings are also generated automatically if you create endpoints using the REST endpoint generator and you add the new resource to an integration graph. Therefore, the only time you need to a URI mapping manually is if you have a resource with one or more foreign keys, you generated the resource using the REST endpoint generator, and you did not add the new resource to an integration graph.