Interactions of ignoreForEvents attribute with data entity relationships

The interactions of the ignoreForEvents attribute with relationships between data entities produce what might appear to be unpredictable results. At the very least, the results are not intuitive.

However, an understanding of event generation and behavior, the definitions of the ignoreForEvents attribute, the direction of data entity relationships, and the behavior of the relationships in light of the attribute helps to predict such outcomes. Such an understanding will also help you to design predictable data entity relationships.

To this end, Guidewire recommends that you configure both sides of a data entity relationship with the same ignoreForEvents attribute value. For example, in an <array>-<foreignkey> pair and a <onetoone>-<foreignkey> pair, use the same ignoreForEvents attribute value for both pair members when possible. This topic assumes that you have followed this recommendation.

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.
Note: As a shorthand, this topic sometimes refers to entities declaring foreign key relationships and one-to-one relationships as foreign key entities and one-to-one entities respectively. Similarly, as a shorthand, the topic sometimes refers to the <foreignkey> and <one-to-one> elements themselves as foreign keys and one-to-ones. The topic refers to the entity to which a foreign key or one-to-one points as the target entity or target.

Event generation and behavior

PolicyCenter automatically generates standard events for most top-level objects. Generally, this event generation occurs upon any addition, modification, removal, or retirement of a top-level entity instance. The occurrence of an event results in the EventFired rule set executing. When this rule set is executed, PolicyCenter generates messages using the context of the event.

ignoreForEvents attribute definitions

The ignoreForEvents attribute has three definitions, a first for entities, a second for most relationships between entities, and a third for <onetoone> entity relationships. With respect to an entity, the value of the ignoreForEvents attribute determines whether to ignore the entity when generating events. With respect to an entity relationship, the ignoreForEvents attribute generally helps to rule out the relationship entity or an activity for event generation. With respect to a <onetoone> entity relationship, the ignoreForEvents attribute, when true, reverses the direction of the parent for a backing <foreignkey> element. This topic concerns only the interactions of the ignoreForEvents attribute with data entity relationships.
Note: PolicyCenter implements <onetoone> entity relationships as arrays, not as a pair of singleton entities. Thus, if an entity B has a <onetoone> entity relationship with an entity A, a parent-child direction exists for that relationship. Moreover, B is the parent of A.

Direction of data entity relationships

With respect to events, every relationship between two entities—foreign key, edge foreign key, one-to-one, and array— has a direction. This direction determines which entity in the relationship is the parent and which is the child.

For any given entity relationship, suppose that the parent entity generates events and the child entity does not generate events. In this scenario, when an instance of the child entity changes, PolicyCenter raises a ParentChanged event. The key in such a scenario is that the relationship between the two entities must flow in the direction of an EventAware entity, a parent entity, to generate an Event. EventAware entities cannot be event children.

For a given entity relationship, first determine whether the preceding scenario is present. If so, the relationship is relevant. If not, the relationship is not relevant. Moreover, if the rules lead to a parent not being a EventAware entity and to the Child being an EventAware entity, no event relationship exists between the two entities. EventAware entities cannot have event parents because updates are not propagated through EventAware entities.

Second, determine which entity is the parent and which entity is the child in accordance with the following logic:
  • An array entity is always the event parent. The entity with the array is the event parent, and the entity with the foreign key is the child.
  • With a one-to-one relationship, the entity declaring the <onetoone> element is the event parent unless the value of the ignoreForEvents attribute on the one-to-one entity is true. PolicyCenter implements one-to-one entities as arrays. In this implementation, the ignoreForEvents attribute only reverses the direction of the relationship between the array and a backing foreign key when the attribute has a value of true. When the ignoreForEvents attribute has a value of false, the one-to-one entity behaves exactly as an array with no reversal of ownership direction. Moreover, the one-to-one entity is the parent, and the foreign key entity is the child. If the ignoreForEvents attribute has a value of true, the foreign key entity is the parent, and the one-to-one entity is the child.
  • With a foreign key relationship, the entity declaring a foreign key is the event parent, and the target entity of the foreign key is the event child. An exception to this scenario occurs if the foreign key backs an array. If the foreign key backs an array, the foreign key entity is the event child.
  • With an edge foreign key relationship, the entity declaring an edge foreign key is the event parent, and the target entity of the edge foreign key is the event child.

Behavior of data entity relationships in light of the ignoreForEvents attribute value

