Udostępnij za pośrednictwem

Dostosowywanie siatki rekordów bazowych w prognozach

Jako deweloper skorzystaj z tej dokumentacji referencyjnej, aby dowiedzieć się więcej o zdarzeniach i obiekcie kontekstu, a następnie dostosować siatkę rekordów bazowych w prognozie. Za pomocą obiektu kontekstu można wykonywać dostosowania, takie jak tworzenie całej siatki lub określonych pól tylko do odczytu, wyłączanie pól, wyświetlanie powiadomień o błędach itd.

Zdarzenia dla siatki rekordów bazowych

Następujące zdarzenia są obsługiwane w prognozowaniu:

Następujące scenariusze przykładów są tworzone na podstawie procedur obsługi zdarzeń:

Zdarzenie OnRowLoad

Zdarzenie OnRowLoad jest wyzwalane dla każdego rekordu bazowego załadowanego w siatce. Obiekt kontekstu przekazany do procedury obsługi zdarzeń OnRowLoad zawiera interfejsy API specyficzne dla bazowego rekordu.

Poniżej przedstawiono przykładowe scenariusze, które można wykonać przy użyciu procedury obsługi OnRowLoad:

Uwaga / Notatka

W przypadku konfiguracji prognozy podstawowe rekordy różnych encji są wyświetlane po wybraniu atrybutu Grupuj w siatce rekordów bazowych. Aby obsłużyć logikę opartą na tych encjach, zobacz przykłady Zawsze włączaj tylko kilka pól na podstawie encji i Wyłącz edytowanie pól na podstawie logiki i encji.

Zdarzenie OnChange

Zdarzenie OnChange jest wyzwalane, gdy wartość komórki w siatce rekordów bazowych jest aktualizowana i komórka jest poza fokusem.

Uwaga / Notatka

  • W przypadku siatki rekordów bazowych każda zmiana pola będzie wyzwalać procedury obsługi zdarzeń OnChange i OnSave, jeśli istnieją.
  • Zapisywanie nie zostanie wyzwolone, jeśli pole zostanie ustawione z powiadomieniami o błędzie przy użyciu interfejsu API klienta w procedurze obsługi zdarzeń OnChange. W przypadku powiadomień związanych z interfejsami API klienta prognozowania przejdź do interfejsu API setNotification w pliku context.getFormContext().data.entity.attributes.getByName("Attribute Name").controls.get(0).
  • Nie ma mapowania między atrybutami procedury obsługi OnChange, a każda zmiana pola wyzwoli procedurę obsługi OnChange z parametrem obiektu kontekstu. Aby zidentyfikować atrybut, który wyzwolił procedurę obsługi, użyj funkcji getIsDirty w obiekcie atrybutu. Więcej informacji: context.getFormContext().data.entity.attributes.getByName("Attribute Name")

Poniżej przedstawiono przykładowy scenariusz, które można wykonać przy użyciu procedury obsługi OnChange:

Zdarzenie OnSave

Zdarzenie OnSave jest wyzwalane, gdy wartość zmieni się w komórce siatki rekordów bazowych i komórka jest poza fokusem. Jeśli jednak procedura obsługi OnChange istnieje dla tej samej konfiguracji prognozy, procedura obsługi OnSave jest wywoływana po procedurze obsługi OnChange.

Procedura obsługi OnSave jest wywoływana przed rzeczywistym zapisaniem pola.

Uwaga / Notatka

  • W przypadku siatki rekordów bazowych każda zmiana pola będzie wyzwalać procedury obsługi zdarzeń OnChange i OnSave, jeśli istnieją.
  • Zapisywanie nie zostanie wyzwolone, jeśli pole zostanie ustawione z powiadomieniami o błędzie przy użyciu interfejsu API klienta w procedurze obsługi OnSave. W przypadku powiadomienia związanego z interfejsami API klienta prognozowania przejdź do interfejsu API setNotification w pliku context.getFormContext().data.entity.attributes.getByName("Attribute Name").controls.get(0).
  • Nie ma mapowania między atrybutami procedury obsługi OnSave, a każda zmiana pola wyzwoli procedurę obsługi OnSave z parametrem obiektu kontekstu. Aby zidentyfikować atrybut, który wyzwolił procedurę obsługi, użyj funkcji getIsDirty w obiekcie atrybutu. Więcej informacji: context.getFormContext().data.entity.attributes.getByName("Attribute Name")

Poniżej przedstawiono przykładowy scenariusz, które można wykonać przy użyciu procedury obsługi OnSave:

Obiekt kontekstu dla procedur obsługi w siatce rekordów bazowych

Obiekt kontekstu zawiera zestaw interfejsów API do wykonywania operacji specyficznych dla rekordu bazowego w prognozie. Ten obiekt kontekstu jest przekazywany jako parametr do procedur obsługi w widoku siatki rekordów bazowych.

Obsługiwane są następujące interfejsy API:

Metoda context.getFormContext

Zwraca odwołanie do rekordu w siatce rekordów bazowych.

context.getFormContext().data.entity

Zwraca obiekt encji i ma następujące metody:

Metoda Typ Zwrot Description
getEntityName() Sznurek Zwraca ciąg reprezentujący nazwę logiczną encji dla rekordu.
getId() Sznurek Zwraca ciąg reprezentujący wartość identyfikatora GUID rekordu.
attributes List Zwraca listę atrybutów powiązanych z widokiem i encją załadowaną jako część siatki rekordów bazowych. Możesz wykonać następujące operacje:
- 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("Attribute Name")

Zwraca encję atrybutu i ma następujące metody:

Metoda Typ Zwrot Description
getName() Sznurek Zwraca ciąg reprezentujący nazwę logiczną atrybutu.
getValue() -- Pobiera wartość danych atrybutu.
getIsDirty() logiczny Zwraca wartość logiczną wskazującą, czy istnieją niezapisane zmiany wartości atrybutu.
controls List Zwraca listę kontrolek dla każdego obiektu atrybutu.
Uwaga: controls długość listy obiektów zawsze wynosi 1 i get(0) może być używana bezpośrednio.

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

Powoduje to zwrócenie mapowania obiektu kontrolki na atrybut i ma następujące metody:

Metoda Typ Zwrot Description
getDisabled() logiczny Zwraca informację, czy kontrolka jest wyłączona.
setDisabled(bool) -- Ustawia wartość wyłączoną (prawda lub fałsz) na kontrolkę.
setNotification(message: string, uniqueId?: string) logiczny Wyświetla komunikat o błędzie kontrolki wskazujący, że dane są nieprawidłowe. Gdy ta metoda jest używana, obok kontrolki w komórce pojawi się czerwona ikona krzyżyka. Umieszczenie wskaźnika myszy na ikonie błędu spowoduje wyświetlenie podanego komunikatu. Wybranie ikony błędu spowoduje ponowne załadowanie wiersza i cofnięcie wszelkich zmian. Element uniqueId służy do czyszczenia tego komunikatu podczas korzystania z metody clearNotification.
clearNotification(uniqueId?: string) logiczny Usuwa komunikat, który jest już wyświetlany dla kontrolki. Jeśli nie podano unikatowego identyfikatora, wszystkie powiadomienia dotyczące tej kontrolki zostaną usunięte.

Uwaga / Notatka

Zalecamy, aby nazwy funkcji w pliku JavaScript były zgodne z nazwami zdarzeń i akceptowały parametr obiektu kontekstu.

Przykład 1:

Utwórzmy kod JavaScript, aby wszystkie pola w siatce rekordów bazowych były dostępne TYLKO DO ODCZYTU. Ponadto wywołamy funkcję OnRowLoad dla każdego wiersza, gdy siatka zostanie załadowana i zapisana pomyślnie.

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

Przykład 2:

Utwórzmy kod JavaScript, aby wyłączyć wszystkie pola z wyjątkiem kilku tylko dla encji Szansa sprzedaży. Ponadto wywołamy funkcję OnRowLoad dla każdego wiersza, gdy siatka zostanie załadowana i zapisana pomyślnie.

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);
                }
            }
        )        
    }
}

Przykład 3:

Utwórzmy kod JavaScript do obsługi różnych encji dla załadowanej konfiguracji prognozy.

W przypadku encji Szansa sprzedaży skrypt wyłączy następujące elementy:

  • Kolumna nazw
  • actualRevenue i actualCloseData, jeśli wartość forecastCategory to najlepszy przypadek, zatwierdzone, pominięte lub potok.
  • estimatedRevenue i estimatedCloseDate, jeśli wartość forecastCategory to szansa wygrana lub utracona.

Podobnie, skrypt wyłączy kolumnę nazwy dla encji konta i wyłączy wszystkie kolumny dla innych encji.

Ponadto wywołamy funkcję OnRowLoad dla każdego wiersza, gdy siatka zostanie załadowana i zapisana pomyślnie.


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);
           }
       )
   }
}

Przykład 4:

Utwórzmy plik JavaScript weryfikacji, który zablokuje zapisanie i wyświetli powiadomienie o błędzie w kolumnie szacowanego przychodu, gdy wartość jest mniejsza niż 10. Ponadto usuniemy powiadomienie o błędzie i zezwolimy na zapisanie, gdy szacowana wartość kolumny przychodów zostanie poprawiona jako większa lub równa 10. W tym miejscu funkcja OnChange jest wywoływana, gdy wartość dowolnego pola jest aktualizowana w siatce rekordów bazowych prognozy.


// 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()

Zwraca obiekt webApiContext i ma następujące metody:

Metoda Description
retrieveRecord(entityLogicalName, id, options)
then (successCallback, errorCallback);		 Pobiera rekord encji. Więcej informacji: retrieveRecord (odwołanie do interfejsu API klienta)
updateRecord(entityLogicalName, id, data)
then(successCallback, errorCallback);		 Aktualizuje rekord encji. Więcej informacji: updateRecord (odwołanie do interfejsu API klienta)
createRecord(entityLogicalName, data)
then(successCallback, errorCallback);		 Tworzy rekord encji. Więcej informacji: createRecord (odwołanie do interfejsu API klienta)
deleteRecord(entityLogicalName, id)
then(successCallback, errorCallback);		 Usuwa rekord encji. Więcej informacji: deleteRecord (odwołanie do interfejsu API klienta)

context.getEventArgs().preventDefault()

Metoda preventDefault() jest dostępna tylko w ramach zdarzenia OnSave. Wywołanie tej metody w OnSave uniemożliwia kontynuowanie zdarzenia zapisywania.

Przykład:

Utwórzmy przykładowy kod JavaScript, aby otworzyć siatkę szans sprzedaży, a następnie zablokować zdarzenie zapisywania automatycznego i otworzyć alert okna, jeśli szacowana wartość przychodu będzie mniejsza niż 10. Ponadto zezwolimy na automatyczne zapisywanie zdarzenia, jeśli szacowana wartość przychodu będzie większa lub równa 10.

// 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");

        }
    }
}

Dostosuj podrzędną siatkę rekordów

  • Last updated on