Data mapping for new properties

There are different situations where you might need to add a property to a schema. This includes:

  • Adding properties for custom entities that have CRUD endpoints generated by the REST endpoint generator
  • Adding properties for custom fields added to a base configuration entity

Whenever you add a property to a schema, there are two or three files you must modify:

  • In the schema extension file, you must add the property to the schema structure.
  • In the mapping extension file, you must define how data is mapped from the data model to the schema
  • In the updater extension file, you must define how data is mapped from the schema to the data model, if the property is writeable

Every API has a set of extension files. The names of the files are:

  • <API>_ext-1.0.schema.json
  • <API>_ext-1.0.mapping.json
  • <API>_ext-1.0.updater.json

Generally speaking, fields in a data model entity follow one of the behaviors listed in the following table. For each behavior, there is a pattern for how the corresponding property is referenced in the schema definition files.

Field behavior Example Schema file Mapping file Updater file
Field is not exposed to Cloud API Application internal information, such as <entity>.CreateUser Omitted Omitted Omitted
Field is read-only The <entity>.id field Included; declared as readOnly Included Omitted
Field must be set during creation and cannot be changed thereafter Claim.LossDate Included; declared as requiredForCreate, x-gw-nullable: false, and createOnly Included Included
Field must be set during creation, but can be changed later Document.Status Included; declared as requiredForCreate, and x-gw-nullable: false Included Included
Field can be set or omitted during creation, and can later be changed Activity.Description Included Included Included

The requirements and syntax vary based on the datatype of the underlying field in the data model entity.

Naming conventions for properties

In REST APIs, the naming convention for properties is to use mixed case, with the first letter being lowercase. For example, in the base configuration, the User entity has an ExperienceType field, which is not exposed to Cloud API. If you were to expose this field to Cloud API, the corresponding property name would be experienceType.

If the data model entity field is an extension field on a base configuration entity, Guidewire recommends appending an _Ext suffix to the field name. If this field is then exposed to Cloud API, Guidewire recommends retaining the suffix in the property name. For example, suppose an insurer extended the User entity with an OnSickLeave_Ext field. If this field were exposed to Cloud API, the corresponding property would be named onSickLeave_Ext.

The x-gw-extension object

Be aware that some property attributes are declared directly on the property itself. This includes:

  • Standard JSON properties, such as readOnly
  • Guidewire extension properties declared directly off the attribute, such as x-gw-sinceExtensionVersion

Other property attributes are Guidewire extensions declared in an object named x-gw-extension. This includes:

  • filterable
  • sortable
  • requiredForCreate

When configuring properties, be sure to place each attribute in the correct place in the JSON.

Data mapping for scalars

A scalar is a single simple value, such as a string, number, datetime, or Boolean.

The schema file

In the schema file, set the type attribute to one of the JSON schema types from the following table.

Data model datatype Corresponding JSON type Additional required attributes
bit boolean
dateonly string An additional "format" attribute set to "date"
datetime string An additional "format" attribute set to "date-time"
decimal number
integer integer
longint integer
longtext string
mediumtext string
money number
percentage number
shorttext string
text string
varchar string

