Breadcrumbs

Webchat installation + Azure setup (Dansk)

 

Forord

Denne vejledning er for teknikere som skal installere Miralix Webchat Service. Teknikeren bør have uddannelse som IT Supporter, eller have tilsvarende kvalifikationer. Derudover have relevant kendskab til Microsoft Azure, Microsoft Azure CLI og Microsoft Azure Bot ressourcer. 

Miralix Chat service sender og modtager beskeder til og fra jeres Webchat kanal mod Miralix Desktop som giver mulighed for at chatte med kunder eller borgere via f.eks. en hjemmeside. 

Miralix chat servicens indstillinger, konfigureres med Miralix Wrench under fanen ”Proxy” i sub-fanen ”Chat”, se evt. brugervejledningen for Miralix Wrench. 

 

GDPR- Persondataforordningen 

General Data Protection Regulation (GDPR), eller persondataforordningen som det typisk kaldes i Danmark, gør at kunder der får installeret Miralix software, skal tage stilling til omfanget og varighed af datalagring. Alle Miralix kunder tilbydes en databehandler aftale, idet Miralix som udgangspunkt ikke har forpligtelser vedrørende denne datalagring. 

 

Forudsætninger for BOT framework/Miralix Chat service 

For at BOT framework/Miralix Chat service kan fungere er der nogle forudsætninger som skal være på plads. 

 

Licenser

For at kunne brugre Webchat på Miralix licens version 1, er der krævet følgende licenser:

Licens nummer

Licens type

1955

Miralix Agent Omni Add-on

4101

Miralix Omni Channel (Web Chat) 

For at kunne brugre Webchat på Miralix licens version 2, er der krævet følgende licenser:

Licens nummer

Licens type

1933

Miralix CX Cloud Digital Web Chat - Add-on

.Net

.NET 8.0 Runtime 64bit + ASP.NET Core Runtime 64bit installeret på Miralix server med Miralix Chat service.

 

MS SQL server 

Der skal være en Microsoft SQL Server eller Microsoft SQL Server Express installeret. Se dokumentet Miralix system krav for yderligere info. 

  • MiralixGreenbox database skal være installeret/ importeret.

 

Miralix Server komponenter 

På server delen skal følgende som minimum være installeret. 

  • Miralix Proxy Service. Se vejledningen Installation Miralix Proxy Service.

  • Miralix Chat service være installeret. Se vejledningen installation Miralix Chat service.

 

Microsoft Azure Bot Ressourcer

Der skal benyttes en Azure brugerkonti som har adgang til at oprette en Azure Bot, app Service, App Service Plan, Ressource Group, App Registration, og tilføje dem til en Azure Subscription. 

 

Dette er nødvendigt for at Azure Bot’en kan modtage og sende beskeder til og fra Miralix Chat service og webchat hjemmesiden. 

 

HTML template, JavaScript og bot konfigurations filerlorer


Miralix har udarbejdet en html Webchat Template fil, og JavaScript fil som gør det nemt at implementere en række funktionaliteter i webchatten, ved hjælp af metodekald.

Derudover vil der også være Azure bot konfigurationsfiler “Miralix.WebChatBot.X.X.X.zip” som skal uploades til Azure botten.

OBS! Ved opdatering af Miralix Chat Service, så skal JavaScript og .zip fil også opdateres.


Webchat template er bygget i HTML-format til hovedsagelig test af Webchat opsætning. Den kan med fordele benyttes, til forståelse og test af Webchat funktionaliteter. 

Disse filer, vil som standard blive lagt i installationsfolderen for Miralix chat servicen.

eks: “C:\Program Files\Miralix\Miralix Chat Service”

OBS! Der gøres opmærksom på at denne Webchat template er udarbejdet til test og at Miralix fraskriver sig et hvert ansvar, hvis denne benyttes i drift.

  

Oprettelse af Azure Bot ressourcer i Microsoft Azure

For at kunne oprette de nødvendige Azure ressourcer gøres der brug af Azure CLI. Se evt. guiden Create an Azure Bot resource via Azure CLI:

https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-deploy-az-cli?view=azure-bot-service-4.0&tabs=userassigned%2Cnewgroup%2Ccsharp

