Configurare l'Agente Spese (Anteprima)

Si applica a Dynamics 365 Project Operations integrato con ERP e Dynamics 365 Project Operations per la produzione

Expense Agent riunisce le funzionalità di Microsoft Dynamics 365 Project Operations, app finanziarie e operative, Microsoft Copilot Studio, Power Automate e Dataverse per automatizzare i flussi di lavoro di elaborazione delle spese usando l'intelligenza artificiale. Questa funzionalità consente di risparmiare tempo e ridurre il lavoro manuale consentendo al sistema di elaborare le ricevute e generare righe di spesa e note spese per gli utenti. Usa connettori Microsoft Power Platform per l'integrazione con Outlook, Microsoft Teams, calendari utente e ambiente delle app finanziarie e operative tramite entità virtuali Dataverse.

L'Agente spesa include più flussi, tre dei quali fungono da agenti di orchestrazione principali:

• Process Emails: questo flusso analizza ogni ora una cartella della cassetta postale configurata e archivia gli allegati come ricevute scollegate in Dynamics 365 Finance.
• Estrai ID ricevuta: questo flusso preleva le ricevute non collegate e attiva l'agente per estrarre i dettagli della ricevuta e creare una riga di spesa non collegata.
• Processo Report Spese – Questo flusso converte le righe di spesa non collegate e genera report spese, basandosi sulla configurazione Raggruppa report per che hai impostato nell'applicazione per ciascuna entità legale.

Inoltre, l'agente si integra con Microsoft Teams, consentendo l'uso di schede adattive per la revisione e l'invio della nota spese.

L'agente si basa su diversi connettori Microsoft Power Platform. Questi connettori sono automaticamente referenziati nei flussi di Power Automate forniti.