For example, a CustomEntityExt resource could have the following scalar properties:

  "definitions": {
    "CustomEntityExt": {
      "title": "Custom entity ext",
      "description": "Custom entity ext",
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "isActive": {
          "type": "boolean"
        },
        "customDescription": {
          "type": "string"
        },
        "expirationDate": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }

The mapping file

In the mapping file, you typically set the path attribute to a field from the data model entity. No other attributes are required.

For example, the following maps the CustomEntityExt resource's customDescription property to the CustomEntity_Ext data model entity's CustomDescription field.

  "definitions": {
    "CustomEntityExt": {
      "customDescription": {
        "path": "CustomEntity_Ext.CustomDescription"
      }
Note:

Within the Guidewire data model, every entity has a virtual field named DisplayName. An entity name is a Gosu expression that determines the value for an entity's DisplayName field. For example, the ABPerson entity might have its entity name set to ABPerson.LastName+", "+ABPerson.FirstName, which for a given ABPerson would render as "Newton, Ray". If an entity has no defined entity name, the default behavior is to return the concatenation of every field in the entity.

If you add a property to a schema that maps to an entity's display name, be sure that there is an entity name defined for that entity. If there is not, then the application will return a concatenation of every field in the entity. This could potentially make information available in Cloud API that you do not want exposed through Cloud API.

For more information on entity names, see the Configuration Guide.

The updater file

If the updater file, you typically set the path attribute to the field in the data model entity. No other attributes are required.

For example, the following maps the CustomEntity_Ext data model entity's CustomDescription field to the CustomEntityExt resource's customDescription property.

  "definitions": {
    "CustomEntityExt": {
      "customDescription": {
        "path": "CustomEntity_Ext.CustomDescription"
      }

Data mapping for new compound values

InsuranceSuite includes several datatypes where multiple values are stored as a unit. This includes the following:

  • Typekey (containing a code and a name)
  • MonetaryAmount and CurrencyAmount (containing a currency and an amount)
  • SpatialPoint (containing a longitude coordinate and a latitude coordinate)
For example, an activity's assignmentStatus property is a typekey. Thus, the response payload for an activity's assignment status has two sub-fields (code and name):
"assignmentStatus": {
  "code": "assigned",
  "name": "Assigned"
}

The schema file

Unlike scalar properties, compound datatype properties do not use the type attribute. They use a $ref attribute that specifies an existing definition for the datatype. The following table lists the $ref values for the common compound datatypes.

Compound datatype $ref value Additional required attributes
Typekey #/definitions/TypeKeyReference A x-gw-extensions attribute with a typelists child attribute that identifies the relevant typelist.
MonetaryAmount #/definitions/MonetaryAmount
CurrencyAmount #/definitions/CurrencyAmount
SpatialPoint #/definitions/SpatialPoint

For example, the mapping for the Activity data model entity's AssignmentStatus field looks like this:

"assignmentStatus": {
  ... 
  "$ref": "#/definitions/TypeKeyReference",
  "x-gw-extensions": {
    "typelist": "AssignmentStatus"
  }
}

The mapping for the Contact data model entity's SpatialPoint field (which is a spatial point) looks like this:

"spatialPoint": {
  ... 
  "$ref": "#/definitions/SpatialPoint"
}

The mapping file

In the mapping file, you must include both the path attribute and an additional mapper attribute. The mapper attribute specifies the mapper that defines how the compound data type is mapped into its schema. The following table lists the mapper attribute values for the common compound datatypes.

Compound datatype mapper value
Typekey #/mappers/TypeKeyReference
MonetaryAmount #/mappers/MonetaryAmount
CurrencyAmount #/mappers/CurrencyAmount
SpatialPoint #/mappers/SpatialPoint

For example, the mapping for the Activity data model entity's AssignmentStatus field looks like this:

    "assignmentStatus": {
      "path": "Activity.AssignmentStatus",
      "mapper": "#/mappers/TypeKeyReference"
    },

The updater file

In the updater file, if the property is writeable, you must include a valueResolver attribute with a child typeName attribute. This attribute specifies a resolver, which defines how to map the structure for the compound datatype to the data model entity. The updater syntax for compound datatypes is:

"<property>": {
  "path": "<pathValue>",
  "valueResolver": {
    "typeName": "<resolverName>"
  }
}

The following table lists the resolver names for the common compound datatypes.

Compound datatype mapper value
Typekey TypeKeyValueResolver
MonetaryAmount MonetaryAmountValueResolver
CurrencyAmount CurrencyAmountValueResolver
SpatialPoint SpatialPointValueResolver

For example, the updater for the Activity resource's assignmentStatus property looks like this:

    "assignmentStatus": {
      "path": "Activity.AssignmentStatus",
      "valueResolver": {
        "typeName": "TypeKeyValueResolver"
      }
    },

Tutorial: Data mapping for new properties

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

In this tutorial, you will add new properties to the base configuration User schema in the Admin API, and provide mapping and updater information as appropriate. To reduce the number of steps required, this tutorial uses fields that already exist on the User data model entity that are not exposed to Cloud API in the base configuration. The data model entity fields used in this tutorial are:

  • CreateTime (this datetime field will be readable but not writeable)
  • Department (this string field will be readable and writeable)
  • ExperienceLevel (this typekey field will be readable and writeable)

(There is an additional tutorial that covers an example of extending a base configuration entity and then extending the base configuration resource to expose those fields. For more information, see Tutorial: Extending a data model entity and its API resource.)

Tutorial steps

1. In Studio, open the admin_ext-1.0.schema.json file.

2. The file contains the following line of code.

"definitions": { }

Replace that line with the following, which defines three new properties.

"definitions": {
  "User": {
    "properties": {
      "createDate" : {
        "title": "CreateDate",
        "description": "The date on which this user was created",
        "type": "string",
        "format": "date-time",
        "readOnly": true
      },
      "departmentName": {
        "title": "DepartmentName",
        "description": "The name of the department this user works in",
        "type": "string"
      },
      "experienceLevel": {
        "title": "ExperienceLevel",
        "description": "The user's level of experience (high, mid, low)",
        "$ref": "#/definitions/TypeKeyReference",
        "x-gw-extensions": {
          "typelist": "UserExperienceType"
        }
      }
    }
  }
}

There is an additional readOnly property specified for createDate. For more information, see Read-only properties.

At this point, you have defined the structure of the new properties. But there is no information on how data flows into and out of this property.

3. In Studio, open the admin_ext-1.0.mapping.json file.

4. The file contains the following line of code.

"mappers": { }

Replace that line with the following, which defines how data is mapped from the database to the createTime, departmentName, and experienceLevel properties.

"mappers": {
  "User": {
    "properties": {
      "createDate" : {
        "path" : "User.CreateTime"
      },
      "departmentName": {
        "path": "User.Department"
      },
      "experienceLevel": {
        "path": "User.ExperienceLevel",
        "mapper": "#/mappers/TypeKeyReference"
      }
    }
  }
}

You now have three new properties with information on how data flows into each property. If these properties were needed only for GETs (and not POSTs or PATCHes), you could restart ClaimCenter now and test your work.

5. In Studio, open the admin_ext-1.0.updater.json file.

6. The file contains the following line of code.

"updaters": { }

Replace that line with the following, which defines how data is mapped from the database to the departmentName and experienceLevel properties.

"updaters": {
  "User": {
    "properties": {
      "departmentName": {
        "path": "User.Department"
      },
      "experienceLevel": {
        "path": "User.ExperienceLevel",
        "valueResolver": {
          "typeName": "TypeKeyValueResolver"
        }
      }
    }
  }
}

These properties can now be used for GETs, POSTs, and PATCHes. The third property, createDate, has been omitted from the updater file. Therefore, it is read-only and only appears in responses.

7. Start (or restart) ClaimCenter.

Testing your work

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user su and password gw.
  2. Enter the following call, but do not click Send yet:
    1. POST http://localhost:8080/cc/rest/admin/v1/users
  3. Specify the request payload.
    1. In the first row of tabs (the one that starts with Params), click Body.
    2. In the row of radio buttons, select raw.
    3. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
    4. Paste the following into the text field underneath the radio buttons.
      {
        "data": {
          "attributes": {
            "username": "configTestUser",
            "departmentName": "schema config tester",
            "experienceLevel" : {
                "code" : "mid"
            }
          }
        }
      }
    5. Click Send.

Results

The response should be "201 Created". The response body should contain information about the new user, including the create date, department, and experience level. Note that:

  • The structure of these fields (their names and types) comes from the schema file.
  • The create date, department, and experience level in the POST response comes from the mapping file.
  • The setting of the user's department and experience level was accomplished by the updater file.