Determine the effects of the value of the ignoreForEvents attribute on data entity relationships in accordance with the following logic:
  • If the value of the ignoreForEvents attribute on a relationship is true, ignore the relationship for event generation unless the relationship involves a one-to-one entity.

    For a relationship involving a one-to-one entity, consider the relationship for event generation as you would an array with a reversed direction of events. In this case, events propagate from the one-to-one entity to the foreign key entity if the latter is EventAware and the former is not.

    For a relationship involving a foreign key or edge foreign key, update events generally will propagate from the target object of the foreign key or edge foreign key. That is, the events generally will propagate by virtue of the target object alone being changed.

    However, consider an important exception to this generalization. Suppose that the only fields changed on the target object of the foreign key or edge foreign key have a value of true for the ignoreForEvents attribute. In this case, the PolicyCenter database reflects the changes. However, PolicyCenter does not consider the target object updated for the purpose of event generation. Whether the foreign key backs an array is irrelevant for this behavior. This behavior allows you to update internal bookkeeping fields without raising events.

    Suppose that you update only an entity that is not EventAware. Although that entity alone will not result in event generation, an EventAware parent or grandparent having an ignoreForEvents attribute with a value of false will. The EventAware parent or grandparent in this case will generate events on the basis of the changed child or grandchild that is not EventAware.

  • If the value of the ignoreForEvents attribute is false, then evaluate the relationship for event generation in accordance with the following logic:
    • Events propagate from any changed entity that is not EventAware and that has an ignoreForEvents attribute with a value of false. The propagation proceeds along a chain of entities from child to parent so long as the last entity in the chain is EventAware.

    • For a relationship involving a one-to-one entity, consider the relationship for event generation as you would an array without a reversed direction of event propagation. In this case, events propagate from the from the foreign key entity to the one-to-one entity if the latter is EventAware and the former is not.

Examples

  1. Array and foreign key

    Suppose that an entity A has a foreign key to entity B and that the foreign key backs an array. Moreover, suppose that B has an array of A. In this case, B is the parent, and A is the child. The ignoreForEvents used is set on the array entity. In this case, the ignoreForEvents used is set on the array, but Guidewire recommends applying the same setting both to the array and to the backing foreign key.

    If the foreign key does not back an array, then A is the parent, and B is the child.

  2. Array and multiple foreign keys
    Suppose the following:
    • Claim has an array of ABC_NonEAEntity with an ignoreForEvents value of false.
    • ABC_NonEAEntity has a foreign key, ClaimID, to Claim with an ignoreForEvents value of true.
    • ABC_NonEAEntity has a foreign key, ABC_AnotherNonEAEntityID, to ABC_AnotherNonEAEntity with an ignoreForEvents value of true.
    Given this premise, the following is true:
    • Claim is an event parent of ABC_NonEAEntity, because of the array.

      That the foreign key of ABC_NonEAEntity to Claim has an ignoreForEvents attribute with a value of true does not matter. This irrelevance is because the foreign key backs an array.

      In addition, under ordinary circumstances, ABC_NonEAEntity would be an event parent of ABC_AnotherNonEAEntity. However, PolicyCenter does not treat ABC_NonEAEntity as an event parent because the foreign key has an ignoreForEvents attribute with a value of true.

    • Given this configuration, the following actions will raise ClaimChanged events:
      • Changing a field on Claim
      • Adding a new ABC_NonEAEntity to Claim
      • Removing an existing ABC_NonEAEntity from Claim
      • Updating any combination of fields on an existing ABC_NonEAEntity, except any combination that includes only ClaimID or ABC_AnotherNonEAEntityID. The exclusion is due to the latter fields having an ignoreForEvents attribute with a value of true.
    • The following independent actions will not raise ClaimChanged events:
      • Updating an existing ABC_AnotherNonEAEntity
      • Changing an existing ABC_NonEAEntity to point to a different ABC_AnotherNonEAEntity

        The reason for no raising of ClaimChanged events is because the only field that changed, ABC_AnotherNonEAEntityID, has an ignoreForEvents attribute with a value of true.

  3. Foreign key and array
    Suppose the following:
    • Entity E has a foreign key F with an ignoreForEvents value of true.
    • An instance of E undergoes a change only to the field for F.
    • No other change would cause PolicyCenter to raise EChanged or XYZChanged events.
    Given this premise, the following is true:
    • PolicyCenter will not consider the instance of E to have changed for event generation purposes.
    • If E is an EventAware entity, PolicyCenter will not raise an EChanged event.
    • If E is not an EventAware entity, PolicyCenter will not raise an XYZChanged event for any event parents of E.
    Suppose further that foreign key F backs an array. Given this elaboration, the following is true:
    • Only the array is used to determine the event propagation relationship between the foreign key and the array.
    • If the array has an ignoreForEvents attribute with a value of true, PolicyCenter will not propagate events between the two entities.
    • Suppose that the foreign key has an ignoreForEvents attribute with a value of true. In this case, PolicyCenter ignores changes to any instance of the foreign key for deciding whether a bean has changed for the purpose of event generation.