Kuluagentin määrittäminen (esiversio)

Soveltuu Dynamics 365 Project Operationsin integroituun ERP:hen ja Dynamics 365 Project Operations valmistusteollisuuteen

Kuluagentti tuo yhteen Microsoft Dynamics 365 Project Operations-, talous- ja toimintosovellusten, Microsoft Copilot Studio, Power Automate ja Dataversen toiminnot kulunkäsittelyn työnkulkujen automatisoimiseksi tekoälyn avulla. Tämä ominaisuus säästää aikaa ja vähentää manuaalista työtä, sillä järjestelmäsi voi käsitellä kuitit ja luoda käyttäjille kulurivejä ja kuluraportteja. Se käyttää Microsoft Power Platform liittimiä integrointiin Outlook, Microsoft Teams, käyttäjäkalentereiden sekä Finance and Operations -sovellusten ympäristöön Dataversen virtuaalisten entiteettien kautta.

Kuluagentti sisältää useita työnkulkuja, joista kolme toimii pääorkestroijina seuraavasti:

• Process Emails – Tämä työnkulku tarkistaa määritetyn postilaatikkokansion tunnin välein ja tallentaa liitteet kiinnittämättöminä kuiteina Dynamics 365 Finance.
• Poimi kuittitunnukset – Tämä työnkulku noutaa liittämättömät kuitit ja käynnistää agentin, joka poimii kuittien tiedot ja luo liittämättömän kulurivin.
• Prosessin kuluraportti – Tämä työnkulku muuntaa yhdistämättömät kulurivit ja luo kuluraportit ryhmittelyraporttien perusteella määrityksillä , jotka määrität sovelluksessa jokaista juridista entiteettiä varten.

Lisäksi agentti integroituu Microsoft Teams, mikä mahdollistaa mukautuvien korttien käytön kuluraporttien tarkistamiseen ja lähettämiseen.

Agentti käyttää useita Microsoft Power Platform liittimiä. Näihin liittimeen viitataan automaattisesti tarjotuissa Power Automate työnkuluissa.

• Outlook (Office 365) – Tämä yhdistin poimii kuitit jaetun postilaatikon kautta.
• Dataverse (virtuaaliset entiteetit) – Tämä yhdistin ja talous- ja toimintosovellukset integroidaan virtuaalisten entiteettien kautta.
• Microsoft Copilot Studio – Tämä liitin kutsuu tekoälymalleja poimimaan vastaanottotiedot.
• Microsoft Teams – Tämä liitin lähettää mukautuvat kortit käyttäjän toimia varten (jos Teamsin integrointi on käytössä).
• Microsoft 365 Users – Tämä liitin noutaa käyttäjäkalenterin tiedot (valinnainen, jos vastaanoton jäsentäminen on kontekstin huomioon ottavaa).

Edellytykset

1. Rahoitus- ja toimintoympäristö: Tarvitset vähintään version 10.0.44 (10.0.2263.175 ja uudemmat) tai 10.0.45 (10.0.1 2345.115 ja uudemmat) tai 10.0.46 (10.0.2428.69 ja uudemmat) rahoitus- ja toimintoympäristöstä agentin asentamiseksi.
2. Kuluagentti-käyttäjän määrittämiseen tarvittavat roolit: Jotta voit suorittaa tämän artikkelin vaiheet, sinun on oltava organisaation järjestelmänvalvoja ja sinulla on oltava seuraavat roolit, jotta voit määrittää kuluagenttikäyttäjän kuluagentin asentamista varten.

Kuluagentin määrittämisen vaiheet

Jos haluat asentaa kuluagentin ja määrittää sen, toimi seuraavasti:

1. Asenna Copilot Finance and Operations -sovelluksille.
2. Ota agentin ominaisuudet käyttöön ympäristössä.
3. Kulukäyttäjän luominen agentin suoritusta varten.
4. Määritä jaettu postilaatikko.
5. Määritä kuluagentti.
6. Ota kuluagentti käyttöön Microsoft Teams (valinnainen – jos tarvitset Microsoft Teams integrointia)

Seuraavissa osioissa kuvataan kukin vaihe yksityiskohtaisesti.

