Guida all’utilizzo delle API di operation

Informazioni preliminari

Il formato supportato per le richieste e le risposte per tutte le API di operation è JSON, devono quindi essere impostati gli header Content-Type ed Accept al valore application/json.

/rest/operation/{serviceName}/{key}

Tramite questa API è possibile agire sulle impostazioni operative di vari servizi, sia in lettura con il verbo GET, sia in scrittura con il verbo POST, sia in cancellazione con il verbo DELETE.

Parametri

Nome	Obbligatorio	Descrizione
serviceName	si	I valori ammessi per questo parametro sono: - BUSYLEVEL: agisce sul livello di occupato - CFBS: (Call Forward Busy) agisce sull’inolto incondizionato in caso di occupato - CFIM: (Call Forward Immediate) agisce sull’inolto incondizionato - CFNA:(Call Forward Not Answer) agisce sull’inoltro in caso di non risposta - CFUN: (Call Forward Unavaiilable) agisce sull’inolto in caso di non disponibile - CLIP: RISERVATO - DND: (Do Not Disturb) agisce sul «non disturbare» - EXTEN_HUNTING: agisce sull’ordine di distribuzione della chiamata ai vari account dell’interno - FORKMOBILE: agisce sul fork delle chiamate verso il numero mobile - HUNTING: DEPRECATO
key	si	L’interno sul quale si vuole operare. Gli utenti che hanno un ruolo che permette il livello di accesso di scrittura o lettura sull’azione SERVICE_OPERATION possono operare senza restrizioni su tutti gli interni del PBX, mentre gli utenti standard del tenant (o utenti il cui ruolo ha livello di accesso nessuno o lista sull’azione SERVICE_OPERATION) possono operare solamente sul proprio interno.

Body della richiesta

Il body dovrà essere

{
    "operationData": "valore"
}

Maggiori dettagli sui valori ammessi sono forniti nel dettaglio di ciascun servizio.

Body della risposta

La struttura di base della risposta (per le richieste GET e POST) è comune a tutti i servizi ed è la seguente

{
    "tenantUuid": "tenentUuid",
    "serviceName": "serviceName",
    "key": "key",
    "operationData": serviceData
}

Le richieste DELETE invece non prevedono body di risposta.

Maggiori dettagli sul valore di operationData sono forniti nel dettaglio di ciascun servizio.

Codici di risposta

Codice HTTP	Descrizione
200	Nessun errore, la richiesta è stata eseguita correttamente
400	Solamente in caso di `POST`, indica che il body della richiesta non è corretto
403	L’utente che ha effettuato la richiesta non ha i privilegi necessari. Questo si verifica quando si verificano entrambe le seguenti condizioni. - l’interno identificato dal parametro `key` non è assegnato all’utente che ha fatto la richiesta - l’utente che ha fatto la richiesta non ha il giusto livello di accesso (lettura per la `GET`, scrittura per `POST` e `DELETE`) sull’azione SERVICE_OPERATION Se una o entrambe le condizioni precedenti sono false (ovvero l’interno è assegnato all’utente che ha fatto la richiesta, oppure l’utente ha il giusto livello di accesso per l’azione SERVICE_OPERATION), l’accesso è consentito

Servizio BUSYLEVEL

GET /rest/operation/BUSYLEVEL/{key}

Questa API permette di conoscere l’attuale valore di livello di occupato impostato per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente del livello di occupato per l’interno 101, l’API da invocare sarà

GET https://<PBX address>/rest/operation/BUSYLEVEL/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "BUSYLEVEL",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito può essere sia il valore booleano false, che sta ad indicare l’assenza di un’impostazione operativa per il livello di occupato, sia il numero intero precedentemente impostato tramite l’API POST.

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "BUSYLEVEL",
    "key": "101",
    "operationData": 1
}

NOTA: In assenza di un’impstazione operativa il livello di occupato per l’intero sarà quello impostato nel template associato all’interno, oppure - in caso di override abilitato per il livello di occupato - quello impostato nell’interno.

