innovaphone®’s PBX web services (a.k.a SOAP API) will be enhanced in version 10. As a result, a new wsdl file version pbx10_00.wsdl is published in the innovaphone web services directory http://www.innovaphone.com/wsdl.
Starting with firmware version 9, the wsdl file versions implemented by the firmware (down to 9.00)
can be read directly from the box, e.g. using the http://xx.xx.xx.xx/pbx10_00.wsdl or
http://xx.xx.xx.xx/pbx900.wsdl URL.
Applications based on this wsdl will work with V10 PBX firmware only. Applications written to the previous pbx501.wsdl and pbx700.wsdl, pbx800.wsdl and pbx900.wsdl will continue to work with V10 firmware.
For an overview of the basic architecture, see the corresponding chapter in the pbx501.wsdl related article.
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. This [wsdl file] defines the PBX web services described in this document.
NB: while you can access and retrieve the WSDL file through this URL on runtime of your application, we'd rather recommend to install a local copy with your application and use this on runtime. This way, your application will be immune against failures of www.innovaphone.com.
There is also an [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.
The SOAP service URI is /PBX0/user.soap for the standard PBX and /PBX-id/user.soap
for a dynamic PBX (where id corresponds to the Id field in the
Reference10:PBX/Dyn-PBXs
configuration dialog). SOAP is accessible via plain HTTP or HTTPS, so valid URLs might be
http://172.16.0.1/PBX0/user.soap or
https://172.16.0.1/PBX0-mydynpbxid/user.soap.
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.
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.
To access the current web services implementation, v, v501, v700, v800 and vx10000 must be present and set to true. These 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 (user is the Long Name of a PBX user). 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 if you use a PBX user account, the user needs to have at least Group/Call Forwards rights.
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).
Verifies a session. You need to supply the session identifier and key returned by a previous call to Initialize. Returns nonzero if successful.
Terminates the session referenced by session. No further events will be received.
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).
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 and visible 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.
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.
The user’s properties are stored in a UserInfo structure, which has the following elements:
true if the user exists. The only case where active can be false is when a user is moved out of the session context. This may happen if the users group assignment is changed or the user is deleted. A single UserInfo event will be posted with active set to false then.
1 if the user is registered, 0 otherwise.
number of current calls.
number of alerting calls
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.
the users GUID. This is a globally unique identifier for the user.
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.
the extension number the user is registered with.
the alias the user is registered with.
the users display name.
the PBX domain if the Gatekeeper ID is used as domain
If true, the h323 name shall be used as primary email address when sending emails to this user.
email addresses of the user. If 'h323email' is not set, the first address in this list shall be used as primary email address when sending emails to this user.
An array of Group records (see below).
An array of Presence records (see below).
If set to true indicates that the config of the user has changed
The type of the user object
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 node of the object.
The object nodes node number (prefix).
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:
The users group memberships are stored in a Group record which has the following elements:
The users presence status is stored in a Presence record which has the following elements:
Returns a handle to the named user (0 on failure). String user
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 xfer 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 xfer is 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.
When disc is set to true, calls to phones of the monitored user are cleared only after the user hangs up the phone. This way it can be avoided that the SOAP application assumes the phone is free but is still off-hook. This only works with innovaphone H.323 endpoints since the Disconnect message used to do this is not defined in the SIP standard.
When a hw argument is provided only the device identified by this is monitored. Please note that a valid handle will be returned even if there is no matching device for user.
Also, the user handle can be used to create and control calls on behalf of the user.
Frees the handle user obtained with UserInitialize. No events will be posted for this user anymore.
Sets the presence of a PBX user.
You can use guid or h323 to identify the user! If no guid is known, use *
as guid value.
If the setting of the presence was ok, the method returns 1. Otherwise 0.
For each User object multiple devices can be configured within the PBX. A device reprersents the physical endpoint used for calls (e.g. phones). Any registration to the PBX is associated to a configured device by the name/number used for the registration. Even thou it is possible that one configured device in the PBX accepts multiple registrations, it is recommened to configure the PBX in a way that there is one registration to a device. This way an application can control which physical endpoint is used for a call.
This function returns an array of devices configured for a user identified by its cn (long name). The cfg flag in UserInfo is set when this information is changed. The structure 'Device' contains the following members:
| hw | The Hardware Id used to identify the device. This string is used to associate any calls to devices. |
| text | A text configured as a description of the device. It can be used to be presented to the user for the user to select a device. |
A call represents one leg of an existing call in the PBX.
The calls attributes are stored in a CallInfo structure, which has the following elements:
the user handle the call belongs to
the call handle
currently unused
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
A calls state. A bit field made up as follows:
| Value | Mask | Meaning |
| 1 | 0xF | setup |
| 2 | 0xF | setup-ack |
| 3 | 0xF | call-proc |
| 4 | 0xF | Alert |
| 5 | 0xF | Connect |
| 6 | 0xF | disconnect sent |
| 7 | 0xF | disconnect received |
| 8 | 0xF | parked |
| 0 | 0x80 | inbound call (*) |
| 128 | 0x80 | outbound call (*) |
| 0 | 0x100 | active call |
| 256 | 0x100 | call on hold |
| 0 | 0x200 | active call |
| 512 | 0x200 | active call put on hold by peer |
(*) 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.
A textual representation of the signalling message causing this event. E.g. “x-setup”.
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:
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:
A Boolean will send a CallInfo event when it's status changes. From the indicated number, you can derive the status as follows:
00 - Auto-Off 01 - Auto-On 10 - Manual-Off 11 - Manual-On
Peer information is stored in a No record with the following elements:
the type of the peer described by the record
the peer’s PBX’s objects common name (if any)
the peer’s phone number
the peer’s h323 alias
the peer’s display name
Various information is stored in Info records with the following elements:
the type of the information described by the record
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)
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.
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. The argument srce164 may be used to override the calling party number (note that this overrides the callers extension, not the full calling party number). Arguments reg and info are currently ignored. The argument rc is usually 0, unless special behavior is required by using other Remote Control Facilities. Returns a handle to the call (0 on failure).
The called number (e164) is interpreted in the context of the user object the call is placed for (user).
From V8HF3 on, if the srce164 argument of UserCall starts with 'r' or 'R', the call is sent with CLIR (calling line identification restricted).
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.
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.
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.
This function establishes a media connection between two parties currently active in a call independent of the signalling connection. acall and bcall are both active (connected) calls. If user is true, the user sides of the calls are connected together, if peer is set to true the peer sides of the calls are connected together. If neither user nor peer is set the calls are connected to their respective signalling peers.
Places a call to the destination described by cn, e164 and h323 and connects call to this destination. Argument info is currently ignored.
Any call forwarding configured for the destination will be ignored. See UserReroute() below.
Performs a rerouting of the call. Call forwardings set for the destination will be obeyed.
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.
Disconnects the call providing cause as disconnect reason. For example the cause code 26 non-selected user clearing could be used to disconnect the call immediately on local phone, so no disconnect tone is played.
Cause is coded as a 7bit integer according to the table found in Reference:ISDN Cause Codes. Argument info is currently ignored.
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.
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.
In V8 hotfix23 an additional parameter remote was added. If set to true, remote will force to play MOH only to remote user (who is being held), set to false maintains the default behaviour (MOH played on remote user and a dialing tone to local user (depending on the pbx firmware, versions prior to v11r2 will play music on hold)). To use this parameter the recent WSDL 8.00 file must be retrieved.
Retrieves the call on hold. The device may or may not display the new status. In any case, the media channel is reconnected.
Parks the call at the PBX object cn and local user on postion position. A position of -1 means any position is allowed. The return value is the handle of the new call.
To unpark calls, use the returned call handle with the UserPickup() function.
The cn argument can be used to identify another object, where the call shall be parked to.
Sends DTMF digits on behalf of the user. If recv is set to true the DTMF is sent to the local user.
Sends User-User_information on behalf of the user. If recv is set to true the uui is sent to the local user.
Sends INFO message on behalf of the user. If recv is set to true the INFO message is sent to the local user. This function can be used to send overlap dialing information.
Sends remote control facility to an innovaphone IP phone. It will be ignored by 3rd-party endpoints.
A remote control facility can be sent to an innovaphone IP phone to activate additional call handling on the device.
The current set of remote control facility function codes actually depends on the firmware used on the telephone, not the WSDL version used for SOAP. The current set is documented in Reference:Remote Control Facility.
This function can be used for example to establish a three-party conference on an innovaphone IP phone. For this use the function UserRc on an active call using the rc value 4, while a second call is on hold. See also the rc argument to UserCall().
Sends an message from the user (which is a handle obtained by a call to UserInitialize) to the destination described by e164 and h323. The parameters src_e164 and src_h323 may be used to override the calling party's information, in order to present a different callback information to the recipient of the message. Returns a handle to the call (0 on failure), which can be used to track the delivery of the message. A event of type 'msg-sent' indicates the delivery of the message.
Instead of monitoring calls using the Poll mechanics, there are some functions to retrieve the current at a certain point in time.
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.
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, except that e164 and cn may be specified. In this case the number in e164 is interpreted in the Node of the user specified with cn. 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, v700, v800 and vx1000 must be set to a non-empty value. In case cn is set to the empty value, FindUser returns results starting from the first object in the PBX.
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.
If the parameter nohide is true, all objects regardless if marked as Hide from LDAP or not are returned by the FindUser function.
This function checks if a destination can be reached from a given user by either a given number or a given name. user is the user handle from which PBX user the searching is started through all PBX nodes up and down. e164 is the number, h323 is a name.
The function returns true, if the number or name is incomplete, otherwise false. If a destination is found, a UserInfo user is delivered.
No session is required to call UserFindDestination, however, you need a valid HTTP authentication.
This function is for internal use only.
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.
location needs to be specified as the h323 attributes value of the PBX node UserInfo data you are interested in.
If tls is set to true, a HTTPS URL is returned.
Converts a given number num into a number diallable from the location of a specific user. Useful in inter-node scenarios where a destination node number and -extension are known, but the required escape prefix digits are unknown.
The SOAP interface can be used for administrational purposes also. This is done via the Admin call. All kinds of PBX objects can be created, read or modified.
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 .
To call Admin, no session is required. However, you must be authenticated as an admin user on the underlying HTTP layer.
Howto:Using the SOAP Admin Function
Please refer to the pbx501.wsdl article for a discussion of the typical design of a SOAP application.
Applications based on this wsdl will work with V10 PBX firmware (and up) 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:
Please read Howto:Authentication in the SOAP interface in case you have problems to authenticate SOAP access.
The PBX SOAP API requires a working PBX.
To work with the PBX API in this version, you must run at least version 7.00 software on your PBX. Also, you must run at least version 5 software on the phones.
There is no specific installation required, as the PBX API is integral part of the PBX (although licenses are required to operate the PBX).
To prepare an PBX for PBX API testing
We have reports that the PBX wsdl is incompatible to some of the contemporary SOAP platforms available in the market. Most notably, Silverlight and Java seem to be affected. These problems are fixed in the v11 implementation of the PBX SOAP interface pbx11_00.wsdl (available at www.innovaphone.com/wsdl/pbx11_00.wsdl ).
Note: This wdsl file is not available directly from the PBX
(e.g. at http://xx.xx.xx.xx/pbx11_00.wsdl)
However, we have had indications that for Java, solutions are possible based on Apache Axis 1.4, Netbeans 6.8 or JAX-RPC.
The PBX does not expect the SOAP client to disconnect the session right after a UserCall. If this is the case (e.g. in a script which merely creates a call on behalf of a user and then terminates), it might happen that the outgoing call from the device will not be created correctly (a matter of timing). In this case, just wait for one second.
Search for articles about SOAP