Difference tree XML configuration

The full set of differences might be more than you want users to see in the user interface. PolicyCenter needs to perform the complex actions like merging changes or integration with external systems. Those parts of the system might need to track a large and complete list of difference items. To configure what differences users can view, you use a difference tree configuration XML file.

By default, PolicyCenter defines one difference tree XML configuration file for each product. PolicyCenter manages difference tree configuration XML files by product, not by line of business. Products that have multiple lines of business, such as commercial package, share one XML file. You can customize these files, and you can create additional files if you create new products. Even if a product has no lines of business, you must add a new difference tree XML configuration file.

In practice, a new line of business is one of the following items.

  • Part of a new product, in which case you add a new XML file
  • Part of an existing product, in which case you customize an existing XML file

A difference tree XML file defines the following situations.

  • Which entities to display with changes to properties
  • Which entities can have child objects in the tree
  • How to group changes in an intuitive way using sections
  • How to display the context of a property or entity by showing ancestor groups in the tree structure

This is primarily a user interface customization. PolicyCenter only uses this XML file to display difference items. Although you can use this to hide some difference items in the user interface, hiding these differences do not fundamentally change the data used in other parts of the application. For example, to apply preemptions or out-of-sequence policy changes, PolicyCenter merge differences that you choose not to display.

However, it is generally best to do as much filtering as possible in the XML configuration. Avoid writing additional Gosu code in the difference helper classes (DiffHelper subclasses) to filter the list of difference items.

There are three ways to filter difference item display in the XML configuration.

  • An ExcludedProperty element in XML excludes certain properties from displaying. An example of this is in IMDiffTree.xml.
  • If you do not define an entity in the XML file, PolicyCenter will not display it.
  • On each <Entity> element in the XML file, there are attributes showadds, showremoves, and showchanges. Use those to suppress difference adds, removes, and changes.

Do as much of your filtering in the XML files as possible. However, note that the difference tree XML file primarily customizes the user interface.

PolicyCenter takes the already-generated list of difference items and this XML file and constructs a tree that represents nodes in the tree at appears in the user interface.

The following steps describe how PolicyCenter uses various objects to create the difference user interface.

  1. Some application flow determines it is time to recalculate the differences user interface.
  2. That code calls the policy period difference plugin method recalculateRootNode. This method must do whatever is necessary to build the difference tree and return it. More precisely, it returns the root node type, which is RowTreeRootNode. Either base your code on the built-in implementation or modify the built-in implementation. The built-in implementation gets the file name of the XML configuration file and then builds the tree. The following steps describe this process in more detail.
  3. Gosu code calculates which XML file to use. By default, the built-in implementation just uses the line of business and returns a specific file. To change the default logic, customize the policy period difference plugin method getDiffTreeConfig. In the base configuration, this method exists only on the implementation class for the built-in plugin implementation. You can put complex logic into this. For example, you might dynamically change which XML file to use for your product based on one or more of the following conditions.
    • Whether the user is an underwriter or a producer and show different levels of detail to each.
    • The difference reason. Is this a multiple version job or comparing a policy to a history revision?
    • Line of business.
    • Other application context.
  4. PolicyCenter loads the XML file based on its file name. It specifies how to present entities, property changes, and how to label sections in the user interface. This file name is an argument to the constructor for the DiffTree class, which controls much of this flow. You can view the DiffTree.gs file in Studio.
  5. PolicyCenter creates an internal in-memory representation of the difference tree XML elements.
  6. PolicyCenter creates a tree of node generators. A node generator knows how to generate a node in the final tree. The node generator tree is roughly parallel to the XML element tree. However, there are important differences. The most important differences between the XML structure and the node generator tree structure are described below.
    • In most cases property changes naturally appear under the entities they are on. Because of this, the format implicitly creates node generators underneath entities that generate nodes for changed properties. Because of this, compared to the input XML file structure, the generator tree has additional objects. (There are ways to customize the property behavior, such as suppressing properties or having them display in other places in the tree structure.)
    • For any entity that you identify in the XML file, in the typical case PolicyCenter creates three node generators. One generator knows how to display a row identifying an added object. One generator knows how to display a row identifying a removed object. One generator (the EntityNodeGenerator) is primarily a container for descendents in the tree. For example, changed properties for that entity appear underneath this section.
  7. PolicyCenter iterates across the list of difference items and finds the appropriate node generator for that difference item using the following information.
    • The type of the object that changed
    • Whether the object was added, removed, or changed
    • If a property changed, what is the property name

    If PolicyCenter does not find a node generator for that information, then PolicyCenter skips this difference item. It does not appear in the difference tree user interface.

  8. For each difference item, PolicyCenter asks the appropriate node generator to generate a new node in the tree of tree nodes. Each node is an object that implement the IDiffTreeNode interface. For example, if a property changed, the node object contains information about how to display that specific property change.
  9. Before proceeding to the next difference item, PolicyCenter must determine where in the destination tree to put the new node. For example, suppose the difference item fixes an incorrect drivers license number for a a driver on car. Presumably you want this change to appear underneath a tree node with a label that describes the driver. If it is important to understand that the driver displays under a specific car, then PolicyCenter must create a node for that label too, one level above the driver.

    PolicyCenter first checks to see if the parent container for this new node already exists in the actual difference tree yet. If it does exist, PolicyCenter sets the new node to point to its parent container. If it does not exist, PolicyCenter asks the appropriate node generator for the parent type to generate the container node. (It knows what generator to use by looking at the tree of node generators, which have parent links that lead up eventually to the root.) This process recursively ensures that all new nodes are contained within ancestor nodes that tell the user the context of the new change.

    For example, suppose there are three changes on a car for an auto policy. For the first property change, PolicyCenter asks the node generator to create the container node representing the car. For additional property changes on that car, PolicyCenter can reuse the existing parent container node that represents the car. All three property changes appear as child nodes underneath the car.

    The result is a complete tree of IDiffTreeNode objects that describe the structure of the difference tree.

  10. The user interface PCF files use the tree to display the difference tree using a tree widget.

The following diagram describes the basic flow of the difference tree creation.


Visual representation of difference tree creation as described in the preceding numbered list.

There is not a one-to-one relationship between the difference items and the nodes in the final output tree. The XML file describes what information appears and how to structure it. The number of input difference items is independent of the number of final output nodes.

  • It is common for the number of nodes in the final difference tree to exceed the number of difference items. This is because PolicyCenter creates nodes to describe ancestors in the tree to what entities changed. Also, some nodes describe groups solely for display purpose (these are called “sections”).
  • The converse could also be true. For example if there is no reference to that entity in the difference tree XML file or you filter out some costs. Thus, there could be more difference items than nodes in the final tree.

For example, consider a single difference item representing a change of driver on a car. The difference tree might include multiple nodes that describe the change as well as multiple levels of context of the change , as shown in the following line. The example shows one difference item but four nodes in the final output tree. The four nodes include nodes that describe the ancestors of the node that describes the change. Users can see each change in its full context.

Root of the line of business → A label that contains “Vehicles” → A specific car → The change of driver