michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
89dabf9d72
netgescon-day0/docs/CTI-WINDOWS-TAPI-PROBE.md

18 KiB
Raw Blame History

CTI Windows TAPI - Guida Semplice

Questa guida serve a fare il primo passo sulla macchina Windows dove hai installato il driver Panasonic TAPI/TSP.

L'obiettivo non e ancora fare il bridge completo.

L'obiettivo adesso e capire tre cose, con calma:

  1. il driver TAPI e davvero visibile a Windows
  2. quali linee o indirizzi espone
  3. la macchina Windows riesce a parlare con NetGescon con il token corretto

File da usare

  • scripts/ops/windows/get-netgescon-panasonic-tapi-info.ps1
  • scripts/ops/windows/test-netgescon-panasonic-api.ps1

Passo 1: apri PowerShell come amministratore

Sulla macchina Windows:

  1. apri il menu Start
  2. cerca PowerShell
  3. fai click destro
  4. scegli Esegui come amministratore

Passo 2: spostati nella cartella dove hai copiato il repo

Esempio:

cd C:\netgescon\netgescon-day0

Passo 3: permetti l'esecuzione dello script nella sessione corrente

Set-ExecutionPolicy -Scope Process Bypass

Questo non cambia in modo permanente la politica della macchina. Vale solo per quella finestra.

Passo 4: estrai le informazioni dal driver TAPI

Prima prova senza filtro:

.\scripts\ops\windows\get-netgescon-panasonic-tapi-info.ps1 -IncludeMembers

Se il risultato e troppo lungo, prova filtrando gli interni che ci interessano:

.\scripts\ops\windows\get-netgescon-panasonic-tapi-info.ps1 -Filter 205
.\scripts\ops\windows\get-netgescon-panasonic-tapi-info.ps1 -Filter 206
.\scripts\ops\windows\get-netgescon-panasonic-tapi-info.ps1 -Filter 201

Lo script crea un file JSON, di default:

netgescon-tapi-info.json

Cosa mi devi mandare dopo questo passo

Mandami una di queste cose:

  1. le righe del riepilogo rapido finali
  2. il contenuto del file JSON
  3. uno screenshot del riepilogo se ti viene piu comodo

Passo 5: verifica che Windows riesca a parlare con NetGescon

Sostituisci:

  • https://staging.netgescon.it con il tuo URL reale, se diverso
  • IL_TUO_TOKEN con il token CTI reale

E lancia:

.\scripts\ops\windows\test-netgescon-panasonic-api.ps1 -BaseUrl "https://staging.netgescon.it" -Token "IL_TUO_TOKEN" -Extension "205"

Cosa deve succedere nel watcher

Devi vedere tre blocchi:

  1. Lookup rubrica
  2. Simulazione incoming
  3. Simulazione call-ended

Se dentro i JSON compare ok: true, allora:

  • il token e giusto
  • la macchina Windows raggiunge NetGescon
  • gli endpoint sono pronti

Se qualcosa fallisce

Caso A: errore creando TAPI.TAPI

Significa che il provider COM TAPI non e registrato bene o il driver Panasonic non e installato correttamente.

Caso B: trovi TAPI ma zero indirizzi

Significa che il driver c'e, ma non sta esponendo ancora linee utilizzabili.

In quel caso di solito bisogna controllare:

  1. configurazione del TSP Panasonic
  2. Check Location
  3. IP PBX e porta 33333
  4. licenza CTI lato centralino

Caso C: gli script API falliscono con 401 Unauthorized

Significa che il token non coincide con quello configurato in NetGescon.

Importante: il watcher Windows non e bloccato. Continua a ricevere eventi TAPI, ma gli invii incoming e call-ended verso staging vengono rifiutati, quindi su NetGescon non compare nulla.

Caso D: gli script API falliscono con timeout o errore TLS

Significa che la macchina Windows non riesce a raggiungere NetGescon su HTTPS.

Cosa faremo subito dopo

Quando mi mandi l'output del primo script, io ti guidero al passo successivo:

  1. capire quali linee TAPI sono quelle giuste
  2. decidere se monitorare 201, 205, 206
  3. scrivere il probe successivo che ascolta davvero gli eventi chiamata

Il primo obiettivo adesso non e fare tutto.

Il primo obiettivo e vedere nero su bianco che il driver Panasonic espone qualcosa che possiamo usare.

Risultato atteso corretto

Se nel JSON o nel riepilogo trovi linee simili a queste, significa che il provider Panasonic sta esponendo davvero gli interni giusti:

  • EXT00201
  • EXT00205
  • EXT00206
  • GRP00601
  • GRP00603