Oprettelse af Azure Bot ressourcer Azure via Azure CLI

 

  1. Hent og installer Azure CLI:
    https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-windows?tabs=azure-cli

  2. Log ind I Azure via Azure CLI igennem PowerShell, med kommandoen ”

az login” I PowerShell vinduet.

Der åbnes nu et browservindue hvori der skal logges ind med brugerkontoen til oprettelse af Azure ressourcerne.

Efter succesfuldt login, vil der udskrives informationer om brugerkontoens tilknyttede subscriptions.
Se figur 1.

image-20230522-113622.png


Figur 1

3. Hvis brugerkontoen har adgang til flere subscription, (kan ses hvis der er flere værdier indenfor ”

{}”) så skal subscription id’et defineres med nedenstående kommando, ellers gå videre til næste step.
az account set --subscription "<Subscription ID>"

Eksempel:
az account set --subscription  "56x63x1x-04x9-43x9-x71x-34xx6x417462"

4. Opret en “App Registration” til botten:

az ad app create --display-name "<Bot_App_Registration_Name>" --sign-in-audience "AzureADandPersonalMicrosoftAccount"

Eksempel: 

az ad app create --display-name "MiralixWebChatBotAppRegistration" --sign-in-audience "AzureADandPersonalMicrosoftAccount"

Når oprettelsen er gennemført, vil der i PowerShell blive vist info omkring den nyligt oprettede ”App Registration”. Se figur 2.

image-20230522-114052.png

Figur 2

Gem værdien fra ”appId”:

5. Opret ”App Secret” (Secret/Password) til ”App Registration”, som skal bruges af Azure bot ressourcerne senere. Se figur 3.

az ad app credential reset --id <AppRegistrationId>


Eksempel:

az ad app credential reset --id 0a5x4xx7-299x-3x6x-x760-xx3x660x00xx


Figur 3

Gem Secret/Password for “App registration”.


6. Opret Azure Ressourcerne Azure Bot, App Service, App Service Plan, og en ressource gruppe.

For mere info se: https://learn.microsoft.com/en-us/cli/azure/deployment/sub?view=azure-cli-latest#az-deployment-sub-create-examples

OBS!
Følgende kommando er en linje uden linjeskifts!


Opret Azure App Service, Azure Service Plan og Azure Ressource group

PowerShell
az deployment sub create --location westeurope --template-uri "https://raw.githubusercontent.com/microsoft/botbuilder-dotnet/main/generators/dotnet-templates/Microsoft.BotFramework.CSharp.EchoBot/content/DeploymentTemplates/DeployWithNewResourceGroup/template-BotApp-new-rg.json" --parameters '{\"groupName\": {\"value\": \"<GroupName>\"}, \"groupLocation\": {\"value\": \"westeurope\"}, \"appServiceName\": {\"value\": \"<AppServiceName>\"}, \"appServicePlanName\": {\"value\": \"<AzureServiceAppPlanName>\"}, \"appServicePlanLocation\": {\"value\": \"westeurope\"}, \"appServicePlanSku\": {\"value\": {\"name\": \"S1\", \"tier\": \"Standard\", \"size\": \"S1\", \"family\": \"S\",\"capacity\": 1}},\"appType\": {\"value\": \"MultiTenant\"},\"appId\": {\"value\": \"<AppID>\"},\"appSecret\": {\"value\": \"<AppSecret>\"},\"UMSIName\": {\"value\": \"\"},\"UMSIResourceGroupName\": {\"value\": \"\"},\"tenantId\": {\"value\": \"\"} }'


Uddybning af parametrene:
--location
Server lokationerne på de forskellige ressourcer.
Her anbefaler vi som udgangspunkt at ligge i dem i den samme region. I eksemplet bruges der ”westeurope” som region, da den indeholder de nødvendige services og har gode svartider fra Danmark.


--parameteres

Indeholder parametre der skal bruges til oprettelse af App Servicen.

OBS!

indholdet af dette skal være escaped til JSON String. https://learn.microsoft.com/en-us/cli/azure/deployment/sub?view=azure-cli-latest#az-deployment-sub-create-examples


