Searching for related objects

AD
DM
DS
ST

You can use the Advanced Search form to search on a name from the related object in a relationship. When you search by entity type, the More fields list contains the custom relationship objects and related object.

Example

You might need to find HCPs that participated in a study related to rheumatoid arthritis. The HCP object and the custom object called STUDY are linked in a custom relationship object (Study Investigator). If you search by the HCP entity type in the advanced search form, the custom relationship object will display in the More fields list and you can select the related object; in this case Clinical Trial, which is the label for the STUDY custom object.

Note: The entity type that you search by must be the owner object.

ClosedAbout custom relationship objects

Objects (Veeva and custom) can be linked by a custom relationship object. In each relationship, one of the objects is defined as the owner object. The owner and related objects are defined when the custom relationship object is created in your Network instance by Veeva.

When administrators configure the custom relationship object in your Network instance, perspective labels are defined for the owner and related objects so the name makes sense when you are viewing it from the other object's record profile.

In the example below, for the HCP (owner object), the STUDY custom object (related) is given the label "Clinical Trial" - a more appropriate name than "Study" in the context of an HCP. So if you use the advanced form to search for HCPs that participated in a specific study, in the More fields list, “Clinical Trial” will be listed below the Study Investigator custom relationship object.

Perform a search

To search for the name of a related object:

  1. In the advanced search form, expand the Search by Entity Type list and select an object; for example, Health Care Professional (HCP). The object must be the owner object in the relationship.

  2. In the More fields section, click + Add Search Fields.
  3. Expand the Field Name list and find the relationship object name; for example, Study Investigator.

  4. From the list under the relationship object, select the label (name) that the owner object uses to refer to the related object. For example, for HCPs, the STUDY custom object is called Clinical Trial.

  5. In the Value field, type the name of the object. This search supports fuzzy search, so the exact name is not required.
  6. Add any other field values to help narrow your search; for example, State, City and so on.
  7. Click Search.

The search results page will display the objects that match your query.

Examples for supported relationship patterns

Using custom relationship objects, several modeling patterns are supported in the custom objects data model. Review the following examples to understand how you can search for the name of a related object.

Many-to-many relationships

The HCP and STUDY example is a many-to-many relationship. HCPs can participate in multiple studies, and studies can include multiple HCPs. Support for the related name depends on which object is defined as the owner object in the relationship:

  • To search for HCPs that participated in specific studies, HCPs must be the owner object.
  • To search for studies that included specific HCPs, STUDY must be the owner object.

Example

The HCP Veeva object and the STUDY custom object are linked using the STUDYINVESTIGATOR_REL__C custom relationship object. When STUDYINVESTIGATOR_REL__C was created, HCP was defined as the owner object.

The referring label (Investigator, Clinical Trial) for the related object is the name of the related_entity_name__v field under the relationship object in the More fields section.

Using this example, search for an HCP that has participated in a study:

  1. In the Advanced Search form, select HCP in the Search by Entity Type field.
  2. In the More fields section, expand the list and find the relationship object name, Study Investigator.
  3. Select Clinical Trial (the referring label) from the list under Study Investigator.
  4. In the Value field, type the name of the study, rheumatoid arthritis.

Arc relationships

Arc relationships support linking a main object to more than one main object type. For example, an EMPLOYEE custom object (sales representative) can have an exclusive relationship with both HCPs and HCOs (account types) using the same custom object relationship (EMPLOYEEACCOUNT_REL__C). In this example, the EMPLOYEE custom object is the owner object in the relationship. For data privacy, objects that contain confidential data, like personal data, are often selected as the owner object so administrators can easily limit the users that have access to the data (using data visibility profiles).

Example

A sales leader might want to search for the sales representative who has the account with St. Michael's Hospital (HCO).

  1. In the Advanced Search form, select Employee in the Search by Entity Type field.
  2. In the More fields section, expand the list and find the Employee Account relationship object.
  3. Choose Account (referring label) from the list under Employee Account.
  4. Type the name of the specific account; for example, St. Michael's Hospital, in the Value field.

Recursive relationships

An entity type can refer to itself, so you can search for names of related objects from the same kind of object. For example, a custom object called EVENT can include conferences, workshops, lectures, symposiums, seminars, and so on. As a sales representative, you might want to search for conferences that held workshops on Atrial Fibrillation (the disease that your product is used for treating).

Example

To search for a conference that held workshops on atrial fibrillation:

  1. Using the Advanced Search form, select Events in the Search by Entity Type field.
  2. In the More fields section, expand the list and find the Related Event relationship object.
  3. From the list under Related Event, choose All Event (referring label).
  4. Type the name of the specific workshop, Atrial Fibrillation.

New entity name field

A new field called related_entity_name__v is introduced to enable users to search for the names of the related objects. This field is only available in the advanced search form and through the Network Search API; it does not display in the custom object data model.

API considerations

Integration users can search for related entity names using the Network API. In the Search API, the <relationship_object_api_name>.related_entity_name__v field can be used in a filter or a field query.

Note that in the Network API, the custom relationship object includes set in the name; for example, for the custom relationship object HCP_STUDY_REL__C, the name in the API is hcp_study_rel_set__c.

Example response

{
    "responseStatus": "SUCCESS",
    "entities": [
        {
            "entityId": "933889313829028228",
            "entityType": "STUDY__C",
            "metaData": {},
            "entity": {
                "study_phase__c": "Phase 3",
                "vid__v": "933889313829028228",
                "primary_country__v": "US",
                "study_official_title__c": "Prospective Evaluation Of Biventricular Pacing In Patients With Left Ventricular Dysfunction After Cardiovascular Surgery",
                "study_name__c": "Biventricular Pacing In Patients With Left Ventricular Dysfunction After Cardiovascular Surgery",
                "study_hcp_rel_set__c": [
                    {
                        "study_hcp_role__c": "Sub-Investigator",
                        "study_hcp_rel_status__c": "A",
                        "related_entity_type__v": "HCP",
                        "record_owner_type__v": "LOCAL",
                        "status_update_time__v": "2019-01-30T22:08:19.000Z",
                        "related_entity_vid__v": "260904859312587776",
                        "related_entity_name__v": "Elliot Brown",
                        "record_delta_id__v": "933889314146189311",
                        "entity_type__v": "STUDY__C",
                        "record_owner_name__v": "Local",
                        "modified_date__v": "2019-01-30T22:08:20.000Z",
                        "record_state__v": "VALID",
                        "is_primary_relationship__v": "N",
                        "vid__v": "933889313829028230",
                        "entity_vid__v": "933889313829028228",
                        "created_date__v": "2019-01-30T22:08:19.000Z",
                        "is_veeva_master__v": false
                    }
                ]
            }
        }
    ]
}