Entity best practices

Entity declarations have three names: a metadata definition file name, an entity attribute name, and a displayName attribute name. Generally, entity declaration names begin with a capital letter. Medial capitals separate words in compound entity names.

Entity declaration names differ with respect to allowing a space to separate words in compound entity names and with respect to requiring a suffix. displayName attribute names permit spaces to separate words. Metadata definition file names and entity attribute names do not. Unlike the other entity declaration names, metadata definition file names require a three letter suffix. These suffixes include .eti, .eix, and .etx.

Metadata definition file names and entity attribute names are required programmatic names. They are for use in the Gosu programming language. These names prohibit spaces altogether. In addition, the base of a metadata definition file name must match the value of the corresponding entity attribute name.

While displayName attribute names are optional, Guidewire recommends that you use such names when two conditions are true. If you create a custom entity and the programmatic entity declaration name for the entity exceeds one word, use a displayName attribute name. For example, an entity with an entity attribute name of Activity does not require a displayName attribute name. However, consider a displayName attribute name when you have an entity attribute name such as ContactAddress or AllEscalatedActivitiesClaimMetric. In these cases, use Contact Address and All Escalated Activities Claim Metric as respective displayName attribute names. The graphical user interface uses the displayName attribute name when displaying the corresponding entity.

In future releases, Guidewire may add or change base entities. If you make your own changes to entities, there is the possibility of a naming conflict with one of these future updates. For example, you may add new entities, or new properties to existing entities. To avoid possible naming conflicts, Guidewire recommends that you append the suffix _Ext to your new entities and properties.

If you add a new entity, add _Ext to the endings of entity names so that Guidewire Studio and the Data Dictionary list them next to any entities that they extend. For example, CreditHistory_Ext. The property names in your new entity do not need the suffix _Ext because the name of the entity already has the _Ext suffix.

If you add new properties to an existing Guidewire entity, add the _Ext suffix to their names. Follow this recommendation for properties, and also for virtual properties and functions added through entity enhancements.

<extension entityName="Policy">
 ...
  <column desc="Description of the column"
    name="MyCustomColumn_Ext" 
    nullok="true"
    default="abc"
    type="varchar"
    <columnParam
      name="size"
      value="60" />
  </column>

  <typekey desc="Description of the typekey"
        name="MyCustomTypekey_Ext" 
        typelist="myCustomTypeList_Ext)" 
        nullok="true" />
 ...
</extension>

Guidewire recommends that you name most fields with a singular word such as Phone or Age. However, because array fields reference a list of objects, Guidewire recommends that you name them with a plural word.

For example, Policy.CurrentRoleAssignment and Policy.CorePolicyNumber are single fields on a Policy entity, but Policy.RiskNotes is an array of multiple notes. Also, for arrays fields that are extensions, make the primary name plural and not the Ext prefix or suffix. For example, use Ext_MedTreatments or MedTreatments_Ext, and not MedTreatment_Exts.

Guidewire recommends that you add ID as a suffix to the column names of foreign keys. By default, the column name of foreign keys have the same name as the foreign key names. Use the columnName attribute of foreignkey elements to override their default column names. For example:

<foreignkey 
    columnName="PolicyID" 
    ... 
    name="Policy"/> 

Adding the suffix ID to the column names of foreign keys helps database administrators identify columns in the database that Guidewire uses as foreign keys.

If you add a foreign key as an extension to a base entity, follow the best practice of adding a prefix or suffix to the name. For example:

<foreignkey 
    columnName="Policy_ExtID" 
    ... 
    name="Policy_Ext"/>