groupName:
Navnet på den nye ”Resource Groupe”, som oprettes i Azure.

groupLocation

Server lokationerne på de forskellige ressourcer.
Her anbefaler vi som udgangspunkt at ligge i dem i den samme region. I eksemplet bruges der ”westeurope” som region, da den indeholder de nødvendige services og har gode svartider fra Danmark.

appServiceName

Navnet på selve den ”Deployment” som oprettes i Azure.

appServicePlanName:
Navnet på den ”App Service Plan”, som oprettes i Azure.

For at bruge en allerede eksisterende ”App Service Plan” se:
https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-deploy-az-cli?view=azure-bot-service-4.0&tabs=multitenant%2Cnewgroup%2Ccsharp

appServicePlanLocation

Server lokationerne på de forskellige ressourcer.
Her anbefaler vi som udgangspunkt at ligge i dem i den samme region. I eksemplet bruges der ”westeurope” som region, da den indeholder de nødvendige services og har gode svartider fra Danm

appServicePlanSku

Prisindstilling for Azure webservicen. Skriv ”S1” for standard.
Dette anbefales så der ikke opstår begrænsninger på grund af antal beskeder til og fra botten/servicen.

Alternativt kan man bruge den gratis model, ”F0”.

For at se begrænsningerne for den gratis model, se:
https://azure.microsoft.com/en-us/pricing/details/bot-services/#pricing  

appId:
App Id’et fra App registreringen.

appSecret:
App Secret/Password til App registreringen.


For yderligere info se: https://learn.microsoft.com/en-us/cli/azure/deployment/sub?view=azure-cli-latest#az-deployment-sub-create-examples


Eksempel:

az deployment sub create --location westeurope --template-uri "https://raw.githubusercontent.com/microsoft/botbuilder-dotnet/main/generators/dotnet-templates/Microsoft.BotFramework.CSharp.EchoBot/content/DeploymentTemplates/DeployWithNewResourceGroup/template-BotApp-new-rg.json" --parameters '{\"groupName\": {\"value\": \"MiralixWebChatBotAzureResourceGroupeName\"}, \"groupLocation\": {\"value\": \"westeurope\"}, \"appServiceName\": {\"value\": \"MiralixWebChatBotAppServiceName\"}, \"appServicePlanName\": {\"value\": \"MiralixWebChatBotAppServicePlanName\"}, \"appServicePlanLocation\": {\"value\": \"westeurope\"}, \"appServicePlanSku\": {\"value\": {\"name\": \"S1\", \"tier\": \"Standard\", \"size\": \"S1\", \"family\": \"S\",\"capacity\": 1}},\"appType\": {\"value\": \"MultiTenant\"},\"appId\": {\"value\": \"0a5x4xx7-299x-3x6x-x760-xx3x660x00xx\"},\"appSecret\": {\"value\": \"XXXXX~XXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"},\"UMSIName\": {\"value\": \"\"},\"UMSIResourceGroupName\": {\"value\": \"\"},\"tenantId\": {\"value\": \"\"} }'

Herefter vil der i resultatet af kommandoen kunne ses om oprettelsen af Azure ressourcerne er succesfuldt. Se figur 4.

image-20230522-123300.png

Figur 4


Opret Azure App Bot 

az deployment sub create --location westeurope --template-uri "https://raw.githubusercontent.com/microsoft/botbuilder-dotnet/main/generators/dotnet-templates/Microsoft.BotFramework.CSharp.EchoBot/content/DeploymentTemplates/DeployWithNewResourceGroup/template-AzureBot-new-rg.json" --parameters '{\"groupName\": {\"value\": \"<GroupName>\"},\"groupLocation\": {\"value\": \"westeurope\"},\"azureBotId\": {\"value\": \"<AzureBotId>\"},\"azureBotSku\": {\"value\": \"S1\"},\"azureBotRegion\": {\"value\": \"global\"},\"botEndpoint\": {\"value\": \"https://<AppServiceNavn>.azurewebsites.net/api/messages\"},\"appType\": {\"value\": \"MultiTenant\"},\"appId\": {\"value\": \"<AppRegistrationID>\"},\"UMSIName\": {\"value\": \"\"},\"UMSIResourceGroupName\": {\"value\": \"\"},\"tenantId\": {\"value\": \"\"} }'


