Adding scalars

A scalar is a single simple value, such as a string, number, datetime, or Boolean. Use the schema, mapping, and updater extension files to add a scalar property to a resource.

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
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 have a type
  • Some types of properties also require a format

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 do the following:

  • Expose the existing JobTitle field so that it is writeable
  • Expose the existing ExternalUser field, but have it be read-only
  • Expose an extension field named HireDate_Ext so that it is writeable
To do this, 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
      },
      "hireDate_Ext": {
        "title": "hireDate_Ext",
        "description": "The user's hire date",
        "type": "string",
        "format": "date"
    }
  }
}

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.

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. If you wanted to expose them, you would first add them to the schema. Then, you would add the following to the admin_ext-1.0.mapping.json extension file.
  "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"
        }
      }
    }
  }