Quando il valore di operationData è 0 significa che il livello di occupato è impostato ad infinito.

POST /rest/operation/BUSYLEVEL/{key}

Questa API permette di impostare il valore di livello di occupato per un certo interno, il parametro key nel path. Supponendo di voler impostare il livello di occupato per l’interno 101 ad 1, l’API da invocare sarà

POST https://<PBX address>/rest/operation/BUSYLEVEL/101

Il body della richiesta dovrà essere

{
    "operationData": 1
}

NOTA: Il valore di operationData può essere anche una stringa, ma questa deve necessariamente contenere un numero intero altrimenti verrà restituita una risposta 400.
Body valido:
{
    "operationData": "1"
}
body non valido:
{
    "operationData": "uno"
}

Il formato del body restituito dall’API di POST è lo stesso della GET, il valore di operationData nella risposta rifletterà quello presente nella richiesta a riscontro dell’avvenuta modifica.

DELETE /rest/operation/BUSYLEVEL/{key}

Questa API permette di cancellare l’impostazione operativa per il livello di occupato impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare il livello di occupato impostato per l’interno 101, l’API da invocare sarà

DELETE https://<PBX address>/rest/operation/BUSYLEVEL/101

Servizio CFBS

GET /rest/operation/CFBS/{key}

Questa API permette di conoscere l’attuale impostazione operativa di inoltro su occupato per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https://<PBX address>/rest/operation/CFBS/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFBS",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito può essere sia il valore booleano false, che sta ad indicare la disabilitazione del servizio, sia una stringa contenente il numero impostato per l’inoltro.

Risposta in caso di inoltro impostato

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFBS",
    "key": "101",
    "operationData": "102"
}

POST /rest/operation/CFBS/{key}

Questa API permette di impostare il numero al quale inoltrare la chiamata in caso di occupato per un certo interno, il parametro key nel path. Supponendo di voler impostare l’inoltro per l’interno 101 verso l’interno 102, l’API da invocare sarà

POST https://<PBX address>/rest/operation/CFBS/101

NOTA: Per questo servizio, il valore da impostare deve essere una sequenza arbitraria di cifre decimali racchiusa tra doppi apici. Questo accorgimento è fondamentale per poter impostare inoltri verso numerazioni che iniziano con lo 0. Se il dato fosse trattato come numero intero questo non sarebbe possibile.
Dovendo essere interpretato come stringa, il dato stesso deve essere racchiuso tra caratteri " (doppio apice) di cui dovrà essere fatto l’escape.

Il body della richiesta dovrà essere

{
    "operationData": "\"102\""
}

Il formato del body restituito dall’API di POST è lo stesso della GET, il valore di operationData nella risposta rifletterà quello presente nella richiesta a riscontro dell’avvenuta modifica.

DELETE /rest/operation/CFBS/{key}

Questa API permette di cancellare l’impostazione operativa per l’inoltro su occupato impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’inoltro impostato per l’interno 101, l’API da invocare sarà

DELETE https://<PBX address>/rest/operation/CFBS/101

Servizio CFIM

GET /rest/operation/CFIM/{key}

Questa API permette di conoscere l’attuale impostazione operativa di inoltro incondizionato per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https://<PBX address>/rest/operation/CFIM/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFIM",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito può essere sia il valore booleano false, che sta ad indicare la disabilitazione del servizio, sia una stringa contenente il numero impostato per l’inoltro.

Risposta in caso di inoltro impostato

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFIM",
    "key": "101",
    "operationData": "102"
}

POST /rest/operation/CFIM/{key}

Questa API permette di impostare il numero al quale inoltrare la chiamata in maniera incondizionata per un certo interno, il parametro key nel path. Supponendo di voler impostare l’inoltro per l’interno 101 verso l’interno 102, l’API da invocare sarà

