Anpassen des zugrunde liegenden Datensatzrasters in Prognosen

Verwenden Sie als Entwickler diese Referenzdokumentation, um mehr über die Ereignisse und das Kontextobjekt zu erfahren, mit dem Sie das zugrunde liegende Datensatzraster in Ihrer Prognose anpassen können. Sie können das Kontextobjekt verwenden, um Anpassungen vorzunehmen, z. B. das gesamte Raster oder bestimmte Felder schreibgeschützt zu machen, Felder zu deaktivieren, Fehlerbenachrichtigungen anzuzeigen usw.

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 die zugrunde liegenden Datensätze verschiedener Entitäten angezeigt, indem das Groupby-Attribut im zugrunde liegenden Datensatzraster 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 im zugrunde liegenden Datensatzraster aktualisiert wird und die Zelle nicht im Fokus ist.

Anmerkung

• Für das zugrunde liegende Datensatzraster löst jede Feldänderung OnChange und OnSave Ereignishandler aus (sofern vorhanden).
• 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 einer Zelle im zugrunde liegenden Datensatzraster aktualisiert 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 das zugrunde liegende Datensatzraster löst jede Feldänderung OnChange und OnSave Ereignishandler aus (sofern vorhanden).
• 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 dem zugrunde liegenden Datensatzraster

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 Datensatzrasteransicht übergeben.

Die folgenden APIs werden unterstützt:

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

Methode context.getFormContext

Gibt einen Verweis auf einen Datensatz im zugrunde liegenden Datensatzraster 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 sich auf die Ansicht und eine Entität beziehen, die als Teil des zugrunde liegenden Datensatzrasters 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:

Lassen Sie uns JavaScript Code erstellen, um alle Felder im zugrunde liegenden Datensatzraster schreibgeschützt zu machen. 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 bester Fall, bestätigt, übersprungen 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 Felds im zugrunde liegenden Datensatzraster 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

Zugrunde liegende Datensätzeraster anpassen