innovaphone wiki - User contributions [en]

Howto:SOAP API Admin Java Sample Code

2018-06-11T18:05:01Z

Franciscopaletta: /* The sample application */

{{3rd_Party_Input}}
==Applies To==
This information applies to

* any innovaphone PBX platform
* Java Runtime Environment

innovaphone PBX web services can be used from Java Runtime Environment. Here is how



==More Information==
===Configuration===
Modify the global variables ''SOAPENDPOINTURL'', ''ADMSOAPUSER'', ''ADMSOAPUSERPWD'', ''SOAPUSER'' and ''CNUSER'' according to your specific system.

===Running Sample Code===
This code is a simple Java console application. It will run on your OS console terminal. As dependencies, you will need JDK to compile the code and JRE to execute it.

To '''compile''', save the code on file '''innoSOAPadm.java''' and provide that file as parameter to '''javac''' command.
*The below code was compiled on javac version 1.8.0 and run on java version 1.8.0 (It was not tested on other versions)
*You may get a warning regarding the function sun.misc.BASE64Encoder().encode() because it is deprecated. Nevertheless the code will run. You may remove that section of the code (used just for authentication on the PBX) but you will have to allow "public" access to /PBX0/user.soap on HTTP(security risk!!!).

====The sample application ====
This section will discuss the sample code. It is not a decent description of the PBX SOAP API. For this, see the related articles.

<code java>

import javax.xml.soap.*;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;

import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;
import org.w3c.dom.NamedNodeMap;

import javax.xml.soap.MessageFactory;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPMessage;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPBody;

import javax.xml.parsers.ParserConfigurationException;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import java.io.StringReader;
import java.io.IOException;

import javax.xml.soap.Node;

public class innoSOAPadm {

//innovaphone general information
private static final String MYNAMESPACE = "pbx";
private static final String MYNAMESPACEURI = "http://www.innovaphone.com/pbx";

//specific system information
private static final String SOAPACTION = "";
private static final String SOAPENDPOINTURL = "http://192.168.0.1/PBX0/user.soap";
private static final String ADMSOAPUSER = "admin"; //PBX admin user
private static final String ADMSOAPUSERPWD = "ip311"; //PBX admin password
private static final String SOAPUSER = "SOAP"; //SOAP user object in PBX with group access to other objects
private static final String CNUSER = "PBX User Four"; //CN of user to perform Poll on

// Main function
public static void main(String args[]) {
callSoapWebService(SOAPENDPOINTURL, SOAPACTION);
}

//Starts web connection and execute the SOAP calls
private static void callSoapWebService(String soapEndpointUrl, String soapAction) {
try {

String session="";
String user="";
String response="";

// Create SOAP Connection
SOAPConnectionFactory soapConnectionFactory = SOAPConnectionFactory.newInstance();
SOAPConnection soapConnection = soapConnectionFactory.createConnection();

SOAPMessage soapResponse = soapConnection.call(createSOAPRequest_Admin(soapAction, session), soapEndpointUrl);

// Print the SOAP Response
System.out.println("Response SOAP Message Trimmed to <return>:");
SOAPBody body = soapResponse.getSOAPBody();
NodeList returnList = body.getElementsByTagName("return");
response=returnList.item(0).getTextContent();
System.out.println(response);
System.out.println("");

System.out.println("Response parsed to Nodes and Attributes:");
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
DocumentBuilder builder = factory.newDocumentBuilder();
InputSource is = new InputSource(new StringReader(response));
Document doc = builder.parse(is);
nodeListPrint(doc.getElementsByTagName("show"));

soapConnection.close();

} catch (Exception e) {
System.err.println("\nError occurred while sending SOAP Request to Server!\nMake sure you have the correct endpoint URL and SOAPAction!\n");
e.printStackTrace();
}
}

//Creates a SOAPmessage with the "Admin" instruction
private static SOAPMessage createSOAPRequest_Admin(String soapAction, String session) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("Admin");
SOAPElement soapBodyElem2 = soapBodyElem.addChildElement("xml");
Name sdcPDUPduName = envelope.createName("type", "xsi", "http://www.innovaphone.com/pbx");
soapBodyElem2.addAttribute(sdcPDUPduName, "xsd:string");
soapBodyElem2.setTextContent("<show><user cn=\"" + CNUSER + "\" /></show>");

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

//Prints all nodes on the nodelist
private static void nodeListPrint(NodeList list){
NodeList childList;
for (int i = 0; i < list.getLength(); i++) {
System.out.println("<"+String.valueOf(list.item(i).getNodeName())+">");
try {
if(list.item(i).hasAttributes()) {
nodeListAttribPrint(list.item(i).getAttributes());
}
if(list.item(i).hasChildNodes()) {
System.out.println("");
childList = list.item(i).getChildNodes();
nodeListPrint(childList);
} else {
System.out.println("");
}
} catch(Exception x) {
System.out.println("\nError getting attributes or child nodes....");
}
}
}

private static void nodeListAttribPrint(NamedNodeMap node) {
for (int i = 0; i < node.getLength(); i++) {
System.out.println(node.item(i).getNodeName() + " = \"" + node.item(i).getNodeValue() + "\"");
}
}

}

</code>

== Known Problems ==

==Related Articles==
[[Reference:SOAP API]]

[[Howto:PBX SOAP Api C-sharp sample code ]]

[[Howto:SOAP with PHP5]]



[[Category:Sample|{{PAGENAME}}]]

Howto:SOAP API Admin Java Sample Code

2018-06-08T19:26:06Z

Franciscopaletta: New page: {{3rd_Party_Input}} ==Applies To== This information applies to * any innovaphone PBX platform * Java Runtime Environment innovaphone PBX web services can be used from Java Runtime Enviro...

{{3rd_Party_Input}}
==Applies To==
This information applies to

* any innovaphone PBX platform
* Java Runtime Environment

innovaphone PBX web services can be used from Java Runtime Environment. Here is how



==More Information==
===Configuration===
Modify the global variables ''SOAPENDPOINTURL'', ''ADMSOAPUSER'', ''ADMSOAPUSERPWD'', ''SOAPUSER'' and ''CNUSER'' according to your specific system.

===Running Sample Code===
This code is a simple Java console application. It will run on your OS console terminal. As dependencies, you will need JDK to compile the code and JRE to execute it.

To '''compile''', save the code on file '''innoSOAPadm.java''' and provide that file as parameter to '''javac''' command.
*The below code was compiled on javac version 1.8.0 and run on java version 1.8.0 (It was not tested on other versions)
*You may get a warning regarding the function sun.misc.BASE64Encoder().encode() because it is deprecated. Nevertheless the code will run. You may remove that section of the code (used just for authentication on the PBX) but you will have to allow "public" access to /PBX0/user.soap on HTTP(security risk!!!).

====The sample application ====
This section will discuss the sample code. It is not a decent description of the PBX SOAP API. For this, see the related articles.

<code java>

import javax.xml.soap.*;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;

import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;

import javax.xml.soap.MessageFactory;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPMessage;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPBody;

import javax.xml.parsers.ParserConfigurationException;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import java.io.StringReader;
import java.io.IOException;

import javax.xml.soap.Node;

public class innoSOAPadm {

//innovaphone general information
private static final String MYNAMESPACE = "pbx";
private static final String MYNAMESPACEURI = "http://www.innovaphone.com/pbx";

//specific system information
private static final String SOAPACTION = "";
private static final String SOAPENDPOINTURL = "http://192.168.0.1/PBX0/user.soap";
private static final String ADMSOAPUSER = "admin"; //PBX admin user
private static final String ADMSOAPUSERPWD = "ip311"; //PBX admin password
private static final String SOAPUSER = "SOAP"; //SOAP user object in PBX with group access to other objects
private static final String CNUSER = "PBX User Four"; //CN of user to perform Poll on

// Main function
public static void main(String args[]) {
callSoapWebService(SOAPENDPOINTURL, SOAPACTION);
}

//Starts web connection and execute the SOAP calls
private static void callSoapWebService(String soapEndpointUrl, String soapAction) {
try {

String session="";
String user="";
String response="";

// Create SOAP Connection
SOAPConnectionFactory soapConnectionFactory = SOAPConnectionFactory.newInstance();
SOAPConnection soapConnection = soapConnectionFactory.createConnection();

SOAPMessage soapResponse = soapConnection.call(createSOAPRequest_Admin(soapAction, session), soapEndpointUrl);

// Print the SOAP Response
System.out.println("Response SOAP Message:");

SOAPBody body = soapResponse.getSOAPBody();
NodeList returnList = body.getElementsByTagName("return");
System.out.println("Response Parsed:");
response=returnList.item(0).getTextContent();
System.out.println(response);
System.out.println("");

soapConnection.close();

} catch (Exception e) {
System.err.println("\nError occurred while sending SOAP Request to Server!\nMake sure you have the correct endpoint URL and SOAPAction!\n");
e.printStackTrace();
}
}

//Creates a SOAPmessage with the "Admin" instruction
private static SOAPMessage createSOAPRequest_Admin(String soapAction, String session) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("Admin");
SOAPElement soapBodyElem2 = soapBodyElem.addChildElement("xml");
Name sdcPDUPduName = envelope.createName("type", "xsi", "http://www.innovaphone.com/pbx");
soapBodyElem2.addAttribute(sdcPDUPduName, "xsd:string");
soapBodyElem2.setTextContent("<show><user cn=\"" + CNUSER + "\" /></show>");

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}
}