Uddybning af parametrene:

--location
Server lokationerne på de forskellige ressourcer.
Her anbefaler vi som udgangspunkt at ligge i dem i den samme region. I eksemplet bruges der ”westeurope” som region, da den indeholder de nødvendige services og har gode svartider fra Danmark.


--parameteres

Indeholder parametre der skal bruges til oprettelse af Azure Botten.

OBS!

indholdet af dette skal være escaped til JSON String. https://learn.microsoft.com/en-us/cli/azure/deployment/sub?view=azure-cli-latest#az-deployment-sub-create-examples


groupName:
Navnet på den nye ”Resource Groupe”, som oprettes i Azure.

groupLocation

Server lokationerne på de forskellige ressourcer.
Her anbefaler vi som udgangspunkt at ligge i dem i den samme region. I eksemplet bruges der ”westeurope” som region, da den indeholder de nødvendige services og har gode svartider fra Danmark.

azureBotId

Navnet på Azure Botten

azureBotSku:
Prisindstilling for Azure Botten. Skriv ”S1” for standard.
Dette anbefales så der ikke opstår begrænsninger på grund af antal beskeder til og fra botten/servicen.

Alternativt kan man bruge den gratis model, ”F0”.

For at se begrænsningerne for den gratis model, se:
https://azure.microsoft.com/en-us/pricing/details/bot-services/#pricing  

botEndpoint

URL til botten: eks “https://<AppServiceNavn>.azurewebsites.net/api/messages”

appId:
App Id’et fra App registreringen.


For yderligere info se: https://learn.microsoft.com/en-us/cli/azure/deployment/sub?view=azure-cli-latest#az-deployment-sub-create-examples


Eksempel:

az deployment sub create --location westeurope --template-uri "https://raw.githubusercontent.com/microsoft/botbuilder-dotnet/main/generators/dotnet-templates/Microsoft.BotFramework.CSharp.EchoBot/content/DeploymentTemplates/DeployWithNewResourceGroup/template-AzureBot-new-rg.json" --parameters '{\"groupName\": {\"value\": \"MiralixWebChatBotAzureResourceGroupeName\"},\"groupLocation\": {\"value\": \"westeurope\"},\"azureBotId\": {\"value\": \"MiralixWebChatBotName\"},\"azureBotSku\": {\"value\": \"S1\"},\"azureBotRegion\": {\"value\": \"global\"},\"botEndpoint\": {\"value\": \"https://MiralixWebChatBotName.azurewebsites.net/api/messages\"},\"appType\": {\"value\": \"MultiTenant\"},\"appId\": {\"value\": \"0a5x4xx7-299x-3x6x-x760-xx3x660x00xx\"},\"UMSIName\": {\"value\": \"\"},\"UMSIResourceGroupName\": {\"value\": \"\"},\"tenantId\": {\"value\": \"\"} }'



