Adding scalars

Extension files

Every API in Cloud API has a set of three extension files that are used to extend resources used by the endpoints in that API. This includes:

A schema extension file, where you can define new properties for a resource
A mapper extension file, where you can define how data from the database is used to populate extension fields
An updater extension file, where you can define how data from extension fields is written to the database

The names of the extension files are defined in the table below. Note that the file name always starts with the API name. For example, the schema extension file for the Common API is common_ext-1.0.schema.json.

Filename	Guidewire Studio node
`<API>_ext-1.0.schema.json`	integration -> schemas -> ext -> <API>.v1
`<API>_ext-1.0.mapping.json`	integration -> mappers -> ext -> <API>.v1
`<API>_ext-1.0.updater.json`	integration -> updaters -> ext -> <API>.v1

Scalars

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

To add a scalar property to a resource, you must modify the schema, mapping, and updater file for the API that contains the endpoints that use the schema. For example, suppose you want to add an extension property for the User schema. This schema is used by endpoints in the Common API. Therefore, you need to modify the following files:

common_ext-1.0.schema.json
common_ext-1.0.mapping.json
common_ext-1.0.updater.json

Note: See also Tutorial: Schema configuration with scalars

The schema extension file

Each schema extension file for every API contains a definitions section. In the base configuration, this section is typically blank, as shown below.

  "definitions": { }

You can add the name of one or more schemas to the definitions section. In each schema, you can define a properties section, which lists one or more properties defined for the schema.

If the property is a base configuration property that is not exposed to Cloud API, Guidewire recommends naming the schema property with an "_Ext" suffix. This is to prevent any possible future conflicts if Guidewire adds the property to the base configuration in a later release.

For scalar values, each property must also have a type.