Vaihe 1: asenna Copilot finance and operations -sovelluksille

Kuluagentti on käytettävissä osana Copilot finance and operations -sovellusten pakettia. Kun olet asentanut tämän paketin ympäristöösi, saat automaattisesti kaikki tarvittavat resurssit, mukaan lukien agentin, ympäristömuuttujat ja Power Automate työnkulut.

Jos haluat asentaa tarvittavan sovelluksen, toimi seuraavasti:

1. Siirry selaimessa Power Platform -hallintakeskukseen.
2. Valitse ympäristöluettelosta sen ympäristön nimi, johon haluat asentaa sovelluksen.
3. Ympäristön tietosivulla (NOT vasemmasta siirtymisruudusta) siirry Resources -osioon ja valitse Dynamics 365 apps.
4. Hae Copilot finance and operations -sovelluksille Dynamics 365-sovellusten luettelosta. Jos se on jo asennettu ja päivitys on saatavilla, valitse Päivitä-painike.
5. Jos sovellusta ei ole lueteltu kohdassa Dynamics 365 sovellukset, valitse Install-sovellus, valitse Copilot finance and operations -sovelluksille ja viimeistele asennus noudattamalla ohjeita.
6. Copilot Finance and Operations -sovellusten on oltava 1.0.3231.4 tai uudempi

Vaihe 2: Agentin ominaisuuksien ottaminen käyttöön ympäristössä

Kun olet asentanut Copilot for Finance and Operations -sovelluspaketin, aktivoi Kuluagentti Dataverse- ja Finance and Operations -ympäristöistäsi.

Ominaisuuden ottaminen käyttöön Dataversessa

Ota Copilot ominaisuusmerkintä käyttöön Power Platform -hallintakeskuksessa. Voit ottaa Copilot ominaisuusmerkinnän käyttöön seuraavasti:

1. Siirry Power Platform -hallintakeskukseen.
2. Valitse Ympäristöt> valitse ympäristö >Asetukset>Tuote> valitse Ominaisuudet.
3. Vahvista, että Copilot -ominaisuusmerkintä on käytössä.

Ominaisuuden ottaminen käyttöön talous- ja toimintoympäristössä

Jos haluat aktivoida agentin talous- ja toimintosovelluksissa, toimi seuraavasti:

1. Kirjaudu sisään talous- ja toimintosovellusten ympäristöön.
2. Siirry kohtaan Ominaisuuksien hallinta ja ota käyttöön Älykäs aloitussivu -ominaisuus sekä agenttien hallinnan ominaisuudet.
3. Voit määrittää kuluagentin (määritys tehdään yrityskohtaisesti) siirtymällä kohtaan Kulujenhallinta>Asetukset>Yleistiedot>Kulujen hallintaparametrit.
4. Määritä Kulujen määritys -agentti -välilehdessä parametrit alla olevassa taulukossa esitetyllä tavalla.

Vaihe 3: Kuluagentti-käyttäjän luominen agentin suoritusta varten

Luo erillinen kuluagenttikäyttäjä, jotta varmistetaan, että agentti suoritetaan työntekijän henkilöllisyydestä riippumatta. Tämä menetelmä parantaa suojausta, hallittavuutta ja pitkän aikavälin ylläpidettävyyttä. Vaikka voit käyttää olemassa olevaa käyttäjätiliä, jolla on tarvittavat oikeudet, käytä järjestelmän omistamia käyttäjätietoja.

Kuluagentti-käyttäjän luominen Microsoft Entra ID

1. Kirjaudu sisään Azure-portaaliin.
2. Valitse käytettävissä olevista Azure-palveluista Microsoft Entra ID.
3. Luo uusi käyttäjä kohdassa Microsoft Entra ID.
4. Valitse Lisää>Käyttäjä>Luo uusi käyttäjä ja anna alla olevat tiedot.
   • Täydellinen käyttäjätunnus
   • Valitse oikea toimialue
   • Näyttönimi
   • Salasana
   • Valitse Tili käytössä -kohta
