Related Records

/**
 * Operations for managing relationships between CRM records
 */
class RelatedRecordsOperations {
    /**
     * Get related records for a specific record
     * @param relatedListAPIName - API name of the related list
     * @param recordId - ID of the parent record
     * @param moduleAPIName - API name of the parent module
     * @param paramInstance - Optional parameters for filtering and pagination
     * @param headerInstance - Optional headers for request customization
     * @returns Promise with APIResponse containing related records
     */
    getRelatedRecords(relatedListAPIName: string, recordId: BigInt, moduleAPIName: string, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;

    /**
     * Update multiple related records
     * @param relatedListAPIName - API name of the related list
     * @param recordId - ID of the parent record
     * @param moduleAPIName - API name of the parent module
     * @param request - Body wrapper containing updated record data
     * @returns Promise with APIResponse containing update results
     */
    updateRelatedRecords(relatedListAPIName: string, recordId: BigInt, moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;

    /**
     * Remove the relationship between records (delink)
     * @param relatedListAPIName - API name of the related list
     * @param recordId - ID of the parent record
     * @param moduleAPIName - API name of the parent module
     * @param paramInstance - Parameters specifying records to delink
     * @returns Promise with APIResponse containing delink results
     */
    delinkRecords(relatedListAPIName: string, recordId: BigInt, moduleAPIName: string, paramInstance: ParameterMap): Promise<APIResponse>;

    /**
     * Get a specific related record
     * @param relatedListAPIName - API name of the related list
     * @param recordId - ID of the parent record
     * @param relatedRecordId - ID of the related record
     * @param moduleAPIName - API name of the parent module
     * @param paramInstance - Optional parameters for field selection
     * @param headerInstance - Optional headers for request customization
     * @returns Promise with APIResponse containing related record data
     */
    getRelatedRecord(relatedListAPIName: string, recordId: BigInt, relatedRecordId: BigInt, moduleAPIName: string, paramInstance?: ParameterMap, headerInstance?: HeaderMap): Promise<APIResponse>;

    /**
     * Update a specific related record
     * @param relatedListAPIName - API name of the related list
     * @param recordId - ID of the parent record
     * @param relatedRecordId - ID of the related record
     * @param moduleAPIName - API name of the parent module
     * @param request - Body wrapper containing updated record data
     * @returns Promise with APIResponse containing update results
     */
    updateRelatedRecord(relatedListAPIName: string, recordId: BigInt, relatedRecordId: BigInt, moduleAPIName: string, request: BodyWrapper): Promise<APIResponse>;

    /**
     * Remove relationship for a specific related record
     * @param relatedListAPIName - API name of the related list
     * @param recordId - ID of the parent record
     * @param relatedRecordId - ID of the related record
     * @param moduleAPIName - API name of the parent module
     * @returns Promise with APIResponse containing delink results
     */
    delinkRecord(relatedListAPIName: string, recordId: BigInt, relatedRecordId: BigInt, moduleAPIName: string): Promise<APIResponse>;
}

const { RelatedRecordsOperations } = require("@zohocrm/nodejs-sdk-2.0/core/com/zoho/crm/api/related_records/related_records_operations");
const { BodyWrapper } = require("@zohocrm/nodejs-sdk-2.0/core/com/zoho/crm/api/related_records/body_wrapper");
const { Record } = require("@zohocrm/nodejs-sdk-2.0/core/com/zoho/crm/api/record/record");
const { ParameterMap } = require("@zohocrm/nodejs-sdk-2.0/routes/parameter_map");

const relatedRecordsOp = new RelatedRecordsOperations();

// Get contacts related to an account
const accountId = "123456789012345678";
const contactsResponse = await relatedRecordsOp.getRelatedRecords("Contacts", accountId, "Accounts");

if (contactsResponse != null) {
    const responseObject = contactsResponse.object;
    if (responseObject instanceof ResponseWrapper) {
        const relatedRecords = responseObject.getData();
        relatedRecords.forEach(contact => {
            console.log(`Contact: ${contact.getFieldValue("Full_Name")}`);
        });
    }
}

// Update a related contact
const contactRecord = new Record();
contactRecord.setId("contact_id_here");
contactRecord.addFieldValue("Phone", "+1-555-0123");

const updateWrapper = new BodyWrapper();
updateWrapper.setData([contactRecord]);

const updateResponse = await relatedRecordsOp.updateRelatedRecord(
    "Contacts",
    accountId,
    "contact_id_here",
    "Accounts",
    updateWrapper
);

// Delink a contact from an account
const delinkResponse = await relatedRecordsOp.delinkRecord(
    "Contacts",
    accountId,
    "contact_id_here",
    "Accounts"
);

/**
 * Operations for accessing related list metadata
 */
class RelatedListsOperations {
    /**
     * Get all related lists for a module
     * @param moduleAPIName - API name of the parent module
     * @returns Promise with APIResponse containing related lists metadata
     */
    getRelatedLists(moduleAPIName: string): Promise<APIResponse>;

    /**
     * Get details of a specific related list
     * @param relatedListId - ID of the related list
     * @param moduleAPIName - API name of the parent module
     * @returns Promise with APIResponse containing related list details
     */
    getRelatedList(relatedListId: string, moduleAPIName: string): Promise<APIResponse>;
}

const { RelatedListsOperations } = require("@zohocrm/nodejs-sdk-2.0/core/com/zoho/crm/api/related_lists/related_lists_operations");

const relatedListsOp = new RelatedListsOperations();

// Get all related lists for Accounts module
const relatedListsResponse = await relatedListsOp.getRelatedLists("Accounts");

if (relatedListsResponse != null) {
    const responseObject = relatedListsResponse.object;
    if (responseObject instanceof ResponseWrapper) {
        const relatedLists = responseObject.getRelatedLists();
        relatedLists.forEach(relatedList => {
            console.log(`Related List: ${relatedList.getDisplayLabel()}, API Name: ${relatedList.getAPIName()}`);
        });
    }
}

/**
 * Body wrapper for related records requests
 */
class BodyWrapper {
    /** Get related records data */
    getData(): Record[];
    /** Set related records data */
    setData(data: Record[]): void;

    /** Get workflow trigger settings */
    getWfTrigger(): boolean[];
    /** Set workflow trigger settings */
    setWfTrigger(wfTrigger: boolean[]): void;
}

/**
 * Response wrapper for related records GET operations
 */
class ResponseWrapper {
    /** Get related records data */
    getData(): Record[];
    /** Get pagination info */
    getInfo(): Info;
}

/**
 * Action wrapper for related records POST/PUT/DELETE operations
 */
class ActionWrapper {
    /** Get action results */
    getData(): ActionResponse[];
}

/**
 * Represents a related list configuration
 */
class RelatedList {
    /** Get related list ID */
    getId(): string;
    /** Set related list ID */
    setId(id: string): void;

    /** Get sequence number */
    getSequenceNumber(): number;
    /** Set sequence number */
    setSequenceNumber(sequenceNumber: number): void;

    /** Get display label */
    getDisplayLabel(): string;
    /** Set display label */
    setDisplayLabel(displayLabel: string): void;

    /** Get API name */
    getAPIName(): string;
    /** Set API name */
    setAPIName(apiName: string): void;

    /** Get related list module */
    getModule(): string;
    /** Set related list module */
    setModule(module: string): void;

    /** Get related list name */
    getName(): string;
    /** Set related list name */
    setName(name: string): void;

    /** Get related list action */
    getAction(): string;
    /** Set related list action */
    setAction(action: string): void;

    /** Get href for API access */
    getHref(): string;
    /** Set href for API access */
    setHref(href: string): void;

    /** Get related list type */
    getType(): string;
    /** Set related list type */
    setType(type: string): void;

    /** Get connected module */
    getConnectedModule(): string;
    /** Set connected module */
    setConnectedModule(connectedModule: string): void;

    /** Get linking module */
    getLinkingModule(): string;
    /** Set linking module */
    setLinkingModule(linkingModule: string): void;
}

/**
 * Response wrapper for related lists operations
 */
class ResponseWrapper {
    /** Get related lists data */
    getRelatedLists(): RelatedList[];
}

/**
 * Parameters for getRelatedRecords operation
 */
class GetRelatedRecordsParam {
    static PAGE: Param;              // Page number for pagination
    static PER_PAGE: Param;          // Records per page
    static FIELDS: Param;            // Fields to retrieve
    static IDS: Param;               // Specific record IDs
    static SORT_BY: Param;          // Sort field
    static SORT_ORDER: Param;       // Sort order (asc/desc)
}

/**
 * Headers for getRelatedRecords operation
 */
class GetRelatedRecordsHeader {
    static IF_MODIFIED_SINCE: Header; // Get records modified since date
    static X_EXTERNAL: Header;        // External system identifier
}

/**
 * Parameters for getRelatedRecord operation
 */
class GetRelatedRecordParam {
    static FIELDS: Param;            // Fields to retrieve
}

/**
 * Headers for getRelatedRecord operation
 */
class GetRelatedRecordHeader {
    static IF_MODIFIED_SINCE: Header; // Get record if modified since date
    static X_EXTERNAL: Header;        // External system identifier
}

/**
 * Parameters for updateRelatedRecords operation
 */
class UpdateRelatedRecordsParam {
    static IDS: Param;               // Record IDs to update
}

/**
 * Parameters for delinkRecords operation
 */
class DelinkRecordsParam {
    static IDS: Param;               // Record IDs to delink
}

const { ParameterMap } = require("@zohocrm/nodejs-sdk-2.0/routes/parameter_map");
const { HeaderMap } = require("@zohocrm/nodejs-sdk-2.0/routes/header_map");
const { GetRelatedRecordsParam, GetRelatedRecordsHeader } = require("@zohocrm/nodejs-sdk-2.0/core/com/zoho/crm/api/related_records/related_records_operations");

// Setup parameters for getting related records
const paramMap = new ParameterMap();
await paramMap.add(GetRelatedRecordsParam.FIELDS, "Full_Name,Email,Phone,Title");
await paramMap.add(GetRelatedRecordsParam.PAGE, 1);
await paramMap.add(GetRelatedRecordsParam.PER_PAGE, 200);
await paramMap.add(GetRelatedRecordsParam.SORT_BY, "Full_Name");
await paramMap.add(GetRelatedRecordsParam.SORT_ORDER, "asc");

// Setup headers
const headerMap = new HeaderMap();
await headerMap.add(GetRelatedRecordsHeader.IF_MODIFIED_SINCE, new Date("2023-01-01T00:00:00Z"));

// Get related records with filters
const response = await relatedRecordsOp.getRelatedRecords(
    "Contacts",
    "account_id_here",
    "Accounts",
    paramMap,
    headerMap
);

/**
 * Common related list API names
 */
class CommonRelatedLists {
    // Account related lists
    static ACCOUNT_CONTACTS: string = "Contacts";
    static ACCOUNT_DEALS: string = "Deals";
    static ACCOUNT_CASES: string = "Cases";
    static ACCOUNT_ACTIVITIES: string = "Activities";
    static ACCOUNT_NOTES: string = "Notes";
    static ACCOUNT_ATTACHMENTS: string = "Attachments";

    // Contact related lists
    static CONTACT_DEALS: string = "Deals";
    static CONTACT_CASES: string = "Cases";
    static CONTACT_ACTIVITIES: string = "Activities";
    static CONTACT_NOTES: string = "Notes";
    static CONTACT_ATTACHMENTS: string = "Attachments";

    // Deal related lists
    static DEAL_CONTACT_ROLES: string = "Contact_Roles";
    static DEAL_STAGE_HISTORY: string = "Stage_History";
    static DEAL_ACTIVITIES: string = "Activities";
    static DEAL_NOTES: string = "Notes";
    static DEAL_ATTACHMENTS: string = "Attachments";

    // Lead related lists
    static LEAD_ACTIVITIES: string = "Activities";
    static LEAD_NOTES: string = "Notes";
    static LEAD_ATTACHMENTS: string = "Attachments";
}

/**
 * Types of record relationships
 */
class RelationshipType {
    static ONE_TO_MANY: string = "one_to_many";         // Parent-child relationship
    static MANY_TO_MANY: string = "many_to_many";       // Junction table relationship
    static LOOKUP: string = "lookup";                   // Lookup field relationship
    static MASTER_DETAIL: string = "master_detail";     // Master-detail relationship
}