Configuring account relationships

Account relationship object model

The following illustration shows account entities associated with account relationships. See the Data Dictionary for a complete list of all properties in the entities. The illustration displays a partial list.



The AccountAccount entity represents a relationship between a SourceAccount and a TargetAccount. The SourceAccount and TargetAccount can be the same. The RelationshipType field is a typekey to the AccountRelationshipType typelist. For more information, see Account relationship typelist.

For account relationships, the Account entity has two arrays: SourceRelatedAccounts and TargetRelatedAccounts. Each array contains AccountAccount entities, which link back to Account with the SourceAccount and TargetAccount fields. The getAllRelatedAccounts method returns a derived array which returns an AccountAccount entity for all source and target related accounts. For most account relationships, this field returns two AccountAccount entities. If an account is related to itself then the return array includes only one AccountAccount entity, even though that AccountAccount appears in both SourceRelatedAccounts and TargetRelatedAccounts.

A single AccountAccount entity represents a bidirectional relationship from its SourceAccount to its TargetAccount. For example, if account A is the parent of account B, then the single AccountAccount also represents that B is the child of A.

The SourceRelatedAccounts array is marked as owner which forces account validation to run when an AccountAccount in this array is added or updated. The default validation ensures that no duplicate relationships are created. The TargetRelatedAccounts array does not need to be owner because the target accounts are included implicitly in the validation rules. For more information about the owner attribute, see <array>. In Studio, the owner attribute is set in Account.eti located in configuration > config > Metadata > Entity.

The SourceAccount, TargetAccount, RelationshipType and Retired fields of each AccountAccount entity must be unique. Therefore, no SourceAccount may be related to the same TargetAccount with the same RelationshipType more than once.

Account relationship typelist

The AccountRelationshipType typelist is extensible, and represents the relationship from the perspective of the source account. The following table lists the codes for the AccountRelationshipType typelist in the base configuration.

Typecode

Name

parent

Parent of

child

Child of

commonowner

Common Ownership

In the base configuration, the parent and child relationships are the inverse of each other, while commonowner is reciprocal. For example, if account A is the parent of account B, then B is the child of A. Similarly, if A is a common owner with B, then B is also a common owner with A.

Account relationship methods in the Account plugin

The getInverseRelationshipType method of the IAccountPlugin takes as input a relationship type, and returns the inverse relationship type. PolicyCenter assumes that all relationships have an inverse relationship, therefore this method must not return null. You can modify the default behavior of getInverseRelationshipType method and add code to handle new typecodes.

Account relationship rule sets

In Studio, rule sets are grouped by function for the purpose of customizing a process. This topic describes the rules that pertain to account relationships.

Note: For information on how to insert and configure Gosu rules, see PolicyCenter Rule Set Categories.

The following table describes rule sets in the default application related to account relationships.

Rule

Description

Validation > Account Validation Rules > Related Accounts

Invoked when an AccountAccount entity is added or updated.

Performs the following checks:

  • Checks that no exact duplicate AccountAccount entities exist on an account, with the same SourceAccount, TargetAccount and RelationshipType fields.
  • Checks that no inverse duplicate AccountAccount entities exist on an account, where the SourceAccount, TargetAccount, and RelationshipType of one matches the TargetAccount, SourceAccount, and inverse RelationshipType of the other. For example, if A is the parent of B, then there must not be another AccountAccount explicitly marking B as the child of A.

If necessary, you can modify or add additional validations.

Account relationship methods in Gosu classes

This topic describes various methods in Gosu classes for working with account relationships.

Adding a relationship

Use the Account.addRelationship method in AccountBaseEnhancement to add relationships to an account. This method creates and returns a new AccountAccount entity. The new AccountAccount appears in Account.SourceRelatedAccounts and in relatedAccount.TargetRelatedAccounts.

Removing a relationship

You can remove a relationships by simply removing the AccountAccount entity in one of the following ways:

  • Calling the removeFromSourceRelatedAccounts or removeFromTargetRelatedAccounts method on an Account entity
  • Calling remove on the AccountAccount entity

Getting relationships

The getRelationship method in the AccountAccountEnhancement wraps an AccountAccount in a new AccountRelationship Gosu object that is aware of the direction of the relationship.

AccountAccount.getRelationship(primaryAccount : Account) : AccountRelationship

This method returns an AccountRelationship which represents an AccountAccount from the perspective of the argument primaryAccount. The AccountRelationship provides two properties, which are both readable and writable:

  • OtherAccount refers to the other account in the relationship from the perspective of primaryAccount. So if primaryAccount is the SourceAccount of a relationship then OtherAccount maps to the TargetAccount. Conversely, if primaryAccount is the TargetAccount in the relationship, then OtherAccount maps to the SourceAccount.
  • RelationshipType is the type of relationship from the perspective of primaryAccount. If primaryAccount is the SourceAccount of an AccountAccount relationship, then RelationshipType is the same as the type in the AccountAccount. If primaryAccount is the TargetAccount, then RelationshipType is the inverse of the type in the AccountAccount.
The following illustrations shows some of these relationships.

Example

Assume there is an AccountAccount whose SourceAccount is A, TargetAccount is B, and RelationshipType is parent. The AccountAccount object has the following relationships:

  • AccountAccount.getRelationship(A).OtherAccount == B
  • AccountAccount.getRelationship(A).RelationshipType == "parent"
  • AccountAccount.getRelationship(B).OtherAccount == A
  • AccountAccount.getRelationship(B).RelationshipType == "child"

Getting all relationships

The Account.getAllRelationships method in AccountBaseEnhancement returns an array of AccountRelationships for all relationships of an account. 

Account.getAllRelationships : AccountRelationship[]

Configuring shared contact search criteria

On the Related Accounts screen, you can search for Accounts with a common account holder or named insured. In the base configuration, the search finds accounts with contacts that are account holders or named insureds on both accounts.

You can view and modify the code for the search in gw.account.SharedContactAccountSearchCriteria.

The SearchableSharedContactRoles property defines the contact roles that this search includes.