23. Microsoft Dynamics 365

Collegando Microsoft Dynamics 365 (e qualsiasi Power App basata su Microsoft Dataverse) al tuo agente, questo potrà leggere e scrivere contatti, lead, opportunità, casi di assistenza, ordini, attività e qualsiasi elemento modellato come tabella Dataverse.

Cosa può fare

• Leggere e cercare record di qualsiasi tabella (account, contatti, lead, opportunità, casi, ordini, prodotti, attività, ecc.)

• Creare, aggiornare ed eliminare record (con conferma per le eliminazioni)

• Eseguire query avanzate: OData (filtrare, ordinare, aggregare) e FetchXML (join complessi, somme e conteggi)

• Esplorare lo schema: tabelle, colonne, relazioni, set di opzioni, ruoli e utenti

• Eseguire azioni e funzioni personalizzate nel tuo ambiente Dataverse (workflow e plugin esposti come azioni)

• Gestire i collegamenti tra record (associazioni 1:N e N:N)

Esempi

"Trova i 5 lead più promettenti degli ultimi 30 giorni e forniscimi il loro numero di telefono e l'ultima nota." "Crea un nuovo contatto "Jane Doe" collegato all'account "ACME Inc"." "Quanti casi sono stati aperti questo mese, raggruppati per priorità?" "Elenca tutti gli account senza opportunità aperte, incluso l'indirizzo e-mail del contatto principale."

Prodotti supportati

Tutto ciò che funziona su Microsoft Dataverse:

• Dynamics 365 Sales (CRM per le vendite)

• Dynamics 365 Customer Service (casi / ticketing)

• Dynamics 365 Field Service

• Dynamics 365 Marketing

• Dynamics 365 Project Operations

• Power Apps personalizzate basate su Dataverse

Non coperti: Dynamics 365 Business Central e Finance & Operations dispongono di API separate e non sono raggiungibili tramite questo connettore.