Se li vedi, il passo successivo e ascoltare gli eventi di chiamata reali.

Passo 6: watcher TAPI via polling

Lo script VBScript di event sink puo fallire con questo errore:

WScript.CreateObject: Impossibile connettere l'oggetto.

Questo non significa che Panasonic TAPI non funziona.

Significa solo che quell'oggetto COM non si lascia agganciare bene da VBScript come sorgente eventi.

Per questo motivo il passo consigliato diventa il polling PowerShell, che e piu robusto.

Usa questi script Windows:

  • scripts/ops/windows/inspect-netgescon-panasonic-address.ps1
  • scripts/ops/windows/poll-netgescon-panasonic-active-calls.ps1

6.1 Ispezione veloce dell'interno 205

.\scripts\ops\windows\inspect-netgescon-panasonic-address.ps1 -Extension 205 -OutFile .\inspect-205.json

Se vuoi fare anche 201 e 206:

.\scripts\ops\windows\inspect-netgescon-panasonic-address.ps1 -Extension 201 -OutFile .\inspect-201.json
.\scripts\ops\windows\inspect-netgescon-panasonic-address.ps1 -Extension 206 -OutFile .\inspect-206.json

6.2 Polling chiamate attive

Lancialo cosi da PowerShell:

.\scripts\ops\windows\poll-netgescon-panasonic-active-calls.ps1 -Extensions "201,205,206" -LogFile .\netgescon-tapi-poll.log

Se vuoi includere anche i gruppi studio:

.\scripts\ops\windows\poll-netgescon-panasonic-active-calls.ps1 -Extensions "201,205,206,601,603" -LogFile .\netgescon-tapi-poll.log

Cosa deve succedere nel polling

All'avvio lo script deve stampare righe tipo:

ADDRESS READY name=EXT00205 dial=205 provider=CTSP0000.tsp

Poi resta in ascolto e interroga periodicamente il provider.

Adesso fai una chiamata reale verso uno degli interni monitorati.

Se tutto va bene compariranno righe tipo:

CALL address=EXT00205 dial=205 idx=1 state=... caller=... called=... connected=...

e lo stesso contenuto verra scritto nel file:

.\netgescon-tapi-poll.log

Cosa mi devi mandare dopo il polling

Mi serve una di queste due cose:

  1. l'output console del polling
  2. il contenuto del file netgescon-tapi-poll.log

Nota importante sui valori State=0 e TerminalCount=0

Nel dump iniziale non e un problema grave.

Quel dump fotografava solo l'elenco indirizzi esposto dal provider.

Il test decisivo adesso non e il numero di terminali, ma se il polling vede comparire una chiamata attiva durante una chiamata vera.

Passo 7: ascolto eventi COM reali

Se il polling resta fermo su IDLE anche dopo le chiamate, ma RegisterCallNotifications e tutto verde, allora il passo corretto e ascoltare gli eventi COM veri del provider.

Usa questo script:

  • scripts/ops/windows/watch-netgescon-panasonic-tapi-com-events.ps1

Lancialo cosi:

.\scripts\ops\windows\watch-netgescon-panasonic-tapi-com-events.ps1 -Extensions "201,205,206" -LogFile .\netgescon-tapi-com-events.log

Cosa deve succedere nell'ispezione interop

All'avvio vedrai le righe di setup e REGISTER OK.

Poi, quando fai una chiamata reale verso 201, 205 o 206, devono comparire righe tipo:

COM EVENT type=...

Se compaiono, abbiamo finalmente il canale giusto da usare per il bridge verso NetGescon.

Passo 8: ispezione interop .NET di TAPI 3

L'output che hai raccolto conferma che l'interop espone davvero i due canali evento utili:

  • ITTAPIEventNotification
  • ITTAPIDispatchEventNotification

In pratica non dobbiamo piu indovinare il nome dell'evento COM. Dobbiamo agganciarci ai wrapper .NET generati dall'interop.

Passo 9: watcher .NET basato sui wrapper evento interop

Usa questo script:

  • scripts/ops/windows/watch-netgescon-panasonic-tapi-dotnet-events.ps1

Lancialo cosi:

.\scripts\ops\windows\watch-netgescon-panasonic-tapi-dotnet-events.ps1 -Extensions "201-208,601,603,0001,0003" -LogFile .\netgescon-tapi-dotnet-events.log

Il watcher ora accetta anche range di interni, quindi 201-208 equivale a 201,202,203,204,205,206,207,208.

Se vuoi una prova limitata di 90 secondi:

.\scripts\ops\windows\watch-netgescon-panasonic-tapi-dotnet-events.ps1 -Extensions "201-208,601,603,0001,0003" -LogFile .\netgescon-tapi-dotnet-events.log -Seconds 90

