Apex-Integration

Eine Apex-Abschlussaktion übergibt Zielgruppenergebnisse an benutzerdefinierte Apex-Logik. Verwenden Sie für neue Implementierungen FinalAction_ManagedAsync_Interface. Campaign Audience Builder übernimmt dann die asynchrone Batch-Verarbeitung und ruft Ihre Logik einmal für jeden Bereich von Zielgruppendatensätzen auf.

Schnittstelle auswählen

Schnittstelle	Verwendung	Verantwortlich für asynchrone Verarbeitung
`lb.FinalAction_ManagedAsync_Interface`	Sie erstellen eine neue Abschlussaktion. Dies ist die empfohlene, Heap-sichere Integration.	Campaign Audience Builder
`lb.FinalAction_Interface`	Sie benötigen ausdrücklich die vollständige Kontrolle über die asynchrone Orchestrierung und übernehmen Batch-Verarbeitung, Laden der Quelldaten, Wiederholungsversuche und Benachrichtigungen selbst. Dies ist die Legacy-Schnittstelle.	Ihre Apex-Klasse

Die Legacy-Schnittstelle wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt. Wählen Sie sie nicht nur deshalb aus, weil sie in einem älteren Beispiel verwendet wird.

Empfohlen: Verwaltete asynchrone Ausführung

Implementieren Sie lb.FinalAction_ManagedAsync_Interface und ihre einzige Instanzmethode:

global interface FinalAction_ManagedAsync_Interface {
    void runSync(String actionApiName, Map<String, Object> args);
}

Trotz ihres Namens ist die Methode runSync auch der Einstiegspunkt für verwaltete asynchrone Arbeit. Bei einer kleinen Zielgruppe kann CAB sie einmal in der initiierenden Transaktion aufrufen. Bei einer größeren Zielgruppe startet CAB eine paketverwaltete Verarbeitung und ruft sie einmal pro Bereich auf.

Ihre Klasse muss global sein, einen zugänglichen parameterlosen Konstruktor besitzen und runSync als Instanzmethode implementieren. Fügen Sie für die verwaltete Schnittstelle weder runAsync hinzu noch implementieren Sie Database.Batchable.

Beispiel

Dieses Beispiel aktualisiert ein Feld, das die Person beim Ausführen der Abschlussaktion auswählt. Das Setzen eines Felds auf einen ausgewählten Wert kann sicher wiederholt werden, falls Salesforce einen Bereich erneut verarbeitet.

global with sharing class DynamicFieldUpdate_FinalActionImpl
        implements lb.FinalAction_ManagedAsync_Interface {

    global DynamicFieldUpdate_FinalActionImpl() {}

    global void runSync(String actionApiName, Map<String, Object> args) {
        List<SObject> results = (List<SObject>) args.get(
            lb.FinalAction.Variable.AUDIENCE_RESULTS.name()
        );

        if (results == null || results.isEmpty()) {
            return;
        }

        String fieldName = (String) args.get('fieldName');
        Schema.SObjectField field = results[0]
            .getSObjectType()
            .getDescribe()
            .fields
            .getMap()
            .get(fieldName);

        if (field == null || !field.getDescribe().isUpdateable()) {
            throw new IllegalArgumentException(
                'The selected field is not available for update.'
            );
        }

        Object value = castValue(field.getDescribe().getSOAPType(), args.get('value'));
        for (SObject result : results) {
            result.put(fieldName, value);
        }
        update results;
    }

    private static Object castValue(Schema.SoapType dataType, Object value) {
        switch on dataType {
            when Boolean {
                return Boolean.valueOf(value);
            }
            when Integer {
                return Integer.valueOf(value);
            }
            when Double {
                return Double.valueOf(value);
            }
            when else {
                return value;
            }
        }
    }

}

Verhalten der verwalteten Ausführung

