Limiting the number of custom relationships

AD
DM

Relationships objects are defined as unlimited (many-to-many) relationships or they are set to one (1) relationship per owner object. When relationships are limited to many-to-one relationships, Network prevents additional related objects from being added to the owner object record.

Defining relationship objects

When you create a custom relationship object, you must specify the Maximum number of relationships per owner setting.

Choose one of the following options:

  • Unlimited - Supports many-to-many relationships. This is the default value.

  • 1 - Supports many-to-one relationships.

Example

When you create a custom relationship object for payer and plan main objects, set the Maximum number of relationships per owner setting to 1.

This should be a many-to-one relationship:

  • One plan belongs to one payer

  • One payer can have many plans

Note: When you save the new custom relationship object, the Maximum number of relationships per owner setting becomes read-only.

Field for limited relationships

Relationship objects contain the foreign keys for the owner object and the related object.

  • entity_vid__v

  • related_entity_vid__v

If you limit a relationship to many-to-one, the Veeva ID (VID) of the related object is added to the owner object as a new foreign key field.

  • related_<related_object_name>_vid__c

The field is added so it can be exported/accessed through target subscriptions, the Network API, and the Profile page. It enables you to JOIN directly on the foreign key of the related object instead of going through relationship object. Downstream systems like Veeva CRM might expect the VID of the related object on the owner object for many-to-one relationships.

Example

The field for the payer (related) object on the plan (owner) object would be related_payer_vid__c.

If more than one relationship exists with the same combination of owner and related object, the field name on the owner is incremented with a counter; for example, related_payer_vid__c and related_payer2_vid__c.

Adding and updating relationships

When the relationship object is limited to a many-to-one relationship, you can add only one relationship for each owner entity record. Adding multiple relationships through either data loading, add requests (API), or manually on the Profile page is also not possible.

  • Source subscriptions - If a source file contains more than one relationship for the same owner, then the main entity will fail to load.

    An error message will be logged.

  • API - If an add or change request is submitted through the Network API and it exceeds the number of allowed relationships, the DCR will display an error message. It will remain in Pending Review status until only one relationship is accepted and the other relationships are rejected.

  • Profile page - Users are prevented from submitting more than one relationship. The New Relationship button is dimmed and the following message displays: The maximum number of relationships is limited to 1.

Updates

Updating the one valid relationship using source subscriptions, the Network API, or the Profile page is supported. This could mean that the relationship is repointed and it changes the related entity VID on the owner object.

Record state/status change

When the relationship object is limited, invalidating or inactivating the relationship automatically removes the Veeva ID (VID) value from the Foreign Key field on the owner.

  • Inactive relationship - When a relationship object's record status (*_rel_status__c field) is set to INACTIVE, the Foreign Key field value on the owner object is updated to -1. If the relationship is updated to ACTIVE, the Foreign Key field value is populated with the VID of the related entity again.

  • Invalid relationship - When a relationship object's record state (record_state__v) is updated to INVALID or DELETED, the related VID field value on the owner object is updated to -1. The relationship cannot be updated to VALID again. A new relationship record must be created.

  • Deleting the related entity - If the related main object's record state is set to INVALID or DELETED, the Foreign Key value is updated to -1 on the owner object

    Important: Use the Delete Custom Object Records data maintenance job to delete the related objects. The job will properly delete/inactivate the relationship itself and its custom keys. This ensures that a new relationship with another related entity can be created again. If active custom keys remain on the invalid/deleted relationship, then incoming relationships might match with those active custom keys and update the invalid/delete relationship instead of creating a new relationship.

Merging records

Owner objects

When a relationship is limited to many-to-one and the owner records are merged, only one relationship can survive as the valid relationship.

Example merge scenarios

Relationship on Winner Relationship on Loser Surviving Relationship
VALID VALID Relationship from the merge winner
INVALID VALID Relationship from the merge loser
VALID INVALID Relationship from the merge winner
None VALID Relationship from the merge loser
VALID None Relationship from the merge winner

Related objects

When the related object records are merged, the Foreign Key field on the owner object of the relationship is updated accordingly.

This could mean that a large number of owner object records are updated. For example, if two Payer records are merged, then all of the Plan records that are linked to the merge loser will have the Foreign Key field updated with the VID of the merge winner.

Unmerging records

Owner objects

If the owner object is unmerged, the status of the relationships from before the merge are restored again.

Related objects

If the related entity is unmerged, the owner objects are not updated with the new VID of the umerged entity. Instead, all owner objects remain related to the winner of the previous merge. You must repoint the relationship to the new unmerged entity, if required.

Exporting configurations

Custom relationship objects can be exported to a target environment. When the relationship object is added to the export package, the owner object and related objects are automatically added.

Important: If the relationship object is limited to many-to-one, do not add the Foreign Key field to the export package. The Foreign Key field for the related object will be generated and added to the owner object when the configuration is imported.