POST https://<PBX address>/rest/operation/CFIM/101

NOTA: Per questo servizio, il valore da impostare deve essere una sequenza arbitraria di cifre decimali racchiusa tra doppi apici. Questo accorgimento è fondamentale per poter impostare inoltri verso numerazioni che iniziano con lo 0. Se il dato fosse trattato come numero intero questo non sarebbe possibile.
Dovendo essere interpretato come stringa, il dato stesso deve essere racchiuso tra caratteri " (doppio apice) di cui dovrà essere fatto l’escape.

Il body della richiesta dovrà essere

{
    "operationData": "\"102\""
}

Il formato del body restituito dall’API di POST è lo stesso della GET, il valore di operationData nella risposta rifletterà quello presente nella richiesta a riscontro dell’avvenuta modifica.

DELETE /rest/operation/CFIM/{key}

Questa API permette di cancellare l’impostazione operativa per l’inoltro incondizionato impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’inoltro impostato per l’interno 101, l’API da invocare sarà

DELETE https://<PBX address>/rest/operation/CFIM/101

Servizio CFNA

GET /rest/operation/CFNA/{key}

Questa API permette di conoscere l’attuale impostazione operativa di inoltro su non risposta per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https://<PBX address>/rest/operation/CFNA/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFNA",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito può essere sia il valore booleano false, che sta ad indicare la disabilitazione del servizio, sia una stringa contenente il numero impostato per l’inoltro.

Risposta in caso di inoltro impostato

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFNA",
    "key": "101",
    "operationData": "102"
}

POST /rest/operation/CFNA/{key}

Questa API permette di impostare il numero al quale inoltrare la chiamata in caso di non risposta per un certo interno, il parametro key nel path. Supponendo di voler impostare l’inoltro per l’interno 101 verso l’interno 102, l’API da invocare sarà

POST https://<PBX address>/rest/operation/CFNA/101

NOTA: Per questo servizio, il valore da impostare deve essere una sequenza arbitraria di cifre decimali racchiusa tra doppi apici. Questo accorgimento è fondamentale per poter impostare inoltri verso numerazioni che iniziano con lo 0. Se il dato fosse trattato come numero intero questo non sarebbe possibile.
Dovendo essere interpretato come stringa, il dato stesso deve essere racchiuso tra caratteri " (doppio apice) di cui dovrà essere fatto l’escape.

Il body della richiesta dovrà essere

{
    "operationData": "\"102\""
}

Il formato del body restituito dall’API di POST è lo stesso della GET, il valore di operationData nella risposta rifletterà quello presente nella richiesta a riscontro dell’avvenuta modifica.

DELETE /rest/operation/CFNA/{key}

Questa API permette di cancellare l’impostazione operativa per l’inoltro su non risposta impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’inoltro impostato per l’interno 101, l’API da invocare sarà

DELETE https://<PBX address>/rest/operation/CFNA/101

Servizio CFUN

GET /rest/operation/CFUN/{key}

Questa API permette di conoscere l’attuale impostazione operativa di inoltro su non disponibile per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https://<PBX address>/rest/operation/CFUN/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFUN",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito può essere sia il valore booleano false, che sta ad indicare la disabilitazione del servizio, sia una stringa contenente il numero impostato per l’inoltro.

Risposta in caso di inoltro impostato

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFUN",
    "key": "101",
    "operationData": "102"
}

POST /rest/operation/CFUN/{key}

Questa API permette di impostare il numero al quale inoltrare la chiamata in caso di non disponibile per un certo interno, il parametro key nel path. Supponendo di voler impostare l’inoltro per l’interno 101 verso l’interno 102, l’API da invocare sarà

POST https://<PBX address>/rest/operation/CFUN/101

