Passen Sie die zugrunde liegenden Datensätze Raster in Prognosen an

Verwenden Sie als Entwickler diese Referenzdokumentation, um mehr über die Ereignisse und Kontextobjekte zu erfahren und die zugrunde liegenden Datensätze Raster in Ihrer Prognose anzupassen. Mit dem Kontextobjekt können Sie Anpassungen vornehmen, z. B. das gesamte Raster oder bestimmte Felder schreibgeschützt machen, Felder deaktivieren, Fehlerbenachrichtigungen anzeigen usw.

Lizenz- und Rollenanforderungen

Anforderungstyp	Sie benötigen
Lizenz	Dynamics 365 Sales Premium oder Dynamics 365 Sales Enterprise Weitere Informationen: Dynamics 365 Sales-Preise.
Sicherheitsrollen	Systemanpasser Weitere Informationen: Vordefinierte Sicherheitsrollen für Vertrieb

Notiz

Das Prognose-Kontextobjekt, auf das in diesem Thema Bezug genommen wird, unterscheidet sich vom Ausführungskontext Microsoft Dataverse. Das Prognosekontextobjekt ist spezifisch für Prognosen und unterstützt die erweiterten Konfigurationen für die zugrunde liegenden Datensätze Raster.

Ereignisse für das zugrunde liegende Raster der Datensätze

Die folgenden Ereignisse werden in der Planung unterstützt:

• OnRowLoad
• OnSave
• OnChange

Die folgenden Beispielszenarien werden auf der Grundlage der unterstützten Handler für Ereignisse erstellt:

• Ein Raster schreibgeschützt machen durch Deaktivieren aller Felder.
• Stets nur wenige Felder auf Basis der Entität aktivieren.
• Bearbeitung von Feldern basierend auf Logik und Entität deaktivieren.
• Anzeigen einer Fehlermeldung basierend auf dem Wert.
• Blockieren Sie die automatische Speicherung auf der Basis des geschätzten Wertes mit preventDefault und öffnen Sie ein Ereignis im Fenster.

OnRowLoad Ereignis

Das Ereignis OnRowLoad wird für jeden zugrunde liegenden Datensatz ausgelöst, der in das Raster geladen wird. Das Kontextobjekt, das an den Handler für das Ereignis OnRowLoad übergeben wird, enthält APIs, die für den zugrunde liegenden Datensatz spezifisch sind.

Im Folgenden finden Sie Beispiele für Szenarien, die Sie mit dem Handler OnRowLoad durchführen können:

• Ein Raster schreibgeschützt machen durch Deaktivieren aller Felder.
• Stets nur wenige Felder auf Basis der Entität aktivieren.
• Bearbeitung von Feldern basierend auf Logik und Entität deaktivieren.

Notiz

Für die Prognosekonfiguration werden zugrunde liegende Datensätze verschiedener Entitäten angezeigt, indem das Attribut Groupby in den zugrunde liegenden Datensätzen Raster ausgewählt wird. Um die Logik auf der Grundlage dieser Entitäten zu handhaben, sehen Sie sich die Beispiele Immer nur einige Felder auf der Grundlage der Entität aktivieren und Die Bearbeitung von Feldern auf der Grundlage von Logik und Entität deaktivieren an.

OnChange-Ereignis

Das OnChange Ereignis wird ausgelöst, wenn der Wert einer Zelle in den zugrunde liegenden Datensätzen Raster aktualisiert wird und die Zelle nicht im Fokus ist.

Anmerkung

• Für die zugrunde liegenden Datensätze Raster wird jede Feldänderung Trigger OnChange und OnSave Ereignishandler, falls vorhanden, betreffen.
• Das Speichern wird nicht ausgelöst, wenn ein Feld mit einer Fehlermeldung über die Client API im OnChange-Handler festgelegt wird. Für Benachrichtigungen im Zusammenhang mit Client-APIs für die Planung gehen Sie zur API setNotification in context.getFormContext().data.entity.attributes.getByName("Attribut Name").controls.get(0).
• Es gibt keine Zuordnung zwischen Attributen und dem Handler OnChange, und jede Feldänderung löst den Handler OnChange mit dem Kontextobjektparameter aus. Um das Attribut zu identifizieren, das den Handler ausgelöst hat, verwenden Sie die Funktion getIsDirty für das Attributobjekt. Weitere Informationen: context.getFormContext().data.entity.attributes.getByName("Attribut Name")

Im Folgenden sehen Sie ein Beispielszenario, das Sie mit dem Handler OnChange ausführen können:

• Fehlerbenachrichtigung basierend auf dem Wert anzeigen.

OnSave Ereignis