• Outlook (Office 365): questo connettore accede alla cassetta postale condivisa per estrarre le ricevute.
• Dataverse (entità virtuali): questo connettore si integra con le app per la finanza e le operazioni tramite entità virtuali.
• Microsoft Copilot Studio: questo connettore richiama i modelli di intelligenza artificiale per estrarre le informazioni sulla ricevuta.
• Microsoft Teams: questo connettore invia schede adattive per le interazioni utente (se l'integrazione di Teams è abilitata).
• Microsoft 365 Users: questo connettore recupera i dettagli del calendario utente (facoltativo, se l'analisi delle ricevute è compatibile con il contesto).

Prerequisiti

1. Ambiente finanziario e operativo: È necessaria almeno la versione 10.0.44 (10.0.2263.175 e successive) o 10.0.45 (10.0.2345.115 e successive) o 10.0.46 (10.0.2428.69 e successive) dell'ambiente finanziario e operativo per installare l'agente.
2. Ruoli richiesti per configurare l'utente di Expense Agent: Per completare i passaggi descritti in questo articolo, è necessario essere l'amministratore di sistema dell'organizzazione e avere i seguenti ruoli per configurare l'utente di Expense Agent per l'installazione.

Passaggi per configurare l'Agente spesa

Per installare e configurare Expense Agent, seguire questa procedura:

1. Installare Copilot per le app finance e operations.
2. Abilita le funzionalità dell'agente nell'ambiente.
3. Crea un utente spesa per l'esecuzione dell'agente.
4. Configurare una cassetta postale condivisa.
5. Configurare l'Agente spesa.
6. Abilitare l'agente spese in Microsoft Teams (facoltativo: se è necessaria l'integrazione con Microsoft Teams)

Le sezioni seguenti descrivono in dettaglio ogni passaggio.

Passaggio 1: Installare Copilot per le app finance and operations

L'Agente delle Spese è disponibile come parte del pacchetto Copilot per le applicazioni di finanza e operazioni. Dopo aver installato questo pacchetto nell'ambiente, si ottengono automaticamente tutti gli asset necessari, inclusi l'agente, le variabili di ambiente e i flussi Power Automate.

Per installare l'app necessaria, seguire questa procedura:

1. Vai all'interfaccia di amministrazione di Power Platform nel browser.
2. Nell'elenco degli ambienti seleziona il nome dell'ambiente in cui si vuole installare l'app.
3. Nella pagina dei dettagli dell'ambiente (NOT dal riquadro di spostamento a sinistra passare alla sezione Resources e selezionare Dynamics 365 apps.
4. Cercare Copilot per le app di finanza e operazioni all'interno dell'elenco delle app di Dynamics 365. Se è già installato ed è disponibile un aggiornamento, seleziona il pulsante Aggiorna.
5. Se l'app non è elencata tra le app di Dynamics 365, selezionare Installa app, selezionare Copilot per le app di finanza e operazioni e seguire le istruzioni per completare l'installazione.
6. Copilot per le app Finance and Operations deve essere 1.0.3231.4 o versione successiva

Passaggio 2: abilita le funzionalità dell'agente nell'ambiente.

Dopo aver installato il pacchetto di Copilot per le app Finance e Operazioni, attivare l'agente spese dall'ambiente Dataverse e dall'ambiente Finance e Operazioni.

Abilitare le funzionalità in Dataverse

Attivare il flag di funzionalità Copilot nell'interfaccia di amministrazione di Power Platform. Per attivare il flag di funzionalità Copilot, seguire questa procedura:

1. Vai a Interfaccia di amministrazione di Power Platform.
2. Seleziona Ambienti>, il tuo ambiente>Impostazioni>Prodotto> select Funzionalità.
3. Verificare che il flag di funzionalità Copilot sia attivato.

Abilitare la funzionalità nell'ambiente per la finanza e le operazioni

Per attivare l'agente nelle app finance and operations, seguire questa procedura:

1. Accedi all'ambiente per la finanza e le operazioni.
2. Vai a Gestione funzionalità e abilita le funzionalità Pagina iniziale immersiva e Gestione agenti.
3. Per configurare l'Agente spesa (il programma di installazione è per persona giuridica), vai a Gestione spese>Configurazione>Generale>Parametri di gestione spese.
4. Nella scheda Agente Inserimento spese configura i parametri come illustrato nella tabella seguente.

Passaggio 3: crea un utente agente spesa per l'esecuzione dell'agente

Creare un utente agente voci di spesa dedicato per assicurarti che l'agente venga eseguito indipendentemente dall'identità di qualsiasi dipendente. Questo approccio consente di gestire la sicurezza, la gestibilità e la manutenibilità a lungo termine. Anche se è possibile usare un account utente esistente con i privilegi necessari, usare un'identità di proprietà del sistema.

Creare l'utente di Expense Agent in Microsoft Entra ID

1. Accedere al portale Azure.
2. Nei servizi di Azure disponibili selezionare Microsoft Entra ID.
3. In Microsoft Entra ID creare un nuovo utente.
4. Seleziona Aggiungi>Utente>Crea nuovo utente
   • Nome dell'entità utente
   • Scegli il dominio appropriato
   • Nome visualizzato
   • Parola chiave
   • Contrassegno di abilitazione dell'account
5. Per visualizzare i dettagli e completare il processo di creazione dell'utente, seleziona Rivedi e crea quindi Crea.
6. Nella pagina Utente (Gestisci > utenti) seleziona un utente e la pagina dei dettagli della visualizzazione.
7. Seleziona Modifica proprietà, passa alla scheda Impostazioni e compila il percorso di utilizzo appropriato.

Assegnare le licenze necessarie all'utente di Agente spesa

Per installare correttamente Agente spesa, assegna le licenze seguenti all'utente Agente spesa.

• Dynamics 365 licenza dei membri di Teams
• Microsoft 365 Business Basic o qualsiasi licenza che copre Microsoft Teams e Outlook (ad esempio, Office 365 E5 con team)
• Power Apps Premium

Per assegnare licenze, seguire questa procedura:

1. Accedere al Centro di amministrazione di Microsoft 365 con un utente che ha il ruolo di Amministratore delle licenze o superiore per assegnare licenze.
2. Selezionare Billing>Licenses>Dynamics 365 Licenza membri di Teams.
3. Seleziona + Assegna licenze.
4. Cerca l'utente dell'Agente spesa creato nel passaggio precedente.
5. Seleziona Assegna per completare l'assegnazione di licenza.
6. Seguire i passaggi da 2 a 5 per le altre licenze, Microsoft 365 Business Basic e Power Apps Premium.

Aggiungere l'utente all'ambiente Power Platform

Per aggiungere l'utente all'ambiente Power Platform, seguire questa procedura:

1. Accedi all'interfaccia di amministrazione di Power Platform e seleziona l'ambiente appropriato.

   Suggerimento

   Questa pagina fornisce informazioni relative all'ID ambiente per Dataverse, all'URL dell'ambiente per Dataverse e all'URL per la finanza e le operazioni. Archivia questi valori per l'uso nelle sezioni successive.

2. Vai ad Accesso > Utenti > Visualizza tutto.

3. Seleziona Aggiungi utente, immetti l'utente dell'agente appena creato e seleziona Aggiungi.

4. Nella pagina Gestisci ruoli di sicurezza aggiungere i ruoli seguenti.

   • Ruolo dell'Agente IA per le voci di spesa
   • Agente finanziario e operativo Configuration Manager
   • Addetto alla personalizzazione del sistema

5. Per confermare le assegnazioni dei ruoli, seleziona Salva.

Questi ruoli forniscono l'accesso a Dataverse e ai componenti Power Automate necessari per il funzionamento dell'agente.

Assegna il ruolo necessario nell'ambiente per la finanza e le operazioni

Per assegnare il ruolo ExpenseAgentRole nell'ambiente finanziario e operativo, seguire questa procedura:

1. Nell'ambiente per la finanza e le operazioni vai ad Amministrazione di sistema>Utenti.
2. Crea un record utente per l'utente dell'agente.
3. Dopo aver creato l'utente, passare alla sezione ruoli dell'utente, selezionare Assegna ruoli e cercare ExpenseAgentRole.
4. Seleziona Salva.

Assegnare l'accesso alla cassetta postale condivisa

L'utente dell'agente deve disporre dell'autorizzazione di Microsoft Graph Mail.Read.Shared. Questa autorizzazione consente all'agente di leggere le conferme dalla cassetta postale condivisa configurata durante l'esecuzione del flusso.

Per assegnare l'accesso alla cassetta postale condivisa, seguire questa procedura:

1. Passare a Microsoft Graph Explorer ed eseguire l'accesso usando l'utente agente creato.
2. Seleziona l'icona utente nell'angolo in alto a destra > seleziona Consenso alle autorizzazioni .
3. Seleziona il menu a discesa per Posta> cerca Mail.Read.Shared> seleziona Consenti e seleziona Accetta.

Riepilogo dei ruoli necessari per l'utente dell'agente creato

Passaggio 4: configurare la cassetta postale condivisa

L'Agente spesa usa una cassetta postale condivisa per ricevere ed elaborare i messaggi di posta elettronica di ricezione. Un utente con il ruolo Amministratore di Exchange deve creare e configurare questa cassetta postale nel Microsoft 365 Admin Center.

Per creare e configurare la cassetta postale condivisa, seguire questa procedura:

1. Accedere al Microsoft 365 Admin Center usando un account amministratore di Exchange.

2. Nel riquadro a sinistra, seleziona Teams & Gruppi>Cassette postali condivise.

   Suggerimento

   Potrebbe essere necessario selezionare Mostra tutto per espandere l'elenco completo.

3. Seleziona Aggiungi una cassetta postale condivisa.

4. Immettere un nome e un indirizzo e-mail per la cassetta postale condivisa.

5. Seleziona Salva modifiche.

6. In Passaggi successivi, seleziona Aggiungi membri a questa cassetta postale condivisa. La gestione dei membri potrebbe richiedere alcuni minuti prima che diventi disponibile.

7. Seleziona Aggiungi membri.

8. Seleziona l'utente dell'agente creato e tutti gli altri utenti che devono monitorare la cassetta postale e seleziona Aggiungi.

9. Seleziona Chiudi.

Passaggio 5: configurare l'Agente spesa

Sono disponibili due opzioni per configurare l'Agente spesa:

• Opzione A: Usare uno script di PowerShell (scelta consigliata)
• Option B: Eseguire l'installazione manuale in Power Apps (senza PowerShell)

Opzione A: Usare uno script di PowerShell (scelta consigliata)

La configurazione manuale dell'agente comporta la creazione e il collegamento di connessioni, l'abilitazione dei flussi Power Automate e la pubblicazione della soluzione. Questo processo può richiedere molto tempo ed è soggetto a errori. Per automatizzare l'installazione, usare uno script di PowerShell dopo l'aggiornamento dei parametri necessari.

Lo script di PowerShell automatizza le attività seguenti:

• Aggiorna le variabili di ambiente necessarie.
• Collega le connessioni di Microsoft Power Platform con i riferimenti alle connessioni della soluzione.
• Abilita tutti i flussi Power Automate richiesti dall'Agente di Gestione Tempo e Spese.
• Pubblica gli agenti Copilot.
• Pubblica la soluzione Dataverse.

Prima di eseguire lo script, devi creare connessioni perché è necessario specificare l'ID connessione per ogni connettore nel file install.ps1. Per creare queste connessioni, seguire questa procedura usando l'utente dell'agente creato.

1. Accedere al portale di Power Apps maker usando l'utente dell'agente appena creato e selezionare l'ambiente.
2. Nel riquadro a sinistra, seleziona Altro, quindi Connessioni.
3. Selezionare Nuova connessione e cercare utilizzando il Nome connessione della tabella seguente (ad esempio, Office 365 Outlook).
4. Seleziona il connettore appropriato dall'elenco e crealo.
5. Dopo aver creato la connessione, prendi nota dell'utente con cui è stata creata la connessione. Dovrebbe essere idealmente l'ID utente dell'agente creato. Aggiornare questo ID utente nel file di installazione creato nel passaggio successivo.
6. Ripeti i passaggi 3 e 4 per ognuna delle connessioni necessarie rimanenti elencate nella tabella seguente.

Informazioni necessarie per creare il file di installazione

Per creare il file di installazione , install.ps1, sono disponibili le informazioni seguenti. Per riferimento, vedi la tabella seguente.

Creare il file dello script di installazione

Creare un file di script di installazione copiando il codice seguente. Inserire le variabili di ambiente necessarie nello script, quindi eseguire lo script usando PowerShell.

Creare un file di script di PowerShell con il codice seguente. Aggiornare i parametri indicati prima di eseguire lo script.

Copiare il codice seguente nel file di script di installazione e salvarlo come "Install.ps1". Aggiornare le variabili nei rispettivi campi dei parametri nella sezione param. È necessario aggiornare 10 variabili.

#requires -Version 7
Param(

   [Parameter(Mandatory=$true, HelpMessage="Dataverse environment id")]
   [string]$DataverseEnvironmentId = "xxxx-xxxx-xxxx-xxx-xxxxxxxxxx", 

   [Parameter(Mandatory=$true, HelpMessage="Dataverse environment URL")]
   [string]$DataverseUrl = "https://org123.crm.dynamics.com",

   [Parameter(Mandatory=$true, HelpMessage="Finance and Operations instance URL")]
   [string]$D365FinanceAndOperationsUrl = "https://org123.operations.dynamics.com",

   [Parameter(Mandatory=$true, HelpMessage="OutlookFolderPath")]
   [string]$OutlookFolderPath = "Inbox",

   [Parameter(Mandatory=$true, HelpMessage="Mailbox Address Id")]
   [string]$MailboxAddressId = "expenseagent@contoso.com",

   [Parameter(Mandatory=$true, HelpMessage="Microsoft Dataverse connection name")]
   [string]$MicrosoftDataverseConnectionName = "createdexpenseagentuser@contoso.com",

   [Parameter(Mandatory=$true, HelpMessage="Microsoft Copilot Studio connection name")]
   [string]$MicrosoftCopilotStudioConnectionName = "createdexpenseagentuser@contoso.com",
   
   [Parameter(Mandatory=$true, HelpMessage="Microsoft Office Outlook connection name")]
   [string]$Office365OutlookConnectionName = "createdexpenseagentuser@contoso.com",

   [Parameter(Mandatory=$true, HelpMessage="Microsoft Office 365 Users connection name")]
   [string]$Office365UsersConnectionName = "createdexpenseagentuser@contoso.com",

   [Parameter(Mandatory=$true, HelpMessage="Microsoft Teams connection name")]
   [string]$MicrosoftTeamsConnectionName = "createdexpenseagentuser@contoso.com",

   [Parameter(Mandatory=$false, HelpMessage="Checks for bot Sync Errors and if there is provisioning required before Agent publish step")]
   [boolean]$CheckBotSyncStatusAndProvisionBots = $false

)

$flows = @(
    "expense entry retry check",
    "expense configuration",
    "get expense outlook folder",
    "generate expense report",
    "send expense report adaptive card",
    "auto match expenses",
    "process emails",
    "extract unattached receipt ids for copilot invocation",
    "extract unattached receipt output using dataverse plugin",
    "generate expense line",
    "generate expense line without project id and status id",
    "identify project ids",
    "user calendar events",
    "process expense report using copilot",
    "invoke expense agent for receipt processing"
)


$agents = @(
    "msdyn_ExpenseEntryAgent",
    "msdyn_ExpenseReportAgent"
)


# Check PS version
if ($PSVersionTable.PSVersion.Major -lt 7) {
    Write-Error 'This script requires at least PowerShell version 7' -ErrorAction Stop
}

# Install the required modules if not already installed or if the version is not 1.0.40
if (-not (Get-Module -ListAvailable -Name Microsoft.PowerApps.PowerShell | Where-Object { $_.Version -ge [Version]"1.0.40" })) {
    Write-Host "Microsoft.PowerApps.PowerShell version 1.0.40 not found. Installing..." -ForegroundColor Yellow
    Install-Module -Name Microsoft.PowerApps.PowerShell -RequiredVersion 1.0.40 -Force -AllowClobber -Scope CurrentUser
} else {
    Write-Host "Microsoft.PowerApps.PowerShell version 1.0.40 is already installed." -ForegroundColor Green
}

if (-not (Get-Module -ListAvailable -Name Microsoft.PowerApps.Administration.PowerShell | Where-Object { $_.Version -ge [Version]"2.0.147" })) {
    Install-Module -Name Microsoft.PowerApps.Administration.PowerShell -RequiredVersion 2.0.147 -Force -AllowClobber -Scope CurrentUser
}

# Install the required modules if not already installed
if (-not (Get-Module -ListAvailable -Name Az.Accounts | Where-Object { $_.Version -ge [Version]"5.0.1"})) {
    Install-Module -Name Az.Accounts -RequiredVersion 5.0.1 -Force -AllowClobber -Scope CurrentUser
}

# Import required modulesds
Import-Module Az.Accounts
Import-Module Microsoft.PowerApps.PowerShell
Import-Module Microsoft.PowerApps.Administration.PowerShell

# global variable declaration
$filter = '$filter'


function Get-AccessToken {
    # Retrieve the access token for the Dataverse environment
    $accessToken = (Get-AzAccessToken -ResourceUrl "$DataverseUrl" -AsSecureString).Token
    Write-Host "Access token for $userId retrieved successfully." -ForegroundColor Green
    return $accessToken
}

function Get-AccessTokenPlainText {
    param(
        [Parameter(Mandatory=$true, HelpMessage="Access token for authentication")]
        [securestring]$accessToken
    )
    # Retrieve the access token for the PVA environment
    $token = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
    [Runtime.InteropServices.Marshal]::SecureStringToBSTR($accessToken))
    return $token
}