NOTA: Per questo servizio, il valore da impostare deve essere una sequenza arbitraria di cifre decimali racchiusa tra doppi apici. Questo accorgimento è fondamentale per poter impostare inoltri verso numerazioni che iniziano con lo 0. Se il dato fosse trattato come numero intero questo non sarebbe possibile.
Dovendo essere interpretato come stringa, il dato stesso deve essere racchiuso tra caratteri " (doppio apice) di cui dovrà essere fatto l’escape.

Il body della richiesta dovrà essere

{
    "operationData": "\"102\""
}

Il formato del body restituito dall’API di POST è lo stesso della GET, il valore di operationData nella risposta rifletterà quello presente nella richiesta a riscontro dell’avvenuta modifica.

DELETE /rest/operation/CFUN/{key}

Questa API permette di cancellare l’impostazione operativa per l’inoltro su non disponibile impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’inoltro impostato per l’interno 101, l’API da invocare sarà

DELETE https://<PBX address>/rest/operation/CFUN/101

Servizio DND

GET /rest/operation/DND/{key}

Questa API permette di conoscere l’attuale impostazione operativa del «non disturbare» per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https://<PBX address>/rest/operation/DND/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "DND",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito sarà un boolean, false che indica la disabilitazione del servizio, e true che indica l’abilitazione del servizio.

POST /rest/operation/DND/{key}

Questa API permette di abilitare/disabilitare il «non disturbare» per un certo interno, il parametro key nel path. Supponendo di voler abilitare il servizio per l’interno 101, l’API da invocare sarà

POST https://<PBX address>/rest/operation/DND/101

NOTA: Per questo servizio il valore da impostare deve essere il valore booleano true o false, ma questo deve essere racchiuso tra doppi apici (diventando di fatto una stringa).

Il body della richiesta dovrà essere

{
    "operationData": "true"
}

Il formato del body restituito dall’API di POST è lo stesso della GET, il valore di operationData nella risposta rifletterà quello presente nella richiesta a riscontro dell’avvenuta modifica.

DELETE /rest/operation/DND/{key}

Questa API permette di cancellare l’impostazione operativa del «non disturbare» impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’impostazione fatta per l’interno 101, l’API da invocare sarà

DELETE https://<PBX address>/rest/operation/DND/101

Servizio FORKMOBILE

GET /rest/operation/FORKMOBILE/{key}

Questa API permette di conoscere l’attuale impostazione operativa del fork delle chiamate verso il numero mobile per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https://<PBX address>/rest/operation/FORKMOBILE/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "FORKMOBILE",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito sarà un boolean, false che indica la disabilitazione del servizio, e true che indica l’abilitazione del servizio.

POST /rest/operation/FORKMOBILE/{key}

Questa API permette di abilitare/disabilitare il fork delle chiamate verso il numero mobile per un certo interno, il parametro key nel path. Supponendo di voler abilitare il servizio per l’interno 101, l’API da invocare sarà

POST https://<PBX address>/rest/operation/FORKMOBILE/101

NOTA: Per questo servizio il valore da impostare deve essere il valore booleano true o false, ma questo deve essere racchiuso tra doppi apici (diventando di fatto una stringa).

Il body della richiesta dovrà essere

{
    "operationData": "true"
}

Il formato del body restituito dall’API di POST è lo stesso della GET, il valore di operationData nella risposta rifletterà quello presente nella richiesta a riscontro dell’avvenuta modifica.

DELETE /rest/operation/FORKMOBILE/{key}

Questa API permette di cancellare l’impostazione operativa del fork delle chiamate verso il numero mobile impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’impostazione fatta per l’interno 101, l’API da invocare sarà

DELETE https://<PBX address>/rest/operation/FORKMOBILE/101

Servizio EXTEN_HUNTING

GET /rest/operation/EXTEN_HUNTING/{key}

Questa API permette di conoscere l’attuale impostazione operativa dell’ordine di distribuzione della chiamata ai vari account associati all’interno (di seguito «hunting» per semplicità) per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https://<PBX address>/rest/operation/EXTEN_HUNTING/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "EXTEN_HUNTING",
    "key": "101",
    "operationData": [
        {
            "priority": 1,
            "accounts": [
                {
                    "id": 1
                },
                {
                    "id": 6
                },
                {
                    "id": 7
                }
            ]
        }
    ]
}