Das OnSave Ereignis wird ausgelöst, wenn ein Wert in einer Zelle der zugrunde liegenden Datensätze Raster geändert wird und die Zelle nicht im Fokus ist. Existiert jedoch der Handler OnChange für dieselbe Planung, wird der Handler OnSave nach dem Handler OnChange aufgerufen.

Der OnSave Handler wird vor dem eigentlichen Speichern des Feldes aufgerufen.

Anmerkung

• Für die zugrunde liegenden Datensätze Raster wird jede Feldänderung Trigger OnChange und OnSave Ereignishandler, falls vorhanden, betreffen.
• Das Speichern wird nicht ausgelöst, wenn ein Feld mit einer Fehlermeldung über die Client API im OnSave-Handler festgelegt wird. Für Benachrichtigungen in Bezug auf die Planung von Client APIs gehen Sie zur setNotification API in context.getFormContext().data.entity.attributes.getByName("Attribut Name").controls.get(0).
• Es gibt keine Zuordnung zwischen Attributen und dem OnSave-Handler, und jede Feldänderung löst den OnSave-Handler mit dem Kontextobjektparameter aus. Um das Attribut zu identifizieren, das den Handler ausgelöst hat, verwenden Sie die Funktion getIsDirty für das Attributobjekt. Weitere Informationen: context.getFormContext().data.entity.attributes.getByName("Attribut Name")

Im Folgenden sehen Sie ein Beispielszenario, das Sie mit dem Handler OnSave ausführen können:

• Blockieren Sie die automatische Speicherung auf der Grundlage des geschätzten Wertes mit preventDefault und öffnen Sie ein Ereignis in einem Fenster.

Kontextobjekt für Ereignishandler in den zugrunde liegenden Datensätzen Raster

Das Kontextobjekt enthält eine Reihe von APIs zur Durchführung von Vorgängen, die für einen zugrunde liegenden Datensatz in einer Planung spezifisch sind. Dieses Kontextobjekt wird als Parameter an die Ereignishandler in der zugrunde liegenden Datensatzansicht Raster übergeben.

Die folgenden APIs werden unterstützt:

• context.getFormContext Methode
• context.getWebApiContext()
• context.getEventArgs().preventDefault()

Methode context.getFormContext

Gibt eine Referenz auf einen Datensatz in den zugrunde liegenden Datensätzen Raster zurück.

context.getFormContext().data.entity

Dies gibt ein Entitätsobjekt zurück und hat die folgenden Methoden:

Methode	Rückgabetyp	Beschreibung des Dataflows
getEntityName()	String	Gibt eine Zeichenfolge zurück, die den logische Namen des Entitätsdatensatz darstellt.
getId()	String	Gibt eine Zeichenfolge zurück, die den GUID-Wert für den Datensatz darstellt.
attributes	List	Gibt eine Liste von Attributen zurück, die mit der Ansicht und einer Entität verknüpft sind, die als Teil der zugrunde liegenden Datensätze Raster geladen wird. Sie können die folgenden Vorgänge durchführen: - context.getFormContext().data.entity.attributes.forEach - context.getFormContext().data.entity.attributes.getByName(arg) - context.getFormContext().data.entity.attributes.get(index)

context.getFormContext().data.entity.attributes.getByName("Attribut Name")

Dies gibt ein Attributobjekt zurück und hat die folgenden Methoden:

Methode	Rückgabetyp	Beschreibung des Dataflows
getName()	String	Gibt eine Zeichenkette zurück, die den logischen Namen des Attributs darstellt.
getValue()	--	Ruft den Datenwert für ein Attribut ab.
getIsDirty()	Boolesch	Gibt einen booleschen Wert zurück, der angibt, ob es ungespeicherte Änderungen an dem Attributwert gibt.
controls	List	Gibt eine Liste von Steuerelementen für jedes Attributobjekt zurück. Anmerkung: Die Länge der Objektliste controls ist immer 1, und get(0) kann direkt verwendet werden.

context.getFormContext().data.entity.attributes.getByName("Attribut Name").controls.get(0)

Dies gibt ein Steuerelement zurück, das dem Attribut zugeordnet ist, und hat die folgenden Methoden:

Methode	Rückgabetyp	Beschreibung des Dataflows
getDisabled()	Boolesch	Gibt zurück, ob das Steuerelement deaktiviert ist.
setDisabled(bool)	--	Legt den deaktivierten Wert (wahr oder falsch) für das Steuerelement fest.
setNotification(message: string, uniqueId?: string)	Boolesch	Zeigt eine Fehlermeldung für das Steuerelement an, um anzugeben, dass Daten ungültig sind. Bei dieser Methode wird neben dem Steuerelement in der Zelle ein rotes Symbol mit einem Kreuz angezeigt. Wenn Sie den Mauszeiger über das Symbol für Fehler bewegen, wird die entsprechende Nachricht angezeigt. Wenn Sie das Symbol für Fehler wählen, wird die Zeile neu geladen und alle Änderungen werden rückgängig gemacht. Die uniqueId wird verwendet, um diese Nachricht zu löschen, wenn Sie die clearNotification-Methode verwenden.
clearNotification(uniqueId?: string)	Boolesch	Entfernt eine Nachricht, die bereits für ein Steuerelement angezeigt wird. Wenn keine eindeutige ID angegeben wird, werden alle Benachrichtigungen für dieses Steuerelement entfernt.

