<entity> elements and related data object types

The <entity> XML root element defines many—if not most—of the PolicyCenter entities.

Attributes of <entity>

The <entity> element contains the following attributes.

<entity>  attribute                   

Description

Default

abstract

If true, you cannot an create instance of the entity type at run time. Instead, you must declare a subtype entity with abstract=false, which you can instantiate. Any of the generated code is abstract.

false

admin

Determines whether you can reference the entity from staging tables:

  • Entity X has admin="true". Suppose that you have another, loadable table Y that has a foreign key to X. Then at the time you load the staging table for Y, you can load public IDs that specify entities of type X that are already in the main tables.
  • Entity X has admin="false". Any Y that you load into a staging table must specify an X that is being loaded into the staging table for X at the same time.

This is important because it allows the staging table loader to do less checking at load time. For example:

  • If admin="false", then the staging table loader merely has to check that all public IDs in ccst_y specify valid entries in ccst_x.
  • If admin="true", then the staging table loader has to check that all public IDs in ccst_y specify a valid entry in ccst_x. It must also check that all public IDs in ccst_y specify a valid entry in cc_x, the main table.

false

autoSplit

Use with effDated entities, whether PolicyCenter auto-splits the entity on a slice edit.

true

cacheable

Internal. If set to false, then Guidewire prohibits entities of this type and all its subtypes from existing in the global cache.

true

consistentChildren

Internal. If set to true, then PolicyCenter generates a consistency check and a loader validation that tries to ensure that links between child entities of this entity are consistent. Guidewire enforces the constraint only while loading data from staging tables. You can detect violations of the constraint on data committed to entity tables after the fact by running a consistency check.

IMPORTANT Guidewire does not enforce consistentChildren constraints at bundle commit.

false

desc

A description of the purpose and use of the entity.

None

displayName

Optional. Creates a more human-readable form of the entity name. You can access this name using the following:

  entity.DisplayName

If you do not specify a value for the DisplayName attribute, then the entity.DisplayName method returns the value of the entity attribute, instead. If you subtype an entity that has a specified display name, then the entity.DisplayName method returns the name of the subtype key.

None

edgeTable

For the purposes of archiving, whether the entity has the semantics of an edge table.

false

effDatedBranchType

Relevant only for entities of type effDated. This value defines the type of the root of the tree in which the effDated entity exists. The only allowed value is PolicyPeriod.

None

effDatedBranchesField

Internal. Relevant only for Policy entities. This value defines the field that refers to the branches of this container.

None

effDatedContainerField

Internal. Relevant only for PolicyPeriod entities. This value defines the field that refers to the container of this branch.

None

effDatedRegistryTableName

Internal. Relevant only for Policy entities. This value defines the name of the table that stores the effdated table registry for this container entity.

None

entity

Required. The name of the entity. You use this name to access the entity in data views, rules, and other areas within PolicyCenter.

This attribute has no maximum or minimum length in and of itself. However, if the final attribute is set to false, the entity has an associated typelist containing as typecodes the names of the entity subtypes. These typecodes have a maximum length of 50 characters. Hence, the entity attribute for all non-final entities has an implicit maximum length of 50.

None

exportable

Unused.

extendable

Internal. If true, it is possible to extend this entity.

true

final

If true, you cannot subtype the entity. If false, you can define subtypes using this entity as the supertype.

IMPORTANT If you define this incorrectly, PolicyCenter generates an error message upon resource verification and the application server refuses to start. PolicyCenter generates this verification error:

  • If you attempt to subtype an entity that is marked as final that exists in the metadata folder in Guidewire Studio™.
  • If you attempt to subtype an entity that is marked as final that exists in the extensions folder in Studio.

true

generateInternallyIfAbsent

Internal. Do not use.

false

ignoreForEvents

The ignoreForEvents attribute indicates whether other entities pass over the instant entity when determining the origin of an event. If the value of ignoreForEvents is true, PolicyCenter ignores the entity in this context.

If the <events> element is not present in an entity, that entity does not generate events. Moreover, that entity does not generate events when you create, modify, or delete it. Thus, it makes no sense for PolicyCenter to examine either that entity or entities that reference it when the product searches for the source of an event.

Nonetheless, even if an entity generates no events, whenever you modify it, PolicyCenter still examines that entity and all entity instances that reference it. The scope of this examination encompasses the non-event-generating entity as well as arrays, foreign keys, and edge foreign keys that reference it. If PolicyCenter finds an entity instance that both generates events and references the modified, non-event-generating entity, the product generates a Changed event for that entity instance. This examination and event generation process results in unnecessary and long chain queries.

Guidewire offers two solutions to the resultant performance challenge. You can avoid the examination and event generation altogether if you set the ignoreForEvents attribute to true on the non-event-generating entity. In this case, PolicyCenter ignores the non-event-generating entity as well as references to it when an event occurs.