Prova bridge dry-run

Quando il watcher eventi e stabile, puoi chiedergli di costruire anche i payload candidati per gli endpoint Laravel senza ancora inviarli.

Comando:

.\scripts\ops\windows\watch-netgescon-panasonic-tapi-dotnet-events.ps1 -Extensions "201-208,601,603,0001,0003" -LogFile .\netgescon-tapi-dotnet-events.log -Seconds 90 -BridgeMode dry-run

In questa modalita vedrai righe aggiuntive tipo:

BRIDGE DRYRUN endpoint=incoming payload=...
BRIDGE MARK answered event_id=...
BRIDGE DRYRUN endpoint=call-ended payload=...

Se il provider non espone ancora il numero esterno della chiamata, vedrai invece:

BRIDGE SKIP endpoint=incoming reason=phone-missing ...

Questo non e un errore del watcher. Significa solo che per quella chiamata Panasonic non ha ancora reso disponibile il numero nel punto del flusso che stiamo leggendo.

Attenzione: -BridgeMode dry-run non invia nulla a NetGescon. Se su staging i Post-it restano fermi, la prima cosa da controllare e che il watcher Windows non sia partito in dry-run ma in live.

Cosa deve succedere nel watcher .NET

All'avvio vedrai prima:

  • REGISTER OK sugli interni monitorati
  • DOTNET CHECK per i wrapper provati
  • DOTNET SUBSCRIBE OK oppure DOTNET SUBSCRIBE KO

Se almeno uno dei wrapper va in DOTNET SUBSCRIBE OK, fai subito una chiamata reale su 201, 205 o 206.

Quando l'aggancio funziona, nel log devono comparire righe tipo:

DOTNET EVENT source=... eventType=... payloadType=... state=... cause=... address=... dial=...

Cosa mi devi mandare dal watcher .NET

Mandami il contenuto completo di:

  • console PowerShell
  • oppure file netgescon-tapi-dotnet-events.log

Con quel log possiamo decidere subito una delle due strade:

  1. il watcher PowerShell/.NET basta e lo estendiamo per chiamare gli endpoint NetGescon
  2. i wrapper non si agganciano e allora scriviamo il sink COM compilato con la firma esatta appena confermata

Se il dry-run produce payload corretti, il passo successivo e passare a:

-BridgeMode live -BaseUrl "https://staging.netgescon.it" -Token "IL_TUO_TOKEN"

Passo 10: tenere il bridge sempre acceso su Windows

Per evitare che tutto dipenda da una finestra PowerShell aperta, usa questi script:

  • scripts/ops/windows/start-netgescon-panasonic-live.ps1
  • scripts/ops/windows/install-netgescon-panasonic-live-task.ps1

10.1 Avvio live manuale

Prima imposta il token come variabile ambiente persistente Windows.

In PowerShell amministratore:

Set-ExecutionPolicy -Scope Process Bypass -Force
[Environment]::SetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "IL_TUO_TOKEN_REALE", "Machine")

Poi avvia il bridge live:

cd C:\netgescon\netgescon-day0
.\scripts\ops\windows\start-netgescon-panasonic-live.ps1 -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "C:\ProgramData\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log"

10.2 Installazione come task automatico all'avvio macchina con account SYSTEM

In PowerShell amministratore:

Set-ExecutionPolicy -Scope Process Bypass -Force
[Environment]::SetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "IL_TUO_TOKEN_REALE", "Machine")
cd C:\netgescon\netgescon-day0
.\scripts\ops\windows\install-netgescon-panasonic-live-task.ps1 -Mode system-startup -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "C:\ProgramData\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log"

Nota importante: quando il task gira come SYSTEM, i drive mappati come S: in genere non esistono. Usa quindi percorsi locali tipo C:\ProgramData\... oppure percorsi UNC.

10.3 Installazione come task al logon utente corrente

Se non hai privilegi amministrativi, usa la modalita legata all'utente corrente.

Set-ExecutionPolicy -Scope Process Bypass -Force
[Environment]::SetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "IL_TUO_TOKEN_REALE", "User")
cd C:\netgescon\netgescon-day0
.\scripts\ops\windows\install-netgescon-panasonic-live-task.ps1 -Mode current-user-logon -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -InteropOutputDir "$env:LOCALAPPDATA\NetGescon\tapi-interop"

10.4 Sequenza rapida in 6 comandi per il tuo caso S:\

Se il repo e davvero montato in S:\ e non hai privilegi amministrativi, usa questi 6 comandi esatti nell'ordine indicato.