Notiz

Wir empfehlen, dass die Funktionsnamen in der JavaScript-Datei mit den Namen der Ereignisse übereinstimmen und den Parameter des Kontextobjekts akzeptieren müssen.

Beispiel 1:

Erstellen wir einen JavaScript-Code, um alle Felder in den zugrunde liegenden Datensätzen Raster als NUR-LESEBAR festzulegen. Außerdem rufen wir die Funktion OnRowLoad für jede Zeile auf, wenn das Raster erfolgreich geladen und gespeichert wurde.

function OnRowLoad(executionContext) {
    // Iterating through all attributes and disabling it.
    executionContext.getFormContext().data.entity.attributes.forEach(
        attribute => {
            attribute.controls.get(0).setDisabled(true);
        }
    )
}

Beispiel 2:

Wir erstellen JavaScript-Code, um alle Felder bis auf einige wenige nur für die Entität Verkaufschancen zu deaktivieren. Außerdem rufen wir die Funktion OnRowLoad für jede Zeile auf, wenn das Raster erfolgreich geladen und gespeichert wurde.

function OnRowLoad(executionContext) {

    // Get the logical name of the loaded entity as part of underlying records grid.
    var entityName = executionContext.getFormContext().data.entity.getEntityName();

    if (entityName === "opportunity") {

        // Defining the attributes list from opportunity that has to be enabled if loaded as part of view.
        var OPTY_ENABLE_ATTRS_LIST = ["name", "msdyn_forecastcategory", "actualvalue", "actualclosedate", "estimatedvalue", "estimatedclosedate"];

        executionContext.getFormContext().data.entity.attributes.forEach(
            attribute => {
                // Disabling all attributes other than OPTY_ENABLE_ATTRS_LIST
                if (!OPTY_ENABLE_ATTRS_LIST.includes(attribute.getName())) {
                    attribute.controls.get(0).setDisabled(true);
                }
            }
        )        
    }
}

Beispiel 3:

Wir erstellen JavaScript-Code, um verschiedene Entitäten für die geladene Konfiguration der Planung zu behandeln.

Für eine Verkaufschance-Entität wird das Skript Folgendes deaktivieren:

• Spalte Name
• actualRevenue und actualCloseData, wenn der forecastCategory-Wert best case, committed, omitted oder Pipeline ist.
• estimatedRevenue und estimatedCloseDate, wenn der forecastCategory-Wert gewonnen oder verloren ist.

In ähnlicher Weise deaktiviert das Script die Namensspalte für die Entität Konto und alle Spalten für andere Entitäten.

Außerdem rufen wir die Funktion OnRowLoad für jede Zeile auf, wenn das Raster erfolgreich geladen und gespeichert wurde.

function OnRowLoad(executionContext) {
		 
    // Get the logical name of the loaded entity as part of underlying records grid.
    var entityName = executionContext.getFormContext().data.entity.getEntityName();
    
    // If loaded logical name of entity in underlying records grid is opportunity.
    if (entityName === "opportunity") {
        
       var allAttrs = executionContext.getFormContext().data.entity.attributes;

       // Disable column name for all records if exists in the view.
       var nameAttr = allAttrs.getByName("name");
       if (nameAttr) {
           nameAttr.controls.get(0).setDisabled(true);
       }

       var fcatAttr = allAttrs.getByName("msdyn_forecastcategory");
       if (fcatAttr) {
           // Disable actualRevenue, actualCloseDate for forecastcategory Bestcase, committed, omitted, or pipeline.
           if (fcatAttr.getValue() <= 100000004 && fcatAttr.getValue() >= 100000001) {
                   var actualRevenueAttr = allAttrs.getByName("actualvalue");
                   var actualCloseDateAttr = allAttrs.getByName("actualclosedate");
                   if (actualRevenueAttr) actualRevenueAttr.controls.get(0).setDisabled(true);
                   if (actualCloseDateAttr) actualCloseDateAttr.controls.get(0).setDisabled(true);
           }
           // Disable estimatedRevenue, estimatedCloseDate for forecastCategory won or lost.
           else if (fcatAttr.getValue() == 100000005 || fcatAttr.getValue() == 100000006) {
                   var estimatedRevenueAttr = allAttrs.getByName("estimatedvalue");
                   var estimatedCloseDateAttr = allAttrs.getByName("estimatedclosedate");
                   if (estimatedRevenueAttr) estimatedRevenueAttr.controls.get(0).setDisabled(true);
                   if (estimatedCloseDateAttr) estimatedCloseDateAttr.controls.get(0).setDisabled(true);
           }
       }
   } 
   
   // Else disable name column, if loaded logical name of entity is Account.
   else if (entityName === "account"){
       var attrNameObj = executionContext.getFormContext().data.entity.attributes.getByName("name");
       if (attrNameObj) {
               attrNameObj.controls.get(0).setDisabled(true);
       }
   } 
   
   // For all other entities
   else {
       executionContext.getFormContext().data.entity.attributes.forEach(
           attribute => {
               attribute.controls.get(0).setDisabled(true);
           }
       )
   }
}

