Panoramica

Questa documentazione descrive il processo di migrazione dalla gestione agenti legacy al nuovo sistema basato su Salesperson Set ID. La migrazione è necessaria per passare da un modello di dati ridondante a uno normalizzato, con significativi vantaggi in termini di spazio su disco e performance.

Attivazione della Migrazione

Il processo di migrazione si compone di due fasi:

Fase 1 (Opzionale ma Consigliata per Volumi di Dati Elevati): Pre-calcolo tramite Job Queue

  • Calcola gradualmente i valori “Salesperson Set ID” in anticipo
  • Può essere eseguita durante il normale orario lavorativo con minimo impatto sugli utenti
  • Riduce significativamente il tempo richiesto per la Fase 2

Fase 2 (Obbligatoria): Migrazione finale tramite attivazione feature flag in Eos Admin Library (EAL)

  • Completa la migrazione al nuovo modello dati
  • Esegue il cambio definitivo della struttura dati

Importante:

  • La migrazione è considerata completa solo quando l’intero processo avviato dall’attivazione del feature flag EAL termina con successo.
  • La migrazione viene eseguita per company: ogni company nell’ambiente richiede una migrazione indipendente.
  • È responsabilità del consulente testare accuratamente la migrazione in un ambiente non di produzione prima di eseguirla in produzione.

Differenze tra Sistema Legacy e Nuovo Sistema

Sistema Legacy

Nel sistema legacy, la gestione degli agenti (ruoli e salesperson) veniva replicata per ogni singola entità gestita dall’app Commissions (CMS):

┌─────────────────────────────────────────────────────────────────────┐
│                        SISTEMA LEGACY                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Customer "CUST001"                                                 │
│    └── EOS Add. Salesperson/Purchaser                               │
│          ├── Role: AGENT1, Salesperson: SP001                       │
│          └── Role: AGENT2, Salesperson: SP002                       │
│                                                                     │
│  Sales Header "INV-0001"                                            │
│    └── EOS Add. Salesperson/Purchaser                               │
│          ├── Role: AGENT1, Salesperson: SP001  ◄── DUPLICATO        │
│          └── Role: AGENT2, Salesperson: SP002  ◄── DUPLICATO        │
│                                                                     │
│  Sales Line "INV-0001, Line 10000"                                  │
│    └── EOS Add. Salesperson/Purchaser                               │
│          ├── Role: AGENT1, Salesperson: SP001  ◄── DUPLICATO        │
│          └── Role: AGENT2, Salesperson: SP002  ◄── DUPLICATO        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Limiti del sistema legacy:

  • Ridondanza dei dati: lo stesso set di ruoli/agenti viene memorizzato N volte
  • Spazio su disco elevato: crescita esponenziale dello storage
  • Performance degradate: query lente su tabelle con milioni di record
  • Manutenzione complessa: aggiornamenti che richiedono modifiche su più record

Nuovo Sistema (Dimension-like)

Il nuovo sistema adotta un approccio simile alla gestione dimensioni di Business Central. Ad ogni combinazione univoca di ruoli e agenti viene assegnato un ID intero univoco (Salesperson Set ID). Le entità gestite dalla CMS memorizzano solo questo ID.

