> For the complete documentation index, see [llms.txt](https://docs.aisuru.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisuru.com/avanzate/integrazioni/model-context-protocol-mcp-su-aisuru/mcp-di-aisuru-quali-sono-e-come-si-attivano/23.-microsoft-dynamics-365.md). # 23. Microsoft Dynamics 365 Collegando **Microsoft Dynamics 365** (e qualsiasi Power App basata su **Microsoft Dataverse**) al tuo Agente, 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. {% hint style="warning" %} **Non coperti**: Dynamics 365 **Business Central** e **Finance & Operations** dispongono di API separate e non sono raggiungibili tramite questo connettore. {% endhint %} ## Parametri di configurazione (autenticazione dell'applicazione) Il connettore utilizza un'**identità 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 è 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 su [**admin.powerplatform.microsoft.com**](https://admin.powerplatform.microsoft.com/) → menu a sinistra **"Ambienti"** → 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 è il valore **`DATAVERSE_ENV_URL`**. #### Passaggio 2 — Ottieni il Tenant ID Vai a [**portal.azure.com**](https://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 è il valore **`AZURE_TENANT_ID`**. #### Passaggio 3 — Crea l'App Registration in Entra ID Sempre su [portal.azure.com](https://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 è 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**: si consiglia `24 months` (annota la data di scadenza, dovrai ruotarlo); * Fai clic su **"Aggiungi".** {% hint style="warning" %} **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, non può essere usato per l'autenticazione). {% endhint %} → questo è il valore **`AZURE_CLIENT_SECRET`** (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**](https://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. {% hint style="info" %} **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 a causa delle autorizzazioni, il messaggio di errore lo indica esplicitamente e ti basta aggiungere il privilegio mancante al ruolo. {% endhint %} ## Riepilogo: dove trovare ogni valore | Parametro | Dove | Cosa | | --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------ | | `DATAVERSE_ENV_URL` | Centro di amministrazione di Power Platform → Ambiente → Dettagli | 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`\*\*oppure **`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 {% hint style="danger" %} **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. {% endhint %}