Beispiel 4:

Erstellen wir eine JavaScript-Validierungsdatei, die das Speichern blockiert und eine Fehlermeldung in der Spalte für den geschätzten Umsatz anzeigt, wenn der Wert unter 10 liegt. Außerdem entfernen wir die Fehlermeldung und lassen das Sichern zu, wenn der Wert der Spalte mit dem geschätzten Umsatz auf einen Wert größer oder gleich 10 korrigiert wird. Hier wird die OnChange Funktion aufgerufen, wenn der Wert eines beliebigen Felds in den zugrunde liegenden Datensätzen Raster einer Prognose aktualisiert wird.

// OnChange function is invoked when any field's value is updated on the underlying records grid of the forecast
function OnChange(executionContext) {

    let entity = executionContext.getFormContext().data.entity;

    // Verify the logical name of the entity and load as part of the underlying records grid.
    if (entity.getEntityName() === "opportunity") {

        // Verify estimated revenue value
        let estValAttr = entity.attributes.get("estimatedvalue");

        // Verify if this attribute exists within the grid view and changed
        if(estValAttr && estValAttr.getIsDirty()) 
        {
            if(estValAttr.getValue() < 10){

                // This will show an error icon next to the estimated revenue field. On hovering over the icon, the below provided message is displayed.
                // Any save attempts are blocked by the system until all notifications are cleared from the columns.
                estValAttr.controls.get(0).setNotification("Estimated revenue cannot be less than 10");
            }
            else{
                // Clearing notifications to save.
                estValAttr.controls.get(0).clearNotification();
            }
        }
    }
}

context.getWebApiContext()

Dieser gibt ein webApiContext-Objekt zurück und hat die folgenden Methoden:

Methode	Beschreibung des Dataflows
retrieveRecord(entityLogicalName, id, options) then (successCallback, errorCallback);	Ruft einen Entitätsdatensatz ab. Weitere Informationen: Datensatz abrufen (Client API-Referenz)
updateRecord(entityLogicalName, id, data) then(successCallback, errorCallback);	Aktualisiert einen Entitätsdatensatz. Weitere Informationen: updateRecord (Client API Referenz)
createRecord(entityLogicalName, data) then(successCallback, errorCallback);	Erstellt einen Entitätsdatensatz. Weitere Informationen: createRecord (Client API Referenz)
deleteRecord(entityLogicalName, id) then(successCallback, errorCallback);	Löscht einen Entitätsdatensatz. Weitere Informationen: Datensatz löschen (Client API-Referenz)

context.getEventArgs().preventDefault()

Die Methode preventDefault() ist nur innerhalb des Ereignisses OnSave verfügbar. Der Aufruf dieser Methode innerhalb von OnSave verhindert, dass das Ereignis „Speichern“ fortgesetzt wird.

Beispiel:

Erstellen wir ein JavaScript-Beispiel, um das Raster der Verkaufschancen zu öffnen, das Ereignis für das automatische Speichern zu blockieren und eine Warnung zu öffnen, wenn der geschätzte Umsatz unter 10 liegt. Außerdem lassen wir das Ereignis „Automatisches Speichern“ zu, wenn der geschätzte Umsatz größer als oder gleich 10 ist.

// OnSave function will be invoked whenever grid attempts to save changes made to any field. 
function OnSave(executionContext){

    let entity = executionContext.getFormContext().data.entity;

    // Verify the logical name of the entity and load as part of the underlying records grid.
    if (entity.getEntityName() === "opportunity") {

        // Verify estimated revenue value
        var estValAttr = entity.attributes.get("estimatedvalue");

        if(estValAttr && estValAttr.getIsDirty() && estValAttr.getValue() < 10){

            // This call will prevent the save event from proceeding
            executionContext.getEventArgs().preventDefault(); 
            alert("Estimated revenue cannot be less than 10");

        }
    }
}

Verwandte Informationen

Zugrundeliegende Datensätze anpassen Raster