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"
}
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 acode
and aname
)MonetaryAmount
andCurrencyAmount
(containing acurrency
and anamount
)SpatialPoint
(containing alongitude
coordinate and alatitude
coordinate)
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
- In Postman, start a new request by clicking the + to the right of the
Launchpad tab.
- On the Authorization tab, select Basic Auth using user su and password gw.
- Enter the following call, but do not click Send yet:
- POST http://localhost:8080/cc/rest/admin/v1/users
- Specify the request payload.
- In the first row of tabs (the one that starts with Params), click Body.
- In the row of radio buttons, select raw.
- At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
- Paste the following into the text field underneath the radio buttons.
{ "data": { "attributes": { "username": "configTestUser", "departmentName": "schema config tester", "experienceLevel" : { "code" : "mid" } } } }
- 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.