function update-EnvironmentVaribleValue {
        param (
        [string]$accessToken,
        [string]$env_key,
        [string]$env_value   # Access token for authentication
    )

    try 
    {
        # Get the environment variable definition
        $envVarDefinition = Invoke-RestMethod -Method Get -Uri "$DataverseUrl/api/data/v9.2/environmentvariabledefinitions?$filter=schemaname eq '$env_key'" -Headers @{
            Authorization = "Bearer $accessToken"
        }

        if ($envVarDefinition.value -ne $null) {
            $envVarDefId = $envVarDefinition.value[0].environmentvariabledefinitionid

            # Get the environment variable value record
            $filterValue = [System.Web.HttpUtility]::UrlEncode("_environmentvariabledefinitionid_value eq $envVarDefId")
            $envVarValue = Invoke-RestMethod -Method Get -Uri "$DataverseUrl/api/data/v9.2/environmentvariablevalues?$filter=$filterValue" -Headers @{
                Authorization = "Bearer $accessToken"
            }

            if ($envVarValue.value -ne $null) {
                $envVarValueId = $envVarValue.value[0].environmentvariablevalueid
                # Update the environment variable value
                Invoke-RestMethod -Method Patch -Uri "$DataverseUrl/api/data/v9.2/environmentvariablevalues($envVarValueId)" -Headers @{
                    Authorization = "Bearer $accessToken"
                    "Content-Type" = "application/json"
                } -Body (@{ value = $env_value } | ConvertTo-Json -Depth 1)
                Write-Host "Environment variable updated with name $env_key and value $env_value" -ForegroundColor Green
            } else {
                Write-Host "Environment variable value not found for $env_key. Skipping..." -ForegroundColor Red
            }
        } 
        else {
            Write-Host "Environment variable definition not found for $env_key. Skipping..." -ForegroundColor Yellow
        }
  }
  catch {
        Write-Host "Failed to update environment variable $env_key. Error: $($_)" -ForegroundColor Red
        throw $_  # Re-throw the error to stop the script if this step is critical
    }

}

