SOAP (celým názvem Simple Object Access Protocol) je protokolem pro výměnu zpráv založených na XML přes síť, hlavně pomocí HTTP. Formát SOAP tvoří základní vrstvu komunikace mezi webovými službami a poskytuje prostředí pro tvorbu složitější komunikace.

Existuje několik různých druhů šablon pro komunikaci na protokolu SOAP. Nejznámější z nich je RPC šablona, kde jeden z účastníků komunikace je klient a na druhé straně je server. Server ihned odpovídá na požadavky klienta.

SOAP je nástupce XML-RPC, ačkoliv si zapůjčuje jeho způsob přenosu dat a další vlastnosti. Obálka, hlavička a tělo komunikace je ale pravděpodobně z WDDX.

Původně ho navrhl Dave Winer, Don Box, Bob Atkinson a Mohsen Al-Ghosein v roce 1998 za podpory firmy Microsoft (kde tou dobou Atkinson a Al-Ghosein pracovali). Dnes je SOAP specifikace držena XML skupinou tvořící internetové protokoly z W3C konsorcia.

Zdroj http://cs.wikipedia.org/wiki/SOAP

Tento dokument popisuje základní metody pro integraci pobočkové ústředny s Informačním systémem, CRM a dalšími systémy. Umožňuje ovládat ústřednu z pohledu administrace tzn. založit linku, změnit parametry atp. Dále umožňuje získávat informace o aktuálních stavech jako jsou aktuální hovory, stav vyzvánění u linek. Umožňuje také periodicky získávat CDR.

Ověření

Probíhá na bázi http basic auth. Heslován je přístup k wsdl souboru. Komunikace je šifrovaná. Login a heslo pro přístup k souboru je přebírán z definice uživatelů v ústředně („Uživatelé“).

URL pro autentizaci: https://IP_ustredny/…ap/ipbx.wsdl

Pro připojení k SOAP serveru je nutné v administračním rozhraní ústředny vytvořit uživatele s právy SOAP.

SOAP typy proměnných

Celé názvosloví bylo zvoleno tak, aby korespondovalo s již zavedeným názvoslovím ve světě PBX.
Místo Line byl zvolen zkrácený název Exten od slova Extension, které znamená v překladu pobočková linka.

Dokumentace viz http://cdn.ipex.cz/ipbx.wsdl

getExtenCalls -> protože linka může současně vést několik hovorů, funkce vrací pole vedených
hovorů. Informace o aktuálních hovorech v ústředně.

SOAP funkce

Zde definujeme funkce, které potřebujeme pro základní interakci našeho IS s ústřednou.

Management linek

getExten Získá nastavení linky. Vrací pole informací o lince (typ LineInfo).
extenInfo Vrací nastavení linky a SIP kanálu.
getCELList Získá serializované pole události.
createExten Vytvoří linku.
deleteExten Zrušení linky.
getAllExten Nastavení všech linek. získání pole informací o linkách (každá typ LineInfo).
updateExten Změna parametru linky.
getExtenCalls Zjištění stavu linky.
redirectExten Změna parametru linky.
getDialplanList Seznam číslovacích plánů.
getOutRouteList Seznam odchozích směrování.
getAllExtenCalls Zjištění stavu všech linek.
deleteSpecialExten Smazani speciální linky a zařízení.
cancelRedirectExten Zruší přesměrování linky lineNumber.
getAllActiveExtenCalls identicka funkce jako getAllExtenCalls, ale tato funkce zobrazuje je ty linky, ktere hovori.

Hovory

originateExten(fromNumber,lineNumber) vyvolá hovor z fromNumber linky(číslo linky) na lineNumber(na jakékoliv číslo)

getExtenCalls získá seznam aktuálních hovorů, které probíhají pro danou linku
getAllExtenCalls získá seznam aktuálních hovorů, které probíhají na všech linkách

isRingingExten(lineNumber) vrátí číslo, které zvoní na lince lineNumber. Když nikdo nevolá vrátí false.
monitorExten(lineNumber,listenerLineNumber) nastavit příposlech
actionTransfer provede přepojení hovoru. Parametry jsou zdrojový kanál a id cílové linky.
hangupExten Ukončení hovorů zadané linky.

Výpisy

getCDRList(fromDate,toDate) získá výpis hovorů (pole, kde budou obsaženy všechny informace z CDR výpisu) omezený úsekem zadaných dat

Statistiky Call Centra

statsQueue Aktivita a celkový přehled front v call centru.
statsQueueUser Aktivita a celkový přehled uživatelů front v call centru.
statsQueueCall Přehled a výpisy hovorů v call centru.

Nahrávání

setRecordingExtenOn(lineNumber) nastaví, že linka bude nahrávaná
setRecordingExtenOff(lineNumber) nastaví, že linka nebude nahrávaná
getMonitorFile(fileName) - stáhne nahrávku hovoru

Ovládání seznamu kontaktů

createContact vytvoří nový kontakt
deleteContact odstraní kontakt
getContact vrací podrobné informace o jednom kontaktu
getAllContacts vrací celý seznam kontaktů. U jednotlivých kontaktů vrací id, celé jméno a telefonní čísla.

Systémové funkce

reloadConfiguration provede nové načtení konfigurace ústředny. Načtení konfigurace je potřeba provést po použití funkcí createExten, updateExten, setRecordingExtenOn a setRecordingExtenOff.

Příklady

Příklad odchozího volání v jazyce PHP. Zavolá linku uživatele, který chce odchozí hovor
uskutečnit. Po zvednutí sluchátka je iniciován hovor na volané číslo.

<?php
$username="soap";
$password="soapheslo";
$client = new
SoapClient("https://IP_ustredny/ipbx/soap/wsdl.php",array('encoding'=>'UTF-8','trace'=>1,'exceptions'=>1,'login'=>$username,'password'=>$password));
// zavolej na telefonni cislo
try {
     $out=$client->__soapCall("originateExten",array("from"=>"85","to"=>"0575750957","callerId"=>"85"));
     print_r($out);
}
     catch (Exception $e)
{
print_r($e);
};
?>

Další příklady k jednotlivým funkcím jsou k dispozici v repozitáři examples - https://bitbucket.org/ipex/examples

SOAP API