For example, in the base configuration data model, the User entity has a JobTitle field (this user's job title) and an ExternalUser field (whether the user works for the insurer or not). The Admin API has /user endpoints, but JobTitle and ExternalUser are not exposed in the Cloud API User resource. Suppose you want to expose them, and you want JobTitle to be writeable and ExternalUser be read-only. You would add the following to the admin_ext-1.0.schema.json extension file.

"definitions": {
  "User": {
    "properties": {
      "jobTitle_Ext" : {
        "title": "jobTitle_Ext",
        "description": "The user's job title",
        "type": "string",
      },
      "externalUser_Ext" : {
        "title": "externalUser_Ext",
        "description": "Whether the user is internal (is an employee of the insurer) or not",
        "type": "boolean",
        "readOnly": true
      }
    }
  }
}

Schema property types (values stored in the database)

The following table identifies the different ways to specify type (and format, if necessary) for the data types supported by the base configuration data model. If a give type has no required or optional format, then the cell in the final column is blank.


Data model column type	Java object type	Schema `type`	Schema `format`
`bit`	`Boolean`	`boolean`
`CurrencyAmount`		(see below)
`dateonly`	`Date`	`string`	`date` (required)
`datetime`	`Date`	`string`	`date-time` (required)
`decimal`	`BigDecimal`	`string`	`gw-bigdecimal` (required)
`integer`	`Integer`	`integer`	`int32` (optional)
`longint`	`Long`	`integer`	`int64` (required)
`longtext`	`String`	`string`
`mediumtext`	`String`	`string`
`MonetaryAmount`		(see below)
`money`	`BigDecimal`	`string`	`gw-bigdecimal` (required)
`percentage`	`Integer`	`integer`	`int32` (optional)
`shorttext`	`String`	`string`
`text`	`String`	`string`
`varchar`	`String`	`string`

CurrencyAmount and MonetaryAmount datatypes

In InsuranceSuite, CurrencyAmount (used in ClaimCenter) and MonetaryAmount (used in PolicyCenter and BillingCenter) are not scalar datatypes. They are the combination of two values: amount and currency. For more information on how to configure schema fields that use these datatypes, see Adding compound datatypes.

Schema property types (dynamically calculated values)

There are some types which are not supported for storage in the database, but they may be returned by entity extensions or other methods. The following table identifies the different ways to specify type (and format, if necessary) for these data types.


Data model column type	Java object type	Schema type	Schema format
n/a	`BigInteger`	`string`	`gw-biginteger` (required)
n/a	`byte[]`	`string`	`byte` (required; this will be treated as the Base64-encoded value)
n/a	`Double`	`number`	You can optionally specify `double` (optional)
n/a	`Float`	`number`	`float` (required)
n/a	`LocalDate`	`string`	`date` (required)
n/a	`LocalTime`	`string`	`time` (required)

Additional properties that are direct children of the property


Attribute	Description	Example
`readOnly`	Boolean identifying if the field as read-only. (The default is `false`.)	`"readOnly": true`
`x-gw-nullable`	Boolean identifying if the field can be explicitly set to null. (The default is `false`.) See Making properties required by the database for more information.	"x-gw-nullable": true
`x-gw-sinceVersion`	String identifying the first version of the API to include the property	"x-gw-sinceVersion": "1.1.0"

For example, suppose the CustomEntity_Ext entity has an ExpirationDate field. The corresponding resource property is read-only, nullable, and was added in version 1.1.0. The property declaration would be:

  "definitions": {
    "CustomEntityExt": {
      "properties": {
        "expirationDate": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "x-gw-nullable": true,
          "x-gw-sinceVersion": "1.1.0"
        },
        ...

Additional properties declared in the x-gw-extension object


Attribute	Description	Example
`createOnly`	Boolean identifying if the field can be specified only when the object is created. (The default is `false`.)	`"createOnly": true`
`filterable`	Boolean identifying if the `filter` query parameter can be used on this field. In other words, collections can be filtered using this property. (The default is `false`.)	`"filterable": true`
`requiredForCreate`	Boolean identifying if the field must be specified when the object is created. (The default is `false`.) See Making properties required by the database for more information.	`"requiredForCreate": true`
`sortable`	Boolean identifying if the `sort` query parameter can be used on this field. In other words, collections can be sorted using this property. (The default is `false`.)	`"sortable": true`

For example, suppose the CustomEntity_Ext entity has an SeverityType field, which is a typekey set to a value in the SeverityType typelist. The corresponding resource property must be specified at create time, cannot be modified after creation, and is both filterable and sortable. The property declaration would be:

  "definitions": {
    "CustomEntityExt": {
      "properties": {
        "severityType": {
          "$ref": "#/definitions/TypeKeyReference",
          "x-gw-extensions": {
          "typelist": "SeverityType",
          "createOnly": true,
          "requiredForCreate": true,
          "filterable": true,
          "sortable": true
        },
        ...

The mapping extension file

Each mapping extension file for every API contains a mappers section. In the base configuration, this section is typically blank, as shown below.

  "mappers": { }

You can add the name of one or more schemas to the mappers section. In each schema, you can define a properties section, which lists one or more properties defined in the schema.

For each property, you must identify how data is mapped from the Guidewire data model to the property. This is done using a path attribute.

  "mappers": {
    "User": {
      "properties": {
        "jobTitle_Ext": {
          "path": "User.JobTitle"
        },
        "externalUser_Ext": {
          "path": "User.ExternalUser"
        }
      }
    }
  }

Mappers for custom entities

If you are adding a custom entity, then in addition to the business properties you wish to expose, the mapper must also contain an "id" property that maps to the data model entity's RestId.

For example, suppose you are defining a mapper for a custom entity named CustomEntityExt with the following business properties: isActive, customDescription, expirationDescription. The mapper would be as follows:

  "mappers": {
    "CustomEntityExt": {
      "properties": {
        "id": {
          "path": "CustomEntity_Ext.RestId"
        },
        "isActive": {
          "path": "CustomEntity_Ext.IsActive"
        },
        "customDescription": {
          "path": "CustomEntity_Ext.CustomDescription"
        },
        "expirationDescription": {
          "path": "CustomEntity_Ext.ExpirationDate"
        }
      }
    }
  }

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 extension file

Each updater extension file for every API contains a updaters section. In the base configuration, this section is typically blank, as shown below.

  "updaters": { }

You can add the name of one or more schemas to the updaters section. In each schema, you can define a properties section, which lists one or more properties defined in the schema.

For each writeable property, you must identify how data is mapped from the property to the Guidewire data model. Similar to the mapping file, this is done using a path attribute. For scalars, it is not unusual for a given property to have the same path value on both the mapping file and the updater file.

For example, in the base configuration data model, the User entity has a JobTitle field and an ExternalUser field. The Admin API has /user endpoints, but JobTitle and ExternalUser are not exposed in the Cloud API User resource. Suppose you want to expose these fields to Cloud API, and you want to make JobTitle writeable and ExternalUser read-only. You would first add these properties to the schema and the mapping file. Then, you would add the JobTitle property to the admin_ext-1.0.updater.json extension file. (ExternalUser is omitted from the updater file because it is read-only.

  "updaters": {
    "User": {
      "properties": {
        "jobTitle_Ext": {
          "path": "User.JobTitle"
        }
      }
    }
  }