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

La migrazione avviene tramite l’attivazione della feature flag nella Eos Admin Library (EAL). Una volta attivata la feature, il sistema passa automaticamente a utilizzare il nuovo modello di dati basato su Salesperson Set ID.

Importante:

  • Una migrazione al nuovo motore agenti è considerata completa solo quando l’intera attività di migrazione attivata con il feature flag EAL è completata senza errori.
  • La migrazione viene eseguita per company: ogni company nell’ambiente deve completare la propria migrazione in modo indipendente.

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 Role: AGENT1, Salesperson/Purchaser: SP001                  │
│ └─ EOS Role: AGENT2, Salesperson: SP002                            │
│                                                                    │
│ Sales Header "INV-0001"                                            │
│ ├─ EOS Role: AGENT1, Salesperson: SP001 ◄── **DUPLICATO**          │
│ └─ EOS Role: AGENT2, Salesperson: SP002 ◄── **DUPLICATO**          │
│                                                                    │
│ Sales Line "INV-0001, Line 10000"                                  │
│ ├─ EOS Role: AGENT1, Salesperson: SP001 ◄── **DUPLICATO**          │
│ └─ EOS Role: AGENT2, Salesperson: SP002 ◄── **DUPLICATO**          │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

🦆🦆🦆🦆🦆 SISTEMA LEGACY 🦆🦆🦆🦆🦆🦆🦆🦆🦆
🦆  ┌────────────────────────────────────┐  🦆
🦆  │ Customer "CUST001"                 │  🦆
🦆  │ ├─ AGENT1/SP001 (Purchaser)        │  🦆
🦆  │ └─ AGENT2/SP002                    │  🦆
🦆  │                                    │  🦆
🦆  │ Sales Header "INV-0001"            │  🦆
🦆  │ ├─ AGENT1/SP001 **DUPLICATO**      │  🦆
🦆  │ └─ AGENT2/SP002 **DUPLICATO**      │  🦆
🦆  │ Sales Line L10000                  │  🦆
🦆  │ ├─ AGENT1/SP001 **DUPLICATO**      │  🦆
🦆  │ └─ AGENT2/SP002 **DUPLICATO**      │  🦆
🦆  └────────────────────────────────────┘  🦆
🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆🦆

Problematiche 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

Tabelle Coinvolte nella Migrazione

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

Database ID Tabella Tipo Note
18 Customer Master Include Ship-to Address (222)
222 Ship-to Address Master Processata insieme a Customer
36 Sales Header Document Include Sales Line (37)
37 Sales Line Document Processata insieme a Header
112 Sales Invoice Header Posted Include Sales Invoice Line (113)
113 Sales Invoice Line Posted Processata insieme a Header
114 Sales Cr.Memo Header Posted Include Sales Cr.Memo Line (115)
115 Sales Cr.Memo Line Posted Processata insieme a Header
5107 Sales Header Archive Archive Include Sales Line Archive (5108)
5108 Sales Line Archive Archive Processata insieme a Header

Campo di Stato Upgrade

Ogni tabella coinvolta contiene un campo “EOS Salesperson Upgrade Status” di tipo enum EOS010 Salesp. Upgrade Status:

Valore Significato
To Calculate Record non ancora processato (default)
Valued Record processato e valorizzato con Salesperson Set ID

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

Caratteristica Descrizione
Esecuzione Sincrona, bloccante
Ambito Per company (ogni company viene migrata separatamente)
Durata Può richiedere ore in base al volume dati della company
Transazione Unica transazione con rollback automatico in caso di errore
Log Genera un log dettagliato salvato in CommissionsSetup."SalesPDataUpdate Log"
Uso tipico Migrazione iniziale o ambienti con downtime pianificato

Flusso di Esecuzione

  1. Checking Environment

    • CheckInterferences(): Verifica interferenze con altre app
    • CheckMissingRolesAndSalesPersons(): Controlla ruoli/agenti mancanti
    • CheckUnknowTable(): Verifica tabelle sconosciute

  2. Data Upgrade

    • TestModifyPermissions(): Verifica permessi di modifica
    • CreateAllRoleSalespersons(): Crea combinazioni Role-Salesperson
    • UpdateAddSalesPersonPurchaser(): Migra dati documenti attivi
    • UpdateAddSalesPersonPurchaserArchive(): Migra dati archiviati
    • UpdateSalesNetworks(): Aggiorna reti vendita

  3. Data Verification

    • CheckDataUpgrade(): Verifica integrità dati migrati
    • CheckDataUpgradeArchive(): Verifica dati archiviati

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

Caratteristica Descrizione
Esecuzione Asincrona tramite Job Queue
Ambito Per company (ogni Job Queue lavora su una specifica company)
Durata singola esecuzione Massimo 10 minuti per esecuzione
Comportamento Riprende da dove era rimasta
Commit Commit progressivi per ogni documento/entità
Configurazione Si consiglia di configurarla tramite la page “EOS010 Salesp Upgrade Status” usando l’action Setup Job Queue
Uso tipico Migrazione 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.

Proprietà Codeunit

codeunit 18008325 "EOS010 SalesP JobQueue Upg"
{
    SingleInstance = true;           // Istanza singola per tracking stato
    TableNo = "Job Queue Entry";     // Eseguibile da Job Queue
    InherentPermissions = X;
    InherentEntitlements = X;
    ...
}