CAB lädt nur die Zielgruppendatensätze und Felder, die für den aktuellen Bereich benötigt werden. Je nach Situation kann CAB aus dem aktuellen Zielgruppen-Snapshot, dem Platform Cache oder dauerhaft gespeicherten Zielgruppenmitgliedsdatensätzen lesen.
AUDIENCE_RESULTS enthält bei einem synchronen Aufruf die vollständige Ergebnisliste und bei einem verwalteten asynchronen Aufruf den aktuellen Bereich.
CAB erstellt für jeden asynchronen Bereich eine neue Klasseninstanz und eine neue Argument-Map. Speichern Sie keinen Zustand zwischen runSync-Aufrufen.
Implementieren Sie runSync so, dass gewöhnliche Batch-Wiederholungen sicher sind. Callouts werden unterstützt. Ein Callout, der teilweise erfolgreich ist und anschließend eine Ausnahme auslöst, kann bei der Wiederholung eines Bereichs erneut ausgeführt werden.
CAB verwaltet die zutreffenden Abschlussbenachrichtigungen. Die Klasse sollte keine zweite Abschlussbenachrichtigung senden, sofern dies nicht ausdrücklich Teil ihrer Geschäftslogik ist.
Snapshot-basierte Teilmengenaktionen verwenden die verwaltete Schnittstelle. Die Legacy-Schnittstelle besitzt keinen Einstiegspunkt für solche Teilmengen-Snapshots.

Argumente

args enthält vordefinierte CAB-Werte und die benutzerdefinierten Eingabevariablen, die für die Abschlussaktion konfiguriert wurden.

Schlüssel	Wert
`AUDIENCE_VERSION_ID`	Die ID der verarbeiteten Zielgruppen-Version.
`AUDIENCE_RESULTS`	Die Zielgruppendatensätze für diesen Aufruf. Bei der verwalteten asynchronen Ausführung ist dies der aktuelle Bereich und nicht die gesamte Zielgruppe.
`BATCH_SIZE`	Die für die Abschlussaktion konfigurierte Batch-Größe.
`GET_SUBSET`	Gibt an, ob sich die Anforderung auf eine Teilmenge der Zielgruppe bezieht.
`NOTIFY_WHEN_DONE`	Gibt an, ob der Aufrufer eine Abschlussbenachrichtigung angefordert hat. CAB übernimmt diese Benachrichtigung bei der verwalteten asynchronen Ausführung.

Diese Schlüssel sind über lb.FinalAction.Variable verfügbar. Wenn eine benutzerdefinierte Eingabe für AUDIENCE_RESULTS konfiguriert ist, aktualisiert CAB diese Eingabe bei jedem verwalteten asynchronen Aufruf ebenfalls mit dem aktuellen Bereich.

Abschlussaktion konfigurieren

Öffnen Sie CAB-Einstellungen, wechseln Sie zu Konfigurieren → Automatisierung und suchen Sie Abschlussaktionen.
Wählen Sie Neu.
Geben Sie den Name der Abschlussaktion und den API-Name der Abschlussaktion ein.
Setzen Sie Typ auf Apex.
Wählen Sie unter Apex-Klasse eine Klasse aus, die lb.FinalAction_ManagedAsync_Interface oder die Legacy-Schnittstelle lb.FinalAction_Interface implementiert.
Geben Sie unter den verfügbaren Eigenschaften und erweiterten Einstellungen optional eine Beschreibung, Erfolgsmeldung und einen Name der benutzerdefinierten Berechtigung ein.
Legen Sie die Batch-Größe fest. Sie ist sowohl die maximale Ergebnisanzahl, die CAB synchron zu verarbeiten versucht, als auch die maximale Anzahl von Datensätzen, die CAB an einen verwalteten asynchronen runSync-Bereich übergibt. Der Standardwert beträgt 500.
Wählen Sie das Zielgruppen-Objekt aus, das von Ihrer Logik unterstützt wird. Die Aktion steht nur für Zielgruppen mit diesem Ergebnisobjekt zur Verfügung.
Fügen Sie alle Zielgruppenfelder hinzu, die Ihre Apex-Logik liest. Id ist immer enthalten.
Definieren Sie alle benutzerdefinierten Eingabevariablen, die beim Ausführen der Aktion ausgefüllt werden sollen. Der Eingabename wird zum entsprechenden Schlüssel in args.
Speichern und aktivieren Sie die Abschlussaktion.

