Overview

Starting from 2020.Summer.1 Imagicle AppSuite release, StoneLock 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:

• IAS Admin ⇒ Global users' visibility
• StoneLock "Complete Management" ⇒ Global users' visibility
• StoneLock "Manage Department User" ⇒ Own department users' visibility

EndPoint

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 StoneLock action based on specific IAS users 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 StoneLock 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: IAS username of the user accessing StoneLock APIs
  • password: IAS password of the user accessing StoneLock APIs
  • ias_url: IAS 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.