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

MINI 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. 

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. 

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. 

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.

Powershell Script

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

Particularly, the following lines must be modified:

• $Uri = 'https://acd-lb/rest/v1.0/1/routingApplications/run/3080'
• $env:API_TOKEN = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  
  

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.

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

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.

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:

$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:

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

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

$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:

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:

Note the call to a stored procedure to achieve this:

{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

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

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