Erstellen Sie für das obige Beispiel die Eingabevariablen fieldName und value. Die Klasse verwendet ihre API-Namen als Schlüssel in der Argument-Map.

Legacy: Asynchrone Orchestrierung mit vollständiger Kontrolle

Verwenden Sie lb.FinalAction_Interface nur, wenn Sie eine Kontrolle benötigen, die der verwaltete Ausführungslebenszyklus nicht bietet. Typische Gründe sind eine benutzerdefinierte Queueable-Kette, die Orchestrierung externer Jobs, spezielle Prüfpunkte oder ein eigenes Abschlussverhalten.

global interface FinalAction_Interface {
    void runSync(String actionApiName, Map<String, Object> args);
    void runAsync(String actionApiName, Map<String, Object> args);
}

Bei dieser Schnittstelle gilt:

CAB ruft Ihre Methode runAsync auf, wenn die Ergebnisanzahl die konfigurierte Batch-Größe überschreitet.
Ihre Klasse ist für den gesamten asynchronen Lebenszyklus verantwortlich, einschließlich Laden der Datensätze, Batch-Verarbeitung oder Verkettung, Wiederholungsversuchen, Limitbehandlung und Benachrichtigungen.
Der asynchrone Aufruf stellt unter AUDIENCE_RESULTS keine materialisierte Zielgruppe bereit. Ihre Orchestrierung muss den richtigen Zielgruppenbereich laden.
lb.FinalAction.getFinalActionQueryLocator(...) ist eine Kompatibilitätshilfe und nicht die empfohlene Strategie für große Zielgruppen. Im Platform-Cache-Modus materialisiert die Methode die gesamte Zielgruppe im Heap, bevor sie einen Query Locator zurückgibt, und ist deshalb für große Zielgruppen nicht sicher.
Der Snapshot-basierte Versand von Teilmengen wird von der Legacy-Schnittstelle nicht unterstützt.

Implementieren Sie nicht beide Schnittstellen, um deren Verhalten zu kombinieren. Wenn eine Klasse beide implementiert, gibt CAB der verwalteten Schnittstelle bei der asynchronen Verarbeitung Vorrang.

Legacy-Klasse migrieren

So übernehmen Sie die verwaltete asynchrone Ausführung:

Ersetzen Sie lb.FinalAction_Interface durch lb.FinalAction_ManagedAsync_Interface.
Entfernen Sie runAsync, Database.Batchable, die Einrichtung des Query Locators und eigenen Benachrichtigungscode.
Behalten Sie die Geschäftsoperation in der Instanzmethode runSync und verarbeiten Sie nur die Datensätze aus AUDIENCE_RESULTS.
Stellen Sie sicher, dass die Operation sicher wiederholt werden kann und nicht vom Zustand eines früheren Bereichs abhängt.
Prüfen Sie die konfigurierte Batch-Größe mit repräsentativen Daten.

Abschlussaktion ausführen

Nach der Aktivierung steht die Abschlussaktion im Aktionsmenü der Zielgruppenergebnisse zur Verfügung, wenn Zielgruppen-Objekt und Benutzerberechtigungen mit ihrer Konfiguration übereinstimmen. Prüfen Sie Beschreibung und Eingabewerte und wählen Sie anschließend Ausführen. CAB führt kleine Aktionen sofort aus und verschiebt größere oder Snapshot-basierte Teilmengenaktionen in die Hintergrundverarbeitung.