function update_EnvironmentVariablesForExpense {
        param (
        [string]$accessToken   # Access token for authentication
    )

    write-host "Updating environment variables..." -ForegroundColor Yellow

    try 
    {
        update-EnvironmentVaribleValue -accessToken $accessToken -env_key "msdyn_ExpenseFnoInstanceUrl" -env_value $D365FinanceAndOperationsUrl
        update-EnvironmentVaribleValue -accessToken $accessToken -env_key "msdyn_ExpenseAgentOutlookFolderPath" -env_value $OutlookFolderPath
        update-EnvironmentVaribleValue -accessToken $accessToken -env_key "msdyn_ExpenseAgentMailboxAddressId" -env_value $MailboxAddressId
        
    }
    Catch {
        Write-Host "Failed to update environment variables. Error: $($_)" -ForegroundColor Red -ErrorAction Stop
    }
}

# Function to publish the solution
function Publish-Solution {
    param (
        [string]$accessToken
    )

    Write-Host "Publishing All" -ForegroundColor Yellow

    # Construct the API endpoint for publishing the solution
    $uri = "$DataverseUrl/api/data/v9.2/PublishAllXml"


    # Make the API call
    try {
        Invoke-RestMethod -Method Post `
            -Uri $uri `
            -Headers @{
                Authorization = "Bearer $accessToken"
                "Content-Type" = "application/json"
            }

        Write-Host "Publish All - Success!" -ForegroundColor Green
    } catch {
        Write-Host "Failed to publish. Error: $($_.Exception)" -ForegroundColor Red
        
    }
}

