Versions Compared

Old Version 2

changes.mady.by.user jtel Support

Saved on

compared with

New Version Current

changes.mady.by.user jtel Support

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Sv translation
languageen

The jtel MiniClient EXE provides APIs which can be used to integrate external systems.

These cover the following use-cases:

  • Automatically calling a REST service from the mini-client when an incoming call is received
  • Automatically calling a windows executable (.EXE) when an incoming call is received
  • Making an outbound call by calling the mini client .EXE using parameters

See also MiniClient Settings for all required settings.

Automatic REST Call

An automatic REST call can be made by the Mini-Client when an incoming call is received. 

To use this feature, the CRM URL must be passed via the standard ACD features (CRM URL in the ACD Group, or via an IVR Application, using the IVR Object "Save additional info and user data".

The following must be configured in the MiniClient configuration:

  • AutomaticRESTCRMUrl - Set to True
  • CurlRESTCommand - if necessary, alter this command as required. The parameters which are influenced by the ACD, i.e. the $crmurl variable, must be passed by GET (i.e. in the URL). 
  • Additional parameters can be added after $crmurl as necessary, or passed as additional POST parameters (a lot, but not all REST services will accept a combination of GET and POST parameters).

Automatic .EXE Call

Status
colourGreen
titleMini Client Release 3

...

,31

...

OR HIGHER

The following parameters must be set:

  • AutomaticEXECallCommand - Set this to the name of the executable to be called.

  • AutomaticEXECallParameters - Set these to the parameters to be passed to the executable. The following variables are available:

    • $ANumber - the called number
    • $GroupName - the name of the ACD group
    • $CRMLink - the complete CRM link provided by the ACD
    • $ServiceNumber - the service number called
    • $ServiceName - the name of the service number called
    • $CallID - the jtel CallID (currently not supported, will be supported in a future release)
    • $UsersUID - the ID of the User logged into the jtel system

Outbound Call

...

- Start Mini-Client with Dial Parameter

To request the MiniClient to dial a number, call it as follows

...

from the command line. 

Translations Ignore

AcdAgentMiniClient.exe --dial <number>

Note: an instance of the mini client must already be running for a logged in ACD user.

Mini Cllient Start with REST Call

When the mini client EXE is started, it may be desirable to communicate information from the local workstation to the jtel system, such as:

  • The Name of the workstation 
  • The IP Address of the workstation
  • A terminal server session ID
  • ...

Use Case

The first use case for this is a specific CRM integration where it is desired to have a screen popup on the local workstation when the agent receives an incoming call.

  • The CRM system in question requires that a REST call be made to the local workstation of the agent to implement this functionality.
  • This means, that the IP Address of the workstation must be saved in the Users jtel Portal data when the agent logs into the workstation.
  • To achieve this, the IP address of the workstation is communicated via the REST API to the jtel system and saved in the user's "NickName" field.
  • Then, when incoming calls are received, the information is available so a REST call can be made to the user's workstation to indicate the incoming call. 
Info

Note: this requires a license for the jtel REST API and the API to be installed.

How it Works

Starting the MiniClient EXE

The MiniClient EXE is no longer started using a shortcut or a link directly to the .EXE itself, but is started using a .cmd file, which in turn calls a powershell script to perform the REST operation. The following scripts can be used:

CMD Script

Create this script, to call the powershell script. 

Code Block
powershell -NoProfile -ExecutionPolicy Bypass -File start_mini_client_with_rest_call.ps1

You can create a shortcut for autostart or as a link which can be used to call this script.

Warning

Note: calling the powershell script below may not be possible on most standard windows installations due to an execution policy restriction.

Powershell Script

You will need to modify the following script when you create it.

Particularly, the following lines must be modified:

The URI should go through the load balancer. If you have setup an FQDN for this, then use that, otherwise you can also use the IP address of the load balancer. 

Also, the ID of the routing application must be provided in the URI. Swap the 1234 in the example script with the actual ID of the routing application you want to use (see below).

The API_TOKEN should be retrieved from Client Master Data.

Code Block
languagepowershell
# How to run this command from a normal .cmd shell:
# powershell -NoProfile -ExecutionPolicy Bypass -File start_mini_client.ps1

# The URI for the REST API
$Uri = 'https://acd-lb/rest/v1.0/1/routingApplications/run/1234'

# The REST API Token.
# This could also be set from somewhere else and not here. 
# For example using: setx API_TOKEN "f336162fb5daeefa4c312a23285d5395d8ecf0c211332e0055406dda16b2f077" from another process or an admin tool.
$env:API_TOKEN = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Build request body for the run routing application API.
$body = @{
  WindowsLoginName = $env:USERNAME
  ComputerName     = $env:COMPUTERNAME
  IPAddress        = (Get-NetIPAddress -AddressFamily IPv4 -PrefixOrigin Dhcp,Manual |
                      Where-Object { $_.IPAddress -ne '127.0.0.1' -and $_.IPAddress -notlike '169.*' } |
                      Select-Object -First 1 -ExpandProperty IPAddress)
}

# Add the required headers
$headers = @{
  'Authorization' = "Bearer $($env:API_TOKEN)"
  'Content-Type'  = 'application/json'
}

# Make the REST call
$response = Invoke-RestMethod -Method Post -Uri $Uri -Headers $headers -Body ($body | ConvertTo-Json -Compress)

# Show the response for debugging
$response

# Build absolute path to the EXE (which should be in the same directory as the script)
$exe = Join-Path $PSScriptRoot 'ACDMiniClient.exe'

$exe

# If SmartScreen/Zone marking is present, unblock (first run only)
try { Unblock-File -LiteralPath $exe } catch { }

# Start detached, with the correct working directory
Start-Process -FilePath $exe -WorkingDirectory $PSScriptRoot

# Close this Shell window if it was launched from explorer
$ppid = (Get-CimInstance Win32_Process -Filter "ProcessId=$PID").ParentProcessId
$parent = Get-Process -Id $ppid -ErrorAction SilentlyContinue

if ($parent.ProcessName -ieq 'explorer') {
    exit   # double-click case
}


Info

This script does the following:

  • Builds a $body object which contains the Windows Login Name, the Computer Name and the IPAddress of the workstation
  • Builds a $headers object which contains the authorization for the jtel REST API
  • Invokes a REST API call to the function routingApplications/run (see this page for details: Routing Applications REST API - Functions), providing the $body object as information to the process which is started
  • Starts the ACDMiniClient.exe
  • Closes the shell window, if it was launched via explorer

Consuming the Provided Information

The next step, is to write a routing application to "consume" the provided information in the jtel system. 

This is a standard Routing Application written in the jtel Workflow GUI - so here you can do ... anything you can do in a jtel workflow (which is just about anything).

In our example, we will update the user's NickName to the provided Workstation Name.

The routing application required to do this could look as follows.

Image Added

Note, when a routing application is started by the REST function routingApplications/run, any JSON data received will be parsed to variables prefixed with $workData.

In our example, we are posting the JSON body created by this part of the script:

Code Block
$body = @{
  WindowsLoginName = $env:USERNAME
  ComputerName     = $env:COMPUTERNAME
  IPAddress        = (Get-NetIPAddress -AddressFamily IPv4 -PrefixOrigin Dhcp,Manual |
                      Where-Object { $_.IPAddress -ne '127.0.0.1' -and $_.IPAddress -notlike '169.*' } |
                      Select-Object -First 1 -ExpandProperty IPAddress)
}

This will result in a JSON object which looks something like this:

Code Block
{
  "WindowsLoginName" : "MyUserName",
  "ComputerName" : "MyComputerName",
  "IPAddress" : "10.1.2.3"
}

And in turn, this will be parsed to the following variables:

Code Block
$workData.WindowsLoginName
$workData.ComputerName
$workData.IPAddress

These variables will be immediately available to use in the routing application.

The User Search object looks like this:

Image Added

This will search for the User who has the LDAP User Name configured in the jtel portal which is the same as what the powershell script determined when it was started. I.e. the local user name stored in the environment variable USERNAME.

If found, we want to update the user:

Image Added

Note the call to a stored procedure to achieve this:

Code Block
{CALL JTELWeb.Users_UpdateNickNameByUID( %Service.ClientsID_%, '$foundUser.usersuid', '$workdata.ComputerName')}

The parameters are provided using variables:

  • %Service.ClientsID_% will contain the current ClientsID
  • $foundUser.usersuid is the UsersUID returned by the User Search
  • $workdata.ComputerName is the name of the computer determined by the PowerShell script


Warning

This routing object will NOT BE AVAILABLE ON A MULTI-TENANT SYSTEM.

Finally, we return a result to the REST API, which in turn will be returned to the PowerShell script:

Image Added

Since the powershell script does not check the result, it doesn't really matter what we return.

Warning

Note: it is important to return something even for the cases where the user was not found, or the DB update fails. This will stop the PowerShell script from timing out (which might take up to 30 seconds).


Sv translation
languagede

Der jtel MiniClient EXE bietet APIs, die zur Integration externer Systeme verwendet werden können.

Diese decken die folgenden Anwendungsfälle ab:

  • Automatischer Aufruf eines REST-Dienstes vom Mini-Client aus, wenn ein eingehender Anruf empfangen wird
  • Automatischer Aufruf einer ausführbaren Windows-Datei (.EXE), wenn ein eingehender Anruf empfangen wird
  • Outbound Anruf durch Aufruf des Mini-Clients .EXE mit Parametern

Sehen Sie auch Mini Client Einstellungen für alle erforderlichen Einstellungen.

Automatischer REST-Anruf

Ein automatischer REST-Anruf kann durch den Mini-Client erfolgen, wenn ein eingehender Anruf empfangen wird. 

Um diese Funktion nutzen zu können, muss die CRM-URL über die Standard-ACD-Funktionen (CRM-URL in der ACD-Gruppe) oder über eine IVR-Anwendung mit dem IVR-Objekt "Speichern Zusatzinfo. und Benutzerdaten" übergeben werden.

In der MiniClient-Konfiguration muss Folgendes konfiguriert werden:

  • AutomaticRESTCRMUrl - Auf True setzen
  • CurlRESTCommand - Falls erforderlich, ändern Sie diesen Befehl nach Bedarf. Die Parameter, die von der ACD beeinflusst werden, d.h. die Variable $crmurl, müssen per GET (d.h. in der URL) übergeben werden. 
  • Zusätzliche Parameter können bei Bedarf nach $crmurl hinzugefügt oder als zusätzliche POST-Parameter übergeben werden (eine Menge, aber nicht alle REST-Dienste akzeptieren eine Kombination von GET- und POST-Parametern).

Automatischer .EXE Call

Status
colourGreen
titleMini Client Release 3.31 or higher

Die folgenden Parameter müssen eingestellt werden:

  • AutomaticEXECallCommand - Set this to the name of the executable to be called.

  • AutomaticEXECallParameters - Set these to the parameters to be passed to the executable. The following variables are available:

    • $ANumber - the called number
    • $GroupName - the name of the ACD group
    • $CRMLink - the complete CRM link provided by the ACD
    • $ServiceNumber - the service number called
    • $ServiceName - the name of the service number called
    • $CallID - the jtel CallID (currently not supported, will be supported in a future release)
    • $UsersUID - the ID of the User logged into the jtel system

Abgehend Telefonieren - Aufruf vom Mini-Client mit Dial Parameter

Um mit dem MiniClient einen Anruf zu tätigen, rufen Sie den Mini-Client mit folgende Kommandozeile auf.

Translations Ignore


Code Block
AcdAgentMiniClient.exe --dial <number>


Voraussetzung ist, für den angemeldeten ACD-Benutzer läuft bereits eine Instanz vom Mini-Client.

Sv translation
languagefr

Le MiniClient EXE de jtel fournit des API qui peuvent être utilisées pour intégrer des systèmes externes.

Ceux-ci couvrent les cas d'utilisation suivants :

  • Appeler automatiquement un service REST depuis le mini-client lorsqu'un appel entrant est reçu
  • Appel automatique d'un exécutable Windows (.EXE) lorsqu'un appel entrant est reçu
  • Effectuer un appel sortant en appelant le mini-client .EXE à l'aide de paramètres

Voir aussi MiniClient Settings pour tous les réglages requis.

Appel automatique REST

Un appel REST automatique peut être effectué par le mini-client lorsqu'un appel entrant est reçu. 

Pour utiliser cette fonctionnalité, l'URL du CRM doit être transmise via les fonctionnalités standard de l'ACD (URL CRM dans le groupe ACD, ou via une application IVR, en utilisant l'objet IVR "Enregistrer des informations supplémentaires et des données utilisateur".

Les éléments suivants doivent être configurés dans la configuration du MiniClient :

  • AutomaticRESTCRMUrl - Réglé sur Vrai
  • CurlRESTCommand - si nécessaire, modifiez cette commande selon les besoins. Les paramètres qui sont influencés par l'ACD, c'est-à-dire la variable $crmurl, doivent être passés par GET (c'est-à-dire dans l'URL). 
  • Des paramètres supplémentaires peuvent être ajoutés après $crmurl si nécessaire, ou passés comme paramètres POST supplémentaires (beaucoup, mais pas tous les services REST acceptent une combinaison de paramètres GET et POST)

Automatic appel .EXE

Status
colourGreen
titleMini Client Release 3,31 ou supérieur

Les paramètres suivants doivent être définis :

  • AutomaticEXECallCommand - Définissez ce paramètre sur le nom de l'exécutable à appeler.

  • AutomaticEXECallParameters - Définissez les paramètres à transmettre à l'exécutable. Les variables suivantes sont disponibles :

    • $ANumber - le numéro appelé
    • $GroupName - le nom du groupe ACD
    • $CRMLink - le lien CRM complet fourni par l'ACD
    • $ServiceNumber - le numéro de service appelé
    • $ServiceName - le nom du numéro de service appelé
    • $CallID - le CallID de jtel (actuellement non supporté, sera supporté dans une prochaine version)
    • $UsersUID - l'ID de l'utilisateur connecté au système jtel

Appel sortant en utilisant la numérotation

Pour demander au MiniClient de composer un numéro, appelez-le comme suit (en supposant qu'une instance est déjà en cours d'exécution pour un utilisateur ACD connecté) :

Translations Ignore

AcdAgentMiniClient.exe --dial

...

<number>