Il valore di operationData restituito sarà un array di oggetti JSON con attributi priority ed accounts. accounts a sua volta è un array di oggetti JSON con solamente l’attributo id, ovvero l’id dell’account.

Nell’esempio riportato sopra si vede che gli account con id 1, 6 e 7 sono tutti inseriti nella priorità 1, ciò significa che al ricevimento di una chiamata questa verrà presentata contemporaneamente a tutti e tre gli account e questi squilleranno in contemporanea.

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "EXTEN_HUNTING",
    "key": "101",
    "operationData": [
        {
            "priority": 1,
            "accounts": [
                {
                    "id": 1
                }
            ]
        },
        {
            "priority": 2,
            "accounts": [
                {
                    "id": 6
                },
                {
                    "id": 7
                }
            ]
        }
    ]
}

In questo secondo esempio sono invece presenti due priorità, nella prima è presente solamente l’account con id 1 e nella seconda gli account con id 6 e 7. In questo caso, al ricevimento di una chiamata questa verrà presentata solamente all’account con id 1 e se questa non viene risposta, l’hunting procederà presentando la chiamata agli altri due account in contemporanea.

È quindi possibile personalizzare completamente la consegna delle chiamate ai vari account dell’interno.

In assenza di una configurazione specifica il comportamento di default sarà la consegna delle chiamate in contemporanea a tutti gli account dell’interno, quindi un’unica priorità con tutti gli account al suo interno.

NOTA: Per il servizio EXTEN_HUNTING non è presente l’API DELETE, per tornare quindi al comportamento di default è necessario impostare l’hunting con un’unica priorità inserendo al suo interno tutti gli account associati all’interno.

POST /rest/operation/EXTEN_HUNTING/{key}

Questa API permette di impostare l’hunting per un certo interno, il parametro key nel path. Supponendo di voler impostare l’hunting per l’interno 101, l’API da invocare sarà

POST https://<PBX address>/rest/operation/EXTEN_HUNTING/101

Formato del body

Per questo servizio il valore da impostare deve essere l’oggetto JSON rappresentante l’hunting, lo stesso tipo di oggetto restituito dalla GET.

Supponiamo di voler impostare un hunting con due priorità dove nella prima è presente solamente l’account con id 1 e nella seconda gli account con id 6 e 7, l’oggetto JSON che rappresenta questa configurazione sarebbe

[
   {
      "priority":1,
      "accounts":[
         {
            "id":1
         }
      ]
   },
   {
      "priority":2,
      "accounts":[
         {
            "id":6
         },
         {
            "id":7
         }
      ]
   }
]

L’oggetto JSON stesso rappresentante la configurazione deve essere trasformato in una stringa mediante l’escape dei caratteri " (doppio apice).
Il body della richiesta dovrà quindi essere

{
    "operationData": "[{\"priority\": 1, \"accounts\": [{\"id\": 1}]}, {\"priority\": 2, \"accounts\": [{\"id\": 6}, {\"id\": 7}]}]"
}

Il formato del body restituito dall’API di POST è lo stesso della GET, il valore di operationData nella risposta rifletterà quello presente nella richiesta a riscontro dell’avvenuta modifica.

GET /rest/operation/queue

Tramite questa API è possibile ottenere le informazioni sui membri dinamici e sullo stato di pausa dei membri (sia statici che dinamici) di tutte le code.

Body della risposta

La struttura della risposta si compone di un oggetto JSON con tanti attributi quante sono le code definite, dove l’attributo è il nome della coda stessa.
All’interno di ciascun oggetto «coda» possono essere presenti gli attributi dynamicMembers e pause. La presenza di uno o entrambi questi attributi è vincolata al fatto che siano stati aggiunti membri dinamici alla coda o che almeno un operatore sia stato messo in pausa o tolto dalla pausa. Quando nessuna di queste condizioni si verifica l’oggetto «coda» avrà valore null.