Parametri di configurazione (autenticazione dell'applicazione)

Il connettore utilizza un'identita dell'applicazione (App Registration in Microsoft Entra ID): un unico account di servizio con le autorizzazioni che scegli, condiviso da tutti gli utenti dell'Agente. Questo e il modello standard per le integrazioni CRM aziendali.

Sono richiesti cinque valori, ottenuti tramite i 6 passaggi seguenti. Tempo stimato: 15-20 minuti. Ti servono privilegi di amministratore Microsoft 365 (per creare l'App Registration) e privilegi di amministratore Dynamics / Power Platform (per assegnare le autorizzazioni nell'ambiente).

Passaggio 1 — Ottieni l'URL dell'ambiente Dataverse

Vai a admin.powerplatform.microsoft.com → menu a sinistra "Environments" → fai clic sul nome dell'ambiente Dynamics da connettere.

Nella scheda a destra, in "Details", troverai "Environment URL": copia l'indirizzo HTTPS completo (ad es. https://orgXXXXXXXX.crm4.dynamics.com — il suffisso crm, crm4, crm12… dipende dalla regione del tenant).

→ questo e il valore DATAVERSE_ENV_URL.

Passaggio 2 — Ottieni il Tenant ID

Vai a portal.azure.com → cerca "Microsoft Entra ID" nella barra superiore e aprilo → nella pagina "Overview" troverai "Tenant ID" (un GUID come ab12cd34-e5f6-7890-abcd-1234567890ab). Fai clic sull'icona di copia.

→ questo e il valore AZURE_TENANT_ID.

Passaggio 3 — Crea l'App Registration in Entra ID

Sempre su portal.azure.com → "Microsoft Entra ID" → menu a sinistra "App registrations" → barra superiore "+ New registration".

• Nome: un nome riconoscibile (ad es. AIsuru Dynamics Connector)

• Tipi di account supportati: scegli "Accounts in this organizational directory only" (tenant singolo — il caso standard)

• URI di reindirizzamento: lascia vuoto (il connettore non utilizza flussi interattivi)

• Fai clic su "Register"

Si apre la pagina della nuova App. Da "Overview" copia "Application (client) ID".

→ questo e il valore AZURE_CLIENT_ID.

Passaggio 4 — Genera il Client Secret

Nella stessa App, menu a sinistra "Certificates & secrets" → scheda "Client secrets" → "+ New client secret".

• Descrizione: ad es. AIsuru secret

• Scadenza: consigliato 24 months (annota la data di scadenza, dovrai rinnovarlo)

• Fai clic su "Aggiungi"

Importante: subito dopo la creazione, la pagina mostra due colonne: "Valore" e "ID segreto". Copia immediatamente il "Valore" (mostrato una sola volta: se esci dalla pagina, dovrai crearne uno nuovo). NON copiare l'"ID segreto" (è solo l'identificatore tecnico e non può essere usato per l'autenticazione).

→ questo è il AZURE_CLIENT_SECRET valore (archiviato in forma crittografata dal gateway).

Passaggio 5 — Aggiungi l'App come utente dell'applicazione in Dataverse

La registrazione dell'App creata in Entra ID non ha automaticamente accesso ai dati Dynamics. Deve essere aggiunta esplicitamente come "utente dell'applicazione" nell'ambiente Dataverse.

Torna a admin.powerplatform.microsoft.com → "Ambienti" → fai clic sull'ambiente → scheda "Impostazioni" in alto → sezione "Utenti + autorizzazioni" → "Utenti dell'applicazione" → "+ Nuovo utente dell'app".

• Fai clic su "+ Aggiungi un'app" → si apre un pannello laterale → cerca l'App per nome (ad es. "AIsuru Dynamics Connector") → selezionala → "Aggiungi"

• Unità aziendale: lascia quella predefinita (l'unità aziendale radice dell'ambiente), a meno che tu non voglia limitare l'Agente a una BU specifica

• Ruoli di sicurezza: fai clic sull'icona della matita → seleziona almeno un ruolo (vedi "Quale ruolo di sicurezza?" di seguito) → "Salva"

• Fai clic su "Crea" in basso

L'App ora appare nell'elenco degli utenti dell'applicazione dell'ambiente ed è autorizzata a chiamare l'API Dataverse con le autorizzazioni del ruolo scelto.

Quale ruolo di sicurezza assegnare?

Il ruolo determina cosa può fare l'Agente sui dati. Scegli in base al caso d'uso:

• CRM in sola lettura (dati anagrafici dei clienti, cronologia delle vendite, opportunità — sola visualizzazione): crea un ruolo personalizzato con autorizzazione Lettura a livello di organizzazione su account, contact, lead, opportunity, opportunityproduct, salesorder, salesorderdetail, invoice, invoicedetail, quote, incident (casi), systemuser, businessunit. Questa è la configurazione consigliata per iniziare in produzione: l'Agente può rispondere a domande sui dati, ma non può modificare nulla

• CRM con accesso in scrittura limitato (l'Agente crea/aggiorna lead, opportunità, attività, contatti): oltre alla Lettura precedente, aggiungi Crea / Aggiungi / Aggiungi a / Scrivi su account, contact, lead, opportunity, task, phonecall, email, appointment. Nessuna eliminazione: l'Agente non deve rimuovere record anagrafici

• Solo Dev / sandbox: ruolo integrato "System Administrator" (con autorizzazioni complete). Comodo per i test, non usarlo in produzione

Suggerimento: in caso di dubbio, inizia con il profilo di sola lettura ed estendilo solo quando sono necessarie nuove operazioni. Se una funzione non riesce per problemi di autorizzazioni, il messaggio di errore lo indica esplicitamente e ti basta aggiungere il privilegio mancante al ruolo.

Riepilogo: dove trovare ogni valore

Parametro	Dove	Cosa
DATAVERSE_ENV_URL	Power Platform admin center → Environment → Details	URL HTTPS dell'ambiente Dataverse
AUTH_METHOD	(fisso)	Lascia client-credentials
AZURE_TENANT_ID	Portale Azure → Microsoft Entra ID → Panoramica	"Tenant ID" (GUID)
AZURE_CLIENT_ID	Portale Azure → Registrazione app → Panoramica	"ID (client) dell'applicazione" (GUID)
AZURE_CLIENT_SECRET	Portale Azure → Registrazione app → Certificati&segreti	La colonna "Valore" del segreto (NON "ID segreto")

Risoluzione dei problemi (se l'agente non riesce alla prima chiamata)

• AADSTS7000215: Invalid client secret → il segreto è errato o scaduto. Hai copiato per errore l'"ID segreto" invece del "Valore"? Genera un nuovo segreto e copia correttamente il Valore

• AADSTS700016: Application not found in tenant → AZURE_TENANT_ID non corrisponde al tenant in cui hai creato l'app. Verifica entrambi

• Principal user (AppId=…) is missing prvReadOrganization privilege o 0x80040220 → hai dimenticato di aggiungere l'app come utente applicazione nell'ambiente (Passaggio 5), oppure il ruolo di sicurezza assegnato è insufficiente per la tabella interrogata dall'agente

• The user does not have access to the Common Data Service environment → l'app è stata aggiunta nell'ambiente SBAGLIATO (sei in un altro tenant o in un altro ambiente dello stesso tenant). Assicurati che DATAVERSE_ENV_URL punti allo stesso ambiente in cui hai eseguito il Passaggio 5

• Immediato 401 Unauthorized → AZURE_CLIENT_ID non corrisponde alla registrazione dell'app, oppure il segreto è stato revocato in Azure

Nota sulla sicurezza: tutti gli utenti dell'agente operano con le autorizzazioni della registrazione dell'app. Assegna all'app il privilegio minimo richiesto in Dataverse e valuta la limitazione per Business Unit / Team se desideri restringere l'accesso ai record all'interno di una singola area organizzativa.