```
┌────────────────────────────────────────────────────────────────────┐
│                        NUOVO SISTEMA                               │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  EOS010 Role-Salesperson Sets (tabella normalizzata)         │  │
│  │  ┌────┬────────────┬─────────────────┐                       │  │
│  │  │ ID │ Salesp.Role│ Salesperson Code│                       │  │
│  │  ├────┼────────────┼─────────────────┤                       │  │
│  │  │ 1  │ AGENT1     │ SP001           │                       │  │
│  │  │ 2  │ AGENT2     │ SP002           │                       │  │
│  │  │... │ ...        │ ...             │                       │  │
│  │  └────┴────────────┴─────────────────┘                       │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  EOS010 Salesperson Set Entry (combinazioni uniche)          │  │
│  │  ┌──────────────────┬──────────────────────────┐             │  │
│  │  │ Salesperson Set  │ Role-Salesperson Set ID  │             │  │
│  │  │       ID         │  (references table above)│             │  │
│  │  ├──────────────────┼──────────────────────────┤             │  │
│  │  │ 100              │ 1 (AGENT1/SP001)         │             │  │
│  │  │ 100              │ 2 (AGENT2/SP002)         │             │  │
│  │  │ 101              │ 1 (AGENT1/SP001)         │             │  │
│  │  │ 101              │ 5 (AGENT3/SP003)         │             │  │
│  │  └──────────────────┴──────────────────────────┘             │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                    │
│  Customer "CUST001"                                                │
│    └── EOS Salesperson Set ID = 100  ◄── SOLO UN INTERO!           │
│                                                                    │
│  Sales Header "INV-0001"                                           │
│    └── EOS Salesperson Set ID = 100  ◄── STESSO ID = STESSO SET    │
│                                                                    │
│  Sales Line "INV-0001, Line 10000"                                 │
│    └── EOS Salesperson Set ID = 100  ◄── NESSUNA RIDONDANZA        │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Vantaggi del nuovo sistema:

  • Drastica riduzione dello spazio occupato: da N record per entità a 1 campo intero
  • Maggiore velocità di elaborazione: query su indici interi molto più performanti
  • Interfaccia utente reattiva: lookup e filtri immediati
  • Manutenibilità: struttura normalizzata e manutenzione semplificata

Oggetti coinvolti nella migrazione

La migrazione interessa le seguenti tabelle (identificate dai rispettivi Database ID):

Database IDTabellaTipoNote
18CustomerMasterInclude Ship-to Address (222)
222Ship-to AddressMasterProcessata insieme a Customer
36Sales HeaderDocumentInclude Sales Line (37)
37Sales LineDocumentProcessata insieme a Header
112Sales Invoice HeaderPostedInclude Sales Invoice Line (113)
113Sales Invoice LinePostedProcessata insieme a Header
114Sales Cr.Memo HeaderPostedInclude Sales Cr.Memo Line (115)
115Sales Cr.Memo LinePostedProcessata insieme a Header
5107Sales Header ArchiveArchiveInclude Sales Line Archive (5108)
5108Sales Line ArchiveArchiveProcessata insieme a Header

Codeunit di Migrazione

Codeunit “EOS010 SalesP Upgrade” (ID: 18008321)

Questa codeunit esegue la migrazione completa e sincrona di tutti i dati. È progettata per essere eseguita una sola volta in un ambiente controllato.

Caratteristiche Principali

CaratteristicaDescrizione
EsecuzioneSincrona, bloccante
AmbitoPer company (ogni company viene migrata separatamente)
DurataPuò richiedere ore in base al volume dati della company
TransazioneUnica transazione con rollback automatico in caso di errore

Flusso di Esecuzione

  1. Checking Environment

    • Verifica interferenze con altre app
    • Controlla ruoli/agenti mancanti
    • Verifica tabelle sconosciute

  2. Data Upgrade

    • Verifica permessi di modifica
    • Crea combinazioni Role-Salesperson
    • Migra dati documenti attivi
    • Migra dati archiviati
    • Aggiorna reti vendita

  3. Data Verification

    • Verifica integrità dati migrati

Quando Usare

  • ✅ Migrazione iniziale in ambiente di test
  • ✅ Ambiente di produzione con possibilità di downtime
  • ✅ Database di piccole/medie dimensioni
  • ⚠️ Nota: La codeunit viene eseguita automaticamente all’attivazione del feature flag EAL, non può essere eseguita manualmente tramite codice
  • ❌ NON attivare il feature flag in ambiente di produzione senza downtime
  • ❌ NON attivare il feature flag su database di grandi dimensioni senza pianificazione

Codeunit “EOS010 SalesP JobQueue Upg” (ID: 18008325)

Questa codeunit esegue la migrazione incrementale e asincrona tramite Job Queue. È progettata per ambienti di produzione dove non è possibile avere downtime.

Caratteristiche Principali

CaratteristicaDescrizione
EsecuzioneAsincrona tramite Job Queue
AmbitoPer company (ogni Job Queue lavora su una specifica company)
Durata singola esecuzioneMassimo 10 minuti per esecuzione
ComportamentoRiprende da dove era rimasta
CommitCommit progressivi per ogni documento/entità
ConfigurazioneSi consiglia di configurarla tramite la page “EOS010 Salesp Upgrade Status” usando l’action Setup Job Queue
Uso tipicoMigrazione graduale in produzione

Funzionamento e Scopo

L’attività eseguita tramite coda processi permette di calcolare il valore di “Salesperson Set ID” su tutte le tabelle supportate in anticipo, velocizzando poi l’upgrade finale quando la feature flag viene attivata.

Importante: La Job Queue opera sui dati della company corrente. Se si hanno più company nell’ambiente, è necessario configurare una Job Queue Entry separata per ciascuna company.

Pianificazione Consigliata:

  • La coda processi deve essere pianificata in una finestra di tempo con pochi o nessun utente, ad esempio durante le ore notturne
  • Per evitare di sforare la finestra temporale, è progettata per eseguire massimo 10 minuti alla volta
  • Si ferma automaticamente dopo 10 minuti e riprende alla successiva esecuzione schedulata

Gestione Modifiche: Qualsiasi record che era stato già elaborato dalla coda processi, se viene modificato da un utente, verrà automaticamente ricalcolato alla successiva esecuzione della Job Queue.

Nota Importante: L’attività di aggiornamento tramite coda processi è opzionale e serve esclusivamente a velocizzare la migrazione finale. La migrazione vera e propria si completa solo con l’attivazione del feature flag EAL.

Configurazione Job Queue Entry

Il Parameter String della Job Queue Entry definisce quali tabelle processare:

18|36|112|114|5107
ValoreTabella Processata
18Customer + Ship-to Address
36Sales Header + Sales Line
112Sales Invoice Header + Lines
114Sales Cr.Memo Header + Lines
5107Sales Header Archive + Lines

Nota: I separatori accettati sono | (pipe) e , (virgola).

Flusso di Esecuzione

┌──────────────────────────────────────────────────────────────────┐
│                    Job Queue Entry Start                         │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  Verifica: CommissionsSetup."Enable SalesP. JobQueue Upg." = TRUE│
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  Parse Parameter String → Lista Table ID                         │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  CreateAllRoleSalespersons() + Commit                            │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  For each TableID in List:                                       │
│    ├── Check: (CurrentDateTime - StartDateTime) > 10 min?        │
│    │     └── YES → Exit                                          │
│    └── NO → Process Table                                        │
│              ├── Filter: "Upgrade Status" = "To Calculate"       │
│              ├── Get Salespersons → Calculate Set ID             │
│              ├── Update Record with Set ID                       │
│              ├── Set Status = "Valued"                           │
│              └── Commit                                          │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  Next Job Queue Execution → Riprende da record non processati    │
└──────────────────────────────────────────────────────────────────┘

Procedura di migrazione raccomandata

Comprendere l’Approccio a Due Fasi

La migrazione può essere eseguita in due modi:

Approccio a Fase Singola (Database Piccoli-Medi):

  • Attivazione diretta del feature flag EAL
  • Adatto per ambienti di test e database di produzione di dimensioni contenute
  • Richiede una finestra di manutenzione proporzionale al volume di dati

Approccio a Due Fasi (Database di Grandi Dimensioni - CONSIGLIATO):

  • Fase 1: Pre-calcolo opzionale tramite Job Queue (giorni/settimane)
  • Fase 2: Attivazione feature flag (minuti/ore)
  • Minimizza il downtime in produzione
  • Distribuisce il carico sul sistema nel tempo

Scenario 1: Database Piccolo-Medio (Fase Singola)

  1. Test Preliminare: Testare sempre la procedura completa in un ambiente non di produzione
  2. Aprire la pagina Salesperson Upgrade Status (CMS)
  3. Utilizzare Calculate Status per valutare il volume di dati corrente e il tempo di migrazione previsto
  4. Pianificare una finestra di manutenzione adeguata
  5. Attivare il feature flag nella Eos Admin Library (EAL)
  6. Monitorare il completamento tramite la pagina di stato
  7. Verificare il log per eventuali problemi
  8. Verificare la funzionalità dell’applicazione post-migrazione

Scenario 2: Database di Grandi Dimensioni (Due Fasi - CONSIGLIATO)

Fase 1: Pre-Calcolo tramite Job Queue (Opzionale ma Consigliato)

Scopo: Questa fase pre-calcola i valori “Salesperson Set ID” per minimizzare la durata della Fase 2.

Passi di Configurazione:

  1. Test Preliminare: Eseguire questa procedura in un ambiente di test per stimare i tempi
  2. Aprire la pagina EOS010 Salesp Upgrade Status
  3. Abilitare il flag Enable Salesperson Job Queue Upgrade
  4. Cliccare l’action Setup Job Queue per creare una Job Queue Entry pre-configurata
  5. Personalizzare la schedulazione della Job Queue Entry:
    • Consigliato: Pianificare durante periodi a basso utilizzo (es. ore notturne)
    • Impostare una ricorrenza appropriata (es. ogni ora)
    • Ogni esecuzione ha una durata massima di 10 minuti
  6. Mettere la Job Queue Entry in stato Ready
  7. Monitorare regolarmente il progresso tramite Calculate Status
  8. Permettere alla Job Queue di eseguire fino a che la percentuale di completamento è sufficientemente alta (tipicamente > 90-95%)

Durata: Questa fase può durare giorni o settimane a seconda del volume di dati e della frequenza di schedulazione.

Fase 2: Migrazione Finale tramite Attivazione Feature Flag (Obbligatoria)

Tempistica: Eseguire durante una finestra di manutenzione pianificata.

Passi:

  1. Verificare la percentuale di completamento della Fase 1 (se la Fase 1 è stata eseguita)
  2. Pianificare una finestra di manutenzione appropriata al volume di dati rimanente
  3. Disabilitare la Job Queue (se in esecuzione) per evitare conflitti
  4. Attivare il feature flag nella Eos Admin Library (EAL)
  5. Monitorare il processo di migrazione tramite la pagina di stato
  6. Verificare il log dettagliato al completamento
  7. Eseguire verifiche e test post-migrazione
  8. Rimuovere o disabilitare la Job Queue Entry se non più necessaria

Durata Attesa:

  • Senza Fase 1: Può richiedere diverse ore a seconda del volume di dati
  • Con Fase 1 completata: Tipicamente si completa in minuti od ore

Vantaggi dell’Approccio a Due Fasi:

  • Finestra di manutenzione significativamente ridotta per la Fase 2
  • Impatto minimo sugli utenti durante la Fase 1
  • Le modifiche degli utenti durante la Fase 1 vengono ricalcolate automaticamente
  • Carico sul sistema distribuito nel tempo

Scenario 3: Ottimizzazione con Code Processi Multiple (Avanzato)

I filtri tabella che si possono applicare alla coda processi possono essere utilizzati per ottimizzare l’aggiornamento in base all’attività utente:

Strategia Consigliata

Tabelle a Bassa Attività Utente (documenti registrati o archiviati):

  • Possono essere elaborate durante le ore di attività utente
  • Tabelle: 112 (Sales Invoice), 114 (Sales Cr.Memo), 5107 (Sales Archive)
  • Basso impatto sulle performance percepite dagli utenti

Tabelle ad Alta Attività Utente (documenti attivi):

  • Devono essere elaborate in fasce orarie scariche (es. notturne)
  • Tabelle: 36 (Sales Header), 37 (Sales Line)
  • Richiedono finestre temporali con pochi o nessun utente attivo

Configurazione Code Processi Multiple

È possibile avere più code processi di aggiornamento in contemporanea purché lavorino su tabelle differenti.

Esempio di configurazione:

Job Queue Entry #1 - Tabelle a bassa attività (orario diurno):

Parameter String: 112|114|5107
Orario: 08:00 - 18:00
Ricorrenza: ogni 30 minuti

Job Queue Entry #2 - Tabelle ad alta attività (orario notturno):

Parameter String: 18|36
Orario: 22:00 - 06:00
Ricorrenza: ogni 15 minuti

Vantaggi Potenziali:

  • Ottimizza l’utilizzo delle risorse nelle 24 ore
  • Riduce l’impatto sugli utenti attivi
  • Può accelerare la preparazione complessiva
  • Fornisce flessibilità nella pianificazione

Considerazioni Importanti:

  • Assicurarsi che le tabelle non si sovrappongano tra le diverse Job Queue
  • Monitorare il carico complessivo e le performance del database
  • Le tabelle Customer (18) possono richiedere considerazioni specifiche in base ai vostri pattern di utilizzo
  • Testare questa configurazione in un ambiente non di produzione prima dell’uso in produzione

Pagina “EOS010 Salesp Upgrade Status” (ID: 18008330)

Pagina di monitoraggio e gestione del processo di upgrade.

Layout

Sezione Setup

CampoDescrizione
Enable Salesperson Job Queue UpgradeAbilita/disabilita l’esecuzione del Job Queue
SalesPerson DataUpdate DateData/ora dell’ultima esecuzione
SalesPerson DataUpdate UserUtente che ha eseguito l’ultimo upgrade
SalesPerson DataUpdate StatusStato: In Progress, Completed, Error

Tip: Clicca su “SalesPerson DataUpdate Status” per scaricare il log dettagliato.

Sezione Tabelle (Repeater)

ColonnaDescrizione
TableNome della tabella
Total RecordsTotale record nella tabella
Processed RecordsRecord con Status = “Valued”
Progress %Percentuale di completamento

Azioni

Calculate Status

Calcola lo stato di upgrade per tutte le tabelle. Questa operazione può richiedere tempo significativo su database di grandi dimensioni.

Setup Job Queue

Crea automaticamente una nuova Job Queue Entry (se non esiste già) configurata per:

  • Eseguire il codeunit EOS010 SalesP JobQueue Upg
  • Parameter String: 18|36|112|114|5107 (tutte le tabelle)
  • Ricorrenza: ogni minuto, tutti i giorni
  • Massimo 3 tentativi in caso di errore

Nota: L’azione crea e configura automaticamente la Job Queue Entry con tutti i parametri corretti, semplificando notevolmente il processo di setup.

Troubleshooting

Errore “Enable SalesP. JobQueue Upg. must have a value”

Causa: Il flag di abilitazione non è attivo.

Soluzione: Abilitare “Enable Salesperson Job Queue Upgrade” nella pagina status.

Performance degradate durante l’esecuzione

Causa: La migrazione compete con le operazioni utente.

Soluzione:

  1. Limitare la finestra temporale del Job Queue alle ore notturne
  2. Ridurre il numero di tabelle processate per esecuzione
  3. Aumentare l’intervallo tra le esecuzioni

Note per gli Implementatori

  1. Backup: Eseguire sempre un backup completo prima di avviare la migrazione.

  2. Test: Testare sempre la migrazione in un ambiente di copia prima della produzione.

  3. Monitoraggio: Durante la migrazione Job Queue, monitorare regolarmente:

    • Spazio su disco
    • Performance del database
    • Stato della Job Queue Entry

  4. Post-Migrazione: Dopo il completamento:

    • Rimuovere la Job Queue Entry
    • Verificare le performance dell’applicazione

EOS Labs -