</code>

== Known Problems ==

==Related Articles==
[[Reference:SOAP API]]

[[Howto:PBX SOAP Api C-sharp sample code ]]

[[Howto:SOAP with PHP5]]



[[Category:Sample|{{PAGENAME}}]]

Howto:Using the SOAP Admin Function

2018-06-08T19:18:15Z

Franciscopaletta: /* Related Articles */

The [[Reference:SOAP API|PBX SOAP interface]] allows you to query and manipulate the entire PBX object configuration (i.e. users). Here is the syntax of the commands.
==Applies To==
This information applies to

* all innovaphone PBX platforms



==More Information==

===Problem Details===
Sometimes, there is a need to access the PBX object configuration (that is, the defined users, trunk lines, nodes, etc.) programmatically. This could be done for examination or for manipulation.

There are various ways to accomplish this, one of it is using the [[Reference:SOAP_API#string_Admin.28string_xml.29|Admin function]] available in the [[Reference:SOAP_API|SOAP API]].

This function takes a single argument '''xml''', which is executed as a command and the resulting output is returned to the user.

===System Requirements===
The SOAP interface and thus the SOAP API's '''Admin''' is available when a working PBX is present in a Box. Please note that the usual restrictions apply for updating entries, namely, entries shall not be modified when LDAP replication is active on the box. Instead, connect to the LDAP masters SOAP interface and do the modifications.

=== Usage ===
The Admin() function may be used to retrieve information from and write information to the PBX. Information written to the PBX is effective immediately.

The '''xml''' argument to '''Admin()''' is an xml string, that has a single top-level element, which is interpreted as command.

Depending on the way the SOAP request is sent the provided '''xml''' argument must be manually XML escaped:

<code mxml>
" "
' '
< <
> >
& &
</code>

Example:
<code mxml>
<show><user cn="PBX User Four" config="true"/></show>
</code>

There are various commands implemented.
====show====
The '''show''' command will show details about an object, selected by its '''cn''' (which is the long name in the PBX user config), e.g.

'''<nowiki><show><user cn="PBX User Four" config="true"/></show></nowiki>'''

<code xml>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pbx="http://www.innovaphone.com/pbx"><SOAP-ENV:Header/><SOAP-ENV:Body>
<Admin><xml xsi:type="xsd:string"><show><user cn="PBX User Four" config="true"/></show></xml>
</Admin></SOAP-ENV:Body></SOAP-ENV:Envelope>
</code>

The attribute config="true" (available starting with version 9) is optional. If used only the pure config stored at a user is provided, without application of templates.

The command will return the data for '''PBX User Four''' (provided there is one):

'''<pre><nowiki>
<show time="2994">
<user
cn="PBX User Four"
guid="4126ec4ee909d3119db10090330600e8"
e164="140"
h323="user-4"
pwd="********"
fake="123"
cfnr="99"
busy-out="4711"
loc="Sindelfingen"
node="root"
filter="normal"
cd-filter="normal"
type="ep">
<cd
type="cfb">
<ep
e164="0900123"/>
</cd>
<cd
type="cfnr">
<ep
e164="0900321"/>
</cd><
<grp
name="test"/>
<grp
name="soap"/>
<ep
type="EP"
addr="172.16.10.38"
port="2069"
product="innovaphone IP230 [-/08-6090020/20080116-01]"
version="6.00 dvl-sr2 [08-60900.20/222/104]"
h323="user-4"
time="336"
lic="true"/>
</user>
</show>
</nowiki></pre>'''

As a special case, you can use the cn '''*''' which will yield a list of all known objects. But be aware that the result of a SOAP request is limited to a fixed amount of bytes (version dependant, currently 300kB). Larger results will cause the request to fail. It is thus not recommended to use this feature as a general purpose mechanism. Also be aware in V9 the ''show'' request with wildcard as ''cn'' will deliver not complete object configuration (some fields are omitted to reduce the amount of data).
It is thus recommended to use calls to [[Reference9:Concept_SOAP_API#UserInfo.5B.5D_FindUser.28string_v501.2C_string_v700.2C_string_v800.2C_string_v900.2C_string_cn.2C_string_h323.2C_string_e164.2C_integer_count.2C_integer_next.29|FindUser]] to retrieve the list of all objects and to use '''Admin()''' with the specific ''cn'' for each object of interest. An example how to retrieve configuration of all objects can be found here [[Howto:Retrieve configuration of all PBX Objects using SOAP API]].

Subtags underneath '''<user>''' include '''cd''', '''grp''', '''pseudo''', '''gw'''. However, this list may change over time and you must not rely on this.

The list of currently known attributes to '''<user>''' is '''guid''', '''cn''', '''h323''', '''e164''', '''hw-id''', '''pbx''', '''loc''', '''node''', '''rep''', '''phys''', '''pwd''', '''cfnr''', '''busy-in''', '''busy-out''', '''type''', '''filter''', '''cd-filter''', '''gi''', '''local'''. Again, this list may change and you must not rely on it.

Please note the appearance of the '''pwd''' attribute ('''pwd="********"'''). It is - of course - not possible to retrieve the password using this interface (in fact, it is not possible to retrieve the password at all).

Some of the information is in fact runtime data, not configuration data. For example, the '''<ep>''' tag shows current registration information for the object.

====add====
The '''add''' command will create a new PBX object, e.g.

'''<pre>
<add>
<user
cn="new PBX User Four"
e164="140"
h323="user-4"
cfnr="99"
busy-out="4711"
loc="Sindelfingen"
node="root"
filter="normal"
cd-filter="normal"
type="ep">
<cd type="cfb">
<ep e164="0900123"/>
</cd>
<cd type="cfnr">
<ep e164="0900321"/>
</cd>
<grp name="soap"/>
<grp name="test"/>
</user>
</add>
</pre>'''

If the addition is ok

'''<pre><nowiki><ok/></nowiki></pre>'''

will be returned.

There is no need to define all attributes, nor is it required to include all the subtags. For example, you can add the call diversions later using the '''<add-attrib>''' command. However, keep in mind that ''incomplete'' objects may cause harm (e.g. objects that have no setting for the '''node''' attribute).

To determine the available attributes and subtags, create an object manually using the web interface and retrieve the xml representation using the '''show''' command.

Any '''guid''' attribute will be ignored and the new object receives a new guid.

====modify====
To modify an existing entry, use the '''modify''' command. It has one subtag '''<user>''' which carries the complete data for the object after modification (not just the data that shall be modified). The object to be modified is determined by the '''guid''' attribute within the '''<user>''' tag. In the absence of this, it is determined by the '''cn''' (aka ''Long Name'') attribute. Thus, to change the long name of an object, you need to specify its guid, otherwise the cn is sufficient.

In fact, the '''modify''' command is functional identical to a '''del''' / '''add''' cycle. The only difference is that the object is not really removed in between, so that the guid stays the same and any action related to the removal of an object (such as the deregistration of endpoints registered on the object) does not happen.

The only ''fool-proof'' method of changing an objects attribute thus is to do a '''show''' / '''modify''' cycle. When the '''pwd''' attribute is given as 8 stars ('''pwd="********"'''), then it is not modified/set. Any other value is interpreted as clear text password. From firmware version 10 upwards, the '''show'' command will additionally report the password in encrypted form. If '''pwdx''' is sent back to the PBX during a '''modify''' command and the '''pwd''' attribute has the value '''********''', then the decrypted value of '''pwdx''' is set as the new password. If '''pwd''' is not '''********''', its value is used as the new password (clear text).

Please note that for a '''modify''' to succeed, the object does not need to exist. In fact, '''modify''' on a non-existing object will create it.

====del====
An object can be deleted using the '''del''' command.
You must specify the '''cn''' attribute to delete an object, the '''guid''' will not do.

'''<pre><nowiki>
<del><user cn="supernew PBX User Four"/></del>
</nowiki></pre>'''

will delete the user with long name "supernew PBX User Four".

====add-attrib / del-attrib====
Some of the PBX object attributes can be accessed separately. This is true for all (usually multi-valued) attributes that live in a separate '''pbx=''' value on the FLASHDIR level. To understand this, have a look at an object and its representations on the XML and FLASHDIR level. Let us assume we have an object with cn '''PBX User Four'''. The '''show''' command yields

'''<pre>
<show time="18613">
<user
cn="PBX User Four"
guid="4126ec4ee909d3119db10090330600e8"
e164="140"
h323="user-4"
pwd="********"
fake="123"
cfnr="99"
busy-out="4711"
loc="Sindelfingen"
node="root"
filter="normal"
cd-filter="normal"
type="ep">
<cd
type="cfb">
<ep
e164="0900123"/>
</cd>
<cd
type="cfnr">
<ep e164="0900321"/>
</cd>
<grp
name="soap"/>
<grp
name="test"/>
</user>
</show>
</pre>'''

On the FLASHDIR level (as seen in ''Config show''), the object looks like this:

<pre>
mod cmd FLASHDIR0 add-item 101
(cn=PBX User Four)
(guid;bin=4126EC4EE909D3119DB10090330600E8)
(h323=user-4)
(e164=140)
(loc=Sindelfingen)
(node=root)
(pbx=<user filter="normal" cd-filter="normal" fake="123" cfnr="99" busy-in="65535" busy-out="4711" pwd="ff8523566a0b5b820f785a6ed1eb24e5"/>)
(pbx=<grp name="soap"/>)
(pbx=<grp name="test"/>)
(pbx=<cd type="cfb"><ep e164="0900123"/></cd>)
(pbx=<cd type="cfnr"><ep e164="0900321"/></cd>)
(usn=35)
</pre>

Any information that is stored in a single '''(pbx=<...''' value can be deleted using '''del-attrib''' or added using '''add-attrib'''. To delete e.g. the CFB to 09000123, you can use

<pre>
<del-attrib>
<user
cn="new PBX User Four">
<cd type="cfb">
<ep e164="0900123"/>
</cd>
</user>
</del-attrib>
</pre>

To delete such an attribute, it is important that you specify the complete attribute xml syntax as subtag to the '''<user>''' tag. In the previous example, this is

<pre>
<cd type="cfb">
<ep e164="0900123"/>
</cd>
</pre>

=== Removing all Devices from User Object ===
to be able to delete all Devices/HW-IDs from an Object, an additional attribute ''no-dev'' must be supplied. Otherwise the PBX will add a device with Hardware-ID set to the Name of the Object.

Example modify request:
<?xml version="1.0"?>
<modify>
<user cn="User 6"
guid="819a174e73365901b90b009033400215"
e164="16"
h323="user6"
pwd="********"
pwdx="529c49b24c3e40c67d3f24f214b843cdd77fe777d7dab77f"
loc="hq"
node="root"
no-dev="true"/>
</modify>

=== Determination of the cn ===
When the '''cn''' of an object is not known, it can be determined by virtue of the [[Reference:SOAP_API#UserInfo.5B.5D_FindUser.28string_v501.2C_string_cn.2C_string_h323.2C_string_e164.2C_integer_count.2C_integer_next.29|SOAP FindUser]] function.

=== Setting and Retrieving Passwords ===
Passwords cannot be retrieved in clear. They can be set and retrieved in encrypted format though, see [[Howto:Using_the_SOAP_Admin_Function#modify|modify]] above. See ''Related articles'' below for a discussion of password encryption in the PBX.

===Uncovering xml commands with V5 PBXs===
On more recent V5 (and later) PBX platforms, you can uncover valid syntax by turning on the configuration changes logging (''Administration'') in the log interface and then performing the action you want to mimic with your SOAP program in the user interface. The xml commands will show up as syslog entries.

== Related Articles ==

* [[Howto:Encrypt_or_Decrypt_PBX_user_passwords]] - how PBX passwords are encrypted
* [[Howto:SOAP API PHP5 Sample Code]] - PHP5 sample code. Also show sample usage of the SOAP Admin() function, so it is good reading even if you do not implement in PHP!
* [[Howto:SOAP API Admin Java Sample Code]] - Java <Admin> sample code.

[[Category:Howto|{{PAGENAME}}]]

Reference:SOAP API

2018-06-08T19:16:09Z

Franciscopaletta: /* Related Articles */

innovaphone®’s PBX software component introduced with firmware V4 features a new call control API, known as “PBX API” (formerly called “XML API”). This API is released with the V5 firmware. This documents gives a short overview.

==Overview==

This documents describes innovaphone’s PBX API, a call control API exposed by the PBX software component running on the IP 21, IP202, IP 400, IP800 and IP 3000.

The PBX API’s goal is to enable 3rd parties to write software targeting the innovaphone® PBX platform. The API is based upon standardized technologies such as XML and SOAP, so that it can be exposed in a platform neutral manner. Developers are thus not restricted to specific platforms when designing their PBX API based applications.

The PBX API is a call control API. That is, by use of the API calls can be monitored, placed, controlled and terminated. However, the PBX API is not the endpoint of a call. Particularly, the PBX API does not provide access to the media stream associated with a call. The PBX API controls calls between endpoints known to the PBX.

Applications, which need to function as the endpoint of a call, must use a different API, which is described in a separate document. However, both APIs can be used simultaneously if required.

[[Image:soap-api-01.png]]

As can be seen in Figure 1, calls live independently of the PBX API and it is transparent to the application what kind of endpoints are actually involved on the call. Thus, calls are seen in a uniform way by the application.

The call control functions provided by the PBX API are actually exposed as a set of SOAP methods by the PBX, which together make a SOAP service.

Strictly speaking, the PBX API is not an API, but a protocol with a well-defined mapping to a transport mechanism. This transport mechanism is HTTP and the mapping is defined by SOAP. The set of methods exposed can be described using a standard SOAP mechanism, the WSDL file (WSDL is for [[http://www.w3.org/TR/wsdl Web Services Description Language]]). This way, users of the PBX API can access these methods from any platform they happen to utilize, provided this platform provides access to SOAP services.

[[Image:soap-api-02.png]]

Only the PBX part shown in Figure 2 is provided by innovaphone®, the left part is left to individual platform software provided by 3rd parties. In particular, the actual API used be the application developer is specific to the development environment or tool she is using.

Many development environments do support SOAP and thus enable access to the SOAP methods exposed by the PBX. We have worked so far with Microsoft’s Visual Studio.NET environment (C# and Visual Basic), as well as plain traditional C++ and PHP5. Customers have reported successful implementations in perl and Delphi.

Looking specifically at the Microsoft.NET environment, there is a language agnostic runtime environment, which implements the IP, HTTP and SOAP layer. On top of this, there are various language implementations sharing this same runtime environment, namely Visual C#, Visual C++ and Visual Basic. While all these languages provide access to the PBX’s SOAP methods, the API used to accomplish this is obviously syntactically different depending on the language used.

Also, other development environments, such as Perl or Python, may provide access to SOAP methods and thus provide yet another PBX API.

Figure 3 shows how various development environments expose syntactically different PBX API’s .

[[Image:soap-api-03.png]]

[[Category:Concept|{{PAGENAME}}]]

== Definition of PBX object (WSDL) ==
Within the SOAP framework there is a mechanism to formally decribe the definition of remote objects. This is done by so called WSDL (Web Service Description Language) files.
According to the used firmware you may use a [[#References|specific wsdl file]] which defines the PBX web services described in this document.

<small>There is also an [[http://www.innovaphone.com/wsdl/pbx.wsdl old version of the wsdl]] available which has less interface functions. This interface can still be accessed by legacy applications and is activated on the PBX by calling the '''Initialize''' Function with fewer arguments ('''Integer Initialize(string user, string appl, out key)'''). It should not be used for new develoments though.</small>

==PBX Objects and Methods==

This section contains a language agnostic description of the PBX API’s object model. Despite of the fact that we are discussing an object model, the PBX API is in fact not an object oriented API. This is because SOAP itself is not really object oriented. In particular, there is no object creation, activation or lifetime concept. This is left up to the service designer. SOAP is more a message exchange mechanism than an object method invocation mechanism. This is reflected in the API structure.

Specifically, objects are represented through handles, which are integers. Objects are created and destroyed using dedicated methods and it’s the users responsibility to manage the lifetime of all objects.

The syntax shown here actually is no valid syntax in any existing language. Please refer to the various sample codes for working syntax.

===Session===

All PBX API methods are executed in the context of a session. A session is created using the '''initialize''' method and is identified by a handle. This handle must be provided to all subsequent method calls.

A session is owned by the PBX API user, i.e. there is no way to have access to a session of another application. Each session has a scope, which defines the view of the PBX the session user has. The scope determines the set of PBX registrations seen by the session.

Scopes are defined and configured in the PBX and are bound to particular PBX users. Thus, a session has a user attribute, which defines the scope. It includes all users which are members of groups '''user''' is active member of. If '''user''' is not an active member of any group, the scope is the user itself.

====Integer Initialize(string user, string appl, bool v, bool v501, out int key)====

To access the current web services implementation, both '''v''' and '''v501''' must be present and set to '''true'''.
These 2 parameters actually convey the wsdl version used by the client. Different versions of the interface use different parameter sets for the Initialize call. Applications should always use the wsdl version current at the time of writing the application.

The method creates a session. The session will have the user '''user'''’s scope. The session handle is returned and is 0 for failure and positive for a valid session handle. '''appl''' specifies the name of the calling application and is used for administrative purposes. The output parameter '''key''' is a random number associated to the session. It may be used in subsequent '''Echo''' operations.

When a session is created, '''UserInfo''' events for all PBX registrations in the scope can be received by the '''Poll''' function. Initially, one '''UserInfo''' per registration within the session’s scope is received (the list is terminated by a '''UserInfo''' with empty '''cn''' and may require multiple '''Poll''' calls to retrieve). Subsequently, '''UserInfo''' events are received when a registrations state changes.

The underlying transport session (HTTP) must authenticate itself either as '''user''' (using the users long name and PBX password) or as the admin user (using the gateway administrator account name and password) to perform an '''Initialize''' and any session related function.

Note that the method to force the SOAP system you are using to authenticate to the PBX is entirely up to the system itself. Some systems even do not support authentication at all. If your SOAP implementation does not support digest authentication, make sure the gateway accepts basic authentication by setting the “''allow HTTP basic authentication''” in the “''General settings''”.

Note that although many HTTP connections may be used in a single session, at least one HTTP connection must remain open during the lifetime of the session. When the last connection disappears, the logical session is terminated after a short timeout. Some SOAP libraries may per default always close the HTTP connection and reconnect on subsequent SOAP calls, which will not work. The SOAP library should either be configured to keep at least one HTTP connection alive or, if this is not an option, the application should take care to always have a an active request pending (such as '''Poll''').

====Echo(integer session, integer key)====

Verifies a session. You need to supply the ''session'' identifier and ''key'' returned by a previous call to '''Initialize'''. Returns nonzero if successful.

====End(integer session)====

Terminates the session referenced by ''session''. No further events will be received.

====Integer Version(out string gkId, out string location, out string firmware, out string serial)====

Returns the version number of the WSDL file the PBX supports. The first released WSDL file had version number 500. The version described by this document has version number 501. Also delivers information about the connected PBX (in ''gkId'', ''location'', ''firmware'' and ''serial'').

====AnyInfo Poll(integer session)====

Returns pending events for the session referenced by ''session''. ''AnyInfo'' is a struct with four arrays as members: ''user'', ''call'', ''reg'' and ''info''. ''user'' is an array of type ''UserInfo'' and call is an array of type CallInfo. The other two arrays ''reg'' and ''info'' are currently not used.

After a successful '''Initialize()'' there will be a ''UserInfo'' event for each defined user in the system. This allows the application to synchronize on the state of all visible users. The list will be terminated by an ''UserInfo'' event for a user with an empty ''cn'' which normally cannot happen since a user entry must have a cn.

===User===

A user represents a configured object within the PBX (a “PBX user”). The PBX API provides the '''UserInitialize''' method to obtain a handle to the user.

====UserInfo====
The user’s properties are stored in a ''UserInfo'' structure, which has the following elements:

*'''boolean active'''

true if the user exists. The only case where active can be false is when a user is deleted. A single UserInfo event will be posted with active set to false then.

*'''integer state'''

1 if the user is registered, 0 otherwise.

*'''integer channel'''

number of current calls.

*'''integer alert'''

number of alerting calls

*'''string type'''

the type of the users device. Currently defined are “'''ep'''” (it is an endpoint), “'''gw'''” (it is a gateway, for example a trunk line), “'''waiting'''” (a call queue) or “'''broadcast'''” (a group). Others may be defined over time.

*'''string guid'''

the users GUID. This is a globally unique identifier for the user.

*'''string cn'''

the common name of the user. This is what the PBX’s LDAP server recognizes as the CN of this user. The user’s name in the PBX configuration applet.

*'''string e164'''

the extension number the user is registered with.

*'''string h323'''

the alias the user is registered with.

*'''string dn'''

the users display name.

*'''Group groups'''

An array of '''Group''' records (see below).

*'''Info info '''

An '''Info''' record describing various aspects of the user. The type of the information described in an individual '''Info''' record is determined by the value of its ''type'' member. Currently defined values for ''type'' are:

**loc

If the object described is not local to the PBX the '''UserInfo''' is sent from, the name of the location the object is homed in is given in this element. See '''LocationUrl''' to find out how to proceed further.

The users group memberships are stored in a '''Group''' record which has the following elements:

**'''string group'''

the name of the group the user is a member of

**'''integer state'''

'''true''' if the user is an active member of the group

====integer UserInitialize(integer session, string user, bool follow)====

Returns a handle to the named ''user'' (0 on failure). String <code>user</code> must be a Long Name(cn). Phone number(e164) is not supported. Use FindUser instead, to retrieve cn to specified e164 number.

Once a user handle is obtained with '''UserInitialize''', '''CallInfo''' events will be posted and retrieved via '''Poll''' for all calls related to the user. If ''follow'' is set to '''true''', '''CallInfo''' events will also be posted for calls which are transferred away from ''user''. Otherwise, such events will be posted only for the user handle which the call has been transferred to. Thus, without setting follow to true, an application will generally not be able to track calls after a transfer unless it has called '''UserInitialize''' for any PBX object a call may be transferred to and matches the new call on the transferred-to user via the '''conf''' information in the '''Info''' record of the new call (which will be identical to the '''conf''' information for the transferred call).

When ''follow'' ist set to '''true''', transferred calls will show up in the '''CallInfo''' records with a '''No''' element of type '''xfer''' that indicates the number the call has been transferred to.

Also, the user handle can be used to create and control calls on behalf of the user.

====void UserEnd(integer user)====

Frees the handle ''user'' obtained with '''UserInitialize'''. No events will be posted for this user anymore.

===Call===
A call represents one leg of an existing call in the PBX.

====CallInfo====
The calls attributes are stored in a '''CallInfo''' structure, which has the following elements:

*'''int user'''

the user handle the call belongs to

*'''int call'''
the call handle

*'''int reg'''

currently unused

*'''bool active'''

'''true''' if the call exists, '''false''' if not. The only case where ''active'' can be '''false''' is when a call is terminated. A single '''CallInfo''' event will be posted with ''active'' set to '''false''' then

*'''integer state'''

A calls state. A bit field made up as follows:
{|
|+
| Value
| Mask
| Meaning
|-
| 1
| 0xF
| setup
|-
| 2 || || setup-ack
|-
| 3 || || call-proc
|-
| 4 || || Alert
|-
| 5 || || Connect
|-
| 6 || || disconnect sent
|-
| 7 || || disconnect received
|-
| 0 || 0x80 || inbound call
|-
| 1 || 0x80 || outbound call
|-
| 0 || 0x100 || active call
|-
| 1 || 0x100 || call on hold
|}

Note that the PBX API is PBX-centric, not terminal centric. As such, it considers a call ''from'' the PBX ''to'' the terminal as ''outbound''.

*'''string msg'''
A textual representation of the signalling message causing this event. E.g. “'''x-setup'''”.

*'''No No'''

An array of '''No''' records (see below). This can include information about various peers related to the call itself. The type of the peer described in an individual '''No''' record is determined by the value of its '''type''' member. Currently defined values for '''type''' are:

**'''peer'''

The current remote end of the call (the local end is determined by the UserInfo identified through the user handle above)

**'''leg2'''

The last diverting user (if any)

**'''ct'''

The last user having transferred the call (if any)

*'''Info info'''

An '''Info''' record describing various aspects of the call. The type of the information described in an individual '''Info''' record is determined by the value of its ''type'' member. Currently defined values for ''type'' are:

**'''conf'''

A string holding the conference id (a GUID) of the conference the call is a leg of

====No Record====

Peer information is stored in a '''No''' record with the following elements:

*'''string type'''

the type of the peer described by the record

*'''string cn'''

the peer’s PBX’s objects common name (if any)

*'''string e164'''

the peer’s phone number

*'''string h323'''

the peer’s h323 alias

*'''string dn'''

the peer’s display name

====Info record====
Various information is stored in '''Info''' records with the following elements:

*'''string type'''

the type of the information described by the record

*'''string vals'''

a string value associated with this information (if any, the ''type'' of the element determines if an '''Info''' element has a string or an integer value)

*'''integer vali'''

an integer value associated with this information (if any)

Note that the call related functions do not return a meaningful value. This is because the operations success is reflected in the subsequent CallInfo events.

====integer UserCall(integer user, string cn, string e164, string h323, int reg, InfoArray info)====

Creates an outgoing call from the '''user''' (which is a handle obtained by a call to '''UserInitialize''') to the destination described by ''cn'', ''e164'' and ''h323''. Arguments ''reg'' and ''info'' are currently ignored. Returns a handle to the call (0 on failure).

Depending on the nature of the device the user is registered with, the device may actually place the call or the PBX may place a call and once it is accepted, it places another call to the destination.

====UserConnect(integer call)====
Connects an existing ''call''. This forces the device the user is registered with to accept the call. It may then go into hands-free mode. Incapable (i.e. non-innovaphone) devices may simply ignore this call.

====UserTransfer (int acall, integer bcall)====
''acall'' and ''bcall'' are both calls a single user currently has active. This method will connect ''acall'' with ''bcall'', leaving the user without both calls.

====bool UserRedirect(integer call, string cn, string e164, string h323, InfoArray info)====
Places a call to the destination described by ''cn'', ''e164'' and ''h323'' and connects ''call'' to this destination. Argument ''info'' is currently ignored.

====integer UserPickup(int user, string cn, integer call, string group, int reg, InfoArray info)====
Redirects a call such that it appears as a new call at ''user''. The call to be redirected can be specified by its ''call'' handle. Alternatively, calls can be picked up by a users ''cn'' or by a ''group'' name. If all parameters are null, an implicit pickup is done. The new call handle is returned. Arguments ''reg'' and ''info'' are currently ignored.

====UserClear(integer call, integer cause, InfoArray info)====
Disconnects the ''call'' providing ''cause'' as disconnect reason.

Cause is coded as a 7bit integer according to the table found in [[Reference:ISDN Cause Codes]].
Argument ''info'' is currently ignored.

====UserCtComplete(integer call, string e164, string h323)====

Sends a notification to the device ''call'' is active on that the remote peer has changed to ''e164'' and ''h323''. This resembles the notification a device may receive if its remote peer transfers the call to the new destination. The device may update its display and/or call data accordingly. This call is often used to force the devices (i.e. telephones) display to show application specific data.

====UserHold(integer call)====
Sets the call on hold. The device may or may not display the hold status. In any case, the media channel is disconnected until a UserRetrieve is called.

====UserRetrieve(integer call)====
Retrieves the ''call'' on hold. The device may or may not display the new status. In any case, the media channel is reconnected.

===Status Retrieval===

Instead of monitoring calls using the ''Poll'' mechanics, there are some functions to retrieve the current at a certain point in time.

====CallInfo[] Calls(integer session, string user)====
Returns an array of '''CallInfo''' records for the calls currently active at the registration defined by ''user''. Please note that this function may be called without having called '''UserInitialize ()''' before. Thus, the call handle information in the '''CallInfo''' records returned is meaningless.

====UserInfo[] FindUser(string v501, string cn, string h323, string e164, integer count, integer next)====
Returns an array of at most ''count'' '''UserInfo''' records for the users matching ''cn'', ''h323'' or ''e164''. Only one of ''cn'', ''h323'' and ''e164'' may be specified. The search string will be used as a starting point into the alphabetically sorted list of objects, that is, a search for “'''A'''” will yield entries starting with “'''A'''” but also – depending on ''count'' – the following entries. Neither search string may be empty. v501 must be set to a non-empty value.

To call '''FindUser''', no session is required, however, you need a valid HTTP authentication.

Be aware that large values for ''count'' may fail and even crash the PBX. If you need to retrieve the whole user list, you should be using 50 as ''count'', provide the last ''cn'' retrieved as new start cn and loop until ''''FindUser''' returns no more results, passing '''true''' as value for ''next'' for all but the first calls.

====string License(integer session, string name)====
This function is for internal use only.

====string LocationUrl(string user v501, string location)====
Returns a string with the HTTP URL for the PBX named location to which a SOAP session can be created. Typically, location is retrieved from the ''vals'' element of an '''Info''' record with ''type'' '''loc''' in an '''UserInfo''' record.

===Administration===
The SOAP interface can be used for administrational purposes also. This is done via the Admin call.

====string Admin(string xml)====

Sends the administrational command ''xml'' to the PBX. The command is executed and any result is returned.

This command allows you to query and modify the PBX object configuration (e.g. to query and set a users call forwarding). The scope and format of the commands valid for ''xml'' is beyond the scope of this document, however, there is a separate article on that (see the [[Reference:SOAP_API#Related_Articles|Related Articles]] below).

To call '''Admin''', no session is required. However, you must be authenticated as an admin user on the underlying HTTP layer.

==Typical design of a PBX SOAP Application==
A typical SOAP application has a thread that collects all PBX events using an infinite loop which calls '''Poll()''', scans the returned '''AnyInfo''' arrays and reacts accordingly. Depending on the type of application, there are 2 typical schemes

*the thread is either initialized with a sequence of calling Initialize() and then UserInitialize() on behalf of a (typically pre-configured) user (1st party scenario) or
*the thread is initialized via Initialize() and then, when Poll() returns UserInfo records later on, UserInitialize() is called once on behalf of any user made known by the UserInfo (3rd party scenario)

In any case, once initialized, the infinite loop of calls to '''Poll()''' will retrieve all relevant events from the PBX, i.e. there is no need to perform distinct calls to '''Poll()''' for different users.

Please note that '''Poll()''' is rather a misnomer, since it does not really poll the PBX but will hang as long as no events are to be delivered. It will not consume extensive CPU cycles thus. In fact, '''Poll()''' will return with an empty '''AnyInfo''' Array if no events are present after a while. This is because many SOAP client implementations consider a call to fail if it takes “long”, where “long” is defined by the client implementation.

When a call to the PBX fails, the PBX link is broken and any associated data structures should be destroyed and the initialization process should start over again. Most importantly, local user and call ids are no longer valid after a restart of a PBX. Please note that some SOAP development environments will transparently reconnect a broken link. To make sure a restart of the PBX is discovered by the application, use the '''Echo()''' call since it will change if the key is invalidated by a restart. Some server type applications will find it convenient to use a separate thread that simply loops with an '''Echo'''/'''Pause''' sequence.

Many applications both react on events returned by '''Poll()''' and on events created by a client or by a user interface. In such cases, make sure that a single SOAP link (depending on the development environment used) is not used for 2 concurrent SOAP calls, as most development systems do not support this. Rather create 2 or more links. We have seen this problem with C#, for example.

SOAP is based on http and thus uses http authentication. Many SOAP development environments will thus send any request unauthorized first and resend it with authorization only when the server has returned the “Unauthorized“ http error code. This obviously causes delays on the client and extensive CPU usage on the PBX. If possible, make sure to configure your SOAP client such that it will send each request authenticated in the first place (a mode sometimes known as “pre-authenticated”).

===Programming languages with no support for ''threads''===

Some programming languages do not have the concept of a "parallel thread". However, some of them nevertheless feature a concept of ''asynchronous operation''.

Visual Basic for example defines so-called ''events'', which are raised asynchronously, yet synchronized with main execution (see [[Howto:SOAP with VisualBasic.Net]] for an example). These can be handled then by user-defined functions.

C# introduces the conecpt of ''delegates'', that will be called asynchronously (see [[Howto:PBX SOAP Api C-sharp sample code]] for more details on using SOAP from C#).

==References==
Latest wsdl file refers to our firmware 10:
* [http://www.innovaphone.com/wsdl/pbx10_00.wsdl Version10-wsdl].
Please check out the [http://wiki.innovaphone.com/index.php?title=Reference10:Concept_SOAP_API corresponding wiki-article] herefore.

Applications based on this wsdl will work with V10 PBX firmware only.

Applications written to the previous pbx501.wsdl, pbx700.wsdl and pbx900.wsdl will continue to work with V10 firmware.

For your reference the old version files are still available:
* [http://www.innovaphone.com/wsdl/pbx501.wsdl Version5-wsdl]
* [http://www.innovaphone.com/wsdl/pbx700.wsdl Version7-wsdl]
* [http://www.innovaphone.com/wsdl/pbx900.wsdl Version9-wsdl]

==Known Problems==
Please read [[Howto:Authentication_in_the_SOAP_interface]] in case you have problems to authenticate SOAP access.

==System Requirements==
The PBX SOAP API requires a working PBX.

To work with the PBX API in this version, you must run at least version 5.01 software on your PBX. Also, you must run at least version 5 software on the phones.

==Installation==
There is no specific installation required, as the PBX API is integral part of the PBX (although licenses are required to operate the PBX).

==Configuration==
To prepare an PBX for PBX API testing
*setup a separate PBX
*install current firmware (at least 5.01)
*configure the PBX as usually
*add an user object called '''API''' , define a ''password'' for this object
*create a new group (e.g. called '''all users'''), by adding a group tag to '''API''', make it ''active''
*add a similar group tag to all other test users
*call '''Initialize()''' and use '''API''' as user and '''API''' and its ''password'' as http credentials

==Related Articles==
:[[Howto:Authentication in the SOAP interface]]
:[[Howto:Clear a call completely with SOAP using UserClear]]
:[[Howto:PBX SOAP Api C sample code]]
:[[Howto:SOAP Api VisualBasic.Net Sample Code]]
:[[Support:TAPI or other SOAP Application fails to function properly if PBX users have special characters in their long or short user name]]
:[[Howto:How to monitor configuration changes in the SOAP interface ]]
:[[Howto:SOAP with PHP5 ]]
:[[Howto:SOAP API Java Sample Code ]]
:[[Howto:Using the SOAP Admin Function]]

[http://wiki.innovaphone.com/index.php?search=soap Search for more articles about SOAP]

Howto:Using the SOAP Admin Function

2018-06-08T18:55:40Z

Franciscopaletta: /* show */

Howto:SOAP API Java Sample Code

2018-05-03T13:44:43Z

Franciscopaletta: /* The sample application */

{{FIXME|reason=TODO: work in progress }}

==Applies To==
This information applies to

* any innovaphone PBX platform
* Java Runtime Environment

innovaphone PBX web services can be used from Java Runtime Environment. Here is how



==More Information==
===Configuration===
Modify the global variables ''SOAPENDPOINTURL'', ''ADMSOAPUSER'', ''ADMSOAPUSERPWD'', ''SOAPUSER'' and ''CNUSER'' according to your specific system.

===Running Sample Code===
This code is a simple Java console application. It will run on your OS console terminal. As dependencies, you will need JDK to compile the code and JRE to execute it.

To '''compile''', save the code on file '''innoSOAP.java''' and provide that file as parameter to '''javac''' command.
*The below code was compiled on javac version 1.8.0 and run on java version 1.8.0 (It was not tested on other versions)
*You may get a warning regarding the function sun.misc.BASE64Encoder().encode() because it is deprecated. Nevertheless the code will run. You may remove that section of the code (used just for authentication on the PBX) but you will have to allow "public" access to /PBX0/user.soap on HTTP(security risk!!!).

====The sample application ====
This section will discuss the sample code. It is not a decent description of the PBX SOAP API. For this, see the related articles.

<code java>

import javax.xml.soap.*;
import org.w3c.dom.NodeList;

public class innoSOAP {
/*
The example below demonstrates the use of SOAP integration to innovaphone PBX.

Reference to innovaphone SOAP integration can be found on:
http://wiki.innovaphone.com/index.php?title=Reference:SOAP_API

INSTRUCTIONS:
Modifi the global variables below according to your specific system.

The program will perform the following tasks:
1 - Send a SOAP message with the instruction "Initialize" and grab the session ID.
2 - Referencing the session ID it will send a SOAP message with the instruction "UserInitialize" and grab the user ID.
3 - Loop on an SOAP instruction "Poll" to keep looking for information on the user CNUSER (refer to global variables below)
User information and Call information.
(The Poll call remains opened until information is provided or time out. In case of timeout PBX sends an emtpy response
and then another Poll call takes place)

Created by:
Francisco Paletta

Version: 0.2
*/

//innovaphone general information
private static final String MYNAMESPACE = "pbx";
private static final String MYNAMESPACEURI = "http://www.innovaphone.com/pbx";

//specific system information
private static final String SOAPACTION = "";
private static final String SOAPENDPOINTURL = "http://192.168.0.1/PBX0/user.soap";
private static final String ADMSOAPUSER = "admin"; //PBX admin user
private static final String ADMSOAPUSERPWD = "ip311"; //PBX admin password
private static final String SOAPUSER = "SOAP"; //SOAP user object in PBX with group access to other objects
private static final String CNUSER = "User 1"; //CN of user to perform Poll on

// Main function
public static void main(String args[]) {
callSoapWebService(SOAPENDPOINTURL, SOAPACTION);
}

//Prints all nodes on the nodelist
private static void nodeListPrint(NodeList list, String tab){
NodeList childList;
for (int i = 0; i < list.getLength(); i++) {
System.out.print(tab+String.valueOf(list.item(i).getNodeName()));
childList = list.item(i).getChildNodes();
if(childList.getLength() != 0) {
if(!childList.item(0).getNodeName().equals("#text")) {
System.out.println("");
nodeListPrint(childList, tab+" ");
}
else {
System.out.print(" -> ");
System.out.println(String.valueOf(childList.item(0).getTextContent()));
}
} else {
System.out.println("");
}
}
}

//Starts web connection and execute the SOAP calls
private static void callSoapWebService(String soapEndpointUrl, String soapAction) {
try {

String session="";
String user="";

// Create SOAP Connection
SOAPConnectionFactory soapConnectionFactory = SOAPConnectionFactory.newInstance();
SOAPConnection soapConnection = soapConnectionFactory.createConnection();

// Send SOAP Message to SOAP Server
SOAPMessage soapResponse = soapConnection.call(createSOAPRequest_Initialize(soapAction), soapEndpointUrl);
// Print the SOAP Response
System.out.println("Response SOAP Message:");
soapResponse.writeTo(System.out);
System.out.println("\n");

SOAPBody body = soapResponse.getSOAPBody();
NodeList returnList = body.getElementsByTagName("InitializeResponse");

System.out.println("Response Parsed:");
nodeListPrint(returnList,"");
System.out.println("");

for (int k = 0; k < returnList.getLength(); k++) {
NodeList innerResultList = returnList.item(k).getChildNodes();
for (int l = 0; l < innerResultList.getLength(); l++) {
if (innerResultList.item(l).getNodeName().equalsIgnoreCase("return")) {
session = String.valueOf(innerResultList.item(l).getTextContent().trim());
}
}
}

soapResponse = soapConnection.call(createSOAPRequest_UserInitialize(soapAction, session), soapEndpointUrl);

// Print the SOAP Response
System.out.println("Response SOAP Message:");
soapResponse.writeTo(System.out);
System.out.println("\n");

body = soapResponse.getSOAPBody();
returnList = body.getElementsByTagName("UserInitializeResponse");

System.out.println("Response Parsed:");
nodeListPrint(returnList,"");
System.out.println("");

for (int k = 0; k < returnList.getLength(); k++) {
NodeList innerResultList = returnList.item(k).getChildNodes();
for (int l = 0; l < innerResultList.getLength(); l++) {
if (innerResultList.item(l).getNodeName().equalsIgnoreCase("return")) {
user = String.valueOf(innerResultList.item(l).getTextContent().trim());
}
}
}

boolean returnValue = true;
while(returnValue){
soapResponse = soapConnection.call(createSOAPRequest_Poll(soapAction, session), soapEndpointUrl);
//The call for Poll remains opened until PBX sends a response. In case of timeout PBX sends an empty response.
//The loop will guarantee another Poll call is send to keep "channel" running.

// Print the SOAP Response
System.out.println("Response SOAP Message:");
soapResponse.writeTo(System.out);
System.out.println("\n");

body = soapResponse.getSOAPBody();
returnList = body.getElementsByTagName("PollResponse");
System.out.println("Response Parsed:");
nodeListPrint(returnList,"");
System.out.println("");
}

soapConnection.close();
} catch (Exception e) {
System.err.println("\nError occurred while sending SOAP Request to Server!\nMake sure you have the correct endpoint URL and SOAPAction!\n");
e.printStackTrace();
}
}

//Creates a SOAPmessage with the "Initialize" instruction
private static SOAPMessage createSOAPRequest_Initialize(String soapAction) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("Initialize");
SOAPElement soapBodyElem1 = soapBodyElem.addChildElement("user");
soapBodyElem1.addTextNode(SOAPUSER);
SOAPElement soapBodyElem2 = soapBodyElem.addChildElement("appl");
soapBodyElem2.addTextNode("JAVA SOAP CALL");
SOAPElement soapBodyElem3 = soapBodyElem.addChildElement("bool");
soapBodyElem3.addTextNode("true");
SOAPElement soapBodyElem4 = soapBodyElem.addChildElement("v501");
soapBodyElem4.addTextNode("true");
SOAPElement soapBodyElem5 = soapBodyElem.addChildElement("v700");
soapBodyElem5.addTextNode("true");
SOAPElement soapBodyElem6 = soapBodyElem.addChildElement("v800");
soapBodyElem6.addTextNode("true");
SOAPElement soapBodyElem7 = soapBodyElem.addChildElement("vx1000");
soapBodyElem7.addTextNode("true");

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

//Creates a SOAPmessage with the "UserInitialize" instruction
private static SOAPMessage createSOAPRequest_UserInitialize(String soapAction, String session) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("UserInitialize");
SOAPElement soapBodyElem1 = soapBodyElem.addChildElement("session");
soapBodyElem1.addTextNode(session);
SOAPElement soapBodyElem2 = soapBodyElem.addChildElement("user");
soapBodyElem2.addTextNode(CNUSER);
SOAPElement soapBodyElem3 = soapBodyElem.addChildElement("follow");
soapBodyElem3.addTextNode("true");

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

//Creates a SOAPmessage with the "Poll" instruction
private static SOAPMessage createSOAPRequest_Poll(String soapAction, String session) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("Poll");
SOAPElement soapBodyElem1 = soapBodyElem.addChildElement("session");
soapBodyElem1.addTextNode(session);

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

}

</code>

== Known Problems ==

==Related Articles==
[[Reference:SOAP API]]

[[Howto:PBX SOAP Api C-sharp sample code ]]

[[Howto:SOAP with PHP5]]



[[Category:Sample|{{PAGENAME}}]]

Howto:SOAP API Java Sample Code

2018-05-03T13:43:34Z

Franciscopaletta: /* The sample application */

{{FIXME|reason=TODO: work in progress }}

==Applies To==
This information applies to

* any innovaphone PBX platform
* Java Runtime Environment

innovaphone PBX web services can be used from Java Runtime Environment. Here is how



==More Information==
===Configuration===
Modify the global variables ''SOAPENDPOINTURL'', ''ADMSOAPUSER'', ''ADMSOAPUSERPWD'', ''SOAPUSER'' and ''CNUSER'' according to your specific system.

===Running Sample Code===
This code is a simple Java console application. It will run on your OS console terminal. As dependencies, you will need JDK to compile the code and JRE to execute it.

To '''compile''', save the code on file '''innoSOAP.java''' and provide that file as parameter to '''javac''' command.
*The below code was compiled on javac version 1.8.0 and run on java version 1.8.0 (It was not tested on other versions)
*You may get a warning regarding the function sun.misc.BASE64Encoder().encode() because it is deprecated. Nevertheless the code will run. You may remove that section of the code (used just for authentication on the PBX) but you will have to allow "public" access to /PBX0/user.soap on HTTP(security risk!!!).

====The sample application ====
This section will discuss the sample code. It is not a decent description of the PBX SOAP API. For this, see the related articles.

<code java>

import javax.xml.soap.*;
import org.w3c.dom.NodeList;

public class innoSOAP {
/*
The example below demonstrates the use of SOAP integration to innovaphone PBX.

Reference to innovaphone SOAP integration can be found on:
http://wiki.innovaphone.com/index.php?title=Reference:SOAP_API

INSTRUCTIONS:
Modifi the global variables below according to your specific system.

The program will perform the following tasks:
1 - Send a SOAP message with the instruction "Initialize" and grab the session ID.
2 - Referencing the session ID it will send a SOAP message with the instruction "UserInitialize" and grab the user ID.
3 - Loop on an SOAP instruction "Poll" to keep looking for information on the user CNUSER (refer to global variables below)
User information and Call information.
(The Poll call remains opened until information is provided or time out. In case of timeout PBX sends an emtpy response
and then another Poll call takes place)

Created by:
Francisco Paletta

Version: 0.2
*/

//innovaphone general information
private static final String MYNAMESPACE = "pbx";
private static final String MYNAMESPACEURI = "http://www.innovaphone.com/pbx";

//specific system information
private static final String SOAPACTION = "";
private static final String SOAPENDPOINTURL = "http://pbx-pure.eaibrasil.com.br/PBX0/user.soap";
private static final String ADMSOAPUSER = "soapadm"; //PBX admin user
private static final String ADMSOAPUSERPWD = "A2Er@h#dx"; //PBX admin password
private static final String SOAPUSER = "SOAP"; //SOAP user object in PBX with group access to other objects
private static final String CNUSER = "Francisco Paletta"; //CN of user to perform Poll on

// Main function
public static void main(String args[]) {
callSoapWebService(SOAPENDPOINTURL, SOAPACTION);
}

//Prints all nodes on the nodelist
private static void nodeListPrint(NodeList list, String tab){
NodeList childList;
for (int i = 0; i < list.getLength(); i++) {
System.out.print(tab+String.valueOf(list.item(i).getNodeName()));
childList = list.item(i).getChildNodes();
if(childList.getLength() != 0) {
if(!childList.item(0).getNodeName().equals("#text")) {
System.out.println("");
nodeListPrint(childList, tab+" ");
}
else {
System.out.print(" -> ");
System.out.println(String.valueOf(childList.item(0).getTextContent()));
}
} else {
System.out.println("");
}
}
}

//Starts web connection and execute the SOAP calls
private static void callSoapWebService(String soapEndpointUrl, String soapAction) {
try {

String session="";
String user="";

// Create SOAP Connection
SOAPConnectionFactory soapConnectionFactory = SOAPConnectionFactory.newInstance();
SOAPConnection soapConnection = soapConnectionFactory.createConnection();

// Send SOAP Message to SOAP Server
SOAPMessage soapResponse = soapConnection.call(createSOAPRequest_Initialize(soapAction), soapEndpointUrl);
// Print the SOAP Response
System.out.println("Response SOAP Message:");
soapResponse.writeTo(System.out);
System.out.println("\n");

SOAPBody body = soapResponse.getSOAPBody();
NodeList returnList = body.getElementsByTagName("InitializeResponse");

System.out.println("Response Parsed:");
nodeListPrint(returnList,"");
System.out.println("");

for (int k = 0; k < returnList.getLength(); k++) {
NodeList innerResultList = returnList.item(k).getChildNodes();
for (int l = 0; l < innerResultList.getLength(); l++) {
if (innerResultList.item(l).getNodeName().equalsIgnoreCase("return")) {
session = String.valueOf(innerResultList.item(l).getTextContent().trim());
}
}
}

soapResponse = soapConnection.call(createSOAPRequest_UserInitialize(soapAction, session), soapEndpointUrl);

// Print the SOAP Response
System.out.println("Response SOAP Message:");
soapResponse.writeTo(System.out);
System.out.println("\n");

body = soapResponse.getSOAPBody();
returnList = body.getElementsByTagName("UserInitializeResponse");

System.out.println("Response Parsed:");
nodeListPrint(returnList,"");
System.out.println("");

for (int k = 0; k < returnList.getLength(); k++) {
NodeList innerResultList = returnList.item(k).getChildNodes();
for (int l = 0; l < innerResultList.getLength(); l++) {
if (innerResultList.item(l).getNodeName().equalsIgnoreCase("return")) {
user = String.valueOf(innerResultList.item(l).getTextContent().trim());
}
}
}

boolean returnValue = true;
while(returnValue){
soapResponse = soapConnection.call(createSOAPRequest_Poll(soapAction, session), soapEndpointUrl);
//The call for Poll remains opened until PBX sends a response. In case of timeout PBX sends an empty response.
//The loop will guarantee another Poll call is send to keep "channel" running.

// Print the SOAP Response
System.out.println("Response SOAP Message:");
soapResponse.writeTo(System.out);
System.out.println("\n");

body = soapResponse.getSOAPBody();
returnList = body.getElementsByTagName("PollResponse");
System.out.println("Response Parsed:");
nodeListPrint(returnList,"");
System.out.println("");
}

soapConnection.close();
} catch (Exception e) {
System.err.println("\nError occurred while sending SOAP Request to Server!\nMake sure you have the correct endpoint URL and SOAPAction!\n");
e.printStackTrace();
}
}

//Creates a SOAPmessage with the "Initialize" instruction
private static SOAPMessage createSOAPRequest_Initialize(String soapAction) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("Initialize");
SOAPElement soapBodyElem1 = soapBodyElem.addChildElement("user");
soapBodyElem1.addTextNode(SOAPUSER);
SOAPElement soapBodyElem2 = soapBodyElem.addChildElement("appl");
soapBodyElem2.addTextNode("JAVA SOAP CALL");
SOAPElement soapBodyElem3 = soapBodyElem.addChildElement("bool");
soapBodyElem3.addTextNode("true");
SOAPElement soapBodyElem4 = soapBodyElem.addChildElement("v501");
soapBodyElem4.addTextNode("true");
SOAPElement soapBodyElem5 = soapBodyElem.addChildElement("v700");
soapBodyElem5.addTextNode("true");
SOAPElement soapBodyElem6 = soapBodyElem.addChildElement("v800");
soapBodyElem6.addTextNode("true");
SOAPElement soapBodyElem7 = soapBodyElem.addChildElement("vx1000");
soapBodyElem7.addTextNode("true");

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

//Creates a SOAPmessage with the "UserInitialize" instruction
private static SOAPMessage createSOAPRequest_UserInitialize(String soapAction, String session) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("UserInitialize");
SOAPElement soapBodyElem1 = soapBodyElem.addChildElement("session");
soapBodyElem1.addTextNode(session);
SOAPElement soapBodyElem2 = soapBodyElem.addChildElement("user");
soapBodyElem2.addTextNode(CNUSER);
SOAPElement soapBodyElem3 = soapBodyElem.addChildElement("follow");
soapBodyElem3.addTextNode("true");

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

//Creates a SOAPmessage with the "Poll" instruction
private static SOAPMessage createSOAPRequest_Poll(String soapAction, String session) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("Poll");
SOAPElement soapBodyElem1 = soapBodyElem.addChildElement("session");
soapBodyElem1.addTextNode(session);

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

}

</code>

== Known Problems ==

==Related Articles==
[[Reference:SOAP API]]

[[Howto:PBX SOAP Api C-sharp sample code ]]

[[Howto:SOAP with PHP5]]



[[Category:Sample|{{PAGENAME}}]]

Howto:SOAP API Java Sample Code

2018-05-03T12:04:04Z

Franciscopaletta: /* Running Sample Code */

{{FIXME|reason=TODO: work in progress }}

==Applies To==
This information applies to

* any innovaphone PBX platform
* Java Runtime Environment

innovaphone PBX web services can be used from Java Runtime Environment. Here is how



==More Information==
===Configuration===
Modify the global variables ''SOAPENDPOINTURL'', ''ADMSOAPUSER'', ''ADMSOAPUSERPWD'', ''SOAPUSER'' and ''CNUSER'' according to your specific system.

===Running Sample Code===
This code is a simple Java console application. It will run on your OS console terminal. As dependencies, you will need JDK to compile the code and JRE to execute it.

To '''compile''', save the code on file '''innoSOAP.java''' and provide that file as parameter to '''javac''' command.
*The below code was compiled on javac version 1.8.0 and run on java version 1.8.0 (It was not tested on other versions)
*You may get a warning regarding the function sun.misc.BASE64Encoder().encode() because it is deprecated. Nevertheless the code will run. You may remove that section of the code (used just for authentication on the PBX) but you will have to allow "public" access to /PBX0/user.soap on HTTP(security risk!!!).

====The sample application ====
This section will discuss the sample code. It is not a decent description of the PBX SOAP API. For this, see the related articles.

<code java>

import javax.xml.soap.*;
import org.w3c.dom.NodeList;

public class innoSOAP {
/*
The example below demonstrates the use of SOAP integration to innovaphone PBX.

Reference to innovaphone SOAP integration can be found on:
http://wiki.innovaphone.com/index.php?title=Reference:SOAP_API

INSTRUCTIONS:
Modify the global variables below according to your specific system.

The program will perform the following tasks:
1 - Send a SOAP message with the instruction "Initialize" and grab the session ID.
2 - Referencing the session ID it will send a SOAP message with the instruction "UserInitialize" and grab the user ID.
3 - Loop on an SOAP instruction "Poll" to keep looking for information on the user CNUSER (refer to global variables below)
User information and Call information.
(The Poll call remains opened until information is provided or time out. In case of timeout PBX sends an emtpy response
and then another Poll call takes place)

Created by:
Francisco Paletta

Version: 0.1
*/

//innovaphone general information
private static final String MYNAMESPACE = "pbx";
private static final String MYNAMESPACEURI = "http://www.innovaphone.com/pbx";

//specific system information
private static final String SOAPACTION = "";
private static final String SOAPENDPOINTURL = "http://192.168.0.1/PBX0/user.soap";
private static final String ADMSOAPUSER = "admin"; //PBX admin user
private static final String ADMSOAPUSERPWD = "ip311"; //PBX admin password
private static final String SOAPUSER = "SOAP"; //SOAP user object in PBX with group access to other objects
private static final String CNUSER = "User 1"; //CN of user to perform Poll on

// Main function
public static void main(String args[]) {
callSoapWebService(SOAPENDPOINTURL, SOAPACTION);
}

//Prints all nodes on the nodelist
private static void nodeListPrint(NodeList list, String tab){
NodeList childList;
for (int i = 0; i < list.getLength(); i++) {
if(!list.item(i).getNodeName().equals("#text")) {
System.out.println("");
System.out.print(tab+String.valueOf(list.item(i).getNodeName()));
}
childList = list.item(i).getChildNodes();
if(childList.getLength() == 0) {
System.out.print(" -> ");
System.out.print(String.valueOf(list.item(i).getTextContent()));
} else {
nodeListPrint(childList, tab+" ");
}
}
}

//Starts web connection and execute the SOAP calls
private static void callSoapWebService(String soapEndpointUrl, String soapAction) {
try {

String session="";
String user="";

// Create SOAP Connection
SOAPConnectionFactory soapConnectionFactory = SOAPConnectionFactory.newInstance();
SOAPConnection soapConnection = soapConnectionFactory.createConnection();

// Send SOAP Message to SOAP Server
SOAPMessage soapResponse = soapConnection.call(createSOAPRequest_Initialize(soapAction), soapEndpointUrl);
// Print the SOAP Response
System.out.println("Response SOAP Message:");
soapResponse.writeTo(System.out);
System.out.println("\n");

SOAPBody body = soapResponse.getSOAPBody();
NodeList returnList = body.getElementsByTagName("InitializeResponse");

System.out.print("Response Parsed:");
nodeListPrint(returnList,"");
System.out.println("\n");

for (int k = 0; k < returnList.getLength(); k++) {
NodeList innerResultList = returnList.item(k).getChildNodes();
for (int l = 0; l < innerResultList.getLength(); l++) {
if (innerResultList.item(l).getNodeName().equalsIgnoreCase("return")) {
session = String.valueOf(innerResultList.item(l).getTextContent().trim());
}
}
}

soapResponse = soapConnection.call(createSOAPRequest_UserInitialize(soapAction, session), soapEndpointUrl);

// Print the SOAP Response
System.out.println("Response SOAP Message:");
soapResponse.writeTo(System.out);
System.out.println("\n");

body = soapResponse.getSOAPBody();
returnList = body.getElementsByTagName("UserInitializeResponse");

System.out.print("Response Parsed:");
nodeListPrint(returnList,"");
System.out.println("\n");

for (int k = 0; k < returnList.getLength(); k++) {
NodeList innerResultList = returnList.item(k).getChildNodes();
for (int l = 0; l < innerResultList.getLength(); l++) {
if (innerResultList.item(l).getNodeName().equalsIgnoreCase("return")) {
user = String.valueOf(innerResultList.item(l).getTextContent().trim());
}
}
}

boolean returnValue = true;
while(returnValue){
soapResponse = soapConnection.call(createSOAPRequest_Poll(soapAction, session), soapEndpointUrl);
//The call for Poll remains opened until PBX sends a response. In case of timeout PBX sends an empty response.
//The loop will guarantee another Poll call is send to keep "channel" running.

// Print the SOAP Response
System.out.println("Response SOAP Message:");
soapResponse.writeTo(System.out);
System.out.println("\n");

body = soapResponse.getSOAPBody();
returnList = body.getElementsByTagName("PollResponse");
System.out.print("Response Parsed:");
nodeListPrint(returnList,"");
System.out.println("\n");
}

soapConnection.close();
} catch (Exception e) {
System.err.println("\nError occurred while sending SOAP Request to Server!\nMake sure you have the correct endpoint URL and SOAPAction!\n");
e.printStackTrace();
}
}

//Creates a SOAPmessage with the "Initialize" instruction
private static SOAPMessage createSOAPRequest_Initialize(String soapAction) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("Initialize");
SOAPElement soapBodyElem1 = soapBodyElem.addChildElement("user");
soapBodyElem1.addTextNode(SOAPUSER);
SOAPElement soapBodyElem2 = soapBodyElem.addChildElement("appl");
soapBodyElem2.addTextNode("JAVA SOAP CALL");
SOAPElement soapBodyElem3 = soapBodyElem.addChildElement("bool");
soapBodyElem3.addTextNode("true");
SOAPElement soapBodyElem4 = soapBodyElem.addChildElement("v501");
soapBodyElem4.addTextNode("true");
SOAPElement soapBodyElem5 = soapBodyElem.addChildElement("v700");
soapBodyElem5.addTextNode("true");
SOAPElement soapBodyElem6 = soapBodyElem.addChildElement("v800");
soapBodyElem6.addTextNode("true");
SOAPElement soapBodyElem7 = soapBodyElem.addChildElement("vx1000");
soapBodyElem7.addTextNode("true");

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

//Creates a SOAPmessage with the "UserInitialize" instruction
private static SOAPMessage createSOAPRequest_UserInitialize(String soapAction, String session) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("UserInitialize");
SOAPElement soapBodyElem1 = soapBodyElem.addChildElement("session");
soapBodyElem1.addTextNode(session);
SOAPElement soapBodyElem2 = soapBodyElem.addChildElement("user");
soapBodyElem2.addTextNode(CNUSER);
SOAPElement soapBodyElem3 = soapBodyElem.addChildElement("follow");
soapBodyElem3.addTextNode("true");

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

//Creates a SOAPmessage with the "Poll" instruction
private static SOAPMessage createSOAPRequest_Poll(String soapAction, String session) throws Exception {
MessageFactory messageFactory = MessageFactory.newInstance();
SOAPMessage soapMessage = messageFactory.createMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();

// SOAP Envelope
SOAPEnvelope envelope = soapPart.getEnvelope();
envelope.addNamespaceDeclaration(MYNAMESPACE, MYNAMESPACEURI);

// SOAP Body
SOAPBody soapBody = envelope.getBody();
SOAPElement soapBodyElem = soapBody.addChildElement("Poll");
SOAPElement soapBodyElem1 = soapBodyElem.addChildElement("session");
soapBodyElem1.addTextNode(session);

MimeHeaders headers = soapMessage.getMimeHeaders();
headers.addHeader("SOAPAction", soapAction);

String authorization = new sun.misc.BASE64Encoder().encode((ADMSOAPUSER+":"+ADMSOAPUSERPWD).getBytes());
headers.addHeader("Authorization", "Basic " + authorization);

soapMessage.saveChanges();

/* Print the request message, just for debugging purposes */
System.out.println("Request SOAP Message:");
soapMessage.writeTo(System.out);
System.out.println("\n");

return soapMessage;
}

}

</code>

== Known Problems ==

==Related Articles==
[[Reference:SOAP API]]

[[Howto:PBX SOAP Api C-sharp sample code ]]

[[Howto:SOAP with PHP5]]



[[Category:Sample|{{PAGENAME}}]]