{
    "Queue 1": {
        "pause": {
            "SIP/101-app": {
                "status": true,
                "timestamp": "2024-01-17 19:07:50.814301+01"
            },
            "SIP/101-cti": {
                "status": true,
                "timestamp": "2024-01-17 19:09:33.84229+01"
            },
            "SIP/101-phone": {
                "status": false,
                "timestamp": "2024-01-17 18:21:43.463215+01"
            }
        },
        "dynamicMembers": {
            "SIP/101-cti": 0
        }
    },
    "Queue 2": null
}

Dettaglio dell’attributo `pause`

L’attributo pause è un oggetto JSON con tanti attributi quanti sono gli account per i quali è stato modificato almeno una volta lo stato di pausa, dove l’attributo è l’identificativo SIP dell’account stesso.

NOTA: L’attributo pause potrebbe non contenere tutti gli account assegnati alla coda, contiene solamente gli account per i quali è stato modificato almeno una volta lo stato di pausa. Gli account assegnati ad una coda, che siano statici o dinamici, e che non compaiono all’interno dell’attributo pause, sono da considerarsi non in pausa.

NOTA: La presenza di un account all’interno dell’attributo pause non ne determina l’assegnazione alla coda.
Per determinare l’elenco degli account assegnati ad una coda deve essere fatta l’unione degli account assegnati staticamente alla coda (recuperabili con l’API GET https://<PBX address>/api/pbx/v2/queue/{id}/account) e gli account dinamici presenti nell’attributo dynamicMembers.

Ogni attributo «SIP account» è un oggetto a sua volta contenente due attributi:

status: valore booleano che identifica lo stato di pausa dell’account nella coda. Se è true l’account è in pausa, se è false non lo è
timestamp: data ed ora, in formato ISO 8601, dell’ultimo cambio di stato

Dettaglio dell’attributo `dynamicMembers`

L’attributo dynamicMembers è un oggetto JSON con tanti attributi quanti sono i membri dinamici aggiunti alla coda, dove l’attributo è l’identificativo SIP dell’account stesso.

L’attributo «SIP account» ha come valore un intero, rappresentante la penalty del membro dinamico all’interno della coda.

Codici di risposta

Codice HTTP	Descrizione
200	Nessun errore, la richiesta è stata eseguita correttamente
403	L’utente che ha effettuato la richiesta non ha i privilegi necessari. Questo si verifica quando - in un PBX multi-tenant, l’utente che ha fatto la richiesta è di macchina e non di tenant. L’accesso a questa API è consentito a tutti gli utenti di tenant

GET /rest/operation/queue/{queueName}

Tramite questa API è possibile ottenere le informazioni sui membri dinamici e sullo stato di pausa dei membri (sia statici che dinamici) di una specifica coda.

Parametri

Nome	Obbligatorio	Descrizione
queueName	si	Il nome della coda per la quale si vogliono ottenere i dati

Body della risposta

La struttura della risposta è la stessa di quella dell’API GET https://<PBX address>/rest/operation/queue, con l’unica differenza che conterrà solamente i dati della coda richiesta.

{
    "Queue 1": {
        "pause": {
            "SIP/101-app": {
                "status": true,
                "timestamp": "2024-01-17 19:07:50.814301+01"
            },
            "SIP/101-cti": {
                "status": true,
                "timestamp": "2024-01-17 19:09:33.84229+01"
            },
            "SIP/101-phone": {
                "status": false,
                "timestamp": "2024-01-17 18:21:43.463215+01"
            }
        },
        "dynamicMembers": {
            "SIP/101-cti": 0
        }
    }
}

Codici di risposta

Codice HTTP	Descrizione
200	Nessun errore, la richiesta è stata eseguita correttamente
403	L’utente che ha effettuato la richiesta non ha i privilegi necessari. Questo si verifica quando - in un PBX multi-tenant, l’utente che ha fatto la richiesta è di macchina e non di tenant. L’accesso a questa API è consentito a tutti gli utenti di tenant
404	La coda specificata nel parametro `queueName` non è stata trovata

POST /rest/operation/queue/{operation}

Tramite questa API è possibile

aggiungere/rimuovere un operatore dinamico ad una specifica coda
aggiungere/rimuovere un operatore dinamico a tutte le code
mettere/togliere dalla pausa un operatore su una specifica coda
mettere/togliere dalla pausa un operatore da tutte le code

Parametri

Nome	Obbligatorio	Descrizione
operation	si	I valori ammessi per questo parametro sono: - pause: per agire sullo stato di pausa - dynamicMember: per agire sui membri dinamici

Body della risposta

Non è previsto nessun body nella risposta per questa API.

Codici di risposta

Codice HTTP	Descrizione
200	Nessun errore, la richiesta è stata eseguita correttamente
400	Il body della richiesta non è corretto
403	L’utente che ha effettuato la richiesta non ha i privilegi necessari. Questo si verifica quando - in un PBX multi-tenant, l’utente che ha fatto la richiesta è di macchina e non di tenant. L’accesso a questa API è consentito a tutti gli utenti di tenant

Gestione degli operatori dinamici

Per le operazioni sugli operatori dinamici deve essere invocata l’API

POST https://<PBX address>/rest/operation/queue/dynamicMember

Body della richiesta

La struttura di base dell’oggetto JSON della richiesta è

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": true,
    "penalty": 0
}

