Define an entity array

About this task

It is often useful to have a field that contains an array of other entities. For example, to represent that a contact can contain multiple address, the Contact entity contains the Contact.ContactAddresses field, which is an array of ContactAddresses entities for each Contact data object.

As you define the entity for the array, consider the type of entity to use. The general rule, is that if another entity does not refer to the new entity through a foreign key, then make the entity versionable. Otherwise, make the entity retireable.

Procedure

  1. Define the entity to use as a member of the array. Although you can use one of the PolicyCenter base entities for an array, it is often likely that you need to define a new entity for this purpose.
  2. Define an array field in the entity that contains the array. You can give the field any name you want. It does not need to be the same name as the array entity.
  3. Define a foreign key in the array entity that references the containing entity. PolicyCenter uses this field to connect an array to a particular data object.

    For more information about

    See

    entity types

    Overview of data entities

    defining a new entity

    Defining a new data entity

    defining an array field

    <array>

    defining a foreign key field

    <foreignkey>

Example

The following example, defines a new retireable entity named ExampleRetireableArrayEntityExt and adds it as an array to the Policy entity.

The first step is to define the array entity:

<?xml version="1.0"?>
<entity entity="ExampleRetireableArrayEntityExt" table="exampleretarray" type="retireable"
        exportable="true">
  <column name="StringColumn" type="shorttext"/>
  <typekey name="TypekeyColumn" typelist="SystemPermissionType" desc="A test typekey column"/>
  <foreignkey name="RetireableFKID" fkentity="ExampleRetireableEntityExt" 
          desc="FK back to ExampleRetireableEntity" exportable="false"/>
  <foreignkey name="KeyableFKID" fkentity="ExampleKeyableEntityExt" 
          desc="FK through to ExampleKeyableEntity" exportable="false"/>
  <foreignkey name="ClaimID" fkentity="Claim" desc="FK back to Claim" exportable="false"/>
  <implementsEntity name="Extractable"/>
  <index name="internal1" unique="true">
    <indexcol name="RetireableFKID" keyposition="1"/>
    <indexcol name="TypekeyColumn" keyposition="2"/>
  </index>
</entity>

To make this example useful, suppose that you now add this array field to the Policy entity. It is possible that a Policy entity already exists in the base configuration. Verify that the data type declaration file does not exist before adding another one. To determine if a Policy extension file already exists, use CTRL-N to search for Policy.etx.

  • If the file does exist, then you can modify it.
  • If the file does not exist, then you need to create one.

Add the following to Policy.etx. 

<extension entityName="Policy" ...>
  ...
  <array arrayentity="ExampleRetireableArrayEntityExt"
         desc="An array of ExampleRetireableArrayEntityExt objects."
         name="RetireableArrayExt" />
  ...
</extension>

Next, modify the array entity definition so it includes a foreign key that refers to Policy: 

<entity entity="ExampleRetireableArrayEntityExt" table="exampleretarray" ... >
  ...
  <foreignkey name="PolicyID" fkentity="Policy" desc="FK back to Policy" exportable="false"/>
</entity>

Finally, create the two referenced entities, ExampleRetireableEntityExt and ExampleKeyableEntityExt.