5. Jos haluat tarkastella tietoja ja tehdä käyttäjän luontiprosessin loppuun, valitse Tarkista ja luo ja valitse sitten Luo.
6. Valitse Käyttäjä-sivulla (Hallinta > Käyttäjät) käyttäjä ja valitse sitten Näytä tiedot -sivu.
7. Valitse Muokkaa ominaisuuksia, siirry Asetukset-välilehteen ja anna soveltuva käyttösijainti.

Vaadittujen käyttöoikeuksien määrittäminen kuluagenttikäyttäjälle

Jos haluat asentaa Kuluagentti-agentin, määritä kuluagenttikäyttäjälle seuraavat käyttöoikeudet:

• Teamsin jäsenten Dynamics 365 käyttöoikeus
• Microsoft 365 Business Basic tai mikä tahansa käyttöoikeus, joka kattaa Microsoft Teams ja Outlook (esimerkiksi Office 365 E5 tiimien kanssa)
• Power Apps Premium

Voit määrittää käyttöoikeuksia seuraavasti:

1. Kirjaudu sisään Microsoft 365 -hallintakeskukseen käyttäjällä, jolla on oikeus määrittää käyttöoikeuksia, jotka ovat käyttöoikeuksien järjestelmänvalvojia tai uudempia.
2. Valitse Billing>Käyttöoikeudet>Dynamics 365 Teamsin jäsenten käyttöoikeus.
3. Valitse +Määritä käyttöoikeuksia.
4. Hae edellisessä vaiheessa luotu kuluagenttikäyttäjä.
5. Viimeistele käyttöoikeuden määritys valitsemalla Määritä.
6. Noudata vaiheita 2–5 muiden käyttöoikeuksien kohdalla – Microsoft 365 Business Basic ja Power Apps Premium.

Lisää käyttäjä Power Platform -ympäristöön

Jos haluat lisätä käyttäjän Power Platform -ympäristöön, toimi seuraavasti:

1. Kirjaudu sisään Power Platform -hallintakeskukseen ja valitse soveltuva ympäristö.

   Vihje

   Tämä sivu sisältää tietoja Dataversen ympäristön tunnuksesta, Dataversen ympäristön URL-osoitteesta sekä talous- ja toimintosovellusten URL-osoitteesta. Tallenna nämä arvot, jotta niitä voi käyttää myöhemmissä osissa.

2. Siirry kohtaan Käyttöoikeus > Käyttäjät > Näytä kaikki.

3. Valitse Lisää käyttäjä, syötä juuri luotu agenttikäyttäjä ja valitse Lisää.

4. Lisää seuraavat roolit Käyttöoikeusroolien hallinta -sivulla.

   • Kulujenhallinnan tekoälyagentin rooli
   • Talous- ja toimintojen agentti Configuration Manager
   • Järjestelmämukauttaja

5. Jos haluat vahvistaa roolien määritykset, valitse Tallenna.

Nämä roolit tarjoavat pääsyn Dataverseen ja Power Automate osia, joita agentin on käytettävä.

Vaaditun roolin määrittäminen talous- ja toimintosovellusten ympäristössä

Jos haluat määrittää ExpenseAgentRole-roolin talous- ja toimintoympäristössä, toimi seuraavasti:

1. Siirry talous- ja toimintosovellusten ympäristössä kohtaan Järjestelmän hallinta>Käyttäjät.
2. Luo käyttäjätietue agenttikäyttäjälle.
3. Kun olet luonut käyttäjän, siirry käyttäjän roolit -osioon, valitse Määritä roolit ja tee haku hakusanalla ExpenseAgentRole.
4. Valitse Tallenna.

Jaetun postilaatikon käyttöoikeuden määrittäminen

Agenttikäyttäjällä on oltava Mail.Read.Shared Microsoft Graph -oikeus. Tämän käyttöoikeuden avulla agentti voi lukea kuitit määritetystä jaetusta postilaatikosta työnkulun suorittamisen aikana.

Määritä jaetun postilaatikon käyttöoikeuden käyttöoikeudet seuraavasti:

1. Siirry kohtaan Microsoft Graph Explorer ja kirjaudu sisään käyttämällä luoneen agentin käyttäjää.
2. Valitse oikeassa yläkulmassa oleva Käyttäjä -kuvake > valitse Hyväksyntä käyttöoikeuksille.
3. Valitse avattava valikko kohdassa Posti> etsi Mail.Read.Shared> valitse Hyväksyntä ja valitse sitten Hyväksy.

Luodun agenttikäyttäjän pakollisten roolien yhteenveto

Vaihe 4: Jaetun postilaatikon määrittäminen

Kuluagentti käyttää jaettua postilaatikkoa sähköpostiviestien vastaanottamiseen ja käsittelyyn. Exchange-järjestelmänvalvojan roolissa olevan käyttäjän on luotava ja määritettävä tämä postilaatikko Microsoft 365 Admin Center.

Voit luoda ja määrittää jaetun postilaatikon seuraavasti:

1. Kirjaudu sisään Microsoft 365 Admin Center Exchange Admin -tilillä.

2. Valitse vasemmanpuoleisessa ruudussa Tiimit ja ryhmät>Jaetut postilaatikot.

   Vihje

   Sinun täytyy ehkä valita Näytä kaikki , jotta voit laajentaa koko luettelon.

3. Valitse Lisää jaettu postilaatikko.

4. Kirjoita jaetun postilaatikon nimi ja sähköpostiosoite.

5. Valitse Tallenna muutokset.

6. Valitse Seuraavat vaiheet -kohdassa Lisää jäseniä tähän jaettuun postilaatikkoon. (Jäsenten hallinta voi olla käytettävissä muutaman minuutin kuluttua.)

7. Valitse Lisää jäseniä

8. Valitse luotu agenttikäyttäjä ja kaikki muut postilaatikkoa valvovat tahot ja valitse sitten Lisää.

9. Valitse Sulje.

Vaihe 5: Kuluagentin määrittäminen

Kuluagentti voidaan määrittää kahdella seuraavalla tavalla:

• Vaihtoehto A: PowerShell-komentosarjan käyttäminen (suositus)
• Option B: Manuaalinen määrittäminen Power Apps (ei PowerShelliä)

Vaihtoehto A: PowerShell-komentosarjan käyttäminen (suositus)

Agentin manuaaliseen määrittämiseen kuuluu yhteyksien luominen ja linkittäminen, Power Automate työnkulkujen käyttöönotto ja ratkaisun julkaiseminen. Tämä prosessi voi viedä paljon aikaa, ja sen aikana voi helposti tulla virheitä. Voit automatisoida määritykset käyttämällä PowerShell-komentosarjaa vaadittujen parametrien päivittämisen jälkeen.

PowerShell-komentosarja automatisoi seuraavat tehtävät:

• Päivittää tarvittavat ympäristömuuttujat.
• Yhdistää Microsoft Power Platform -liitännät ratkaisun yhteyksien viitteisiin.
• Ottaa käyttöön kaikki Power Automate työnkulut, joita Aika- ja kuluagentti vaatii.
• Julkaisee Copilot agentteja.
• Julkaisee Dataverse-ratkaisun.

Ennen komentosarjan suorittamista on luotava yhteydet, sillä install.ps1-tiedoston jokaiselle yhdistimelle on annettava yhteystunnus. Voit luoda nämä yhteydet noudattamalla seuraavia vaiheita käyttäen luotua agentin käyttäjää.

1. Kirjaudu sisään Power Apps maker portal käyttämällä juuri luotua agenttikäyttäjää ja valitse ympäristösi.
2. Valitse vasemmanpuoleisessa ruudussa Lisää ja valitse sitten Yhteydet.
3. Valitse Uusi yhteys ja hae käyttämällä seuraavan taulukon yhteyden nimeä (esimerkiksi Office 365 Outlook).
4. Valitse luettelosta soveltuva yhdistin ja luo se.
5. Kun yhteys on luotu, ota huomioon käyttäjä, jolle yhteys on luotu. Parhaassa tapauksessa se on luodun agentin käyttäjätunnus. Päivitä tämä käyttäjätunnus asennustiedostossa, jonka luot seuraavassa vaiheessa.
6. Toista vaiheet 3 ja 4 kaikille jäljellä oleville vaadituille yhteyksille, jotka mainitaan alla olevassa taulukossa.

