BuildScopeForRecord

Overview

Step 1 of the programmatic access pipeline. Given a Salesforce record ID, resolves which records are "in scope" for communications using the BuildCommunicationScopeForRecord strategy. The strategy determines — for any given context record (e.g. an Opportunity) — which related records should be searched for phone numbers and activity links (e.g. the Opportunity itself plus its related Account and Contacts).

The result is a RecordRefSets — an immutable collection of record references grouped by SObject type. Use getScope() to inspect it, excluding(Id) to narrow it, then call one of the conversion methods to continue:

• toGatherPhoneNumbersRequest() → feeds step 2 of the call path (GatherPhoneNumbersInScope)
• toGetEmailMessageIdsRequest() → feeds step 3 of the email path (GetEmailMessageIds) — emails are record-scoped, not phone-number-scoped

The same scope response can feed both paths independently.

Request

Construct the Request directly and pass it to the handler:

BuildScopeForRecord.IHandler handler =
    BuildScopeForRecord.construct(SharingRule.WithSharing);

BuildScopeForRecord.Response scopeResult =
    handler.execute(new BuildScopeForRecord.Request(recordId));

The SharingRule passed to construct() is forwarded to the BuildCommunicationScopeForRecord strategy — use WithSharing to respect the running user's CRM record visibility when the strategy queries related records.

Response

Both conversion methods can be called on the same Response independently — the scope is not consumed.

Testing

MockBuildScopeForRecord is a package-provided test double. Call use() to install it for the current test transaction, then returning() to configure the scope it will produce. The real strategy and scope-building logic are bypassed entirely.

@isTest
static void myTest() {
    MockBuildScopeForRecord.use()
        .returning(RecordRefSets.empty());

    // Your code that calls BuildScopeForRecord receives the configured scope.
    MyService.run(someRecordId);
}

The mock ignores the input record ID and always returns the configured RecordRefSets. Use RecordRefSets.empty() when scope contents do not affect the assertion being made, or supply a populated scope to drive downstream behaviour.