Reference:SOAP API

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.

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 [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.

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. At this time, we have worked with Microsoft’s .NET environment. To use the sample applications provided with the beta kit, you need to install the .NET runtime. To modify and compile the sample applications, you will need the Visual.NET tools.

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 .

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. This [wsdl file] defines the PBX web services described in this document.

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.

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 applet 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 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. 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). 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).

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.

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. Next currently is ignored. v501 must be set to a non-empty value.

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

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. The scope and format of the commands valid for xml is beyond the scope of this document.

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

References

The wsdl definition is available at http://www.innovaphone.com/wsdl/pbx501.wsdl.

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 IP200.

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 version 5.01 firmware
• 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 the password as http credentials