Efterfølgende Konfiguration af Azure Bot ressourcer via Azure Portal

  1. Log ind på Azure Portal (https://portal.azure.com) med en administrator konto som vist i figur 5. 

image-20230106-131202.png

Figur 5

 2. Søg eller naviger til de nyligt oprettede ressourcer. Se figur 6.  

image-20230106-131303.png

Figur 6

3. Tilgå ”App Service” ressourcen, scrol ned i venstre sidebar og klik på ”Advanced Tools” knappen og derefter klik på ”Go ->”. Se figur 7.

image-20230106-131347.png

Figur 7

 4. Herefter åbner siden Kudu. Kudu er motoren bag en række funktioner i Azure app services, der er relateret til kildekontrolbaseret implementering, og andre implementeringsmetoder for synkronisering.

Gå op under ”Tools” og vælg ”Zip push deploy”, og slet alle elementerne i tabellen på siden. Så siden ser ud som i figur 8. 

image-20230106-131414.png

Figur 8

 Når tabellen er tom, indsættes/uploades Zip filen ”Miralix.WebChatBot{versions nr}.zip” ind på siden. (Zip filen kan findes på Miralix serveren, når der er installeretet Miralix chat service. Der kan bruges funktionen ”Drag and drop” på Kudo hjemmesiden)

Vent på at alt er overført, og der står "Deployment succesful" som det sidste. Se figur 9.

image-20230106-131449.png

Figur 9

 

5. Luk siden, og gå tilbage til ”App Service” i Azure portalen, og under ”Overview” (øverste i venstre side), klik på ”Restart” knappen i den øverste menu bar.


 Opret forbindelse fra Miralix til Azure Bot

Når Azure Bot er oprettet, kan der skabes forbindelse til Azure Bot igennem flere kanaler(Channels), og til dette skal der bruges en ”Channel Site” ”Secret Key”.


OBS! Det er vigtigt at der bruges secret keys fra et "Site” og ikke secret keys fra en ”Channel”, ellers vil webchat ikke virke.

 

  1. Navigere til ”Channels” under sidemenuen i Azure, under den pågældende Azure Bot ressource. Herefter ses der alle de aktive kanaler for Azure Bot’en. Hvis det er første gang Azure benyttes er der kun aktiveret en ”webchat Channel”. Lav en ”Direct Line” kanal ved at klikke på ”Direct Line” under ”Available Channels”. Se figur 10. 

image-20230106-132002.png

   Figur 10


 2. Klik på ”Default_Site”. Se figur 11.

image-20230106-132046.png

Figur 11

3. Klik ”Show” ud fra en af felterne og ”Secret key” vil blive vist.

Gem disse ”Secret Keys” til konfiguration senere i Miralix Wrench. Se figur 12.

image-20230106-132126.png

 Figur 12


4. Denne ”Secret Key” er hvad der skal benyttes for at skabe forbindelse til Azure Bot’en fra Miralix og forbinde Miralix til andre brugere der benytter sig af samme Azure Bot. I Wrench konfigureres løsningen til at bruge denne ”Secret Key” samt Bot ID'et (botID) fra Azure Bot ressourcen, for at aktivere webchat. Gem indstillingerne ved at klikke på ”Save Settings”.

For at forbindelsen oprettes, skal WebChat servicen genstartes. Klik på ”Restart WebChat service”. Se figur 13.  

image-20230106-132213.png

 Figur 13

Test forbindelse til Azure Bot

 På samme måde som I skaber forbindelse mellem Miralix Desktop og Azure Bot, skal der også benyttes en ”Secret key” til at skabe forbindelse mellem Azure Bot og hjemmesidens webchat.

 For at skabe forbindelsen mellem Azure Bot og Webchat henvises til guiden Connect a bot to Web Chat » https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-connect-webchat?view=azure-bot-service-4.0 .

Det er muligt at integrere Webchatten på hjemmesiden ved hjælp af JavaScript eller React. 

Integrer JavaScript filen med Azure Web Chat channel

  1. Gå ind under ”Web Chat” kanalen i ”Channels” på Azure botten via Azure portalen. Se figur 14. Kopier en af de to ”Secret keys” fra ”Web Chat Site” ligesom vist på figur 15. Denne skal indsættes i JavaScript filen. 

image-20230106-132324.png

Figur 14

image-20230106-132434.png

Figur 15

  1. For at starte en chat, skal Azure Bot frameworket bruge en webchat ”Secret Key”. Denne ”Secret key” rådes til at holdes gemt, så andre ikke kan opsnappe den, og bruge den til at skabe forbindelse til samme chat forbindelse. I JavaScript-filen fra Miralix, skal webchat Secret key indtastes direkte i JavaScript koden, på linjen markeret i Figur 16. Herefter bliver der generet en token til at starte en samtale igennem Microsoft Bot framework DirectLine API. 

image-20230106-132503.png

Figur 16

 Obs! Det rådes at implementere ovenstående i ens egen backend, som ved eksempelvis et API-kald i stedet kan hente en gyldig token ud, og dermed holde ens ”Secret Key” væk fra browseren.

 

3. For at starte webchatten, skal ”renderWebChat” metoden kaldes. For at stoppe forbindelsen til Azure Bot/samtalen skal metoden ”disconnectWebChat” kaldes, hvorefter samtalen afsluttes.

 

4. For at route til forskellige køer, kaldes metoden ”setWebChatRoutingString” med en ”string” som parameter i WebChattemplaten, som vist i figur 17. Denne ”string” bliver sendt med når der bliver oprettet en ny samtale, og skal derfor sættes før kaldet til ”renderWebChat" metoden i JavaScript filen. Derefter kan Miralix Chat service ”lytte” efter denne ”string” i en rutningsliste i Miralix Supervisor Add-on, og placere chatten i den ønskede webchat kø.

image-20230106-132546.png

Figur 17

Mulighed for at udfylde bruger informationer inden chat-start, og sende med beskeder, til visning i Miralix Desktop.

  1. I WebChat-templaten benyttes der en form ved navn ”webChatForm”. Når denne form bliver ”submittet” bliver værdierne fra formen, indsat i en ”keypairvalue-array” i Java”cript i ”handleSubmit” metoden. Denne vil blive modtaget i Miralix Desktop, når der bliver oprettet en Webchat forespørgsel. Dette sker i ”renderWebChat” metoden, som bliver kaldt til sidst. Key vil være ”name” parametret i input taggene, som ses i figur 18, og ”value” vil være selve inputtet som brugeren indtaster i det pågældende input. 

image-20230106-132612.png

Figur 18

 2. I WebChattemplaten bliver data’en indtastet nu sendt videre mod Miralix, som metadata. Eksemplet herpå kan ses i figur 19.

image-20230106-132655.png

Figur 19

 3. Følgende skal oprettes inden man kan oprette en indtastningsmenu, rækkefølgen er (kun første gang):

Aktivere webchat i Miralix Wrench. se wrench vejledning herom.

Tilføj en web chat kø

Tilføj en Web chat identifikation

Tilføj web chat tekster

Tilføj en web chat menu

Tilføj en web chat indtastningsmenu

Tilføj evt. en webchat tidsplan


For at ovenstående virker, skal der i Miralix Supervisor, under indtastningsmenu’en som er tilknyttet Webchat flow’et. I ”Webchat header” tilføjes en eller flere parameter. For at få fat på de værdier der er sendt med metadata’en fra webchatten, vælges ”Web chat metadata parameter” i dropdown menuen og herefter klikkes på Indsæt knappen. Se figur 20. 

image-20230106-132729.png

Figur 20

 4. Herefter vil der blive tilføjet et parameter i tekst-feltet ”Custom header”, hvor der i parentesen kan skrives navnet på den ”metadata” parameter, der skal vises værdien af i ”headeren”. Som i vist i figur 21 hvor det er fornavn, efternavn, e-mail, og telefonnummer der skal vises. Værdien skal stemme overens med værdien i WebChat-templaten/Hjemmesiden. 

image-20230106-132800.png

Figur 21

 5. Det er muligt at tilføje tekst foran ”Web chat metadata parameter”. Denne tekst bliver vist i ”headeren” som opstillet i tekstfeltet, hvor det derimod selvfølgelig kun er værdien af alle metadata ”properties”, der bliver vist i ”headeren”, som vist på figur 22.

image-20230106-132839.png

Figur 22

Webchat med React:       

Der er i første version ikke lavet noget eksempel af en React fil til implementering af webchatten, fra Miralix. Der kan med fordel hentes inspiration fra Javascript fil, og det nedenstående link, for at integrere webchatten med React.

Se Eksempler på integration vha. React » https://github.com/microsoft/BotFramework-WebChat    

Styling af webchatten

Det er muligt at style webchatten afhængigt af hvordan Webchatten opsættes på jeres hjemmeside.

Overordnet set giver React flere muligheder for styling, fremfor CDN (Content Delivery Networks), men mulighederne er generelt mange. I figur 23 ses hvad de to forskellige muligheder understøtter.

image-20230106-132916.png

Figur 23

I den tilhørende Javascript fil fra Miralix, vil alt styling i selve webchatten, findes i 'styleOptions'-objektet.