Set-ExecutionPolicy -Scope Process Bypass -Force
cd S:\
[Environment]::SetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "IL_TUO_TOKEN_REALE", "User")
.\scripts\ops\windows\install-netgescon-panasonic-live-task.ps1 -Mode current-user-logon -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -InteropOutputDir "$env:LOCALAPPDATA\NetGescon\tapi-interop"
Start-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"
Get-ScheduledTaskInfo -TaskName "NetGescon Panasonic Live Bridge"

Se il quarto comando fallisce, non lanciare il quinto: significa che il task non e stato creato.

Il file di log non esiste finche il task non parte davvero almeno una volta. Dopo che il sesto comando mostra che il task esiste, puoi seguire il log con:

Get-Content "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -Tail 100 -Wait

Passo 11: messa in esercizio su staging

Quando il watcher e avviato e i log mostrano DOTNET SUBSCRIBE OK, la checklist minima per entrare davvero in live e questa.

11.1 Verifica token prima di fare chiamate reali

Sul PC Windows che gira il bridge:

[Environment]::GetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "User")

Se leggi il placeholder o una stringa vecchia, riscrivilo con quello reale e poi reinstalla/rilancia il task.

11.2 Smoke test HTTP verso staging

.\scripts\ops\windows\test-netgescon-panasonic-api.ps1 -BaseUrl "https://staging.netgescon.it" -Token "IL_TUO_TOKEN_REALE" -Extension "205"

Se questo test non restituisce ok: true, non fare ancora chiamate reali: il problema e a livello token o connettivita HTTP.

11.3 Come leggere il log del bridge live

Nel log live, questi casi significano cose diverse:

  • BRIDGE LIVE OK endpoint=incoming: la chiamata e stata accettata da staging
  • BRIDGE LIVE OK endpoint=call-ended: la chiusura chiamata e stata accettata da staging
  • BRIDGE LIVE KO endpoint=incoming error=(401) Non autorizzato: token errato sul bridge Windows oppure token diverso su staging
  • BRIDGE IGNORE endpoint=... category=EXT mode=group-first: evento visto ma non scelto come sorgente autorevole per il bridge

11.4 Dove vedere le nuove chiamate su staging

Quando l'invio live va a buon fine, le nuove chiamate Panasonic compaiono in due punti applicativi:

  1. Strumenti -> Post-it Gestione
  • legge i record chiamate_post_it
  • e il punto principale per vedere le chiamate create dal bridge
  1. flussi tecnici basati su communication_messages
  • canale panasonic_csta
  • utili per verifica tecnica e correlazione con routing/intercettazione operatore

In aggiunta, il banner operatore mobile usa anche panasonic_csta, quindi una chiamata instradata a un interno monitorato puo comparire anche lato operatore senza passare solo da SMDR.

11.5 Procedura rapida di ripartenza se staging smette di ricevere chiamate

Sul PC Windows:

cd S:\
Stop-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge" -ErrorAction SilentlyContinue
.\scripts\ops\windows\install-netgescon-panasonic-live-task.ps1 -Mode current-user-logon -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -InteropOutputDir "$env:LOCALAPPDATA\NetGescon\tapi-interop"
Start-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"
Get-Content "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -Tail 100 -Wait

Se dopo una chiamata reale appare 401, fermati subito: il bridge sta funzionando ma staging sta rifiutando il token.

Avvio immediato del task:

Start-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"

Stato task:

Get-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"
Get-ScheduledTaskInfo -TaskName "NetGescon Panasonic Live Bridge"

Stop task:

Stop-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"

Rimozione task:

Unregister-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge" -Confirm:$false

ma solo dopo aver validato bene il contenuto dei payload dry-run.

Se il provider Panasonic accetta RegisterCallNotifications, ma:

  • il polling resta sempre IDLE
  • CallHubs resta none
  • Register-ObjectEvent dice che non esiste l'evento Event

allora PowerShell in late binding non basta piu.

In quel caso il passo corretto e generare l'interop .NET della type library tapi3.dll e vedere i nomi reali di tipi, delegate ed eventi da usare in un watcher compilato.

Usa questo script:

  • scripts/ops/windows/inspect-netgescon-tapi-interop.ps1

Lancialo cosi:

.\scripts\ops\windows\inspect-netgescon-tapi-interop.ps1

Cosa deve succedere

Lo script:

  1. usa le classi .NET gia presenti in Windows
  2. genera un assembly .NET da C:\Windows\System32\tapi3.dll
  3. elenca i tipi che contengono Event
  4. elenca i tipi legati a ITTAPI

Cosa mi devi mandare

Mandami l'output completo dello script.

Con quello preparo il watcher compilato con i nomi esatti esposti dall'interop reale della tua macchina Windows.