dove

Nome	Obbligatorio	Descrizione
queue	no	È il nome della coda alla quale vogliamo aggiungere/rimuovere il membro dinamico. Se l’attributo non è presente nella richiesta, questa agirà su tutte le code
account	si	È l’identificativo SIP dell’account da aggiungere/rimuovere dai membri dinamici
enabled	no	È un valore booleano che indica l’operazione da compiere. Se è `true` l’account viene aggiunto ai membri dinamici, se è `false` viene rimosso. Se l’attributo non è presente nella richiesta questo viene interpretato come `false`
penalty	no	È il valore di penalty da assegnare all’account (solamente in caso di aggiunta del membro dinamico), deve essere un intero `>= 0`. Se l’attributo non è presente nella richiesta questo viene interpretato come `0`

Aggiunta di un operatore dinamico ad una specifica coda

Supponiamo di voler aggiungere l’account SIP/101-phone-2 come membro dinamico della coda Queue 2 con penalty 1, il body della richiesta dovrà essere

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": true,
    "penalty": 1
}

Aggiunta di un operatore dinamico a tutte le code

Supponiamo di voler aggiungere l’account SIP/101-phone-2 come membro dinamico su tutte le code con penalty 0, il body della richiesta dovrà essere

{
    "account": "SIP/101-phone-2",
    "enabled": true,
    "penalty": 0
}

Rimozione di un operatore dinamico da una specifica coda

Supponiamo di voler rimuovere l’account SIP/101-phone-2 dai membri dinamici della coda Queue 2, il body della richiesta dovrà essere

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": false
}

Rimozione di un operatore dinamico da tutte le code

Supponiamo di voler rimuovere l’account SIP/101-phone-2 dai membri dinamici di tutte le code, il body della richiesta dovrà essere

{
    "account": "SIP/101-phone-2",
    "enabled": false,
}

Gestione della pausa degli operatori

Per le operazioni sulla pausa degli operatori deve essere invocata l’API

POST https://<PBX address>/rest/operation/queue/pause

Body della richiesta

La struttura di base dell’oggetto JSON della richiesta è

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": true
}

dove