function Get-FlowGuidByName {
    param (
        [string]$accessToken,   # Access token for authentication
        [string]$flowName       # Name of the flow to search for
    )

    #Write-Host "Retrieving GUID for flow: $flowName" -ForegroundColor Yellow

    # Construct the API endpoint with a filter for the flow name
    $encodedFlowName = [System.Web.HttpUtility]::UrlEncode($flowName)
    $uri = "$DataverseUrl/api/data/v9.2/workflows?$filter=name eq '$encodedFlowName'"

    try {
        # Make the API call
        $response = Invoke-RestMethod -Method Get `
            -Uri $uri `
            -Headers @{
                Authorization = "Bearer $accessToken"
                "Content-Type" = "application/json"
            }

        # Check if the flow was found
        if ($response.value.Count -gt 0) {
            $flow = $response.value[0]
            Write-Host "Flow found: $($flow.name) with GUID: $($flow.workflowid)" -ForegroundColor Green
            return $flow.workflowid
        } else {
            Write-Host "No flow found with the name: $flowName" -ForegroundColor Red
            return $null
        }
    } catch {
        Write-Host "Failed to retrieve flow GUID. Error: $($_.Exception.Message)" -ForegroundColor Red
        return $null
    }
}


# Function to activate a Power Automate flow
function Activate-Flow {
    param (
        [string]$DataverseUrl,  # Dataverse environment URL
        [string]$accessToken,   # Access token for authentication
        [string]$flowId         # GUID of the flow to activate
    )

    # Construct the request body
    $body = @{
        "statecode" = 1  # Activated
        "statuscode" = 2 # Activated
    } | ConvertTo-Json -Depth 1 -Compress

    # Construct the API endpoint
    $uri = "$DataverseUrl/api/data/v9.2/workflows($flowId)"

    # Make the API call
    try {
        Invoke-RestMethod -Method Patch `
            -Uri $uri `
            -Headers @{
                Authorization = "Bearer $accessToken"
                "Content-Type" = "application/json"
            } `
            -Body $body

        Write-Host "Flow activated successfully." -ForegroundColor Green
    } catch {
        Write-Host "Failed to activate flow. Error: $($_.Exception.Message)" -ForegroundColor Red
    }
}

function Get-ConnectionRefIdFromLogicalName  {
    param (
        [string]$accessToken,
        [string]$connectionRefLogicalName
    )
    $uri = "$DataverseUrl/api/data/v9.2/connectionreferences?$filter=connectionreferencelogicalname eq '$connectionRefLogicalName'"
    $response = Invoke-RestMethod -Method Get `
    -Uri $uri `
    -Headers @{
        Authorization = "Bearer $accessToken"
        "Content-Type" = "application/json"
    }

    if ($response -ne $null) {
        write-host "Connection reference id found: $($response.value[0].connectionreferenceid) " -ForegroundColor Green
        return $response.value[0].connectionreferenceid
    }
    else {
        Write-Host "No connection reference found for logical name: $connectionRefLogicalName" -ForegroundColor Red
        return $null
    }
}

function Get-ConnectionId {
    param (
        [string]$userProvidedName,
        [string]$providerName
    )

    try {
        $matchedConnectionId = $null
        # Added -ErrorAction Stop to ensure the catch block is triggered on failure
        $connections = Get-PowerAppConnection -EnvironmentName $DataverseEnvironmentId -ConnectorNameFilter $providerName -ErrorAction Stop
        
        foreach ($con in $connections) {
            if (($con.ConnectionName -eq $userProvidedName) -or ($con.DisplayName -eq $userProvidedName)) {
                $matchedConnectionId = $con.ConnectionName
                break
            }
        }

        if ($null -eq $matchedConnectionId) {
            # Use 'throw' to create a terminating error that the calling function can catch
            throw "Unable to find connection '$userProvidedName' for provider '$providerName'."
        }

        return $matchedConnectionId
    }
    catch {
        # Catch any errors from Get-PowerAppConnection or the 'throw' statement above
        Write-Error "Failed to get connection ID for '$userProvidedName'. Error: $_"
        throw # Re-throw the error to stop the script if this step is critical
    }
}

function Get-ConnectionReferenceId {
    param(
        [string]$connectionReferenceLogicalName,
        [securestring]$accessToken
    )

    try {
        $uri = "$DataverseUrl/api/data/v9.2/connectionreferences?$filter=connectionreferencelogicalname eq '$connectionReferenceLogicalName'"
        
        # Added -ErrorAction Stop for clarity, though Invoke-RestMethod often terminates on HTTP errors
        $response = Invoke-RestMethod -Method Get -Uri $uri -Authentication Bearer -Token $accessToken -ContentType 'application/json' -ErrorAction Stop
            
        if ($null -eq $response -or $response.value.Count -eq 0) {
            throw "Connection reference not found for logical name '$connectionReferenceLogicalName'."
        }

        $connectionReferenceDisplayName = $response.value[0].connectionreferencedisplayname
        $connectionReferenceId = $response.value[0].connectionreferenceid

        Write-Host "updating connection $connectionReferenceDisplayName for logical name $connectionReferenceLogicalName)"
        return $connectionReferenceId
    }
    catch {
        Write-Error "Failed to get connection reference ID for '$connectionReferenceLogicalName'. Error: $_"
        throw # Re-throw to notify the calling function
    }
}

function Set-ConnectionReferenceConnection {
    param (
        [string]$connectionReferenceLogicalName,
        [string]$userProvidedConnectionName,
        [string]$providerName,
        [securestring]$accessToken
    )

    try {

        # These functions will now throw terminating errors if they fail
        $connectionReferenceId = Get-ConnectionReferenceId -connectionReferenceLogicalName $connectionReferenceLogicalName -accessToken $accessToken
        $connectionId = Get-ConnectionId -userProvidedName $userProvidedConnectionName -providerName $providerName

        $body = @{
            "connectionid" = "$connectionId"
        } | ConvertTo-Json -Depth 1

        $uri = "$DataverseUrl/api/data/v9.2/connectionreferences($connectionReferenceId)"
        # Write-Host "Updating connection reference URI: $uri with connection id $connectionId"

        Invoke-RestMethod -Method Patch -Uri $uri -Authentication Bearer -Token $accessToken -ContentType 'application/json' -Body $body -ErrorAction Stop
    
        Write-Host "Connection reference updated successfully." -ForegroundColor Green
    }
    catch {
        # This block will catch errors from any of the functions called within the try block
        Write-Error "Failed to set connection reference for '$connectionReferenceLogicalName'. Error: $_"
        throw
    }
}

function Activate-Flows {
    param (
        [string]$accessToken,
        [array]$expenseAIFlows
    )

    foreach ($flowName in $expenseAIFlows) {
         Write-Host "Activating flow: $flowName" -ForegroundColor Yellow

        # Call the Get-FlowGuidByName function to get the flow GUID
        $flowGuid = Get-FlowGuidByName -dataverseUrl $DataverseUrl -accessToken $accessToken -flowName $flowName

        if ($flowGuid -ne $null) {
            # Write-Host "Flow Name: $flowName, Flow GUID: $flowGuid" -ForegroundColor Green
            Activate-Flow -dataverseUrl $DataverseUrl -accessToken $accessToken -flowId $flowGuid
            # Write-Host "Flow Name: $flowName, Flow GUID: $flowGuid Activated" -ForegroundColor Green
        } else {
            Write-Host "Flow Name: $flowName not found." -ForegroundColor Red
        }
    }
}


# Function to retrieve the Agent ID by name
function Get-AgentIdBySchemaName {
    param (
        [string]$DataverseUrl,
        [string]$accessToken,
        [string]$agentSchemaName
    )

    Write-Host "Retrieving agent ID for agent schema: $agentSchemaName" -ForegroundColor Yellow

    # Construct the API endpoint to retrieve the bot
    $uri = "$DataverseUrl/api/data/v9.2/bots?$filter=schemaname eq '$agentSchemaName'"

    try {
        # Make the API call
        $response = Invoke-RestMethod -Method Get -Uri $uri -Headers @{
            Authorization = "Bearer $accessToken"
            "Content-Type" = "application/json"
        }

        if ($response.value.Count -gt 0) {
            $agentId = $response.value[0].botid
            return $agentId
        } else {
            Write-Host "No agent found with the name: $agentSchemaName" -ForegroundColor Red
            return $null
        }
    } catch {
        Write-Host "Failed to retrieve agent ID. Error: $($_)" -ForegroundColor Red
        return $null
    }
}

function Check-BotSyncErrors {
        param (
        [string]$DataverseUrl,
        [string]$accessToken,
        [string]$botId
    )

    Write-Host "Retrieving Sync Status for bot ID: $botId" -ForegroundColor Yellow

    # Construct the API endpoint to retrieve the bot
    $uri = "$DataverseUrl/api/data/v9.2/bots($botId)"
    try {
        # Make the API call
        $response = Invoke-RestMethod -Method Get -Uri $uri -Headers @{
            Authorization = "Bearer $accessToken"
            "Content-Type" = "application/json"
        }

        if ($null -ne $response.synchronizationstatus) {
            # Parse the JSON string in synchronizationstatus
            $syncStatusObj = $response.synchronizationstatus | ConvertFrom-Json
            $state = $syncStatusObj.currentSynchronizationState.state
            $provisioningStatus = $syncStatusObj.currentSynchronizationState.provisioningStatus

            Write-Host "Synchronization State: $state" -ForegroundColor Green
            Write-Host "Provisioning Status: $provisioningStatus" -ForegroundColor Green

            if ( $state -contains "Error" -or $provisioningStatus -contains "Error") {
                Write-Host "Bot has synchronization errors." -ForegroundColor Red
                return 0
            } else {
                if ( $state -eq "Synchronized" -or $state -eq 'Synchronizing' -and ($provisioningStatus -eq  "Provisioned" -or $provisioningStatus -eq  "ProvisionedWithoutRegistration")) {
                    Write-Host "Bot synchronization is done." -ForegroundColor Yellow
                    return 1
                } else {
                    Write-Host "Bot synchronization is in progress." -ForegroundColor Green
                    return 2
                }
            }
        } else {
            Write-Host "No synchronization status found for bot ID: $botId" -ForegroundColor Red
            return $null
        }
    } catch {
        Write-Host "Failed to retrieve agent ID. Error: $($_)" -ForegroundColor Red
        return $null
    }
}


# Function to provision a PVA bot
function Provision-Agent {
    param (
        [string]$DataverseUrl,
        [string]$accessToken,
        [string]$agentId
    )

    # Construct the API endpoint for publishing the bot
    $uri = "$DataverseUrl/api/data/v9.2/bots($agentId)/Microsoft.Dynamics.CRM.PvaProvision"

    try {
        # Make the API call
        Invoke-RestMethod -Method Post -Uri $uri -Headers @{
            Authorization = "Bearer $accessToken"
            "Content-Type" = "application/json"
        }

        Write-Host "Agent Provisioning successfully!" -ForegroundColor Green
        # Add 30 second delay to allow the publish process to complete
        Start-Sleep -Seconds 30
        return $true
    } catch {
        Write-Host "Failed to Provision Agent. Error: $($_.Exception.Message)" -ForegroundColor Red
    }
    return $false
}


# Function to publish a PVA bot
function Publish-Agent {
    param (
        [string]$DataverseUrl,
        [string]$accessToken,
        [string]$agentId
    )

    Write-Host "Publishing agent with ID: $agentId" -ForegroundColor Yellow

    # Construct the API endpoint for publishing the bot
    $uri = "$DataverseUrl/api/data/v9.2/bots($agentId)/Microsoft.Dynamics.CRM.PvaPublish"

    try {
        # Make the API call
        Invoke-RestMethod -Method Post -Uri $uri -Headers @{
            Authorization = "Bearer $accessToken"
            "Content-Type" = "application/json"
        }

        Write-Host "Agent published successfully!" -ForegroundColor Green
        # Add 30 second delay to allow the publish process to complete
        Start-Sleep -Seconds 30
    } catch {
        Write-Host "Failed to publish Agent. Error: $($_.Exception.Message)" -ForegroundColor Red
    }
}

function Publish-Agents {
    param (
        [string]$accessToken,
        [array]$agentSchemas
    )

    if (-not $agentSchemas -or $agentSchemas.Count -eq 0) {
        Write-Host "No agent schemas provided. Skipping agent publishing." -ForegroundColor Yellow
        return
    }

    foreach ($agentSchema in $agentSchemas) {
        #Write-Host "Publishing agent schema: $agentSchema" -ForegroundColor Yellow

        try {
                # Construct the API endpoint for publishing the agent schema
                $agentId = Get-AgentIdBySchemaName -dataverseUrl $DataverseUrl -accessToken $accessToken -agentSchemaName $agentSchema

                if ($agentId -ne $null) {
                    # check for sync errors
                    if ($CheckBotSyncStatusAndProvisionBots) {
                        $syncStatus = Check-BotSyncErrors -dataverseUrl $DataverseUrl -accessToken $accessToken -botId $agentId
                        if (0 -eq $syncStatus) {
                            Write-Host "Agent has sync errors. Skipping the publish process. Please check the bot: $agentId details" -ForegroundColor Red
                            continue
                        } elseif (2 -eq $syncStatus) {
                            Write-Host "Agent synchronization is still in progress. reprovisioning the agent." -ForegroundColor Yellow
                            if (Provision-Agent -dataverseUrl $DataverseUrl -accessToken $accessToken -agentId $agentId -eq $false) {
                                Write-Host "Agent reprovisioning failed. Skipping the publish process. Please check the bot: $agentId details" -ForegroundColor Red
                                continue
                            }
                        } else {
                            Write-Host "Agent synchronization is done. Proceeding to publish." -ForegroundColor Green
                        }
                    }
                    # Step 4: Publish the bot
                    Publish-Agent -dataverseUrl $DataverseUrl -accessToken $accessToken -agentId $agentId
                } else {
                    Write-Host "Agent not found. Cannot proceed with publishing.Skipping the step" -ForegroundColor Yellow
                }
        }
        catch {
            Write-Host "An error occurred while publishing agent schema: $agentSchema. Error: $_" -ForegroundColor Red
        }
    }

}


# Main script execution
try {

    $expenseAIFlows = $flows
    $agentSchemas = $agents

    # Step 1: Interactive login to Azure
    Connect-AzAccount -UseDeviceAuthentication
    $accessToken = Get-AccessToken
    $accessTokenPlainText = Get-AccessTokenPlainText -accessToken $accessToken

    # Step 2: Setup ennviornment variables
    update_EnvironmentVariablesForExpense -accessToken $accessTokenPlainText 
    Write-Host "Environment variables updated successfully!" -ForegroundColor Green

    # Step 3: Check active connections
    Set-ConnectionReferenceConnection -userProvidedConnectionName $MicrosoftDataverseConnectionName -providerName "/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps" -connectionReferenceLogicalName "msdyn_sharedcommondataserviceforapps_2c2d4" -accessToken $accessToken

    Set-ConnectionReferenceConnection -userProvidedConnectionName $MicrosoftCopilotStudioConnectionName -providerName "/providers/Microsoft.PowerApps/apis/shared_microsoftcopilotstudio" -connectionReferenceLogicalName "msdyn_sharedmicrosoftcopilotstudio_26d9d" -accessToken $accessToken

    Set-ConnectionReferenceConnection -userProvidedConnectionName $Office365OutlookConnectionName -providerName "/providers/Microsoft.PowerApps/apis/shared_office365" -connectionReferenceLogicalName "msdyn_sharedoffice365_9b471" -accessToken $accessToken

    Set-ConnectionReferenceConnection -userProvidedConnectionName $MicrosoftTeamsConnectionName -providerName "/providers/Microsoft.PowerApps/apis/shared_teams" -connectionReferenceLogicalName "msdyn_sharedteams_8ea9c" -accessToken $accessToken

    Set-ConnectionReferenceConnection -userProvidedConnectionName $Office365UsersConnectionName -providerName "/providers/Microsoft.PowerApps/apis/shared_office365users" -connectionReferenceLogicalName "msdyn_sharedoffice365users_909b9" -accessToken $accessToken
    

    # Step 4: Activate flows
    Activate-Flows -accessToken $accessTokenPlainText -expenseAIFlows $expenseAIFlows

    # step 5: publish the agents
    Publish-Agents -accessToken $accessTokenPlainText -agentSchemas $agentSchemas

    # Step 6: Publish the solution 
    Publish-Solution -accessToken $accessTokenPlainText

    Write-Host "Agent setup completed successfully!" -ForegroundColor Green

} catch {
    Write-Host "An error occurred: $_" -ForegroundColor Red
}

Per attivare il file di PowerShell, seguire questa procedura:

1. Aprire PowerShell (versione minima richiesta - PowerShell 7).
2. Passare al percorso in cui è stato salvato il file. Usa la <posizione del file> del comando cd .
3. Attiva lo script di installazione. (Usa il comando ".\Install.ps1").
4. Seguire le istruzioni per accedere a Azure.
5. Dopo l'accesso, potrebbe essere necessario autorizzare un'altra volta. Usa l'ID utente dell'agente creato.

Attendere che lo script venga eseguito completamente e cercare il messaggio Agent setup completed successfully!

Dopo l'esecuzione dello script, Agente spesa è completamente configurato e pronto per l'uso.

Opzione B: configurata manualmente in Power Apps (senza PowerShell)

Se non si vuole usare lo script di PowerShell, è possibile configurare manualmente l'agente spese tramite Power Apps. Questo processo comporta l'aggiornamento delle variabili di ambiente, l'abilitazione dei flussi Power Automate e la pubblicazione della soluzione.

Aggiornamento delle variabili di ambiente

Per aggiornare le variabili di ambiente, seguire questa procedura:

1. Accedere a Power Apps e selezionare l'ambiente.

2. Seleziona Soluzioni, quindi apri Soluzione predefinita (o la soluzione in cui è installato l'agente).

3. Vai a Variabili di ambiente e imposta i valori seguenti.

   Nome variabile	Descrizione
   Percorso cartella Outlook gestione delle spese	Specifica il percorso della cartella da monitorare nella cassetta postale condivisa (per impostazione predefinita Posta in arrivo).
   ID dell'indirizzo della cassetta postale condivisa dell'Agente di spesa	Specifica l'indirizzo e-mail della cassetta postale condivisa. Per usare la cassetta postale dell'utente connesso, immetti NA.
   URL istanza Finance and Operations	Specifica l'URL dell'ambiente per le app per la finanza e le operazioni (ad esempio, https://org123.contoso.com).

Abilitare i flussi di Power Automate

L'Agente delle Spese si basa sui seguenti flussi di Power Automate:

• Controllo dei tentativi per l'inserimento spese
• Configurazione spese
• Ottieni la cartella Outlook delle voci di spesa
• Genera un report spese
• Invia scheda adattiva della nota spese
• Corrispondenza automatica delle spese
• Elabora messaggi e-mail
• Estrai gli ID delle ricevute non allegati per la chiamata del copilota
• Estrai l'output della ricevuta non allegata utilizzando il plug-in Dataverse
• Genera riga di spesa
• Genera una riga di spesa senza ID progetto e ID stato
• Identificare gli ID progetto
• Eventi del calendario utente
• Elabora la nota spese utilizzando il copilota
• Attivare l'agente di spesa per l'elaborazione delle ricevute

Per abilitare i flussi, seguire questa procedura:

1. Accedere a Power Automate e selezionare l'ambiente.

2. Seleziona Flussi personali.

3. Per ognuno dei 15 flussi nell'elenco precedente, seguire questa procedura:

   1. Trova il flusso.
   2. Seleziona Modifica.
   3. Vai alla visualizzazione Finestra di progettazione precedente. disattivando l'opzione Nuova finestra di progettazione.
   4. Autentica le connessioni necessarie (fino a quando non vengono visualizzati i segni di spunta verdi).
   5. Seleziona Continua e quindi Salva.
   6. Seleziona Attiva per abilitare il flusso.

Pubblicare la soluzione

Dopo aver completato la configurazione di tutte le variabili di ambiente e i flussi, segui questa procedura per pubblicare la soluzione.

1. In Power Apps passare a Solutions.
2. Seleziona l'ambiente e la soluzione.
3. Seleziona Pubblica tutte le personalizzazioni.

Al termine di questi passaggi, l'Agente delle Spese è completamente configurato e pronto per l'uso.

Passaggio 6: Abilitare l'Agente delle Spese in Microsoft Teams (facoltativo)

Per abilitare la comunicazione tramite Teams per l'agente delle spese, aggiungere il canale Teams all'agente in Power Apps. L'agente può quindi inviare schede adattive tramite Teams.

Abilitare il canale di Teams

Per abilitare il canale teams, seguire questa procedura:

1. Accedere a Copilot Studio e selezionare l'ambiente corretto.
2. Nella scheda Agenti, seleziona Agente Inserimento spese.
3. Nella visualizzazione agente, nella scheda Channels selezionare Teams e Microsoft 365 Copilot.
4. Seleziona Aggiungi canale per abilitare l'integrazione di Teams e segui la procedura descritta nella sezione Configurare la disponibilità delle app teams per configurare con chi si vuole condividere l'app.

Per altre informazioni, vedere Aprire il pannello di configurazione per il canale Teams + Microsoft 365.

Configurare la disponibilità dell'app Teams

Per configurare la disponibilità dell'app Teams, seguire questa procedura:

1. Dopo aver creato l'app Teams, selezionare Opzioni di disponibilità.

2. Seleziona con chi desideri condividere l'app:

   • Utenti specifici all'interno dell'organizzazione
   • Intera organizzazione

3. Invia l'app per l'approvazione.

Pubblicare l'app nell'interfaccia di amministrazione di Teams

Per pubblicare l'app nell'interfaccia di amministrazione di Teams, seguire questa procedura:

1. Accedi all'Interfaccia di amministrazione di Teams.
2. Vai a Gestisci app dell'app > Teams. Cercare "expense" (Spese) e selezionare Expense Entry Agent app in cui lo stato dell'app è bloccato.
3. Seleziona Pubblica per sbloccare l'app. Al termine dell'azione di pubblicazione, assicurarsi che lo stato dell'app venga modificato in sbloccato.

Per altre informazioni, vedere Connettere e configurare un agente per Teams e Microsoft 365.

Al termine di questi passaggi, l'Agente delle Spese è pronto per l'uso.

Disinstallare l'Agente spesa

Per disinstallare l'agente spese, seguire questi passaggi:

1. Accedere al portale di Microsoft Power Apps Maker.
2. Seleziona Soluzioni, cerca msdyn_ExpenseAI, seleziona i tre puntini quindi Elimina.
3. Ricerca msdyn_FnOCopilotAnchor e poi elimina la soluzione.