As an alternative, you can avoid the examination and event generation in some cases while allowing the process in others. To effect this selective avoidance, set the ignoreForEvents attribute to true not on the non-event-generating entity. Rather, set it to true only on event-generating entity instances both that reference the entity and that you want PolicyCenter to ignore. Such referencing entity instances might be arrays, foreign keys, or edge foreign keys.

In this case, when you modify the non-event-generating entity, PolicyCenter does not ignore the entity altogether. When you modify the entity, event-generating entity instances that reference the entity and on which the ignoreForEvents attribute is false still generate events. Instead, PolicyCenter ignores only the referencing entity instance on which you set the ignoreForEvents attribute to true.

Thus, if you want no events triggered at all when you modify a non-event-generating entity, set the ignoreForEvents attribute on that entity to true. If you want some events avoided and some triggered, take this step only on event-generating entities that reference the non-event-generating entity and that you want to ignore.
Important: With the ignoreForEvents attribute, PolicyCenter rules out specific entities or activities for event generation. The attribute eliminates events where they are not needed. Hence, the attribute results in improved performance. Set the ignoreForEvents attribute to true as appropriate to ensure optimal performance. This performance improvement is especially important for any entity shared among graph entities, such as Claim, Policy, or Account.

false

instrumentationTable

Internal.

false

loadable

If true, you can load the entity through staging tables.

true

lockable

Internal. If set to true, PolicyCenter adds a lock column (lockingcolumn) to the table for this entity. PolicyCenter uses this to acquire an update lock on a row. The most common use is on objects in which it is important to implement safe ordering of messages. In that case, the entity that imposes the safe ordering needs to be lockable.

IMPORTANT Guidewire strongly recommends that you do not use this locking mechanism.

false

overwrittenInStagingTable

Internal. If true and the entity is loadable, the loader process auto-populates the staging table during import.

IMPORTANT If set to true, do not attempt to populate the table yourself, because the loader import process overwrites this table.

false

platform

Internal. Do not use. The only real effect is to change the location in which the table appears in a data distribution report.

false

priority

The priority of the corresponding subtype key. This value is meaningful only for entities participating in a subtype hierarchy, which can be either the <subtype> entities or the root <entity>.

-1

readOnly

Optional. The typical use of read-only entities is for tables of reference data that you import as administrative data and then never touch again.

You can add a read-only entity only to a bundle that has the allowReadOnlyBeanChanges() flag set on its commit options. That means that inserting, modifying or deleting a read-only entity requires one of these special bundles.

You cannot set bundle commit options from Gosu. Therefore, you cannot modify these entities from Gosu, unless some Gosu-accessible interface gives you a special bundle. The administrative XML import tools use such a special bundle. However, Guidewire uses these tools internally only in the PolicyCenter product model.

None

setterScriptability

See Data objects and scriptability.

None

subpackage

Subpackage to which the class corresponding to this entity belongs.

None

table

Required. The name of the database table in which PolicyCenter stores the data for this entity. PolicyCenter automatically prefixes table names with pc_ for base entities and pcx_ for extension entities.

Guidewire recommends the following table naming conventions:

  • Do not begin the table name with any product-specific extension.
  • Use only unaccented, lowercase Roman letters and the underscore character.
  • Prefix the table name with test_ if you use the table solely for testing.
  • Because PolicyCenter automatically prefixes extension table names with pcx_, if you run into limits on the length of the table name, you can consider removing the _Ext suffix from the table name.

The table name has no minimum allowable length so long as the name is not an empty string. Guidewire enforces the following restrictions on the maximum allowable length of the table name:

  • loadable="true" — maximum of 25 characters
  • loadable="false" — maximum of 26 characters

None

temporary

Internal. If true, then this table is a temporary table that PolicyCenter uses only during installation or upgrade.

PolicyCenter deletes all temporary tables after it completes the installation or the upgrade.

false

type

Required. See Overview of data entities for a discussion of data entity types.

None

typelistTableName

The typelist that PolicyCenter generates when you create a non-final entity has an associated database table. If you do not specify a value for the typelistTableName attribute, then PolicyCenter uses the name of the entity as the table name for the subtype typelist.

However, PolicyCenter places a restriction of 25 characters on the length of the database table name. You use the typelistTableName attribute to specify the database table name for the typelist if an entity name is too long to become a valid typelist table name.

It is not valid to use this attribute with entity types marked as final.

None

validateOnCommit

Internal. Do not use. If true, PolicyCenter validates this entity during a commit of a bundle that contains this entity.

true
Important: Do not modify internal entity attributes. This instruction applies even in the case of custom entities.
Important:

If you create a non-final <entity> element, then PolicyCenter automatically creates a typelist with the same name as the resulting entity. The typelist allows you to keep track of the subtypes of that entity. PolicyCenter creates this typelist whether or not a <subtype> element exists that refers to the non-final <entity> element.