Tiedot, joita tarvitaan asennustiedoston luomisessa

Asennustiedoston luomiseksi – install.ps1, on käytettävissä seuraavat tiedot. (Tiedot löytyvät alla olevasta taulukosta.)

Asennuksen komentosarjatiedoston luominen

Luo asennuksen komentosarjatiedosto kopioimalla seuraava koodi. Lisää tarvittavat ympäristömuuttujat komentosarjaan ja suorita komentosarja PowerShellin avulla.

Luo PowerShell-komentosarjatiedosto käyttäen seuraavaa koodia. Päivitä mainitut parametrit ennen komentosarjan suorittamista.

Kopioi seuraava koodi asennuksen komentosarjatiedostoon ja tallenna se nimellä 'Install.ps1'. Päivitä param-osan parametrikenttien muuttujat . Sinun on päivitettävä 10 muuttujaa.

#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
}

Käynnistä PowerShell-tiedosto seuraavasti:

1. Avaa PowerShell (pienin vaadittu versio – PowerShell 7).
2. Siirry sijaintiin, johon tallensit tiedoston. (Käytä komentoa cd <tiedoston sijainti>).
3. Käynnistä asennuksen komentosarja. (Käytä komentoa .\Install.ps1).
4. Kirjaudu sisään Azure noudattamalla ohjeita.
5. Kun olet kirjautunut sisään, saatat joutua valtuuttamaan sen vielä kerran. (Käytä luodun agentin käyttäjätunnusta.).

Odota, että komentosarja suoritetaan kokonaan, ja etsi viestin , jonka mukaan Agentin asennus on suoritettu onnistuneesti!

Kun komentosarja on suoritettu onnistuneesti, kuluagentti on täysin määritetty ja valmis käytettäväksi.

Vaihtoehto B: Määritä manuaalisesti Power Apps (ei PowerShelliä)

Jos et halua käyttää PowerShell-komentosarjaa, voit määrittää kuluagentin manuaalisesti Power Apps kautta. Tähän prosessiin kuuluu ympäristömuuttujien päivittäminen, Power Automate työnkulkujen käyttöönotto ja ratkaisun julkaiseminen.

Päivitä ympäristömuuttujat

Voit päivittää ympäristömuuttujia seuraavasti:

1. Kirjaudu sisään Power Apps ja valitse ympäristösi.

2. Valitse Ratkaisut ja avaa sitten oletusratkaisu (tai ratkaisu, johon agentti on asennettu).

