Integration graphs

An integration graph is a special base configuration schema and mapper that is used by certain base configuration outbound integrations to send information about a parent object and its children objects. Integration graphs are not used by Cloud API, but the files that define them are a part of Cloud API.

As of this release, Cloud API has the following integration graphs:

  • The ClaimCenter claim_graph, whose parent is Claim
  • The PolicyCenter policyperiod_graph, whose parent is PolicyPeriod
  • The ContactManager contact_graph, whose parent is Contact

There are several outbound integrations that make use of integration graphs. Depending on the InsuranceSuite application, this may include:

  • Guidewire App Events
  • Cloud Rules
  • Analytics and Data Services (ADS)

Guidewire recommends against insurers configuring integration graphs directly. However, when you generate endpoints for a custom entity, you can also add the custom resource to an integration graph if the resource has a parent resource and that parent resource belongs to the integration graph. To add the custom resource to the graph, answer the final prompt ("Should <CustomEntity> be added to an integration graph?") with "y". There may be an additional prompt asking for the name of the graph.

  • If the entity is effective-dated, the information is added to the policy period graph.
  • If the entity is not effective-dated, an additional prompt asks for the name of the graph to add the entity to.

When a custom entity is added to an integration graph, the REST endpoint generator modifies the following files:

  • The <graphName>_graph_ext-1.0.schema.json file
  • The <graphName>_graph_ext-1.0.mapping.json file
  • The shared_ext-1.0.apiconfig.yaml file

You do not need to configure the graph schema file. But, configurations are required in the graph mapper file and the apiconfig.yaml file.

The graph schema file

The graph schema file defines the structure of the integration graph. When you specify that you want to add a custom resource to a given graph, the REST endpoint generator adds code to the corresponding <graphName>_graph_ext-1.0.schema.json file.

For example, suppose you generated endpoints for the CustomEntity_Ext data model entity and added the corresponding resource to the PolicyPeriod graph. The policyperiod_graph_ext-1.0.schema.json file has the following code added (shown in bold): 

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "x-gw-combine": [
    "ext.account.v1.account_ext-1.0",
    "ext.common.v1.common_ext-1.0",
    "ext.policyperiod.v1.policyperiod_ext-1.0",
    "gw.content.pc.policyperiod.v1.policyperiod_graph_content-1.0"
  ],
  "definitions": { 
    "PolicyPeriod": { 
      "properties": { 
        "customEntitiesExt": { 
          "title": "Custom entities ext", 
          "description": "The collection of custom entities ext on this policy period", 
          "type": "array", 
          "items": { 
            "$ref": "#/definitions/CustomEntityExt" 
          } 
        } 
      } 
    } 
  } 
}

Typically, the graph schema file does not require configuration.

The graph mapper file

The graph mapper file defines how information is written to the properties in an integration graph. When you specify that you want to add a custom resource to a given graph, the REST endpoint generator adds code to the corresponding <graphName>_graph_ext-1.0.mapping.json file.

For example, suppose you generated endpoints for the CustomEntity_Ext data model entity and added the corresponding resource to the PolicyPeriod graph. The policyperiod_graph_ext-1.0.mapping.json file has the following code added (shown in bold): 

{ 
  "schemaName": "ext.policyperiod.v1.policyperiod_graph_ext-1.0",
  "combine": [
    "ext.account.v1.account_ext-1.0",
    "ext.policyperiod.v1.policyperiod_ext-1.0",
    "gw.content.pc.policyperiod.v1.policyperiod_graph_content-1.0"
  ],
  "mappers": { 
    "PolicyPeriod": { 
      "schemaDefinition": "PolicyPeriod", 
      "root": "entity.PolicyPeriod", 
      "properties": { 
        "customEntitiesExt": { 
          "path": "TODO RestEndpointGenerator provide a collection  
                   of CustomEntities_Ext", 
          "mapper": "#/mappers/CustomEntityExt" 
        } 
      } 
    } 
  } 
}

You must configure the file by specifying the path for custom entity collection properties. This is typically set to the corresponding array on the parent data model entity.

Following on from the previous example, the path attribute in policyperiod_graph_ext-1.0.mapping.json file would need to be set as follows: 

{ 
  "schemaName": "ext.policyperiod.v1.policyperiod_graph_ext-1.0",
  "combine": [
    "ext.account.v1.account_ext-1.0",
    "ext.policyperiod.v1.policyperiod_ext-1.0",
    "gw.content.pc.policyperiod.v1.policyperiod_graph_content-1.0"
  ], 
  "mappers": { 
    "PolicyPeriod": { 
      "schemaDefinition": "PolicyPeriod", 
      "root": "entity.PolicyPeriod", 
      "properties": { 
        "customEntitiesExt": { 
          "path": "PolicyPeriod.CustomEntities_Ext", 
          "mapper": "#/mappers/CustomEntityExt" 
        } 
      } 
    } 
  } 
}

Mapping in the apiconfig file

The shared_ext-1.0.apiconfig.yaml maps shared element resource and collection resources to Gosu Resource files. It also specifies URI mappings for integration graphs. When you specify that you want to add a custom resource to a graph, the REST endpoint generator adds code to the corresponding shared_ext-1.0.apiconfig.yaml file.

For example, suppose you generated endpoints for the CustomEntity_Ext data model entity and added the corresponding resource to the PolicyPeriod graph. The shared_ext-1.0.apiconfig.yaml file has the following code added (shown in bold):

entityURIMappings:
 CustomEntity_Ext:
    uri: "${parentUri}/custom-entities-ext/${CustomEntity_Ext.RestId}"
    parent: "TODO RestEndpointGenerator link to the parent of CustomEntity_Ext"

You must configure the file by specifying the parent for custom entities. This is typically set to the corresponding foreign key on the custom data model entity.

Following on from the previous example, the path attribute in the shared_ext-1.0.apiconfig.yaml file would need to be set as follows:

entityURIMappings:
  CustomEntity_Ext:
    uri: "${parentUri}/custom-entities-ext/${CustomEntity_Ext.RestId}"
    parent: "CustomEntity_Ext.PolicyPeriod"

Marking graph properties as eventSafe

The REST endpoint generator also checks if the root entity for the endpoint generates events. If it does, it sets the eventSafe property on the graph mapping property appropriately.