Configurazione Job Queue Entry

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

18|36|112|114|5107
Valore Tabella Processata
18 Customer + Ship-to Address
36 Sales Header + Sales Line
112 Sales Invoice Header + Lines
114 Sales Cr.Memo Header + Lines
5107 Sales 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    │
└──────────────────────────────────────────────────────────────────┘

Controllo Esecuzione

// Verifica se il Job Queue Upgrade è in esecuzione
procedure GetIsRunningJobQueueUpgrade(): Boolean

Procedura di migrazione raccomandata

Scenario 1: Ambiente di Test o Piccolo Database

Pre-requisito: Attivare la feature flag nella Eos Admin Library (EAL).

  1. Aprire la pagina Salesperson Upgrade Status (CMS)
  2. Verificare lo stato attuale con Calculate Status
  3. Abilitare la feature flag nella Eos Admin Library (EAL) - questo avvierà automaticamente l’esecuzione della codeunit EOS010 SalesP Upgrade
  4. Verificare il completamento tramite lo stato “Completed”
  5. Controllare il log in caso di errori

Scenario 2: Ambiente di Produzione con Downtime Minimo (CONSIGLIATO)

Pre-requisito: Attivare la feature flag nella Eos Admin Library (EAL).

Fase 1: Preparazione tramite Job Queue (prima dell’upgrade finale)

  1. Aprire la pagina EOS010 Salesp Upgrade Status
  2. Abilitare il flag Enable Salesperson Job Queue Upgrade
  3. Cliccare l’action Setup Job Queue - questa azione crea automaticamente la Job Queue Entry con tutti i parametri pre-configurati
  4. Opzionalmente, personalizzare la Job Queue Entry appena creata:
    • Impostare finestra temporale notturna o con pochi utenti
    • Impostare ricorrenza appropriata (es. ogni ora durante la notte)
    • La durata massima di ogni esecuzione è automaticamente limitata a 10 minuti
  5. Mettere in stato Ready la Job Queue Entry
  6. Monitorare il progresso tramite Calculate Status nella pagina di upgrade
  7. La Job Queue calcola in anticipo il “Salesperson Set ID” su tutte le tabelle supportate

Fase 2: Attivazione finale

Una volta che la Job Queue ha elaborato la maggior parte dei record:

  1. Verificare che la percentuale di completamento sia elevata (es. > 95%)
  2. L’upgrade finale sarà molto più veloce poiché la maggior parte dei dati è già valorizzata
  3. Disabilitare il Job Queue se non più necessario

Vantaggi di questo approccio:

  • ✅ Upgrade finale rapidissimo
  • ✅ Nessun impatto sugli utenti durante la preparazione
  • ✅ Modifiche utente gestite automaticamente (ricalcolo alla successiva esecuzione)
  • ✅ Sicurezza: elaborazioni brevi (max 10 minuti) che non bloccano il sistema

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:

  • ✅ Massimizza l’utilizzo delle risorse nelle 24 ore
  • ✅ Minimizza l’impatto sugli utenti attivi
  • ✅ Accelera la preparazione complessiva
  • ✅ Flessibilità nella pianificazione

Attenzioni:

  • Assicurarsi che le tabelle non si sovrappongano tra le diverse Job Queue
  • Monitorare il carico complessivo del database
  • Le tabelle Customer (18) possono richiedere considerazioni specifiche in base all’uso

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

Pagina di monitoraggio e gestione del processo di upgrade.

Layout

Sezione Setup

Campo Descrizione
Enable Salesperson Job Queue Upgrade Abilita/disabilita l’esecuzione del Job Queue
SalesPerson DataUpdate Date Data/ora dell’ultima esecuzione
SalesPerson DataUpdate User Utente che ha eseguito l’ultimo upgrade
SalesPerson DataUpdate Status Stato: In Progress, Completed, Error

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

Sezione Tabelle (Repeater)

Colonna Descrizione
Table Nome della tabella
Total Records Totale record nella tabella
Processed Records Record 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

Riferimenti Tecnici

Tabelle Nuova Struttura

Tabella ID Descrizione
EOS010 Role-Salesperson Sets 18008320 Combinazioni univoche Role-Salesperson
EOS010 Salesperson Set Entry - Entry per ogni Salesperson Set ID
EOS010 Salesp. Set Tree Node - Struttura ad albero per lookup veloce

Enum

Enum ID Valori
EOS010 Salesp. Upgrade Status 18008320 To Calculate, Valued

Codeunit Correlate

Codeunit ID Utilizzo
EOS010 Salespersons Mngt 18008320 Gestione Salesperson Set
EOS010 DataUpg ManualBinding - Event binding durante migrazione

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. Rollback: In caso di problemi gravi, è possibile:

    • Ripristinare il backup
    • Reimpostare tutti i campi “EOS Salesperson Upgrade Status” a “To Calculate”
    • Svuotare le tabelle della nuova struttura

  5. Post-Migrazione: Dopo il completamento:

    • Disabilitare il flag “Enable SalesP. JobQueue Upg.”
    • Rimuovere la Job Queue Entry
    • Verificare le performance dell’applicazione

EOS Labs -