3. Siirry Ympäristömuuttujat-kohtaan ja määritä alla mainitut arvot.

   Muuttujan nimi	Kuvaus
   Kuluagentti Outlook kansiopolku	Määritä jaetussa postilaatikossa valvottava kansiopolku (oletusarvoisesti se on Saapuneet-kansio).
   Kustannusagentin jaetun postilaatikon osoite-ID	Määritä jaetun postilaatikon sähköpostiosoite. Jos haluat käyttää sisäänkirjautuneen käyttäjän postilaatikkoa, anna arvoksi Ei mitään.
   Finance and Operations -ilmentymän URL-osoite	Määritä talous- ja toimintosovellusten ympäristön URL-osoite (esimerkiksi https://org123.contoso.com).

Ota Power Automate -työnkulut käyttöön

Kuluagentti käyttää seuraavia Power Automate työnkulkuja:

• Kulujen määrityksen uudelleenyritysten tarkistus
• Kulun määritys
• Kulujen Outlook-kansion noutaminen
• Kuluraportin luominen
• Kuluraportin mukautuvan kortin lähettäminen
• Kulujen automaattinen täsmäyttäminen
• Käsittele sähköpostiviestit
• Liittämättömien kuittien tunnusten poimiminen avustajan kutsua varten
• Liittämättömän kuitin tuloksen poimiminen Dataverse-laajennuksen avulla
• Kulurivin luominen
• Kulurivin luominen ilman projektin ja tilan tunnusta
• Projektien tunnusten tunnistaminen
• Käyttäjien kalenteritapahtumat
• Kuluraportin käsitteleminen avustajan avulla
• Kuluagentin kutsuminen vastaanoton käsittelyä varten

Voit ottaa työnkulut käyttöön seuraavien ohjeiden avulla:

1. Kirjaudu sisään Power Automate ja valitse ympäristösi.

2. Valitse Omat työnkulut.

3. Toimi edellisen luettelon kunkin 15 työnkulun kohdalla seuraavasti:

   1. Etsi työnkulku.
   2. Valitse Muokkaa.
   3. Vaihda Vanha suunnitteluohjelma -näkymään poistamalla käytöstä Uusi suunnitteluohjelma -vaihtoehto.
   4. Todenna kaikki vaaditut yhteydet (kunnes vihreät tarkistusmerkit tulevat näkyviin).
   5. Valitse Jatka ja valitse sitten Tallenna.
   6. Valitse Ota käyttöön ottaaksesi prosessin käyttöön.

Julkaise ratkaisu

Kun kaikki ympäristömuuttujat ja työnkulut on määritetty, julkaise ratkaisu alla olevien ohjeiden avulla.

1. Siirry Power Apps kohtaan Solutions.
2. Valitse ympäristö ja ratkaisu.
3. Valitse Julkaise kaikki mukautukset.

Kun olet suorittanut nämä vaiheet, Kuluagentti on täysin määritetty ja valmis käytettäväksi.

Vaihe 6: Ota kuluagentti käyttöön Microsoft Teams (valinnainen)

Jos haluat ottaa Käyttöön Teams-pohjaisen viestinnän kuluagentille, lisää Teams-kanava agentille Power Apps. Agentti voi sitten lähettää mukautuvia kortteja Teamsin kautta.

Teams-kanavan ottaminen käyttöön

Ota Teams-kanava käyttöön seuraavasti:

1. Kirjaudu sisään Copilot Studio ja valitse oikea ympäristö.
2. Valitse Agentit-välilehdessä Kulujen määrityksen agentti.
3. Valitse agenttinäkymässä Channels -välilehdeltä Teemoja ja Microsoft 365 Copilot.
4. Valitse Lisää kanava, jos haluat ottaa käyttöön Teams-integroinnin. Määritä, kenelle haluat jakaa sovelluksen, käyttämällä Teams-sovelluksen käytettävyyden määrittäminen -osan ohjeita.

Lue lisää artikkelista Avaa Teams + Microsoft 365 -kanavan määrityspaneeli.

Teams-sovelluksen käytettävyyden määrittäminen

Määritä Teams-sovelluksen käytettävyys seuraavasti:

1. Kun Teams-sovellus on luotu, valitse Käytettävyysasetukset.

2. Määritä seuraavasti, kenelle haluat jakaa sovelluksen:

   • Tietyt käyttäjät organisaatiossa
   • Koko organisaatio

3. Lähetä sovellus hyväksyttäväksi.

Sovelluksen julkaiseminen Teams-hallintakeskuksessa

Jos haluat julkaista sovelluksen Teamsin hallintakeskuksessa, toimi seuraavasti:

1. Kirjaudu Teamsin hallintakeskukseen.
2. Siirry teams-sovellukseen > Sovellusten hallinta. Hae "kulu" ja valitse Kulun merkintä -agenttisovellus , jossa sovelluksen tila on estetty.
3. Poista sovelluksen esto valitsemalla Julkaise. Kun julkaisutoiminto on valmis, varmista, että sovelluksen tila muuttuu estottomana.

Lue lisää artikkelista Sihdistä ja määritä teamsin agentti ja Microsoft 365.

Kun olet suorittanut nämä vaiheet, Kuluagentti on valmis käytettäväksi.

Kuluagentin asennuksen poistaminen

Jos haluat poistaa Kuluagentti-asennuksen , toimi seuraavasti:

1. Kirjaudu sisään Microsoft Power Apps maker-portaaliin.
2. Valitse Ratkaisut, hae msdyn_ExpenseAI, valitse kolme pistettä ja valitse sitten Poista.
3. Etsi msdyn_FnOCopilotAnchor ja poista ratkaisu.