Phone Lock REST APIs

Starting from Imagicle UCX Suite 2020.Summer.1 release, Phone Lock enables two REST APIs which allow respectively to lock and unlock phone lines at global level or department level.

Required permissions

To invoke those APIs, the following permission levels are required:

• Imagicle Admin ⇒ Global users' visibility

• Phone Lock "Complete Management" ⇒ Global users' visibility

• Phone Lock "Manage Department User" ⇒ Own department users' visibility

EndPoints

To unlock phone lines:

http://{ias-server}/fw/Apps/StoneLock/WebAPI/Phones/Unlock

To lock phone lines:

http://{ias-server}/fw/Apps/StoneLock/WebAPI/Phones/Lock

Filters

You can invoke above APIs by optionally adding QueryString filters to further narrow the Phone Lock action based on specific Imagicle user's fields:

/Lock?filterField=<value>

Available fields for filtering are:

• department

• customField1

• customField2

• customField3

• customField4

• customField5

• customField6

• customField7

• customField8

• customField9

• customField10

API Invoke samples

Please find below a couple of samples to invoke Phone Lock APIs:

Request URL (client REST, PUT)

http://staging.imagicle.local/fw/Apps/StoneLock/WebAPI/Phones/Lock?department=R%26D&customField1=Example1

cURL

curl -X PUT "http://staging.imagicle.local/fw/Apps/StoneLock/WebAPI/Phones/Lock?department=R%26D&customField1=Example1" -H "accept: */*"

Scheduled phone lines lock and unlock using Windows Task Scheduler

Windows Task Scheduler is suitable to schedule automatic phone lines lock and unlock at a certain time of the day. This is accomplished by creating a PowerShell script. See below the procedure to create such a script:

• Create a new PowerShell script using a text editor and call it script.ps1

• Copy the following code inside text file:

$username='' <# user on behalf of phones will be locked #>
$password='' <# password of the user on behalf of phones will be locked #>

<# set authentication headers for API request #>
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("$($username):$($password)"))
$Headers = @{
    Authorization = "Basic $encodedCreds"
}

<# set IAS parameters #>
$ias_url = '' <# IAS IP Address/FQDN affected by the API call #>
$action = 'Lock' <# action to be performed by the API (including filters) #>
$url = "http://$($ias_url)/fw/Apps/StoneLock/WebAPI/Phones/$($action)"

<# API request #>
Invoke-WebRequest -Uri $url -Headers $Headers -Method PUT

• Now configure above purple-marked field with the appropriate data:

  • username: UCX Suite username of the user accessing Phone Lock APIs

  • password: UCX Suite password of the user accessing Phone Lock APIs

  • ias_url: UCS Suite FQDN/IP address where APIs are invoked (i.e. 192.168.1.60)

  • action: This is the action to be initiated through API call (Lock or Unlock). Here you can optionally add specific filters, with above mentioned syntax.

Windows Task Scheduler usage

• Launch Windows Task Scheduler from Start menu and create a new schedule, specifying a new action including:

  • Program/script: Powershell.exe

  • Add arguments: path to script.ps1 text file

    

• Please add trigger and conditions, based on desired schedule time.