Supertype entities

A supertype entity is a data model entity which has one or more other entities that act as subtypes. In a supertype/subtype entity structure:

  • The top-level entity is referred to as the parent entity or the supertype entity.
  • Each lower-level entity is referred to as a child entity or a subtype entity.

For example, suppose there is an Interaction_Ext entity that captures information about an interaction (a phone call, email, or in-person conversation) that the insurer has with someone else. The Interaction_Ext entity has two subtypes: InteractionWithInsured_Ext and InteractionWithVendor_Ext.

  • The Interaction_Ext supertype has an InteractionDate datetime field.
  • InteractionWithInsured_Ext has an isComplaint Boolean field.
  • InteractionWithVendor_Ext has an isBillable Boolean field.

When you use the REST endpoint generator to generate endpoints for a supertype entity, the following additional prompt is asked:

The entity '<CustomEntity>' is a concrete type that has subtypes. Do you wish for subtypes 
to (sh)are this endpoint or have their own (se)parate endpoints? sh/se

You can choose either shared handling or separate handling. With shared handling, the REST endpoint generator CRUD endpoints that are intended to work with information at both the supertype and subtype level simultaneously. When you choose separate handling, it creates CRUD endpoints that are intended to work with information at the supertype level only, and if you want to work with information at the subtype level, you must generate an additional set of endpoints for each subtype.

Shared handling

Shared handling is designed for situations where the bulk of the information is at the supertype level and you want to manage the information with a single set of endpoints.

In this approach, the tool generates a single element resource and a single set of CRUD endpoints. After configuration, the element resource would typically include fields declared at the supertype level and at each subtype level. A single GET can potentially return objects of different subtypes.

The subtype field

The REST endpoint generator automatically adds a subtype field. This field tracks the subtype of a given object. The field must be specified when an object is created, as it is used to determine how to create the object. Once created, an object's subtype value cannot be changed.

Data mapping requirements

The only properties that are automatically added to the resource are the id and subtype properties. All other properties, from both the supertype and subtype levels, must be configured manually.

In the schema file, Guidewire recommends configuring subtype fields so that they can be populated only when the object is of that subtype. This prevents invalid data from being added to the database.

The syntax for specifying these behaviors on subtype fields is as follows:

"definitions": {
  "<supertype>": {
    "properties": {
      "<subtypeFieldName>": {
        "x-gw-nullable": true,
        "x-gw-extensions": {
          "entitySubtype": "<subtypeThatOwnsThisField>"
        }
      },

In the mapping file, the mapper for a subtype field must cast the supertype entity as the specific subtype entity. It must also include a predicate attribute that specifies the correct subtype.

The syntax for specifying these behaviors is as follows:

"mappers": {
  "<supertype>": {
    "properties": {
      "<subtypeFieldName>": {
        "path": "(<Supertype> as <Subtype>).<subtypeFieldName>",
        "predicate": "<Supertype> typeis <Subtype>"
      },

In the updater file, the updater for a subtype field must cast the supertype entity as the specific subtype entity.

The syntax for specifying these behaviors is as follows:

"updaters": {
  "<supertype>": {
    "properties": {
      "<subtypeFieldName>": {
        "path": "(<Supertype> as <Subtype>).<subtypeFieldName>"
      },

Shared handling example

For example, suppose there is an Interaction_Ext entity that captures information about an interaction (a phone call, email, or in-person conversation) that the insurer has with someone else. The Interaction_Ext entity has two subtypes: InteractionWithInsured_Ext and InteractionWithVendor_Ext.

  • The Interaction_Ext supertype has an InteractionDate datetime field.
  • InteractionWithInsured_Ext has an isComplaint Boolean field.
  • InteractionWithVendor_Ext has an isBillable Boolean field.

The REST endpoint generator creates CRUD endpoints for the Interaction_Ext entity as root resource endpoints using shared subtype handling.

The following endpoints are generated:

  • GET /interaction-ext
  • POST /interaction-ext
  • GET /interaction-ext/{interactionExtId}
  • PATCH /interaction-ext/{interactionExtId}
  • DELETE /interaction-ext/{interactionExtId}

After configuration, the schema definition for Interaction_Ext would include the following:

"definitions": {
  "Interaction_Ext": {
    "properties": {
      "id": {
        "title": "ID",
        "description": "The unique identifier of this element",
        "type": "string",
        "readOnly": true
      },
      "subtype": {
        "title": "Subtype",
        "description": "The specific type of...",
        "type": "string",
        "x-gw-type": "typekey.Interaction_Ext",
        "x-gw-extensions": {
          "createOnly": true,
          "filterable": true,
          "requiredForCreate": true,
          "sortable": true
        }
      },
      "interactionDate": {
        "type": "string",
        "format": "date-time"
      },
      "isComplaint": {
        "type": "boolean",
        "x-gw-nullable": true,
        "x-gw-extensions": {
          "entitySubtype": "InteractionWithInsured_Ext"
        }
      },
      "isBillable": {
        "type": "boolean",
        "x-gw-nullable": true,
        "x-gw-extensions": {
          "entitySubtype": "InteractionWithVendor_Ext"
        }
      },
      ...

After configuration, the mapping definition for Interaction_Ext would include the following:

"mappers": {
  "Interaction_Ext": {
    "properties": {
      "id": {
        "path": "Interaction_Ext.RestId"
      },
      "subtype": {
        "path": "Interaction_Ext.Subtype"
      },
      "interactionDate": {
        "path": "Interaction_Ext.InteractionDate"
      },
      "isComplaint": {
        "path": "(Interaction_Ext as InteractionWithInsured_Ext).IsComplaint",
        "predicate": "Interaction_Ext typeis InteractionWithInsured_Ext"
        }
      },
      "isBillable": {
        "path": "(Interaction_Ext as InteractionWithVendor_Ext).IsBillable",
        "predicate": "Interaction_Ext typeis InteractionWithVendor_Ext"
        }
      },
      ...

After configuration, the updater definition for Interaction_Ext would include the following:

"updaters": {
  "Interaction_Ext": {
    "properties": {
      "subtype": {
        "path": "Interaction_Ext.Subtype"
      },
      "interactionDate": {
        "path": "Interaction_Ext.InteractionDate"
      },
      "isComplaint": {
        "path": "(Interaction_Ext as InteractionWithInsured_Ext).IsComplaint"
        }
      },
      "isBillable": {
        "path": "(Interaction_Ext as InteractionWithVendor_Ext).IsBillable"
        }
      },
      ...

Separate handling

Separate handling is designed for situations where there is so much information at the subtype level that you want to manage each subtype as a distinct entity.

In this approach, you must run the REST endpoint generator for the supertype and each subtype. This means that you will have a resource and set of CRUD endpoints for the supertype and an additional resource and set of CRUD endpoints for each subtype. It also means that the supertype endpoints can be used to interact with objects declared at the supertype level, and only objects declared at the supertype level. The supertype endpoints will not interact with objects declared at the subtype level.

When you run the REST endpoint generator for the supertype and choose separate handling, there is no subtype field automatically added to the resource.

Data mapping requirements

With separate handling, each entity in the data model is treated as a distinct entity. Therefore, there are no special requirements around how to specify schema definitions and mappers.

Keep in mind that if there are any supertype fields that you want to have access to when using the subtype endpoints, you must configure these fields in each subtype resource.

Separate handling example

For example, suppose there is an Interaction_Ext entity that captures information about an interaction (a phone call, email, or in-person conversation) that the insurer has with someone else. The Interaction_Ext entity has two subtypes: InteractionWithInsured_Ext and InteractionWithVendor_Ext.

  • The Interaction_Ext supertype has an InteractionDate datetime field.
  • InteractionWithInsured_Ext has an isComplaint Boolean field.
  • InteractionWithVendor_Ext has an isBillable Boolean field.

The REST endpoint generator creates the following. In each case, the custom entity is the root resource for the endpoint:

  • CRUD endpoints for the Interaction_Ext entity using separate subtype handling.
  • CRUD endpoints for the InteractionWithInsured_Ext entity
  • CRUD endpoints for the InteractionWithVendor_Ext entity

The following endpoints are generated:

  • Endpoints for working with Interaction_Ext entities
    • GET /interaction-ext
    • POST /interaction-ext
    • GET /interaction-ext/{interactionExtId}
    • PATCH /interaction-ext/{interactionExtId}
    • DELETE /interaction-ext/{interactionExtId}
  • Endpoints for working with InteractionWithInsured_Ext entities
    • GET /interaction-with-insured-ext
    • POST /interaction-with-insured-ext
    • GET /interaction-with-insured-ext/{interactionWithInsuredExtId}
    • PATCH /interaction-with-insured-ext/{interactionWithInsuredExtId}
    • DELETE /interaction-with-insured-ext/{interactionWithInsuredExtId}
  • Endpoints for working with InteractionWithVendor_Ext entities
    • GET /interaction-with-vendor-ext
    • POST /interaction-with-vendor-ext
    • GET /interaction-with-vendor-ext/{interactionWithVendorExtId}
    • PATCH /interaction-with-vendor-ext/{interactionWithVendorExtId}
    • DELETE /interaction-with-vendor-ext/{interactionWithVendorExtId}

Schema definitions

After configuration, the schema definition for Interaction_Ext would include the following:

"definitions": {
  "Interaction_Ext": {
    "properties": {
      "id": {
        "title": "ID",
        "description": "The unique identifier of this element",
        "type": "string",
        "readOnly": true
      },
      "interactionDate": {
        "type": "string",
        "format": "date-time"
      },
      ...

The schema definition for InteractionWithInsured_Ext would include the following:

"definitions": {
  "InteractionWithInsured_Ext": {
    "properties": {
      "id": {
        "title": "ID",
        "description": "The unique identifier of this element",
        "type": "string",
        "readOnly": true
      },
      "interactionDate": {
        "type": "string",
        "format": "date-time"
      },
      "isComplaint": {
        "type": "boolean",
      },
      ...

The schema definition for InteractionWithVendor_Ext would include the following:

"definitions": {
  "InteractionWithVendor_Ext": {
    "properties": {
      "id": {
        "title": "ID",
        "description": "The unique identifier of this element",
        "type": "string",
        "readOnly": true
      },
      "interactionDate": {
        "type": "string",
        "format": "date-time"
      },
      "isBillable": {
        "type": "boolean",
      },
      ...

Mapping definitions

After configuration, the mapping definition for Interaction_Ext would include the following:

"mappers": {
  "Interaction_Ext": {
    "properties": {
      "id": {
        "path": "Interaction_Ext.RestId",
      },
      "interactionDate": {
        "path": "Interaction_Ext.InteractionDate",
      },
      ...

The mapping definition for InteractionWithInsured_Ext would include the following:

"mappers": {
  "InteractionWithInsured_Ext": {
    "properties": {
      "id": {
        "path": "InteractionWithInsured_Ext.RestId"
      },
      "interactionDate": {
        "path": "InteractionWithInsured_Ext.InteractionDate"
      },
      "isComplaint": {
        "path": "InteractionWithInsured_Ext.IsComplaint"
        }
      },
      ...

The mapping definition for InteractionWithVendor_Ext would include the following:

"mappers": {
  "InteractionWithVendor_Ext": {
    "properties": {
      "id": {
        "path": "InteractionWithVendor_Ext.RestId"
      },
      "interactionDate": {
        "path": "InteractionWithVendor_Ext.InteractionDate",
      },
      "isBillable": {
        "path": "InteractionWithVendor_Ext.IsBillable"
        }
      },
      ...

Updater definitions

After configuration, the updater definition for Interaction_Ext would include the following:

"updaters": {
  "Interaction_Ext": {
    "properties": {
      "interactionDate": {
        "path": "Interaction_Ext.InteractionDate",
      },
      ...

The updater definition for InteractionWithInsured_Ext would include the following:

"updaters": {
  "InteractionWithInsured_Ext": {
    "properties": {
      "interactionDate": {
        "path": "InteractionWithInsured_Ext.InteractionDate"
      },
      "isComplaint": {
        "path": "InteractionWithInsured_Ext.IsComplaint"
        }
      },
      ...

The updater definition for InteractionWithVendor_Ext would include the following:

"updaters": {
  "InteractionWithVendor_Ext": {
    "properties": {
      "interactionDate": {
        "path": "InteractionWithVendor_Ext.InteractionDate",
      },
      "isBillable": {
        "path": "InteractionWithVendor_Ext.IsBillable"
        }
      },
      ...