Nome	Obbligatorio	Descrizione
queue	no	È il nome della coda per la quale vogliamo mettere/togliere dalla pausa l’operatore. Se l’attributo non è presente nella richiesta, questa agirà su tutte le code
account	si	È l’identificativo SIP dell’account da mettere/togliere dalla pausa
enabled	no	È un valore booleano che indica l’operazione da compiere. Se è `true` l’account viene messo in pausa, se è `false` viene tolto dalla pausa. Se l’attributo non è presente nella richiesta questo viene interpretato come `false`

Messa in pausa di un operatore su una specifica coda

Supponiamo di voler mettere in pausa l’account SIP/101-phone-2 sulla coda Queue 2, il body della richiesta dovrà essere

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": true
}

Messa in pausa di un operatore su tutte le code

Supponiamo di voler mettere in pausa l’account SIP/101-phone-2 su tutte le code, il body della richiesta dovrà essere

{
    "account": "SIP/101-phone-2",
    "enabled": true
}

Togliere dalla pausa un operatore su una specifica coda

Supponiamo di voler togliere dalla pausa l’account SIP/101-phone-2 sulla coda Queue 2, il body della richiesta dovrà essere

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": false
}

Togliere dalla pausa un operatore su tutte le code

Supponiamo di voler togliere dalla pausa l’account SIP/101-phone-2 su tutte le code, il body della richiesta dovrà essere

{
    "account": "SIP/101-phone-2",
    "enabled": false,
}

Guida all’utilizzo delle API di operation

Informazioni preliminari

/rest/operation/{serviceName}/{key}

Parametri

Body della richiesta

Body della risposta

Codici di risposta

Servizio BUSYLEVEL

GET /rest/operation/BUSYLEVEL/{key}

POST /rest/operation/BUSYLEVEL/{key}

DELETE /rest/operation/BUSYLEVEL/{key}

Servizio CFBS

GET /rest/operation/CFBS/{key}

POST /rest/operation/CFBS/{key}

DELETE /rest/operation/CFBS/{key}

Servizio CFIM

GET /rest/operation/CFIM/{key}

POST /rest/operation/CFIM/{key}

DELETE /rest/operation/CFIM/{key}

Servizio CFNA

GET /rest/operation/CFNA/{key}

POST /rest/operation/CFNA/{key}

DELETE /rest/operation/CFNA/{key}

Servizio CFUN

GET /rest/operation/CFUN/{key}

POST /rest/operation/CFUN/{key}

DELETE /rest/operation/CFUN/{key}

Servizio DND

GET /rest/operation/DND/{key}

POST /rest/operation/DND/{key}

DELETE /rest/operation/DND/{key}

Servizio FORKMOBILE

GET /rest/operation/FORKMOBILE/{key}

POST /rest/operation/FORKMOBILE/{key}

DELETE /rest/operation/FORKMOBILE/{key}

Servizio EXTEN_HUNTING

GET /rest/operation/EXTEN_HUNTING/{key}

POST /rest/operation/EXTEN_HUNTING/{key}

Formato del body

GET /rest/operation/queue

Body della risposta

Dettaglio dell’attributo pause

Dettaglio dell’attributo dynamicMembers

Codici di risposta

GET /rest/operation/queue/{queueName}

Parametri

Body della risposta

Codici di risposta

POST /rest/operation/queue/{operation}

Parametri

Body della risposta

Codici di risposta

Gestione degli operatori dinamici

Body della richiesta

Aggiunta di un operatore dinamico ad una specifica coda

Aggiunta di un operatore dinamico a tutte le code

Rimozione di un operatore dinamico da una specifica coda

Rimozione di un operatore dinamico da tutte le code

Gestione della pausa degli operatori

Body della richiesta

Messa in pausa di un operatore su una specifica coda

Messa in pausa di un operatore su tutte le code

Togliere dalla pausa un operatore su una specifica coda

Togliere dalla pausa un operatore su tutte le code

Dettaglio dell’attributo `pause`

Dettaglio dell’attributo `dynamicMembers`