Suppose that you change a final <entity> element to a non-final <entity> element. Suppose further that you already have a typelist with the same name as the resulting entity. In this case, you must change the name of the preexisting typelist beforehand. Otherwise, the automatic typelist generation cannot proceed, and you will receive an error.

Subelements of <entity>

The <entity> element contains the following subelements.

<entity>  subelement             

Description

array

See <array>.

checkconstraint

Internal.

column

See <column>.

customconsistencycheck

Internal.

datetimeordering

Internal.

dbcheckbuilder

Internal.

edgeForeignKey

See <edgeForeignKey>.

events

Indicates that the entity raises events and that the entity is aware of events. See <events>.

foreignkey

See <foreignkey>.

fulldescription

See <fulldescription>.

implementsEntity

See <implementsEntity>.

implementsInterface

See <implementsInterface>.

index

See <index>.

jointableconsistencycheck

Internal.

monetaryamount

Handles monetary amounts. The <monetaryamount> subelement is a compound data type that stores its values in two separate database columns: a <money> column type, and a typekey to the Currency typelist.

onetoone

See <onetoone>.

remove-index

See <remove-index>.

searchColumn

See <entity> elements and related data object types

searchTypekey

Defines a search denormalization typekey in the database. The denormalization copies the value of a column on another table into a typekey field on the denormalizing table. You must link the tables through a foreign key. The purpose of this denormalization is to avoid costly joins in performance critical searches.

tableAugmenter

Internal.

typekey

See <typekey>.

validatetypekeyinset

Internal.

validatetypekeynotinset

Internal.
Important: Do not modify internal entity subelements even in the case of custom entities.

The <searchColumn> subelement

The <searchColumn> subelement on <entity> defines a search denormalization column in the database. The denormalization copies the value of a column on another table into a column on the denormalizing table. You must link the tables through a foreign key. The purpose of this denormalization is to avoid costly joins in performance-critical searches.

The use of search denormalization columns adds overhead to updates, as does any denormalization. Guidewire recommends that you only use these columns if there is an identifiable performance problem with a search that is directly related to the join between the two tables.

Note: It is possible to have a <searchColumn> sublement on the <extension> and <subtype> elements as well.

The <searchColumn> element contains the following attributes.

<searchColumn>  attribute  

Description

Default

columnName

Name to use for the database column corresponding to this property. If you do not specify a value, then PolicyCenter uses the name value instead.

The columnName attribute must be no more than 30 characters in length. It allows only unaccented Roman letters, numbers, and the underscore character. The first character of the columnName attribute must be a letter. Although the underscore character is allowable here, Guidewire discourages its use.

None

deprecated

If true, then PolicyCenter marks the item as deprecated in the Data Dictionary and places a Deprecated annotation on it in the Guidewire Studio API Reference.

If you deprecate an item, use the description to explain why.

For more information, see Data entity subelements.

false

desc

Description of the intended purpose of this column.

None

name

Required. Name of the column on the table and the field on the entity. The name value maps to the accessor and mutator methods of a field on the entity, not the actual private member field. For example, name maps to setName and getName, not the private _name member field.

Column names must contain letters only. A column name cannot contain an underscore.

None

sourceColumn

Required. Name of the column on the source entity, whose value this column copies. The sourceColumn must not name a localized column.

None

sourceForeignKey

Required. Name of a foreign key field on this entity, which refers to the source entity for this search denormalization column. The sourceForeignKey must not be importable against existing objects.

None

sourceSubtype

Optional name of the particular subtype on which the source column is defined. If not specified, then PolicyCenter assumes that the source column to exist on the entity referred to by the source object. However, you must specify this value if the sourceColumn is on a subtype of the entity referred to by sourceForeignKey.

None

For example, suppose that you set the following attribute definitions:

  • searchColumn – MyDenormColumn
  • sourceForeignKey – Source
  • sourceColumn – SourceField

This declaration says:

Copy the value of SourceField on the object pointed to by the foreign key named Source into the field named MyDenormColumn. PolicyCenter automatically populates the column as part of bundle commit, staging table load, and database upgrade.

If you need to denormalize a field on a subtype of the entity referred to by the foreign key, then you can specify the optional sourceSubtype attribute.

As with linguistic denormalization columns, you cannot access the value of these search denormalization columns in memory. The value is only available in the database. Thus, you can only access the value through a database query.

It is possible to make a query against a search denormalization column that is a denormalization of a linguistic denormalization column. In that case, the query generator knows not to wrap the column values in the linguistic denormalization function. This preserves the optimization that linguistic denormalization columns provide.

It is important to understand that search denormalization columns specify one column only — the column that you specify with the sourceColumn attribute. So, if you want to denormalize both a column and its linguistic denormalization, then you need two separate search denormalization columns. However, in this case, you typically would just want to denormalize the linguistic denormalization column. You would only want to denormalize the source column if you wanted to support case-sensitive searches on it.

Search denormalization columns can only specify <column> or <typekey> fields.