innovaphone wiki - User contributions [en]

Courseware:IT Plus Overview

2026-05-19T08:29:33Z

Ckl:

''innovaphone Plus'' is a series of courses, each covering advanced aspects of the configuration of innovaphone devices in separate topics. Each topic can be worked through on individually or in any order. Further topics will be added over time. Each topic is based on the latest firmware at the time of creation. All topics based on the same firmware version (e.g. 14r2) are included in the same course of the series.

Access to ''innovaphone Plus'' requires a valid innovaphone ''Plus'' corporate subscription. See [https://www.innovaphone.com/en/partner/training/innovaphone-plus-training.html innovaphone Plus Training] for details.

The rest of this article gives you an overview of the topics covered and in which course they can be found.
__NOEDITSECTION__
{{#invoke-url: https://class.innovaphone.com/moodle2/itplus-overview.php?wiki=true}}

Reference13r2:Concept Talking to the v13 Application Platform using PHP

2025-07-09T10:49:09Z

Ckl: /* PBX / App Platform */

This is a slight rewrite of the [[Reference13r1:Concept Talking to the v13 Application Platform using PHP | older article]] in the Reference13r1 namespace. While there is nothing technically wrong with the old article, some of the authentication methods described there are no longer recommended for use with scripts. In particular, it is not recommended that a script authenticate as a PBX user. Instead, it should always authenticate against a PBX ''App'' type object. If the script needs to access other App services, it should use the ''Services'' API described in https://sdk.innovaphone.com/13r2/doc/appwebsocket/Services.htm.

==Applies To==
This information applies to

* innovaphone platform running the 13r2 (or later) ''App Platform ''
* PBX running 13r2 (or later) firmware
* PHP script accessing the ''App Services'' available on the ''App Platform''

==More Information==
===Problem Details===
The v13 App Platform runs several ''App Services'' that provide services used by ''Apps'' running in the context of the ''myApps'' client. Apps (written in JavaScript) are loaded from the App Platform and launched by the myApps client. They communicate with the App Services using a JSON-based WebSocket protocol. ''Apps'' can also be loaded from the PBX (so called ''PBX Apps'').

The ''vanilla'' way to go when it comes to 3rd party integration is to write a ''custom App Service'' and install it on the ''App Platform''. The creation of such ''App Services'' is facilitated by the [https://sdk.innovaphone.com/13r2/doc/sdk.htm ''v13 SDK''].

Note: The mechanisms described here are available in the 13r2 SDK, so all links to the SDK are given for the 13r2 version. To access other versions of the SDK as they become available, go to [https://sdk.innovaphone.com SDK root] and follow the links to the version of interest.

[[Image:app-platform-php-appplatform-simplified.png]]

However, in some scenarios you may want to talk to the PBX or existing App Services directly from your own application (i.e. not via an App running in the myApps client). This article describes how to do this. General considerations are given that apply to all programming languages, and some sample code is given in PHP.

[[Image:app-platform-php-appplatform-simplified-3rd-party.png]]

==== Authentication ====
To talk to the PBX or another ''App Service'', your application (written in PHP or any other language that can talk to a WebSocket) needs to be logged in to the PBX. While an ''App'' does not need to worry about this, as the ''myApps'' client (which is the context in which all ''Apps'' run) would take care of this, an App Service needs to implement the protocol itself.

The process is as follows:
* An ''App'' type object must be created on the PBX for your application.
* The ''App'' object defines the authentication credentials (''Name'' and ''Password'') as well as the access rights of your application (i.e., the APIs in the ''App'' tab, the licenses in the ''License'' tab, and the Apps in the ''Apps'' tab)
* The application must log in to the PBX using the credentials configured for the ''App'' type object that corresponds to the application. In other words, it logs in as the App, not as a specific user
* The application can then use the allowed PBX APIs (according to the definitions in the ''Grant access to APIs'' section in the ''App'' tab of the ''App'' object).
* The application can authenticate to other allowed App services (as defined in the ''Apps'' tab of the ''App'' object) using the PBX ''Services'' API. It can then request services from these App Services

==== WebSocket ====
''App Services'' (as well as the aforementioned PBX APIs) communicate using messages sent through WebSockets. The content of those messages has JSON syntax.

Although WebSockets are based on the HTTP protocol (for example, they usually use ports 80/443), they behave fundamentally different than HTTP connections in that they are ''asynchronous''. With HTTP, all requests are synchronous, that is, each request is responded to by an answer. Also, only the HTTP client can send requests, not the server. With WebSocket however, both sides can (once they have agreed to upgrade the HTTP connection to a WebSocket connection) send messages at any time. Such messages may trigger 0, 1 or more response messages, depending on the application protocol. The protocol itself does not define a relation between a message and its response messages. As there is no such thing as a synchronous ''request/response'' cycle with WebSocket, an asynchronous programming model is required to take full advantage of the WebSocket approach.

==== JSON ====
JSON stands for ''J''ava''S''cript''O''bject''N''otation. It is a subset of the syntax JavaScript uses to denote (complex) data constants. Here is an example: <code >{"mystring":"a","myint":42}</code>. As such, it allows to store the value of an object as a string and also to set the value of an object from a string (a process known as ''serialization/unserialization'' in many programming languages). JSON allows us to put the value of an object in to a WebSocket message and also of course to retrieve such value from a WebSocket message. Compared to XML (which more or less allows the same), it is much more compact.

Although JSON is related to JavaScript, most programming languages can deal with it. For example, PHP has the <code>json_encode()</code> and <code>json_decode()</code> functions, C# has the <code> DataContractJsonSerializer</code> class.

Here is a full example of the JSON message that might be used to authenticate towards the PBX
<syntaxhighlight lang="json">
{
"mt": "AppLogin",
"digest": "955da4b8351557c54c25b99fa8aad9e8b4ba7a4090ac5c2664e7ef7a301e6586",
"domain": "",
"sip": "",
"guid": "",
"dn": "",
"app": "myapplication",
"info": {}
}
</syntaxhighlight>

When working with ''App Services'', there are three message members which are somehow special for all such services.
; mt (string) : the ''m''essage ''t''ype. Each message must have an <code>mt</code> member which denotes the message type
; api (string, optional) : some App services (and in particular the PBX) support different defined sets of messages (referred to as ''api''). In this case, the ''mt'' message member is not sufficient to specify the type of message. Instead, the API identifier must be given in the ''api'' message member. The [https://sdk.innovaphone.com/13r2/doc/appwebsocket/RCC.htm RCC api] provided by the PBX would be an example where all messages sent to or received from the PBX for this API must have an ''api'' message member with the (string) value <code>"RCC"</code>
; src (string, optional) : this member may be sent along with messages sent to an ''App Service''. If the message triggers responses, the ''App Service'' will copy the <code>src</code> member in to the responses. This allows the client to associate responses to the message that initiated them.
All other members (if any) are defined by the application protocol.

==== Definition of Application Protocols ====
Message types, their members and the message flow are part of the documentation in the [https://sdk.innovaphone.com/13r2 software development kit (SDK)] that comes with the ''App Platform''. In this article, we only touch them for educational purposes.

=== PHP Sample Code ===
These scripts use a configuration from a file called ''my-pbx-data.php''.

To provide proper data for your environment to the scripts, create the file ''my-pbx-data.php'' as follows:
<syntaxhighlight lang="php">
<?php
$pbxdns = "your-pbx-dns-or-ip";
$pbxapp = "your-app-object-name";
$pbxpw = "your-pbx-app-password";
</syntaxhighlight>

Our little example (available in <code>application.php</code>) will connect to 2 ''App Services'' on the ''App Platform'', ''Devices'' and ''Users'' to retrieve some configuration data. To authenticate towards the App service instances, a dedicated PBX ''App'' object in the PBX with appropriate rights is used.

===== PBX configuration =====
You will need a PBX which has been set up using the standard ''Install'' procedure (http://$pbxdns /install.htm).

On that PBX, you additionally need to create an ''App'' type object
* whose ''Name'' property is equal to the value of ''$pbxapp''
* whose ''Password'' is equal to the value of ''$pbxpw''
* that has ticked ''Services'' in the ''Grant access to APIs'' section of the ''App'' tab
* that has ticked ''devices-api'' and ''users-admin'' in the ''Apps'' tab

===== Login =====
Logging-in to the PBX requires the following steps:
* request a challenge from the PBX using the ''AppChallenge'' message
: <syntaxhighlight lang="json">sent->PBXWS {"mt":"AppChallenge"}</syntaxhighlight >
* receive the challenge from the PBX
: <syntaxhighlight lang="json">received<-PBXWS {"mt":"AppChallengeResult","challenge":"8b7d8a1a3a281efd"}</syntaxhighlight >
* compute the digest based on the App data, the secret and the challenge
: <syntaxhighlight lang="json">sent->PBXWS
{
"mt": "AppLogin",
"digest": "1a07f3c20d2a4f6b117c64d845b9bed7b884b49b82868f0e2b73200553c40e2d",
"domain": "",
"sip": "",
"guid": "",
"dn": "",
"app": "myapplication",
"info": {}
}</syntaxhighlight >
* receive the confirmation from the PBX
<syntaxhighlight lang="json">received<-PBXWS {"mt":"AppLoginResult","ok":true}</syntaxhighlight >

This handshake is implemented in the ''AppPlatform\AppLoginAutomaton'' class available in classes\websocket.class.php. The thing that needs to be added is the WebSocket connection to the PBX (an ''AppPlatform\WSClient'' object required as constructor argument for the ''AppPlatform\AppLoginAutomaton'' class). We do this using a derived class named ''PbxAppLoginAutomaton'':

<syntaxhighlight lang="php">
class PbxAppLoginAutomaton extends AppLoginAutomaton {

function __construct($pbx, AppServiceCredentials $cred, $useWS = false) {
$this->pbxUrl = (strpos($pbx, "s://") !== false) ? $pbx :
$this->pbxUrl = ($useWS ? "ws" : "wss") . "://$pbx/PBX0/APPS/websocket";
// create websocket towards the well known PBX URI
$this->pbxWS = new WSClient("PBXWS", $this->pbxUrl);
parent::__construct($this->pbxWS, $cred);
}
}
</syntaxhighlight>

This class takes the URL to the PBX and the credentials (wrapped in an object of class ''AppPlatform\AppServiceCredentials'') as constructor arguments:

<syntaxhighlight lang="php">
$app = new PbxAppLoginAutomaton($pbxdns, new AppPlatform\AppServiceCredentials($pbxapp, $pbxpw));
</syntaxhighlight>

Our new class ultimately is a derivative of the ''AppPlattform\FinitStateAutomaton'' class, so we can run the automaton like:

<syntaxhighlight lang="php">
$app->run();
</syntaxhighlight>

The automaton will do the authentication towards the PBX as shown above and then terminate (which causes the ''run()'' member function to return).

The code then verifies that the log-in to the PBX succeeded:

<syntaxhighlight lang="php">
if (!$app->getIsLoggedIn()) {
die("login to the PBX failed - check credentials");
}
</syntaxhighlight>

Eh voilà, we are connected to the PBX.

That was the easy part :-)

Note that the code for the ''PbxAppLoginAutomaton'' can be found in the classes/websocket.class.php file.

===== Determination of available services =====
Now that we are successfully connected to the PBX, we can determine the services that are available to our application. This is done using the ''Services'' API available in the PBX (which is described in the SDK's [https://sdk.innovaphone.com/13r3/doc/appwebsocket/Services.htm ''Services'' page]).

Only a few steps are required:
* subscribe to the available services information
: <syntaxhighlight lang="json">sent->PBXWS {"mt":"SubscribeServices","api":"Services"}</syntaxhighlight>
: note the additional <code>api</code> member
* receive the respones
: <syntaxhighlight lang="json">received<-PBXWS {"api":"Services","mt":"SubscribeServicesResult"}</syntaxhighlight>
: note that there is no further information in this message. The actual list of services will be received later on
* unsubscribe from the list of services as we do not need dynamic updates
: <syntaxhighlight lang="json">sent->PBXWS {"mt":"UnsubscribeServices","api":"Services"}</syntaxhighlight>
* receive the actual list of services available to us
: <code>received< - PBXWS </code>
: <syntaxhighlight lang="json">
{
"api": "Services",
"mt": "ServicesInfo",
"services": [{
"name": "devices-api",
"title": "DevicesApi",
"url": "https://192.168.178.71/sample.dom/devices/innovaphone-devices-api",
"info": {
"apis": {
"com.innovaphone.devices": {}
}
}
}, {
"name": "users-admin",
"title": "Users Admin",
"url": "https://192.168.178.71/sample.dom/usersapp/innovaphone-usersadmin"
}]
}
</syntaxhighlight>
: note that the actual list of services depends on the configuration of the ''Apps'' tab in the ''App'' object for our application

Life was easy so far as we have derived the ''PbxAppLoginAutomaton'' utility class which simply did what we wanted so far, except for the initialization in its constructor. Now we want to implement further conversation with the PBX, which requires some more fundamental understanding of the finite state automaton classes.

===== The finite state automaton classes =====
Generally, to talk to the PBX or any App service, you can of course use just any WebSocket library directly. We are using (and recommending) a derivative of the [https://github.com/Textalk/websocket-php Textalk] websocket classes. We simplified the code a bit and also added support for receiving WebSocket messages asynchronously. You will find this code in <code>classes/textalk.class.php</code>.

However, solely using the textalk classes leaves you with quite a bit of work to do. As discussed above, there are some challenges:
* websocket is async by nature
: you will need some support for receiving messages asynchronously at least. Aside from the support for asynchronous receipt of messages added to the Textalk classes, the sample code has some classes which allow you to easily create ''event driven'' code which processes messages whenever they come in and not when you expect them to come in
* PBX login requires some fiddling with encryption schemes

The sample code includes some classes to create ''finite state automatons''. Also it has some classes derived from this, which actually implement the protocols required to log-in to the PBX and the ''App Services''

Those extensions can be found in <code>classes/websocket.class.php</code>.

===== The asynchronous programming model =====
PHP is not really nicely prepared for asynchronous programming. To deal with that, we have created a utility class called ''FinitStateAutomaton''. This class handles the communication to a single ''App Service''. This is why it has a WebSocket connection as argument to the constructor (our WebSocket implementation is actually called ''WSClient''). The class will use this WebSocket to talk to the ''App Service''. As we have seen above, the ''PbxAppLoginAutomaton'' utility class creates such an ''WSClient'' object and passes it to the ''AppLoginAutomaton'' (which extends the ''FinitStateAutomaton'' class).

However, if you try to instantiate such a class (like <syntaxhighlight lang="php">$mya = new FinitStateAutomaton($mywebsocket)</syntaxhighlight> you will see that this is not possible, as the class is ''abstract''. This means that there are some member functions missing which must be implemented by a derived class. These functions are those which know how to handle messages received from the ''App Service''.

Let us look at how the ''AppLoginAutomaton '' class does this:

<syntaxhighlight lang="php">
class AppLoginAutomaton extends FinitStateAutomaton {
public function ReceiveInitialStart(Message $msg) {

$this->log("requesting challenge");
$this->sendMessage(new Message("AppChallenge"));

}
}
</syntaxhighlight>
It defines an override for the abstract ''ReceiveInitialStart'' member function. This function, as all functions whose name begins with ''Receive'' is called when an event is fed into the automaton. Usually, this event is a message (of type ''AppPlatform\Message'') received from an app service. In this special case however, it is a pseudo event generated by the system indicating that the automaton should start (hence the name ''ReceiveInitial'''Start'''''). So it implements the first action the automaton performs.

In our case, as discussed above, it sends an ''AppChallenge'' message to the PBX. Recall that such an automaton is always instantiated with a single ''WSClient'' argument, which is the WebSocket connection used to talk to the App service (or the PBX which behaves like an App service). In other words, a single instance of a ''FinitStateAutomaton'' always talks to a single App service only. This is why we can simply say

<syntaxhighlight lang="php">
$this->sendMessage(new Message("AppChallenge"));
</syntaxhighlight>
without specifying a destination and resulting in an AppChallenge message
<syntaxhighlight lang="json">
sent->PBXWS {"mt":"AppChallenge"}
</syntaxhighlight>
sent to the PBX.

Eventually, the PBX will respond with an ''AppChallengeResult'' message.
<syntaxhighlight lang="json">
received<-PBXWS {"mt":"AppChallengeResult","challenge":"95ed003a24c3fc89"}
</syntaxhighlight>
When this happens, the system will call the ''ReceiveInitial'''AppChallengeResult''''' member function:

<syntaxhighlight lang="php">
public function ReceiveInitialAppChallengeResult(Message $msg) {
$infoObj = new \stdClass();
$infoHashString = json_encode($infoObj, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$hashcode = hash('sha256', $sha = "{$this->cred->app}:::::{$infoHashString}:{$msg->challenge}:{$this->cred->pw}");
// $this->log("computed challenge $sha", "debug"); // do not output in any other category than "debug" coz it includes the password
$this->sessionKey = hash('sha256', "innovaphoneAppSessionKey:{$msg->challenge}:{$this->cred->pw}");
$this->sendMessage($this->loginData = new Message("AppLogin", "digest", $hashcode, "domain", "", "sip", "", "guid", "", "dn", "", "app", $this->cred->app, "info", $infoObj));
}
</syntaxhighlight>

It does some cryptographic magic to compute a digest from the available information and then sends an ''AppLogin'' message to the PBX:

<syntaxhighlight lang="php">
$this->sendMessage($this->loginData = new Message("AppLogin", "digest", $hashcode, "domain", "", "sip", "", "guid", "", "dn", "", "app", $this->cred->app, "info", $infoObj));
</syntaxhighlight>
resulting in a message such as
<syntaxhighlight lang="json">
sent - >PBXWS {
"mt": "AppLogin",
"digest": "955da4b8351557c54c25b99fa8aad9e8b4ba7a4090ac5c2664e7ef7a301e6586",
"domain": "",
"sip": "",
"guid": "",
"dn": "",
"app": "myapplication",
"info": {}
}
</syntaxhighlight>
being sent to the PBX.

The PBX would verify the correctness of the provided digest and then return an ''AppLoginResult'' message.
<syntaxhighlight lang="json">
received<-PBXWS {"mt":"AppLoginResult","ok":true}
</syntaxhighlight>
Due to the reception of such a message, the ''ReceiveInitialAppLoginResult'' member function is called. It does a bit of internal housekeeping and then does two interesting things:
<syntaxhighlight lang="php">
public function ReceiveInitialAppLoginResult(Message $msg) {

$response->setMt("AppLoginSuccess");
$this->postEvent($response);

return "Dead";
}
</syntaxhighlight>
This code creates a ''$response'' message and sets the ''mt'' member to <code>AppLoginSuccess</code>. It returns the string "Dead" then.

The event function (''ReceiveInitialAppChallengeResult'') we looked at so far did not have any explicit return statement. In PHP terms that means that it returns a ''null'' value. When an event returns a string however, it indicates that the automaton shall move to a new state.

In our case, the new state is named "Dead" and it has a special meaning. An automaton in state "Dead" is considered to be terminated. The system will not listen for incoming messages on the automaton's WSClient socket any further.

Note that the initial state of any automaton is named <code>Initial</code>. This is why event member functions are named ''Receive'''Initial'''Start'' for example. If a member function returns a new state name other than <code>Dead</code>, the member functions called upon subsequent incoming messages will be named ''Receive'''NewStateName'''Event''. Also, the first thing the system will do is call the ''Receive'''NewStateName'''Start'' member function.

===== Working with multiple automatons =====
Obviously, applications may want to talk to multiple destinations, e.g. to the PBX for authentication and to one or more other App services. As a single ''FiniteStateAutomaton'' always talks to a single ''WSClient'' connection, we need to instantiate multiple automatons to be able to talk to multiple destinations:

<syntaxhighlight lang="php">
$a1 = new Type1Automaton();
$a2 = new Type2Automaton();
$transitioner = new AppPlatform\Transitioner($a1, $a2);
$transitioner->run();
</syntaxhighlight>

''AppPlatform\Transitioner'' is a helper class that takes a number of automatons (either listed as multiple arguments or wrapped in an array and given as single argument) as constructor arguments. When its ''run'' member function is called, it will in turn call all of the automatons ''ReceiveInitialStart'' member functions and then listen for messages coming in on any of the automatons ''WSClient'' connections.

By the way, the ''FinitStateAutomaton'''s own ''run'' member function is trivial:

<syntaxhighlight lang="php">
/**
* utility function for the simple case you want to run a single (i.e. this) automaton only
*/
public function run($sockettimeout = 5) {
$auto = new Transitioner($this);
$auto->run($sockettimeout);
}
</syntaxhighlight>

The remaining question is how different automaton instances communicate to each other. This is done using the ''FinitStateAutomaton'''s ''postMessage'' member function as in

<syntaxhighlight lang="php">
$this->postEvent($response);
</syntaxhighlight>

shown above in the ''ReceiveInitialAppLoginResult'' event function. When ''postEvent'' is called, the system would call the corresponding event functions in all currently active automatons. Note that these member functions are called synchronously, that is, they are already executed when the ''postEvent'' function returns.

===== Tandems =====
The ''postEvent'' mechanisms allows two or more automatons to work in tandem. To see how that works, we can have a look at the ''Pbx2AppAuthenticator'' class.

<syntaxhighlight lang="php">
/**
* class that authenticates to an App service with help from the PBX
*/
class Pbx2AppAuthenticator extends \AppPlatform\FinitStateAutomaton {
</syntaxhighlight>
This class takes a ''ServiceConnector'' as constructor argument (for example one delivered from the ''PbxAppLoginAutomaton'') and creates a WebSocket connection (actually a ''WSClient'' object) towards the App service described by the ''ServiceConnector''.

<syntaxhighlight lang="php">
public function __construct(ServiceConnector $svc) {
$this->svc = $svc;
parent::__construct($svc->connect(), $svc->name);
}
</syntaxhighlight>
The first thing it then does is to send an ''AppChallenge'' message to the service:
<syntaxhighlight lang="php">
public function ReceiveInitialStart(Message $msg) {
$this->sendMessage(new Message ("AppChallenge"));
}
</syntaxhighlight>
When the service returns the challenge, the class needs help from the ''PbxAppLoginAutomaton'' class (which talks to the PBX as we have seen before). To get help, it posts a ''GotChallenge'' message which includes the challenge received from the service and the name of that service.
<syntaxhighlight lang="php">
public function ReceiveInitialAppChallengeResult(Message $msg) {
$this->postEvent(new Message ("GotChallenge", "from", $this->svc->name, "challenge", $msg->challenge));
}
</syntaxhighlight>

When the ''PbxAppLoginAutomaton'' class (which has already been used to authenticate towards the PBX) is activated again (resulting in a call of its ''ReceiveInitialStart'' event function) it will determine that it already obtained a service list from the PBX (see above) and will therefore move into the new state named ''SvcAuthenticate''.
<syntaxhighlight lang="php">
public function ReceiveInitialStart(Message $msg) {
if (empty($this->services)) {
// initial login to the PBX
return parent::ReceiveInitialStart($msg);
}
else {
// PBX assisted login towards App services
return "SvcAuthenticate";
}
}
</syntaxhighlight>
When the ''GotChallenge'' event is posted, the ''ReceiveSvcAuthenticateGotChallenge'' event function is called
<syntaxhighlight lang="php">
public function ReceiveSvcAuthenticateGotChallenge(Message $msg) {
$this->log("got challenge info from $msg->from");
$this->sendMessage(new Message ("GetServiceLogin", "api", "Services", "app", $msg->from, "challenge", $msg->challenge, "src", $msg->from));
}
</syntaxhighlight>
and sends a ''GetServiceLogin'' message to the PBX which includes the service name and the challenge. It also includes a ''src'' property set to the name of the App. This will instruct the PBX to include the same property when the response is sent, so that the returned information can be associated with the proper service later on.

The PBX will eventually respond with a ''GetServiceLoginResult'' message. This needs to be passed to the ''Pbx2AppAuthenticator'' class instance which will send it to the service. This is done using the ''postEvent'' mechanism again:
<syntaxhighlight lang="php">
public function ReceiveSvcAuthenticateGetServiceLoginResult(Message $msg) {
$this->postEvent(new Message ("GotChallengeResult", "for", $msg->src, "msg", $msg));
</syntaxhighlight>
The ''Pbx2AppAuthenticator'' class instance which is interested in exactly this ''GetServiceLoginResult'' response has a ''ReceiveInitialGotChallengeResult'' event function which is called due to this ''postEvent'':
<syntaxhighlight lang="php">
public function ReceiveInitialGotChallengeResult(Message $msg) {
if ($msg->for == $this->svc->name) {
$this->sendMessage(new Message ("AppLogin",
"app", $msg->msg->app,
"domain", $msg->msg->domain,
"sip", $msg->msg->sip,
"guid", $msg->msg->guid,
"dn", $msg->msg->dn,
"digest", $msg->msg->digest,
"pbxObj", $msg->msg->pbxObj,
"info", $msg->msg->info));
}
}
</syntaxhighlight>
The function verifies that it has been called for the challenge result it is actually interested in and then passes it to its service. The service will return an ''AppLoginResult'' message which is processed by the ''ReceiveInitialAppLoginResult'' function:
<syntaxhighlight lang="php">
public function ReceiveInitialAppLoginResult(Message $msg) {
if (empty($msg->ok) || $msg->ok != 1) {
$this->log("FAILED to log in to $msg->app ($this->svc->name", "error");
}
else {
$this->log("logged in to $msg->app ({$this->svc->name})", "runtime");
$this->svc->authenticated = true;
}
return "User";
}
</syntaxhighlight>
The event function checks if the login was successfull (it should have been) and then moves into the new "User" state. This will trigger the ''ReceiveUserStart'' to be called which simply moves to the ''Dead'' state (that is, it terminates the automaton).
<syntaxhighlight lang="php">
/**
* this simply ends the automaton. Override it if you derive a class from this
* @param Message $msg
* @return string
*/
public function ReceiveUserStart(Message $msg) {
//
return "Dead";
}
</syntaxhighlight>

So why is this? This is just convenience. In a real application, we obviously would want to continue talking to the service but the ''Pbx2AppAuthenticator'' class doesn't know how to. So we would certainly create a new class of our own which extends the ''Pbx2AppAuthenticator'' class and overrides the '' event function. A very simple example can be seen in the ''application.php'' script:
<syntaxhighlight lang="php">
class UsersLister extends AppPlatform\Pbx2AppAuthenticator {
public function ReceiveUserStart(\AppPlatform\Message $msg) {
$this->sendMessage(new AppPlatform\Message("UserData",
"maxID", 9999, "offset", 0, "filter", "%", "update", false, "col", "id", "asc", true));
}

public function ReceiveUserUserDataInfo(\AppPlatform\Message $msg) {
$this->log("from {$this->svc->name}: user: id $msg->id, name $msg->username", "runtime");
return "Dead";
}
}
</syntaxhighlight>
This sample class simply sends a ''UserData'' message to the ''users-admin'' service and prints out the user information from the resulting ''UserDataInfo'' response.

So this was an example of how automatons can work in tandem. However, the mechanism can also be used to work with more than two automatons. In the sample code, an instance of the ''Pbx2AppAuthenticator'' class (more precisely, a derived class such as the ''UsersLister'' class above) is created for each of the services listed by the PBX as available to our App. They are pushed into an array of ''FinitStateAutomaton''s in addition to the instance of the ''PbxAppLoginAutomaton'' class used to talk to the PBX:
<syntaxhighlight lang="php">
// connect to services we need
$authenticators = [$app];

// scan list of available app services for those we are interested ion
foreach ($app->getServices() as $svc) {
/* consider if we need this */
switch ($svc->type) {
case "innovaphone-devices-api":
$authenticators[] = new DevicesLister($svc);
break;
case "innovaphone-usersadmin":
$authenticators[] = new UsersLister($svc);
break;
}
}
</syntaxhighlight>
The resulting list of tasks is then run using the ''Transitioner'' helper class:
<syntaxhighlight lang="php">
// tell class talking to PBX how many authentications we need to do
$app->setNumberOfAuthentications(count($authenticators) - 1);

$tr = new AppPlatform\Transitioner($authenticators);
$tr->run();
</syntaxhighlight>

=== More sample code ===
==== Using the PbxAdminApi ====
This is a simple piece of code that uses the [https://sdk.innovaphone.com/13r3/doc/appwebsocket/PbxAdminApi.htm PbxAdminApi] to create a duplicate of the App object we were using in the first sample code (''application.php''). It is available in ''pbxadminapi.php''. Before you can use the sample, you must make sure that the ''Admin'' check-mark is ticked in the ''App'' tab of your App object.

It first uses the ''PbxAppLoginAutomaton'' to log in to the PBX.

<syntaxhighlight lang="php">
// Login to PBX
$app = new AppPlatform\PbxAppLoginAutomaton($pbxdns, new AppPlatform\AppServiceCredentials($pbxapp, $pbxpw));
$app->run();
if (!$app->getIsLoggedIn()) {
die("login to the PBX failed - check credentials");
}
</syntaxhighlight>

It then uses a new derivative of the ''FiniteStateAutomaton'' class to create the cloned object, passing the WSClient object used by the ''PbxAppLoginAutomaton'' class to its constructor:
<syntaxhighlight lang="php">
/**
* class to create a new PBX App object just like the one we use for this application
*/
class AppObjectCreator extends AppPlatform\FinitStateAutomaton {

public function ReceiveInitialStart(AppPlatform\Message $msg) {
//
{
return "CopyObject";
}
}

/**
*
* @global string $pbxapp h323-name of source App object
* @param AppPlatform\Message $msg
*/
public function ReceiveCopyObjectStart(AppPlatform\Message $msg) {
global $pbxapp;
$this->sendMessage(new AppPlatform\Message(
"GetObject",
"api", "PbxAdminApi",
"h323", $pbxapp));
}

public function ReceiveCopyObjectGetObjectResult(AppPlatform\Message $msg) {
// patch $msg so it can be used for object creation
$msg->setMt("UpdateObject");
// a new one shall be created, no update of the exiting one
unset($msg->guid);
// assert unique identifiers
$msg->h323 .= "-clone";
$msg->cn .= " (clone)";
// we don't want any "Devices" entries
unset($msg->devices);

$this->sendMessage($msg);
}

public function ReceiveCopyObjectUpdateObjectResult(AppPlatform\Message $msg) {
if (isset($msg->guid)) {
$this->log("App object clone created with Guid $msg->guid", "runtime");
} else {
$this->log("App object clone could not be created: $msg->error", "runtime");
}
return "Dead";
}
}
$me = new AppObjectCreator($app->getWs());
$me->run();
</syntaxhighlight>

==== Using the RCC API ====
To run this sample code, you must make sure
* there is a waiting queue with ''Name'' (h323/sip) <code>sink</code>
: * it has an ''Alert Timeout'' set to a reasonable number (some seconds, e.g. 3)
: * it has the ''1st Announcement URL'' set to <code>MOH</code>
* there must be a user object
: * it has our application (''myapplication'') check-mark ticked in its ''Apps'' tab
: * it has a phone registered or a softphone provisioned
* the App object for our application (''myapplication'') must have the ''RCC'' check-mark ticked in its ''App'' tab

This sample code demonstrates use of the [http://sdk.innovaphone.com/13r2/doc/appwebsocket/RCC.htm RCC] API. It monitors some PBX user objects and shows all related calls. If a peer named ''sink'' is called, the call is forcefully terminated by our script. It is available in the ''rccapi.php'' sample code file.

The code uses a derivative of the ''FinitStateAutomaton'' class called ''RemoteControlUser''. The first thing it does is to send an ''Initialize'' message to the PBX which initializes the use of the ''RCC'' api.

<syntaxhighlight lang="php">
class RemoteControlUser extends AppPlatform\FinitStateAutomaton {

private $myusers = [];
private $mycalls = [];

public function ReceiveInitialStart(AppPlatform\Message $msg) {
// move to Monitoring state
return "Monitoring";
}

public function ReceiveMonitoringStart(AppPlatform\Message $msg) {
// Initialize RCC Api
$this->sendMessage(new AppPlatform\Message(
"Initialize",
"api", "RCC"
));
}
</syntaxhighlight>

The PBX will send a number of ''UserInfo'' messages in response to the ''Initialize'' message. One message will be sent for each user that has our application check-mark ticked in its ''Apps'' tab. Those users then are said to be monitored by the application using the RCC API.

For each new monitored user that is announced this way, the user information is stored in a class-local array. Also, an ''UserInitialize'' message is sent.

<syntaxhighlight lang="php">
public function ReceiveMonitoringUserInfo(AppPlatform\Message $msg) {
// remember UserInfo and do UserInitialize on the user
if (isset($this->myusers[$msg->h323])) {
$this->log("user '$msg->h323' updated", "runtime");
}
else {
$this->log("new user '$msg->h323'", "runtime");
$this->myusers[$msg->h323] = new stdClass();
$this->sendMessage(new AppPlatform\Message(
"UserInitialize",
"api", "RCC",
"cn", $msg->cn,
"src", $msg->h323 // use "src" to be able to associate response
));
}
$this->myusers[$msg->h323]->info = $msg;
}
</syntaxhighlight>

The ''UserInitializeResponse'' message will include a client-local identifier for the initialized user called ''user''. We remember it in our class-local array of users:

<syntaxhighlight lang="php">
public function ReceiveMonitoringUserInitializeResult(AppPlatform\Message $msg) {
// remember local user id returned from UserInitialize (associated by "src")
$this->myusers[$msg->src]->user = $msg->user;
}
</syntaxhighlight>

When a user object is monitored (that is, when there was a successful ''UserInitializeResponse'' message), the PBX will start to send additional ''CallInfo'' messages for each call related to the user and for all call-state changes.

We look at those messages and determine if the remote party (the ''peer'') is called ''sink''. If so, we remember this call. If such remembered call later announces to be connected (a ''CallInfo'' message with ''msg'' member ''r-conn'' is received, we terminate the call by sending an appropriate ''UserEnd'' message.

<syntaxhighlight lang="php">
public function ReceiveMonitoringCallInfo(AppPlatform\Message $msg) {
// a call state update
$this->log("user $msg->user call $msg->call event $msg->msg", "runtime");
// see if the call is towards the waiting queue "sink"
if (isset($msg->peer) && isset($msg->peer->h323) && $msg->peer->h323 == "sink") {
$this->log("user $msg->user call $msg->call with peer h323=sink (notified with $msg->msg)", "runtime");
// remember this call for monitoring
$this->mycalls[$msg->call] = $msg;
}

// check if we monitor this call and if we are connected
if (isset($this->mycalls[$msg->call])) {
switch ($msg->msg) {
case "r-conn" :
$this->log("call $msg->call connected ($msg->msg) - disconnecting", "runtime");
$this->sendMessage(new AppPlatform\Message(
"UserClear",
"api", "RCC",
"call", $msg->call,
"cause", 88, // "Incompatible destination" see https://wiki.innovaphone.com/index.php?title=Reference:ISDN_Cause_Codes
));
break;
case "del" :
$this->log("call $msg->call ended ($msg->msg) - terminating", "runtime");
return "Dead";
}
}
}
</syntaxhighlight>

There is one other interesting mechanism which is used in this script:
<syntaxhighlight lang="php">
public function timeout() {
$this->log("timeout", "runtime");
}
</syntaxhighlight>

When the system waits for incoming events, there is (by default) a timeout of 5 seconds. If there are no incoming events during this time, an error message is issued and all the automatons are terminated. However, if an automaton implements an override for the ''timeout'' function and it does not return true, the timeout will be ignored. This is why our script waits a long time for the end of the call, occasionally spitting out a log message.

===System Requirements===
To run the sample code, you need
* a platform that is able to run v13r2 PBX firmware (e.g. an IP411, but any other will do too)
* a platform that can run the v13r2 app platform (the same IP411 would do), so if you choose to use a gateway, you will need an SSD
* a web server running PHP 8.x or up (the code has not been tested with PHP 5.6 or 7, but it may run with no problems)
* your favourite PHP IDE

You can download the PBX firmware from [https://store.innovaphone.com/release/download.htm store.innovaphone.com].

===Installation===
The PBX and App Platform is installed using the ''Install''.
==== PBX / ''App Platform'' ====
* if you choose to use a gateway platform, install an SSD
* upgrade your box (or IPVA) to the latest v13r2 (or later)
* you will need two extra IP address. One for the ''App Platform'', one for the PBX
* perform a factory reset
* access the box and you will see the installer (if not, use <code>htps://<ip-of-our-pbx>/install.htm</code>)
* complete the installer using IP addresses instead of DNS names, so that it installs a PBX and a fresh ''App Platform'' (you can of course also use DNS names during the Install if you have them operational for the PBX and App platform IP addresses. For running the sample code, it does not matter)
* be sure to note the ''Admin Password'' shown in the installer
* the installer will ask for the name of an ''admin account''. Be sure to note name and password.
* for convenience, consider to not turn on ''two factor authentication''

==== PHP Script ====
* unpack the sample sources in to your web server's content directories
* make sure PHP scripts can be executed in the ''.../sample/sources'' directory
* configure the PBX according to the hints given with the individual sample code above
* open the file ''application.php'' in your browser

===Known Problems===

====Missing php_openssl extension====
In case following error appears, make sure to enable php_openssl in your php environment configuration:
Fatal error: Uncaught Error: Call to undefined function AppPlatform\openssl_random_pseudo_bytes()

=== Download ===
The sample code can be downloaded [http://wiki.innovaphone.com/index.php?title=Howto:Wiki_Sources#websocketphp8 here ]


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

Reference7:HTTP Request Message Format

2025-06-17T13:55:46Z

Ckl: /* POST */

innovaphone devices will send data to external HTTP servers in various situations. This article describes these situations and the request formats used.

== Log Messages ==
[[Reference7:Configuration/General/Logging|Configuration/General/Logging]]

=== GET ===
When '''Method External(GET)''' is selected, the HTTP server will receive a GET request with the following form data parameters (a.k.a. ''query args''):
{|
| Parameter || Example || Description
|-
| event || syslog || The '''event''' parameter will always have the value '''syslog'''. This allows the receiving script to distinguish it from CDR data.
|-
| time || 1214319593 || The time the log messages was created. Coded as number of seconds since January 1st, 1970. If '''time''' is 0, the internal clock has not (yet) been set.
|-
| date || 20080624-145953 || The same value as '''time''', except that is is coded in a human readable format.
|-
| msg || LOG_HTTP 3 TCP-Up 172.16.10.14:7793 172.16.0.17:471 || The message itself
|}

If the receiving HTTP server is running a scripting engine such as PHP, the individual fields will be received as request query parameters. In PHP they can be accessed via '''$_GET''':

_GET: Array
(
[event] => syslog
[time] => 0
[date] => 19700101-000000
[from] => IP24-1d-00-8d
[msg] => LDIR_SOCK 4 TCP-Out 0.0.0.0:0 0.0.0.0:389
)

=== POST ===
When '''Method External(POST)''' is selected, the HTTP server will receive a POST request. The request body (i.e. the ''post data'') is ''not'' coded as a form-data. Instead, the arguments are put into the request body exactly as the query string when using GET (e.g. <code>?event=syslog&...</code>).

== CDRs ==

== Alarms/Events ==

Reference7:HTTP Request Message Format

2025-06-17T13:55:09Z

Ckl: /* POST */

innovaphone devices will send data to external HTTP servers in various situations. This article describes these situations and the request formats used.

== Log Messages ==
[[Reference7:Configuration/General/Logging|Configuration/General/Logging]]

=== GET ===
When '''Method External(GET)''' is selected, the HTTP server will receive a GET request with the following form data parameters (a.k.a. ''query args''):
{|
| Parameter || Example || Description
|-
| event || syslog || The '''event''' parameter will always have the value '''syslog'''. This allows the receiving script to distinguish it from CDR data.
|-
| time || 1214319593 || The time the log messages was created. Coded as number of seconds since January 1st, 1970. If '''time''' is 0, the internal clock has not (yet) been set.
|-
| date || 20080624-145953 || The same value as '''time''', except that is is coded in a human readable format.
|-
| msg || LOG_HTTP 3 TCP-Up 172.16.10.14:7793 172.16.0.17:471 || The message itself
|}

If the receiving HTTP server is running a scripting engine such as PHP, the individual fields will be received as request query parameters. In PHP they can be accessed via '''$_GET''':

_GET: Array
(
[event] => syslog
[time] => 0
[date] => 19700101-000000
[from] => IP24-1d-00-8d
[msg] => LDIR_SOCK 4 TCP-Out 0.0.0.0:0 0.0.0.0:389
)

=== POST ===
When '''Method External(POST)''' is selected, the HTTP server will receive a POST request. The request body (i.e. the ''post data'') is ''not'' coded as a form-data. Instead, the arguments are put into the request body exactly as the query string when using GET (e.g. <nowiki><code>?event=syslog&...</code></nowiki>).

== CDRs ==

== Alarms/Events ==

Courseware:IT Advanced - Agenda

2025-05-05T19:20:22Z

Ckl:

{{#moodlebook: Master Templates / V15 Templates / Advanced | Agenda | 151}}

Courseware:IT Advanced - 11 How to setup the Application Platform after a factory reset

2025-04-30T09:18:00Z

Ckl: Protected "Courseware:IT Advanced - 11 How to setup the Application Platform after a factory reset" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V15 Templates / Advanced | How to setup the Application Platform after a factory reset | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 11 How to setup the Application Platform after a factory reset

2025-04-30T09:17:51Z

Ckl: Created page with "{{#moodlebook: Master Templates / V15 Templates / Advanced | How to setup the Application Platform after a factory reset | 151 }} {{PAGENAME}}"

{{#moodlebook: Master Templates / V15 Templates / Advanced | How to setup the Application Platform after a factory reset | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 10 Password relations

2025-04-30T08:48:14Z

Ckl: Protected "Courseware:IT Advanced - 10 Password relations" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V15 Templates / Advanced | Password relations | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 10 Password relations

2025-04-30T08:47:52Z

Ckl: Created page with "{{#moodlebook: Master Templates / V15 Templates / Advanced | Password relations | 151 }} {{PAGENAME}}"

{{#moodlebook: Master Templates / V15 Templates / Advanced | Password relations | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 09 Custom certificates

2025-04-30T08:22:56Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | Custom certificates | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 08 Using a custom DNS on your mobile phone

2025-04-30T08:22:03Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | Using a custom DNS on your mobile phone | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 07 Public access to PBX resources (practice)

2025-04-30T08:21:30Z

Ckl:

{{#moodlebook: Master Templates / V15 Templates / Advanced | Public access to PBX resources (practice)| 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 06 Public Access to PBX Resources (theory) - optional

2025-04-30T08:20:36Z

Ckl:

{{#moodlebook: Master Templates / V15 Templates / Advanced | Public Access to PBX Resources (theory) - optional | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 05 Setting up the Apps

2025-04-30T08:20:03Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | Setting up the Apps | 151 }}

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

Courseware:IT Advanced - 04 Setting up the Application Platform

2025-04-30T08:19:26Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | Setting up the Application Platform | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 03 The Application Platform

2025-04-30T08:18:18Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | The Application Platform | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 01 innovaphone overall Product Design

2025-04-30T08:17:11Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | innovaphone overall Product Design | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 02 PBX - initial Configuration

2025-04-30T08:16:25Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | PBX - initial Configuration | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Reference13r3:IP4/NAT/General

2025-04-29T07:58:42Z

Ckl:

__NOTOC__
If the device is used as a router, it is able to connect IP terminals from the network with a non-public address to the public Internet. For this, '''NAT''' (Network Address Translation) is necessary. Additional configuration is required on the different IP interfaces (e.g. ETH, PPP, etc.) to define on which interfaces the public and on which interfaces the private network is accessed.

;Enable NAT: If this checkmark is set, NAT is enabled. Without this checkmark being set all other NAT settings are without effect.

;Default forward destination: If all incoming data packets from the public network are to be forwarded to a particular private IP address, the destination IP address must be entered here.

;Disable DNS Forwarding: No DNS requests are answered by this host, if this option is enabled.

===Add new map===
;Port-specific forwarding: To be able to address several internal destinations, different port numbers are assigned to IP addresses of the internal network here.

===STUN/TURN server===
;Enable STUN: If this checkmark is set, a STUN server is started on the box. The STUN server works like a regular STUN server from external. From internal binding requests create a NAT mapping and the binding response contains the public address of the mapping.

;Non standard port: The port that shall be used for the STUN server. If empty the well known port 3478 is used.

;STUN Changed Address: If the ''Enable STUN'' checkmark is ticked, an IP address:port must be configured, which will be used as source address for replies, when the client is asking for a ''changed address''. This is used for the classic STUN NAT detection mechanism. Basically any address/port can be used here. It could be that a IP provider does not forward packets with a wrong address, so it is safer to use an address, which is valid in the network of the device. It is also better to use an address, which is not used for something else, because it could be that the local router uses these packets to update its ARP table. You can use 3480 as port. Note that NAT detection will not work properly if no ''STUN Changed Address'' is configured

;TURN: Up to four TURN accounts can be configured. If a TURN account is configured a TURN server is enabled for this account.

;TURN Public Address: A TURN server can be operated in a private network behind a firewall. In this case port forwarding must be configured on the firewall for the complete RTP port range to the TURN server. On the TURN server the used public address of the firewall has to be configured, so that this can be provided to the remote RTP peer to send the RTP data to.

;Cluster: TURN servers can be operated in a cluster behind a single firewall. Each TURN server within the cluster should be assigned a separate RTP port range. On the firewall port forwarding to the different TURN servers has to be forwarded for the RTP port ranges. To distribute the incoming requests standard TCP or UDP load balancing to the different TURN servers has to be configured.
:If in this setup the other RTP peer use the same TURN cluster, the RTP is forwarded between the two session using the public firewall address, this requires the firewall to support hairpinning. To avoid this, on each TURN server all the TURN servers of the cluster can be configured, with their RTP port ranges (first, last) and their local (internal) addresses. If the RTP peer is identified as belonging to the same cluster, the local address is then used for the RTP.

== Known Issues ==

Note: In v12r1 and higher version it's no longer necessary to enable NAT for the STUN/TURN services be enabled. If NAT is disabled make sure the UDP-NAT port range values are also deleted / not set.

==Related Articles==

* [[Howto:How to configure NAT in V6]]
* [[Howto:Avoid DNS Amplification Attacks]]

Reference15r1:Services/Reverse-Proxy

2025-04-17T07:00:01Z

Ckl: /* SMTP */

[[Category:Concept|Reverse Proxy]]
[[Category:Concept Reverse Proxy]]
The reverse proxy is used to forward H.323, SIP, LDAP, HTTP and SMTP requests it receives to other hosts, based on system information like gatekeeper name host name, path or domain.
This way it can be controlled which services may be accessed thru the reverse proxy.
A reverse proxy may be located at the boundary of an private and a public network, or inside the private network, if the respective ports are forwarded to it by the NAT Router/Firewall.
It can be even configured on the same device as the PBX itself. In this case the other services on the device should use non-standard ports, so that the reverse proxy can receive the requests on the standard port and forward them locally to the non-standard ports.

== General Parameters ==

;No IPv4: Turn off IPv4 for the reverse proxy function
;No IPv6: Turn off IPv6 for the reverse proxy function
;H.323/TCP, H.323/TLS: Ports for incoming H.323 TCP or TLS Connections. Use 1720 and 1300 for the standard ports.
;SIP/TCP, SIP/TLS: Ports for incoming SIP TCP or TLS Connections. Use 5060 and 5061 for the standard ports.
;LDAP, LDAPs: Ports for incoming LDAP TCP or TLS Connections. Use 389 and 636 for the Standard ports.
;HTTP, HTTPS: Ports for incoming HTTP TCP or TLS Connections. Use 80 and 443 for the Standard ports.
;SMTP, SMTPS: Ports for incoming SMTP TCP or TLS Connections. Use 25 and 587 for the Standard ports.
;Log Forwarded Requests: activate protocol dependent logging for successfully forwarded / accepted requests
;Log Rejected Requests: activate protocol dependent logging for rejected / non-accepted requests
;Blacklist Expiration: Time in minutes after which an entry put in the blacklist automatically, will be removed from the blacklist.
;Suspicious Requests/min: Threshold to put an address into the blacklist
;Public NAT router address: Required for SIP if RP is behind NAT. External SIP clients will receive this value in Route header of SIP messages. You can configure DNS name or IP address and port here. If not configured, RP writes it's own local IP address and port into Route header of SIP messages. This works only if RP has a public local IP address.

== Hosts ==

List of configured hosts. Click on the host Name to edit or delete. Use new to add new host

;Out
:Destination IP-Address (IPv4 or IPv6) for this rule, following by the plain text port
:Destination DNS name: must start with '''@''' and is limited to 15 chars. For longer names, you can use a DNS suffix (see below).
;TLS
:Port for encrypted traffic
;Check Certificate
:If the Check Certificate checkmark is set, for the internal connection TLS is used only if the received certificate matches the user name within the protocol. This way a host receiving a request through the Reverse Proxy using TLS can assume that the connection was authenticated using a valid certificate, which matches the user.
;App Login
:Experimental feature to allow access only if a myPBX session has been previously authenticated. Not supported for myApps.
;Default
:This rule will be used if only the Domain without a path or file in the URI was requested. The empty path is then replaced by the specified URL when the request is forwarded (e.g. an entry ''<nowiki>http://</nowiki><host>/web/index.htm'' with the ''Default'' check-mark ticked will match requests with no path and the request is forwarded with the path set to ''/web/index.htm''). Note that also, an implicit rule is created that forwards all requests for files in and beneath the folder where the default document is in (in the example rule, requests to all files under ''<nowiki>http://</nowiki><host>/web'' will be forwarded)
;MTLS:
:Request MTLS on incoming connections. The requesting client has to provide the TLS Server Name on the incoming TLS connection. The Server Name is used to match to the host. If the checkmark is set, MTLS is requested then. If no Server Name is provided or no valid client certificate a connection for this host is rejected. The name od the received and validated certificate is forwarded as X-Remote-Cert HTTP header.
;Network
:''adddr:network'' to restrict a configured protocol to certain networks

=== SMTP ===
The host is searched for using different criteria based on the incoming socket.

The criteria are searched in the order given and the first match wins.

;TLS: the SNI of the TLS handshake
;EHLO: the client hostname send inside the client EHLO SMTP protocol message
;AUTH: the username of an AUTH PLAIN login. The whole username is matched and if no match is found, the domain part after an @ sign if present.
;RCPT-TO: the recipient mail address. The whole mail address is matched and if no match is found, the domain part.

==== STARTTLS ====

* If the EHLO message is already suitable to detect the host, STARTTLS is handled by the server behind the RP and port forwarding must be done to the non TLS port in this case.
* Otherwise the RP itself handles the STARTTLS handshake. It then doesn't matter if you internally forward to the non TLS port or the TLS port but STARTTLS won't be done anymore in any case.

== DNS Suffixes ==

If you want to forward requests to internal DNS names instead of IP addresses and such an internal DNS name is longer than 15 chars, you must use DNS suffixes to reference it. 

;Id: a unique id which is used as reference
;Suffix: a suffix which is used as replacement of #Id

If you want to use such a suffix inside '''Out''' of a host, you must write it like this:
'''@host1.#1''' -> this will be expanded to '''host1.example.com''', if the suffix with Id 1 has the value example.com

== Counter ==

Current top ten address with suspicious requests

== Addresses ==

Blacklist/Whitelist addresses

Reference14r1:Concept Let's Encrypt

2024-11-07T21:54:46Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App. Of course, an empty rule (such as the one that the reverse proxy PBX Manager plugin creates) will do.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device.
:: For innovaphone devices, such rules are not necessary (except for the AP as outlined above).
* The App Platform must be able to communicate with the Let's Encrypt URLs.

'''Conclusion''': the recommended steps for obtaining certificates are as follows:
* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''<code>/.well-known/acme-challenge/</code>)
* configure the Connector for Let's Encrypt App on your AP
* configure the Let's Encrypt client on your AP
* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Concept Let's Encrypt

2024-11-06T14:39:21Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device.
:: For innovaphone devices, such rules are not necessary (except for the AP as outlined above).
* The App Platform must be able to communicate with the Let's Encrypt URLs.

'''Conclusion''': the recommended steps for obtaining certificates are as follows:
* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''<code>/.well-known/acme-challenge/</code>)
* configure the Connector for Let's Encrypt App on your AP
* configure the Let's Encrypt client on your AP
* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Concept Let's Encrypt

2024-11-06T14:34:55Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device
: for innovaphone devices, such rules are not necessary (except for the AP as outlined above)
* The App Platform must be able to communicate with the Let's Encrypt URLs.

:: Conclusion: the recommended steps for obtaining certificates are as follows
::* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''<code>/.well-known/acme-challenge/</code>)
::* configure the Connector for Let's Encrypt App on your AP
::* configure the Let's Encrypt client on your AP
::* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Concept Let's Encrypt

2024-11-06T14:30:50Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device
* The App Platform must be able to communicate with the Let's Encrypt URLs.

:: Conclusion: the recommended steps for obtaining certificates are as follows
::* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''<code>/.well-known/acme-challenge/</code>)
::* configure the Connector for Let's Encrypt App on your AP
::* configure the Let's Encrypt client on your AP
::* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Concept Let's Encrypt

2024-11-06T14:29:56Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device
* The App Platform must be able to communicate with the Let's Encrypt URLs.

:: Conclusion: the recommended steps for obtaining certificates are as follows
::* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''/<code>/.well-known/acme-challenge/</code>)
::* configure the Connector for Let's Encrypt App on your AP
::* configure the Let's Encrypt client on your AP
::* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''/<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Settings/Phone settings/Device settings

2024-11-06T10:31:21Z

Ckl: /* Configuration entries for automated deployment */

;Headset
:Enable/Disable headset support
;LCD light
:Set current display brightness. 0 (off) - 15 (max). Default 8.
;LCD light (idle state)
:Display brightness applied 30s after last action. 0 (off) - 15 (max). Default 2.
:To prevent display dimming, set ''LCD light'' and ''LCD light (idle state)'' to same level
;Energy saving
:Time frame in which the display is switched off instead of being dimmed if in idle state. Format <starthours>-<endhours> in 24h-notation with leading zeros. E.g. 17-09 turns off display between 17 o'clock (5pm) until 9 o'clock (9am). Default is 22-06.
:To prevent switching off the display, set ''Energy saving'' to ''00-00''.

===Configuration entries for automated deployment===
;LCD light
;
vars create PHONE/LCD-BACKLIGHT p 8
;LCD light (idle state):
vars create PHONE/LCD-IDLE-BACKLIGHT p 2
;Energy saving:
vars create PHONE/ENERGY-SAVING-TIME p 22-06

'''Example to be used in Devices configuration/Expert configuration'''

Use the [[{{NAMESPACE}}:Concept_Update_Server#Check_command | check command ]] as in the example below to prevent re-execution every 30 seconds

# Use check command to prevent boot loops (after vars create a reset is needed)
mod cmd UP1 check iresetn Energy-Saving

vars create PHONE/LCD-BACKLIGHT p 8
vars create PHONE/LCD-IDLE-BACKLIGHT p 2
vars create PHONE/ENERGY-SAVING-TIME p 22-07

Reference14r1:Settings/Phone settings/Device settings

2024-11-06T10:25:09Z

Ckl:

;Headset
:Enable/Disable headset support
;LCD light
:Set current display brightness. 0 (off) - 15 (max). Default 8.
;LCD light (idle state)
:Display brightness applied 30s after last action. 0 (off) - 15 (max). Default 2.
:To prevent display dimming, set ''LCD light'' and ''LCD light (idle state)'' to same level
;Energy saving
:Time frame in which the display is switched off instead of being dimmed if in idle state. Format <starthours>-<endhours> in 24h-notation with leading zeros. E.g. 17-09 turns off display between 17 o'clock (5pm) until 9 o'clock (9am). Default is 22-06.
:To prevent switching off the display, set ''Energy saving'' to ''00-00''.

===Configuration entries for automated deployment===
;LCD light
;
vars create PHONE/LCD-BACKLIGHT p 8
;LCD light (idle state):
vars create PHONE/LCD-IDLE-BACKLIGHT p 2
;Energy saving:
vars create PHONE/ENERGY-SAVING-TIME p 22-06

'''Example to be used in Devices configuration/Expert configuration'''

Use the check command as in the example below to prevent re-execution every 30 seconds

# Use check command to prevent boot loops (after vars create a reset is needed)
mod cmd UP1 check iresetn Energy-Saving

vars create PHONE/LCD-BACKLIGHT p 8
vars create PHONE/LCD-IDLE-BACKLIGHT p 2
vars create PHONE/ENERGY-SAVING-TIME p 22-07

Howto:PHP based Update Server V2

2024-11-06T10:17:24Z

Ckl: /* Using vars create */

==Applies To==
This information applies to

* all innovaphone devices
* web server running PHP 5 (e.g. Linux Application Platform)

All Versions prior to 13r1 (for 13r1 and later, see [[Reference13r1:Concept App Service Devices]] instead).

By default, the [[Reference10:Concept_Update_Server | Update Manager]] mechanism reads a file that corresponds to the device type (e.g. <code>update-ip222.htm</code>). While this makes sense (update scripts may vary by device type), it is sometimes tedious, as you have to edit a huge amount of files which typically are (at least partly) identical.

Here is a PHP script that can be used as an ''Update Server'' that allows you to simplify the handling of update scripts. It also includes a mechanism that makes sure that all devices always have the same firmware installed as a given ''master device'' has. Finally, it implements a straight forward configuration backup scheme.

This article describes version 2 of this update server (build 2006 and up). The previous version is described in [[Howto:PHP_based_Update_Server]]. The enhancements are
* Status user interface showing all known devices
* Ability to roll out custom device certificates
* Ability to provide configuration files to MTLS-authenticated devices only (e.g. in order to keep certain configuration settings secure)
* Hide configuration files from public read access

==More Information==
=== Requirements ===
The update server script requires a web server with working PHP 5.3 or higher platform. It has been tested with Apache and ligHTTPD (on a [[Reference10:Concept Linux Application Platform | Linux Application Platform]]). On IIS, neither the certificate roll-out nor the MTLS authentication or configuration backup works with IIS.

The platform running the PHP scripts must have a valid time setting!

PHP 8 is supported from build 2023.

=== Features ===
The update server can
* update all your devices with boot code and firmware that corresponds to the versions running on a reference device of your choice
* save backups of your devices configuration. Backups are saved only if the configuration changed since the last backup
* invoke your own update scripts depending on
** various phases (e.g. you can have ''staging'' scripts which are only executed once and normal scripts which are executed in normal operation later on)
** devices classes (e.g. you can have different scripts for phones and gateways)
** environments (e.g. you can have scripts for your internal devices and others for devices in home offices)
** the device serial number
* roll out customer specific device certificates
* roll out update scripts to devices only that have identified themselves with a valid device certificate (MTLS)
* maintain a list of devices in your installation along with some vital information about each individual device

=== Installation ===
==== On the Linux Application Platform ====
Here is how you would install it on the [[Reference10:Concept_Linux_Application_Platform|LAP]]. Some of the steps may not be necessary if you don't want to use all features.

On the ''Linux Application Platform'', you would
* open the LAP's file system using a SFTP client such as e.g. [https://winscp.net/eng/index.php WinSCP] (if you have not yet changed it, the default credentials will be <code>root/iplinux</code>, see [[Reference10:Concept_Linux_Application_Platform#Default_Credentials | Concept Linux Application Platform]]). Note that you must use SFTP rather than WebDAV, as WebDAV will not give access to the executable web server files
* create a new root directory underneath <code>/var/www/innovaphone/mtls</code>, e.g. <code>/var/www/innovaphone/mtls/update</code>
* download the complete file package of scripts and files [https://github.com/innovaphone/php-update-server here]
* copy all files and directories in to this new directory
** create your local config files. We will never overwrite these in further updates.
***Rename <code>config/user-config-sample.xml</code> to <code>config/user-config.xml</code>
***Rename <code>scripts/all-all-all-sample.txt</code> to <code>scripts/all-all-all.txt</code>
* change owner and group of all files and directories to <code>www-data</code>, change mode to 0600 for all files and 0700 for all directories (see [[#Migrating_from_build_2000_an_newer | below]] for how to do this with WinSCP)

* log in to the LAP's admin UI (if you have not yet changed it, the default credentials will be <code>admin/linux</code>, see [[Reference10:Concept_Linux_Application_Platform#Default_Credentials | Concept Linux Application Platform]]) and open its ''Administration/Web Server/Change web server properties and public access to the web/webdav'' configuration UI. Add the following paths to ''Public Web Paths'' (assuming your base directory is called <code>update</code>):
** <code>/mtls/update</code>
** <code>/mtls/update/web</code>
** <code>/mtls/update/admin</code>
** <code>/mtls/update/fw/</code> (note the trailing slash!)
: make sure that no other sub-directories of ''update'' are listed
: make sure you have no trailing '/' in any of these paths (except ''fw/')
: this will make sure the update server's admin user interface is not accessible to the public

At this point, you should be able to access the update server's admin user interface, e.g. <code>http://update.yourcompany.com/mtls/update/admin/admin.php</code>. However, the only thing you see is a login page. Please note that your browser should ask you for a password for this page (unless you already entered it before). Cookies must be enabled for the login page to work properly.

===== If you want to provide HTTPS Acess to the Update Server =====
For HTTPS access to the update server, you may want to install your own server certificate under ''Administration/Certificates/Current server certificate''. However, this is not strictly required (you will experience some warning messages when using your browser to access the update server, however, calling devices will work just fine).

===== If you want to setup MTLS-restricted Delivery of Update Scripts =====
If you think you have sensitive information in your update scripts, you should make sure to deliver such scripts to your own verified devices only. This can be done by authenticating calling devices with ''mutual TLS'' (MTLS). In this case, the calling device must use HTTPS to retrieve the update script and present a trusted client certificate that identifies itself as the calling device (that is, has the device serial as the certificate's ''common name'' (CN)).

For this feature, you need to ''Configure mutual TLS'' in the LAP's ''Administration/Web Server'' panel. Simply tick the ''Active'' check-mark and select an appropriate ''MTLS Port''. The port must not conflict with any other TCP port used on the LAP, so neither 80 nor 443 is a good choice. 444 is a good choice. Although it [http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?&page=8 is assigned to the snpp protocol] by IANA, it is not used by the LAP (and probably rarely used anyway).

If MTLS is already activated on your LAP, simply take note of the currently configured ''MTLS Port''.

 
Please note that MTLS access is ''not possible'' through a ''reverse proxy'' (RP). This is because the RP always will terminate the incoming TLS connection and establish its own to the target. Therefore, the client certificate presented to the target server is the RP's certificate, not the original clients certificate. In our context - where MTLS is used to verify the identity of the original caller - clients must not access the update server through an RP.

You can either expose your update server directly to the internet (and carefully think through the security implications) or create specific TCP port forwarding towards the update server in your NAT-router/firewall. In this case, we recommend to use non-standard HTTP and HTTPS ports on the NAT router (cause this will already keep most of the HTTP port scanners out there in the internet from functioning).

 
Also, you will need the public key of all the CAs you will trust. These must be configured in to the web server so it can trust the certificates your devices will present to it. See [[#Enforcing_Trust]] for details.

==== On an Apache Server running on the Windows Operating System ====
The update server will run on Apache too. However, as we did not test this setup thoroughly, we recommend to use the LAP's LigHTTPD instead.

* For hints on using MTLS on an Apache Web Server, see [[Reference10:Concept_Provisioning#Enforcing_mutual_TLS_on_Apache | Enforcing mutual TLS on Apache]]
* For hints on getting the ''innovaphone device certificate authority'' public keys (which you may or may not need), see [[Reference10:Concept_Provisioning#How_to_get_inno-dev-ca-certificate.crt | How to get inno-dev-ca-certificate.crt ]]

==== On Microsoft's IIS ====
We do not recommend to use IIS as
* it does not support PUT easily
* it is not compatible with the innovaphone device's MTLS implementation

===Update existing installation===

* download the [https://github.com/innovaphone/php-update-server new sources]
* copy all files and directories to your existing installation folder (overwrite existing files)
* change owner and group of all files and directories to www-data, change mode to 0600 for all files and 0700 for all directories

===Configuration===

If you intend to deliver your update scripts with MTLS (that is, with HTTPS and mutual certificate check)
* you will need to have the full name of your ''certificate Authority'' (CA) as it is noted as ''Common Name'' (CN) in your CA's certificate
* also, you will need a PEM version of your CA's public key (a ''PEM version'' of a certificate is a text file that begins with a line like <code>-----BEGIN CERTIFICATE-----</code>)

Also, you need to know the ''MTLS Port'' configured in your LAP (see [[#If_you_want_to_setup_MTLS-restricted_Delivery_of_Update_Scripts| If you want to setup MTLS-restricted Delivery of Update Scripts ]] above).

All tweakable parameters are set in <code>user-config.xml</code>. You may want to use an XML-capable editor such as notepad++, netbeans or Visual-Studio for editing. if your editor supports it, you benefit from the ''document type description'' (DTD) provided in <code>full-config.dtd</code>.

<syntaxhighlight lang="html5">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config debugmerge="false" debugcerts="false" debugscript="false">
</config>
</syntaxhighlight>

The attributes of the <code>config</code> tag control some aspects of debugging. For now, simply set all 3 to <code>"true"</code> instead of <code>"false"</code>. Do not forget to revert them back to <code>"false"</code> when everything runs smoothly, large log files will result if not.

==== Securing Access ====
To control access to the update server's data, you should set a login. This can be done in the ''master'' tag by specifying both ''user'' and ''password'':

<syntaxhighlight lang="html5">
<master ... user="myadmin" password="mysecret"/>
</syntaxhighlight>
Default username and password are admin/password.

==== Delivering Firmware and Boot Code ====
At this point, you can simulate a device by requesting an update script using an URL like <code>http://update.yourcompany.com/mtls/update/update.php?type=IP232&sn=00-90-33-00-00-00&hwid=IP232-00-00-00&ip=1.2.3.4</code> in your browser (please note that this URL should not ask you for a password). Most likely, your browser will wait a little while and then say something like:

...
# failed to use cached data (cache not current), retrieving info online
# cannot get PBX info: cannot access http://yourmasterdevice.youdomain.tld/CMD0/box_info.xml, reading cache
# cannot get cached PBX info: cannot access cache/master-info.xml - exit

This is because you did not yet specify the ''master device'' which always runs the reference firmware.

The idea here is that you have one innovaphone device in your system where the firmware is always manually updated. All other devices shall follow this reference firmware. The update server will deliver the firmware that runs on the master device to calling devices. For this to work, you need to set the ''info'' attribute of the [[#master|''master'']] tag and leave everything else ''as is''.

Remember that you do all your local configuration changes in <code>user-config.xml</code>.

As ''master'' is a first level tag, you can add it directly underneath the opening ''<config>'' tag. The only thing we need to define right now is the path to read the firmware information from your master device. Let's say your reference device has the IP address <code>172.16.0.10</code>, you end up with

<syntaxhighlight lang="html5">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config debugmerge="true" debugcerts="true" debugscript="true">
<master info="http://172.16.0.10/CMD0/box_info.xml" user="myadmin" password="mysecret"/>
</config>
</syntaxhighlight>
(you could use a DNS name instead of the IP address of course).
The ''info'' URL is used by the update server itself only, it is never used by devices requesting an update script.

When you refresh the page that simulates a device requesting an update script, the output should now change to something like

...
# failed to use cached data (cache not current), retrieving info online
# current firmware (unknown) does not match required firmware (130178)
...

This is to say that your master device runs firmware 130178 and the calling device does not (actually, as the calling client is simulated by your browser, it does not transmit its current firmware to the update server so it is ''(unknown)'').

In order to actually update the clients with firmware and boot code, the files must be made available to the calling client somehow. This is done by specifying an URL in the [[Reference10:Concept_Update_Server#Prot_command | prot ]] and [[Reference10:Concept_Update_Server#Boot_command | boot ]] commands sent to the calling device:

...
# current firmware (unknown) does not match required firmware (130178)
mod cmd UP0 prot http://update.yourcompany.com/mtls/update/fw/130178/ ser 130178
# current boot code (unknown) does not match required boot code (130112)
mod cmd UP0 boot http://update.yourcompany.com/mtls/update/fw/130112/ ser 130112
...

By default, the URL generated points to a sub-directory of your update server called ''fw'': <code>http://update.yourcompany.com/mtls/update/fw/130178/</code>. Note that this default URL expects sub-directories underneath the ''fw'' directory which correspond to the firmware and boot code build number. The file structure thus would be like

/var/www/innovaphone/mtls/update/fw
/130178
/ip232.bin
/130112
/boot232.bin

Note that the URL ends with a slash (<code>/</code>). This instructs the calling device to append the appropriate file name itself when retrieving the file (see [[Reference10:Concept_Update_Server#Prot_command | the prot command ]] for details).

However, you can also specify any other URL by setting the ''url'' attribute in the ''fwstorage'' tag of your <code>user-config.xml</code>. In this attribute, certain meta words will be replaced (see [[#fwstorage | the ''fwstorage'' tag ]] for details). The default setting for example is <code>fw/{build}/</code>.

You can disable firmware and boot code updates altogether by setting the ''info'' attribute in the ''master'' tag to an empty value.

==== Your own Update Script Files ====
The update server will deliver update scripts to calling devices which are synthesized from a number of ''update script snippets'' which you define yourself. The idea is that many devices share parts of their configuration while other parts are different. This depends on
* the device ''class'' (e.g. a phone or a gateway)
: the device class is automatically derived from its model. In fact, a single device may be in multiple classes. For example, an IP232 is in these classes: ''phone, pre_opus_phone, phone_newui'' which basically says that its a phone and has no OPUS codec yet but a "new" user interface (as opposed to the old one found e.g. on an IP110). A number of useful classes are pre-defined, but you can add your own in <code>user-config.xml</code>.
* the device's environment (e.g. ''home-office'', ''branch-office'')
: These reflect the fact that devices may need different configuration if they are in different locations (or environments). The update server does not know about a device's environment, which is why you need to configure it in to the devices update URL if you need this. By default, there is a single environment defined called ''default'', but of course, you can add your own
* phase
: configuring devices may need multiple phases to go through. If more than one phase is defined, the device will go through all phases sequentially, which is why a ''phase'' has a numerical ''seq'' attribute. Phases are went through in order of this attribute. When the device has reached the last phase, it will stay there. By default, there is only one phase called ''update''

You can define update script snippets for any combination of device, environment and phase. You do so simply by placing appropriate files in to the ''scripts'' directory on your update server.

Let's have a closer look at the web page we used to simulate a device calling for an update script before (<code>http://update.yourcompany.com/mtls/update/update.php?type=IP232&sn=00-90-33-00-00-00&hwid=IP232-00-00-00&ip=1.2.3.4</code>). It will show you all the possible files it would deliver to the device:

# possible files (from scripts):
# scripts/update-all-00_90_33_00_00_00.txt does not exist
# scripts/update-all-default.txt does not exist
# scripts/update-phone-00_90_33_00_00_00.txt does not exist
# scripts/update-phone-default.txt does not exist
# scripts/update-pre_opus_phone-00_90_33_00_00_00.txt does not exist
# scripts/update-pre_opus_phone-default.txt does not exist
# scripts/update-phone_newui-00_90_33_00_00_00.txt does not exist
# scripts/update-phone_newui-default.txt does not exist

The update script snippet files need to have proper names to define when they should be delivered. As you can see, they all start with <code>update-</code> which means that they apply to devices which are in the ''update'' phase. As by default there is only a single phase defined, all possible file names start with <code>update-</code>.

The next part here is either <code>phone-</code>, <code>pre_opus_phone-</code>, <code>phone_newui-</code> or <code>all-</code>. This is because the calling IP232 is in three classes, so all respective snippets will be delivered to it. ''all'' however is a wild-card. That is, such files will be delivered to all devices, no matter what class they are in. You may wonder why there was no ''all'' for the phase. This is because there is only a single phase defined. If there would be more, the ''all''-variation of the phase-part of the file name would be appear.

The third part finally is either <code>default</code> or <code>00_90_33_00_00_00</code> in our case. ''default'' is the name of the only ''environment'' that is defined by default. ''00_90_33_00_00_00'' is the device's serial number which is treated as an implicitly defined environment name. This allows you to deliver certain snippets to a single device only.

Now let's create an update script snippet that is delivered to all phones in the default environment when they are in the update phase. The file name (which looks like ''phase''<code>-</code>''class''<code>-</code>''environment''<code>.txt</code>) has to be <code>update-phone-default.txt</code> therefore. Just for an exercise, let us set the device name (as shown in the browser's title bar) to ''This is a Phone!''.
The command to do so is <code>config add CMD0 /name This+is+a+Phone%21</code>, so your file may look like this

# set the device name
config add CMD0 /name This+is+a+Phone%21

(btw: did you observe that config line arguments need to be url-encoded?). Now create the file and upload it in to the ''scripts'' directory of you update server. When you now refresh the page which simulates the device calling for an update script, you will see something like this:

...
# newest script (scripts/update-phone-default.txt) 11s old
# files being updated (scripts/update-phone-default.txt 11s old, waiting for at least 90s to expire)

When you update multiple script snippets, it is often undesirable that a device retrieves an inconsistent state of the scripts you are working on (e.g. if you already have saved one but not yet the other). To avoid this, the update server will look at the files modification dates and if one of those that needs to be delivered to the device is younger than 90 seconds, it will not send any of them at all.

So when you wait for the 90 seconds to pass and refresh the page again, you will see something like this:

# firmware build info cache is current
# phase: update, nextphase: , environment: default, type: IP232, classes: phone+pre_opus_phone+phone_newui
# possible files (from scripts):
...
# scripts/update-phone-default.txt 4.1 mins
...
# scripts/update-phone-default.txt
# { begin script 'scripts/update-phone-default.txt'
# set the device name
config add CMD0 /name This+is+a+Phone%21

# end script 'scripts/update-phone-default.txt' }

# trigger reset if required
config write
config activate
iresetn

As you can see, your snippet has been delivered by the update script. However, the update server has also added some trailing commands which write back the config to the devices flash memory (<code>config write</code>), activate it (<code>config activate</code>) and trigger a reset if needed (<code>iresetn</code>).

If there are multiple snippets available for a calling device, all of them are concatenated in the sequence shown in the header of the returned script (where the possible file names are listed)

==== Device Status ====
When you have a lot of devices which are served by the update server, you may want to have a list of these devices along with some useful information regarding each devices.

You can enable this by defining the ''status'' tag in your <code>user-config.xml</code>. So open the file and add the tag right next to the ''master'' tag you added before:

<syntaxhighlight lang="html5">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config>
<master info="http://172.16.0.10/CMD0/box_info.xml"/>
<status
dir="status"
/>
</config>
</syntaxhighlight>

When you have done so, please refresh the page that simulates your calling device and then open <code>http://update.yourcompany.com/mtls/update/admin/admin.php?mode=status</code>. You will now see a device list (well, a list with a single device, the one you simulated using your browser). The list will show some information regarding the devices that requested an update script lately. For more options, see [[#status]].

==== Device Backup ====
It is generally useful to have recent backups of all of your device configurations. The update server supports that if you enable it by defining the ''backup'' tag in your <code>user-config.xml</code>. Simply put it right next to the ''master'' or ''status'' tag you added before:

<syntaxhighlight lang="html5">
...
<backup
dir="backup"
/>
</syntaxhighlight>

If you have done so and then refresh the page that simulates your calling device, you will now see

...
# scripts/update-phone_newui-default.txt does not exist

mod cmd UP0 scfg http://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m

instead of

...
# scripts/update-phone_newui-default.txt does not exist

# Backups not enabled in config

When a client requests an update script the next time, this will initiate a configuration backup which is stored underneath the ''backup'' directory. For each device, a sub-directory is created and all backup files are stored therein. By default, the last 10 differing configuration backups are kept.

==== Controlling the Time-frames when Snippets are delivered ====
The update client built-in to innovaphone devices allows to restrict updates to certain time frames (e.g. only during the night). This can be controlled using the [[Reference10:Concept_Update_Server#Times_command | times ]] command.

You can configure the update server to use the time commands by setting the ''allow'' and ''initial'' attributes in the ''times'' tag in your <code>user-config.xml</code>.

<syntaxhighlight lang="html5">
<times
allow="22,23,0,1,2,3,4"
initial="1"/>
</syntaxhighlight>

If either the ''allow'' or ''initial'' attribute is present, the update script will contain a line like

...
# Restricted times
mod cmd UP1 times /allow 22,23,0,1,2,3,4 /initial 1

In the example above, all update script activity will occur only between 10pm and 5am (local device time). For more details, see [[Reference10:Concept_Update_Server#Times_command | Concept Update Server]]

==== Using and Enforcing HTTPS ====
Your devices can either use HTTP or HTTPS to access the update server. In normal operation, the update server will generate URLs (e.g. the URLs used to retrieve firmware or to backup configurations) for the same protocol.

However, you can enforce use of HTTPS by setting the ''forcehttps'' attribute in the [[Howto:PHP_based_Update_Server_V2#times | ''times'' ]] tag to <code>true</code>. If so, a device calling in with HTTP will be re-configured to use HTTPS:

...
# using HTTP and 'forcehttps' is set -> need to switch to HTTPS

# changed state query args: polling, phase
# new url=https://update.yourcompany.com/mtls/update/update.php?polling=5&phase=&type=#t&sn=#m&hwid=#h&ip=#i
...
(note that if you are using a non-standard port for HTTPS, you must define it using the ''httpsport'' attribute).

==== Delivering Custom Certificates ====
innovaphone devices come with pre-defined, trustworthy device certificates. However, all ''soft'' devices (such as the softwarephone, myPBX for Android/iOS or the IPVA) do not. Also, in many scenarios customers run their own ''public key infrastructure'' (PKI) and request their own certificates to be used instead of the pre-defined. This is why there is a need to roll-out custom certificates to devices.

The update server supports this task to an extend. It can
* check if a calling device has a proper certificate
* instruct a calling device without proper certificate to create a ''certificate signing request'' (CSR)
* download the CSR to the update server for easy access by the administrator
* upload a signed CSR to the device
* upload the public key(s) of the CA in to the device's trust list

In order to roll-out custom certificates with the update server, the administrator needs to
* run his own PKI (a.k.a. ''certificate authority'' (CA))
* monitor CSRs that appear in the update server's device list
* approve the request by manually submitting it to his own CA
* upload the signed CSR to the update server

Also, all devices must run ''V12r1 SR8'' or newer before the new certificate can be uploaded. Devices with older firmware will be updated automatically (see [[#Delivering_Firmware_and_Boot_Code]] above). However, the new firmware must be ''V12r1 SR8'' or later.

To learn how you can create proper device certificates with your own windows CA, see [[Howto:Creating custom Certificates using a Windows Certificate Authority]].

By default, custom certificates are turned off and you will see a note like

# certificates: either certificate handling or state tracking not enabled - not doing any certificate checking

in the delivered update script.

Custom certificates are turned on by adding a ''customcerts'' tag to your <code>user-config.xml</code>:

<syntaxhighlight lang="html5">
...
<customcerts
dir="certs"
/>
...
</syntaxhighlight>

The page that simulates your calling device will now include a line saying:

# certificates: we dont know anything about the current certificate state - not doing any certificate checking

In order to decide if or if not a calling device has a valid certificate, the device needs to send its current public key to the update server. This is done by enabling ''queries'' in your <code>user-config.xml</code>. ''Queries'' is a means to have the device submit certain information to the update server. In the update server's default configuration, two queries are defined but not enabled:

* the query ''certificates'' sends the current certificate state
* the query ''admin'' sends the current device name (as set in ''General/Admin'')

To enable a query, you must specify the class a calling device must be in in order to execute the query. This is done by adding an ''applies'' tag for the respective query in your configuration:

<syntaxhighlight lang="html5">
...
<queries>
<query id="admin">
<applies>*</applies>
</query>
<query id="certificates">
<applies>*</applies>
</query>
</queries>
...
</syntaxhighlight>

This basically says that both queries should be executed by devices of just any class. Unless you enable queries, your update script will include lines such as:

# no queries defined for any of callers classes: phone+pre_opus_phone+phone_newui

Once you have enabled them, you will see something like

...
# query 'certificates'
mod cmd UP0 scfg https://update.yourcompany.com/mtls/update/update.php?mode=query&sn=#m&id=certificates ser nop /always mod%20cmd%20X509%20xml-info
# query 'admin'
mod cmd UP0 scfg https://update.yourcompany.com/mtls/update/update.php?mode=query&sn=#m&id=admin ser nop /always mod%20cmd%20CMD0%20xml-info
...

You can display the data sent by a query in the device status display. To do so, you need to define one or more ''show'' tags as part of the respective ''query'' tag:

<syntaxhighlight lang="html5">
...
<query id="certificates">
<applies>*</applies>

<show title="Subject">/state/queries/certificates/info/servercert/certificate/@subject_cn</show>
<show title="Issuer">/state/queries/certificates/info/servercert/certificate/@issuer_cn</show>
</query>
...
</syntaxhighlight>

Two steps however are still missing:

* a) you need to tell the update server the names of all the CAs you consider trustworthy. This is done by listing their names in the ''CAname'' attribute of the ''customcerts'' tag:

<syntaxhighlight lang="html5">
...
<customcerts
dir="certs"
CAname="innovaphone Device Certification Authority,innovaphone Device Certification Authority 2,innovaphone-INNO-DC-W2K8-Zertifizierungsserver"
/>
...
</syntaxhighlight>

: The example shown defines that you will accept both of innovaphone's device certificate authorities and also your own CA called ''innovaphone-INNO-DC-W2K8-Zertifizierungsserver''. Devices with device certificates issued by one of these CAs will be left untouched. For all other devices (for example, any ''myPBX for Android/iOS'' device that has a self-signed certificate), the generation of a custom certificate will be initiated.

* And b) you need to provide the public key of your CA (so it can be uploaded to the calling device's trust list). You need to place the DER (not PEM) encoded public key in to a file called <code>certs/CAkey-01.cer</code> on your update server (if you want to upload the whole certificate chain, put all of the public keys in the chain in to separate additional files called <code>certs/CAkey-02.cer</code> and so forth.

For more details on how to approve certificate signing requests, see [[#Approving Certificate Signing Requests]] below.

==== Enforcing Trust ====
Update script snippets may include sensitive information which you do not want to disclose to the public. Even though you can force the use of HTTPS (see above), this still does not keep your data secure. After all, an attacker could simply request an update script from your update server using HTTPS. To secure your data, you need to make sure that snippets are only sent to devices which identify themselves using a trusted certificate with a correct ''common name'' (CN). This is done using ''mutual transport layer security'' (MTLS). Therefore, you need to configure MTLS in the LAP (see [[#If_you_want_to_setup_MTLS-restricted_Delivery_of_Update_Scripts | If you want to setup MTLS-restricted Delivery of Update Scripts]] above).

You can enable this by setting ''forcetrust'' to <code>true</code> and ''httpsport'' to the port configured as ''MTLS Port'' in your web server. This is done in the ''times'' tag of your <code>user-config.xml</code>.
<syntaxhighlight lang="html5">
<times
...
forcehttps="true"
httpsport="444"
forcetrust="true"
/>
</syntaxhighlight>
Please note that ''forcetrust'' does nothing unless ''forcehttps'' is also set!

If so, the update server will deliver update script snippets only to clients which identify themselves with a proper certificate. For this to work, you will need to add the public key of your certificate authority to your web server's list of trusted certificates.

When using the ''Linux Application Platform'' (LAP), you need to add the PEM-encoded public key of your certificate authority to the ''innovaphone-ca.pem'' file in <code>/home/root/ssl_cert</code>. When you have installed the LAP, this file will contain the PEM-encoded public keys of the 2 innovaphone device certificate authorities. You can simply add the public key of your CA to the end of this file:

-----BEGIN CERTIFICATE-----
...inno-ca public key...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...inno-ca2 public key...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...your-ca public key...
-----END CERTIFICATE-----

You will need to restart the LigHTTPD then (most easily done by restarting the entire LAP (''Diagnose/Reset'') or by issuing the command <code>/etc/rc2.d/S02lighttpd restart</code> from the linux root command prompt). Finally, you must set the ''forcetrust'' attribute.
(Note that the ''innovaphone-ca.pem'' file may be overwritten when a new LAP version is installed. It is thus a good idea to keep a copy and check it after an upgrade).

When ''forcetrust'' is effective and the calling device does not use HTTPS, it will be reconfigured to do so:

# using HTTP and 'forcehttps' is set -> need to switch to HTTPS
...
# new url=https://update.yourcompany.com:444/update/update.php?polling=5&phase=&type=#t&sn=#m&hwid=#h&ip=#i&env=default

If the calling device uses HTTPS but sends no certificate, you will see a message like

# cannot verify CN with HTTPS: SSL_CLIENT_S_DN_CN not present - fix web server configuration or use MTLS-enabled port!

This is probably because it is using a non-MTLS enabled port for HTTPS (e.g. the standard port 443) although MTLS is configured for a different port.

If the calling device uses HTTPS and sends a certificate but the CN does not match the serial number of the device, you will see a message such as

# Device claims to be 'IP232-30-00-af' but identifies as 'CKL-CELSIUS-W10.innovaphone.sifi' by TLS

If the calling device uses HTTPS and sends a certificate but the certificate is not trusted because its issuer is not listed in ''innovaphone-ca.pem'' (see above), the connection will be refused

In all such cases, no snippet will be delivered. If the certificate is good, you will see a message like

# good certificate(CN='IP232-30-00-af')

followed by the appropriate snippets.

==== Using multiple Phases ====
When you configure multiple phases, all phases up to the final phase are stepped through and when all associated update script snippets for all phases are done, the device will ultimately stay in the final phase. This can be used e.g. to implement update script snippets which are executed once only when the device is initialized. Settings made in all but the last phase can later be overridden by the user or an administrator. The settings done in the update script settings for the final phase however are re-executed whenever one of your update script files for this phase changes.
The process of deploying some initial settings is often called ''staging''.

To enable staging, you therefore create a new phase that comes before the default phase (which is ''update''). Phases are sorted numerical by an attribute called ''seq''. As the default phase ''update'' is defined with ''seq=200'', your new staging phase must be defined with a lower seq value:

<syntaxhighlight lang="html5">
...
<phases>
<phase id="staging" seq="100"/>
</phases>
...
</syntaxhighlight>

When you define such a phase, there will be new possible update script snippet file names:

# phase: staging, nextphase: update, environment: default, type: IP232, classes: phone+pre_opus_phone+phone_newui
# possible files (from scripts):
# scripts/all-all-00_90_33_30_00_af.txt does not exist
# scripts/all-all-default.txt does not exist
# scripts/all-phone-00_90_33_30_00_af.txt does not exist
# scripts/all-phone-default.txt does not exist
# scripts/all-pre_opus_phone-00_90_33_30_00_af.txt does not exist
# scripts/all-pre_opus_phone-default.txt does not exist
# scripts/all-phone_newui-00_90_33_30_00_af.txt does not exist
# scripts/all-phone_newui-default.txt does not exist
# scripts/staging-all-00_90_33_30_00_af.txt does not exist
# scripts/staging-all-default.txt does not exist
# scripts/staging-phone-00_90_33_30_00_af.txt does not exist
# scripts/staging-phone-default.txt does not exist
# scripts/staging-pre_opus_phone-00_90_33_30_00_af.txt does not exist
# scripts/staging-pre_opus_phone-default.txt does not exist
# scripts/staging-phone_newui-00_90_33_30_00_af.txt does not exist
# scripts/staging-phone_newui-default.txt does not exist

First of all, there are new names for this particular phase. Furthermore, as we now have multiple phases, the new wild-card name ''all'' is possible.

An example for a staging script snippet might be a file called <code>staging-all-all.txt</code>:

# change admin password
config add CMD0 /user admin,my-admin-password
config activate
config rem CMD0 /user

This will set the admin password to <code>my-admin-password</code> during staging (it should be obvious that such staging should only be done in combination with [[#Enforcing_Trust|Enforcing Trust]], see above).

=== A complete <code>user-config.xml</code> Sample ===
Here is a complete sample of a configuration file.

<syntaxhighlight lang="html5">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config debugmerge="true">
<master info="http://172.16.0.10/CMD0/box_info.xml"/>
<status
dir="status"
missing="1000"
/>
<backup
dir="backup"
/>
<times
allow="22,23,0,1,2,3,4"
initial="1"
forcehttps="true"
httpsport="444"
forcetrust="true"
/>
<customcerts
dir="certs"
CAname="innovaphone Device Certification Authority,innovaphone Device Certification Authority 2"
CSRsan-dns-1="{name}.company.com"
CSRsan-dns-2="{hwid}.company.com"
CSRsan-dns-3="{rdns}"
CSRsan-ip-1="{realip}"
/>
<phases>
<phase id="staging" seq="100"/>
</phases>
<environments>
<environment id="intranet"/>
<environment id='sifi'>
<implies>intranet</implies>
</environment>
<environment id='berlin'>
<implies>intranet</implies>
</environment>
<environment id='verona'>
<implies>intranet</implies>
</environment>
<environment id='homeoffice'/>
<environment id='mobile'/>
</environments
<queries>
<query id="admin">
<applies>*</applies>
</query>
<query id="certificates">
<applies>*</applies>
<show title="Subject">/state/queries/certificates/info/servercert/certificate/@subject_cn</show>
<show title="Issuer">/state/queries/certificates/info/servercert/certificate/@issuer_cn</show>
</query>
</queries>
</config>
</syntaxhighlight>

=== Operation ===

==== Configuring and Debugging a real Device ====
To configure your device for use with the update server, you simply set <code>http://update.yourcompany.com/mtls/update/update.php</code> as ''Command File URL'' in ''Services/Update'' (you can optionally add a <code>?env=envname1,envname2</code> query argument if you want to set one or more specific environments for your device). The update server will re-configure the device later on so that it uses all the required query arguments.

Generally, there are the following methods to set the ''Command File URL''
* configure it manually using the admin GUI
* provide it to the device using DHCP (this will however not work for the softwarephone or ''myPBX for Android/iOS'')
* use the innovaphone provisioning service (see [[Reference10:Concept_Provisioning|Reference10:Concept Provisioning]] for details)

Once the ''Command File URL'' is set on the device, you can debug what the update client in the device does, using the normal trace mechanism. For this, you will want to open the ''Debug'' page (<code>http://x.x.x.x/debug.xml</code>) and set the ''Update/Polling'' and ''Update/Execution'' check-marks. When the update client queries the update server, you will see lines like

0:0826:465:5 - upd_poll: state IDLE -> RECV
0:0826:465:7 - IP.0 -> UPD-POLL.0 : SOCKET_GET_LOCAL_ADDR_RESULT(172.16.100.201,255.255.0.0,0,'',ANY)
0:0826:466:0 - IP.0 -> UPD-POLL.0 : SOCKET_GET_LOCAL_ADDR_RESULT(172.16.100.201,255.255.0.0,0,'',ANY)
0:0826:695:0 - upd_poll: state=RECV sent()
0:0826:752:0 - upd_poll: status 200 headercomplete=1 contentlength=0
0:0826:754:0 - upd_poll: recv_data(2199)
0:0826:754:1 - upd_poll: recv_data(0) EOF
0:0826:754:1 - upd_poll: GET EOF - state=RECV http-status=200 length=2199
0:0826:754:1 - upd_poll: do commands
0:0826:754:1 - upd_poll: state RECV -> EXEC

in the trace. Commands included in the update script will look like

0:0826:754:5 - script::get_line: >line(mod cmd UP0 scfg https://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m)
0:0826:754:5 - upd_poll: pass 'mod cmd UP0 /sync scfg https://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m')

Finally, you do not need to wait for the next time the device decides to contact the update server. Instead, you can force this by sending an <code>http://</code>''your-device-ip<code>/!mod cmd UP1 poll</code> to the device.

==== The Device Status Update Page ====
If status tracking is enabled (see [[#Device_Status | Device Status]] above), the update server will keep a list of devices it knows of. You can see this list by calling <code>http://update.yourcompany.com/mtls/update/admin/admin.php?mode=status</code>.

By default, the list will not be updated unless you refresh the page. However, if you set the ''refresh'' attribute in the ''status'' tag in your ''user-config.xml'' file to <code>60</code>, all entries in this list will be refreshed every 60 seconds (however, the list itself will not be reloaded, so to see new devices, you need to refresh the entire page). Devices that have not been seen for more than 7 days are shown in a different colour. Devices that have not been seen for longer than 90 days will be silently removed from the list.

===== Filtering =====
From build 2011, you can filter the devices shown using the ''device filter'' field in the ''Device'' column header. The filter string is matched against ip-address, serial number, type, name, phase, class, environment, firmware and bootcode. Also, you can filter by using the keywords ''present'' and ''missing'' (based on the ''missing'' attribute of the ''status'' tag in your configuration file). If one of these attributes match your filter expression, the device is shown.

A filter expression must match a complete ''word''. For example, if you filter by <code>16</code> this would match the ip-address <code>172.</code>16<code>.0.20</code> but it would not match <code>192.</code>16<code>8.0.1</code>.

If you specify multiple filter expressions (separated by white space), only devices which match all of the expressions will be shown. For example, if you filter by <code>172.16. ip222</code> this might match all IP222 in your 172.16.*.* network. Filter expressions are case insensitive.

==== Approving Certificate Signing Requests ====
When you use custom certificate roll-out, you will see a column ''Certificates'' in the device status list, showing the devices certificate status.

[[Image:PHP_based_Update_Server_V2_Device_Status.png]]

If a CSR has been created on the device, this will be available for download in the ''Files'' section of the ''Info'' column. You can submit the CSR to your CA and then upload the signed request (using the ''Upload'' button in the ''Files'' section of the ''Info'' column). The signed request will eventually be uploaded to the device then. On the device itself, the CSR is shown in ''General/Certificates''.

[[Image:PHP_based_Update_Server_V2_CSR.png]]

==== Certificate Errors ====
When a signed certificate request uploaded to the device can not be installed on the device, you will see a message like <code>Certificate upload error - certificate handling stopped</code> in the ''Certificates'' columns for the device. In this case, any further processing will be stopped. Most likely, the reason is that you uploaded the wrong file as signed certificate request (either not a signed certificate at all or a signed request for another device).

In this case
* remove any certificate request from the device
* remove the <code>X509/REQUESTERROR</code> from the device configuration (i.e. <code>vars del X509/REQUESTERROR</code>)
: these 2 steps can be easily done by resetting the device to factory defaults and then set the ''Update URL'' again
* remove any stored files for the device on the update server (shown in the ''Certificates'' column)

The normal process will start all over again then.

=== Migrating old PHP Update Server Installations ===
==== Migrating from build 2000 and newer ====
* Copy all files and folders, '''except''' the ''scripts'' and ''config'' folder, from the source to your destination
* make sure all files and directories have correct owner (''www-data''), group (''www-data'') and mode (''read''/''write'' plus ''execute'' for directories)
: for example, in WinSCP you can use the ''Properties (F9)'' dialogue on the installations root folder:
: [[Image:PHP based Update Server V2-WinSCP-Properties.png]]
* open the ''StatusPage'' and make sure you refresh all cached files in your browser (depending on your browser, this may happen with Ctrl-R or Ctrl-F5)

==== Migrating from build 1011 and older ====
To upgrade from the [http://download.innovaphone.com/ice/wiki-src/index.php?urloffset=php-update-server%2F&name=php-update-server+%28all+available+builds%29&reverselevel=0&maxbuilds=999&root=c%3A%2Finetpub%2Fwwwroot%2Fdownload%2Fice%2Fdownload%2Fp%2Fwiki-src%2Fphp-update-server%2F1010+%28PHP+based+Update+Server+final%29%2F.. old version (builds up to 1011)] of the PHP based update server (as described in [[Howto:PHP based Update Server]]), do the following

* diff your <code>config.xml</code> to the one originally shipped (you can download it at [http://download.innovaphone.com/ice/download/p/wiki-src/php-update-server/1011%20(PHP%20based%20Update%20Server%20final)/php-update-server-1011.zip download.innovaphone.com/ice/wiki-src])
: take note of all the changes you made to it
* install the new version of the update server to a different URL
* configure it according to your needs by modifying <code>user-config.xml</code>. Do not modify the new <code>config.xml</code>!
** apply all modifications you did to your old <code>config.xml</code> to your new <code>user-config.xml</code>
** if you have used a custom setting for fwstorage/@url, you need to change it a bit. Change for example <code>url="http://myfwserver.mycompany.com</code> to <code>http://myfwserver.mycompany.com/{build}/</code> (note the trailing slash!)
* copy all your update script snippet files from the old server (these are all the .txt files in the old server's root directory) to the <code>scripts</code> directory of your new server
* copy the complete <code>fw</code> tree from the old server to the <code>fw</code> directory of your new server
* thoroughly test your new installation with some test devices
* when satisfied, edit <code>update-migrate.php</code> and change the code as described in the comment inside the file
* copy <code>update-migrate.php</code> from the new installation to the old installation
* on one of the devices which are currently served by the old update server, change the ''Command File URL'' so that it points to <code>update-migrate.php</code> instead of <code>update.php</code>. Do not change anything else in the URL. So if it currently is set to e.g.
: <code>https://172.16.0.90/update/update.php?type=#t&env=sifi&polling=0&phase=update</code>, change it to
: <code>https://172.16.0.90/update/update-migrate.php?type=#t&env=sifi&polling=0&phase=update</code>
* verify that this device properly switches to your new installation
** the ''Command File URL'' is changed so that it points to the new installation
** the device shows up in the device status page of your new server

* rename <code>update.php</code> to <code>update-old.php</code> in your old update server
* rename <code>update-migrate.php</code> to <code>update.php</code> in your old update server
* verify that all of your devices start showing up in the new server's status page

=== Complete Parameter Reference ===
Note: attributes are marked with an ''at'' (<code>@</code>) prefix. So ''master/@info'' refers to the ''info'' attribute in the ''master'' tag.

The following tags and attributes are available in the <code>user-config.xml</code> file, their default values are configured in <code>config.xml</code> (which you should not modify):

==== master ====
Defines the reference device where the firmware and boot code information is taken from.
; master/@info : the URL to the device info data. Set it to an URL like <code>http://</code>''your-reference-device''<code>/CMD0/box_info.xml</code>. Please note that this device must not have the ''Password protect all HTTP pages'' set in ''Services/HTTP/Server''. If you use the literal <code>none</code>, the master device will not be queried
; master/@expire : the firmware info cache lifetime. The firmware information is cached in a file (to make sure this information is present even if the reference device is off-line). The cache will not be refreshed before the ''expire'' time (in seconds) is expired
; master/@cache : the cache file name. The web server must be able to write this file (see [[#Installation | ''Installation'' ]] above)
; master/@user : if non-empty, this is the user name required to access the update server's web ui
; master/@password : the password

From build 2009, you can control the firmware and bootcode version to use on update:
; master/@firmware : if set, it may be one of
:: <code>master</code> (default if not set) : the firmware version is derived from the master device
:: <code>none</code> : the firmware update is generally disabled
:: ''build-number'' : the firmware is set to a certain ''build-number'' regardless of the firmware running on the master device
; master/@bootcode: if set, it may be one of
:: <code>master</code> (default if not set) : the bootcode version is derived from the master device
:: <code>firmware</code> : the bootcode version is set to the firmware version. This may be useful if the master device has no bootcode (e.g. the ipva)
:: <code>none</code> : the bootcode update is generally disabled
:: ''build-number'' : the bootcode is set to a certain ''build-number'' regardless of the bootcode running on the master device

<syntaxhighlight lang="html5">
<master
info="http://172.16.0.10/CMD0/box_info.xml"
expire="3600"
cache="cache/master-info.xml"
user="myadmin"
password="mysecret"
firmware="4711"
bootcode="firmware"
/>
</syntaxhighlight>

==== master/applies ====
Available from build 2009.

Boot code and firmware updates are only executed by devices which match all of the given <applies> conditions. A condition is met if the device belongs to the class that is given as tag content. If the ''env'' attribute is set, the tag content is interpreted as an ''environment'' name which has to match.

; master/applies/@env : if this attribute exists, the tag content is compared with the environments the device is in. Otherwise, it is compared with the classes it is in
<syntaxhighlight lang="html5">
<master
info="http://172.16.0.10/CMD0/box_info.xml"
expire="3600"
cache="cache/master-info.xml"
user="myadmin"
password="mysecret"
firmware="4711"
bootcode="firmware">

<applies>phone</applies>
<applies env="">berlin</applies>
</master>
</syntaxhighlight>

==== fwstorage ====
Defines from where the device will retrieve the firmware files for updates.
; fwstorage/@url : defines the URL to retrieve the files from. In this URL, the following meta words will be replaced as follows:
:* <code>{build}</code> - the requested firmware or boot-code
:* <code>{model}</code> - the devices type (e.g. <code>IP232</code>). This is derived from the ''type'' query argument used in the update URL which is set to the value <code>#t</code> which in turn is expanded to the [[Reference10:Concept_Update_Server#Scfg_command|''device type'']] of the device requesting the update script
:* <code>{filetype}</code> - the type of the required file, either <code>boot</code> or <code>prot</code>
:* <code>{filename}</code> - (from build 2014) the boot code or firmware filename for the device in lower case. Required if you use the LAP as firmware storage and firmware files are falsely requested in uppercase letters (as URLs on the LAP are case sensitive and if the files are requested with upper case names, the original files with lowercase name are not found). This also allows you to use alternate firmware file names (such as e.g. <code>ip110-sip.bin</code>). See the ''filenames'' tag
Note that if the ''url'' ends with a slash (<code>/</code>), the calling device will automatically [[Reference10:Concept_Update_Server#Prot_command|append the name of the requested file]]. In this case, the file system the URL points to must therefore contain sub-directories for each firmware build which contain the corresponding firmware builds (e.g, ''fw/12345/ip232.bin''). If ''url'' is not an URL (as is the case for the default value <code>fw/{build}/</code>), it is treated as a sub-directory underneath the update server's root directory

<syntaxhighlight lang="html5">
<fwstorage url="fw/{build}/"/>
</syntaxhighlight>

===== Loading firmware files from innovaphone.com =====
You can also load firmware from the innovaphone.com web site. To do so, set ''url'' like so:

<syntaxhighlight lang="html5">
<fwstorage url="http://webbuild.innovaphone.com/{build}/"/>
</syntaxhighlight>

Please note that ''this is a voluntary service, no guarantee of availability, no service level agreement''.

[[User:Ckl|ckl]] 15:40, 21 February 2023 (CET) This service has been discontinued. You may consider using <code>https://store.innovaphone.com/release/download/{build}/</code> instead.

==== backup ====
Defines where backup files are kept.
; backup/@dir : the directory underneath the script directory where backups are stored
; backup/@nbackups : the number of different backup files kept
; backup/@scfg : the target URL for the scfg command. If this is not an url, it is interpreted relative to the script directory URL. You can add more options for the ''scfg'' command, like in <code>scfg="update.php?mode=backup&hwid=#h&sn=#m ser hourly /force 1"</code> (this example will make sure backups are attempted only once per hour, so as to reduce load on the server).

<syntaxhighlight lang="html5">
<backup
dir="backup"
nbackups="10"
scfg="update.php?mode=backup&hwid=#h&sn=#m"
/>
</syntaxhighlight>

==== status ====
Defines details regarding the state kept for a device requesting an update script.
; status/@dir : the directory the status files are kept in (e.g. <code>status</code>). Used as the name for a sub-directory underneath your install directory on your web server. You must make sure that files in this directory cannot be read by anyone without proper authentication, as such files may contain sensitive information.
; status/@expire : if set and not empty, devices which have not requested an update script will be removed from the inventory after ''n'' seconds. For example, ''expire="7776000"'' will forget about devices after 90 days with no contact
; status/@missing : devices are shown in a different colour (indicating that they are ''missing'') after ''n'' seconds. For example, ''missing="604800"'' will flag devices as missing after 7 days with no contact
; status/@refresh : if set and not empty and larger than zero, the admin user interface showing the known devices will refresh the status of all shown devices each ''n'' seconds
; status/@logkeep : number of seconds log messages for individual devices will be kept
; status/usehttpsdevlinks : if set to true, links to devices in the status page are created using the https:// scheme
<syntaxhighlight lang="html5">
<status
dir="status"
expire="7776000"
missing="200"
refresh="10"
logkeep="90"
usehttpsdevlinks="true"
/>
</syntaxhighlight>

==== times ====
Defines details regarding the delivery of update scripts to requesting devices.

; times/@dir : the directory the update scripts are stored in. For security reasons, you may want to make sure that files in this directory cannot be read without proper authentication.

These attributes define the arguments of the [[Reference10:Concept_Update_Server#Times_command | times command]]. If neither ''allow'' nor ''initial'' is set, no ''times'' command is used (that is, the update scripts will be processed at all times).
; times/@allow : the hours to be used in the ''times'' command (as in <code>mod cmd UP1 times /allow </code>''hours'')
; times/@initial
: the minutes to be used in the ''times'' command (as in <code>mod cmd UP1 times /initial </code>''minutes''). If you want to use initial staging of virgin devices ''forcestaging'' must be <code>true</code>.

Delivered update scripts can include a [[Reference10:Concept_Update_Server#Check_command | check command ]] if the ''check'' attribute is set to <code>true</code>. . In this case, the devices will executed the scripts again only when you have edited/changed them.
; times/@check : if set to true, update scripts will be executed once only (unless their contents change)

When editing a number of update scripts, it is often not desirable if one changed script is already executed before another is changed too. When the ''grace'' attribute is set to a positive value, no script at all is delivered to requesting devices unless ''n'' seconds have expired since the last edit. For example, setting ''grace'' to 90 gives you one and a half minute to finish all your edits.

; times/@grace : defines the number of seconds that must expire before update script changes take effect

The update server works in either ''fast'' or ''normal'' mode. In ''fast'' mode, update scripts have to be requested more frequently, for example to step through multiple staging phases faster. This is enforced by modifying the calling device's ''Interval'' setting in [[Reference11r1:Services/Update | ''Services/Update '']] and setting it to 1 in ''fast'' mode.

; times/@interval : polling interval in minutes for normal operation (that is, when all staging is done)
; times/@polling : when you are using multiple ''phases'' (e.g. ''staging'' and ''update''), this defines the number of seconds to wait before the device reads the scripts for the next phase (see [[Reference10:Concept_Update_Server#Provision_command | provision command]]) (please do not modify the default value)

In some installations it may be desired to deliver update scripts with HTTPS only or even only to calling devices which have identified themselves with a proper TLS certificate.

; times/@forcehttps : if set to <code>true</code>, update scripts will only be delivered if the device call in with HTTPS. If the device is ready to receive an update script and still calls in with HTTP only, its ''Command File URL'' will be re-configured to use HTTPS automatically.
; times/@httpsport : if you use a non-standard port for HTTPS access to update scripts, it can be defined here
; times/@httpsurlmod : if your HTTPS URL differs from the HTTP URL, you can specifiy a ''modifier''. It has the form <code>!</code>''pattern''<code>!</code>''replacement''<code>!</code> where ''pattern'' is a [http://docs.php.net/manual/en/pcre.pattern.php PHP PCRE pattern]. For example, <code>!mtls/!!i</code> will remove the string <code>mtls/</code> from the URL used by the device to create the HTTPS URL to use. The delimiter (in this case "!") can be changed according to your own wishes, the first character defines the delimiter. The "i" at the end ignores uppercase.

Note: If you want to change the hostname of your URL, you have to add the Port 444 to your hostname. The code should then look like this: <code>!hostname1:444/mtls/!hostname2:444/!i</code>.
; times/@forcetrust : if set to <code>true</code>, update scripts will only be delivered if the device call in with HTTPS and a valid and trusted client certificate that identifies itself as the devices it claims to be
; times/@forcestaging : before build 2009, the restrictions imposed by the times/@allow settings affected all update ''phases''. This however makes staging cumbersome, as you usually want to restrict normal configuration changes to off-working-hours. If it is <code>true</code>, the restriction will be applied only to the last phase (that is, the ''staging'' phases will execute immediately). Also, the final phase will be executed once by staged devices.
: Since build 2021 the standard value was changed to <code>true</code>.

<syntaxhighlight lang="html5">
<times
dir="scripts"
allow=""
initial=""
check="true"
polling="5"
interval="15"
grace="90"
forcehttps="true"
httpsport="444"
forcetrust="false"
httpsurlmod="!mtls/!!i"
forcestaging="true"
/>
</syntaxhighlight>

==== phases ====
Defines the scripting phases. In many installations, there are initializations which should be performed once only. This is known as the ''staging'' phase. Once this is done, the devices continue with the execution of the normal update scripts (this phase is known as ''update'' by default). In the (unlikely) event that you want more or less phases, you can add/remove ''phase'' tags.
==== phases/phase ====
; phases/phase/@id : the name for the phase
; phases/phase/@seq: the sequential number for the phase. Phases are stepped-through in the numeric order defined by their ''seq'' attribute.

By virtue of the ''seq'' attribute, you can insert phases in to the set of phases defined by default, which is
<syntaxhighlight lang="html5">
<phases>

<phase id="staging" seq="100"/>
<phase id="update" seq="200"/>
</phases>
</syntaxhighlight>
For example,
<syntaxhighlight lang="html5">
<phases>
<phase id="phase" seq="150"></phase>
</phases>
</syntaxhighlight>
will insert a custom phase ''myphase'' as second phase.

==== environments ====
Defines the distinguished environments. Devices can have zero or more ''environments'' associated. The environments a device is considered to be in must be passed as <code>?env=</code>''name1,name2,..'' URL query arg in the update url.

Update scripts for all environments listed will be applied.
First the environment scripts itself, then all implied environments in the same order as the ''implies'' tags are listed in the config.

The default config file defines the environments ''intern'' and ''homeoffice'' but you can define your own if you like.

==== environments/environment ====
; environments/environment/@id : the name for the environment

==== environments/environment/implies ====
Each ''environment'' may have a number of sub-tags of type ''implies''. It contains the ''id'' of another ''environment''. If a device is in an environment with an ''implies'' sub-tag, it is assumed that it is in the implied environment also.
<syntaxhighlight lang="html5">
<environments>
<environment id='hq'>
<implies>intranet</implies>
</environment>
<environment id='intranet'/>
<environment id='homeoffice'/>
</environments>
</syntaxhighlight>
The <code>implies</code> tag handles no recursion (therefore, in the above example, if ''intranet'' would have an implies, a device in environment ''hq'' would not inherit this implication. Instead, you must list it explicitly for the ''hq'' environment).

If multiple environments will be used they will be applied also in the same order as the ''environment'' tags are listed in the config.

;There are some special things to keep in mind when adding multiple environments in the ''env'' attribute and they use the ''implies'' tag in the config.
:- The first environment specified in the arg ''env'' will be processed as expected with all children.
:- Recursive ''implies'' from an environment added via ''implies'' is not performed. (No children's children)
:- Only the first environment which is specified in the ''env'' arg with implies is processed, all additional values in the arg ''env'' will be ignored.
:- If the environment in the arg ''env'' it is not the first value, then it must also use the ''implies'' config to implies itself. Otherwise only child are processed.

==== classes ====
Defines the available device classes. Devices of different classes (e.g. phones and gateways) can have different update scripts. The device class is derived from the <code>#t</code> (device type) query arg of the update script URL (which is why you must configure it in the update URL). By default, the classes ''phone'', ''opus_phone'', ''pre_opus_phone'', ''phone_oldui'', ''phone_newui'', ''mobile'', ''gw'', ''fxogw'', ''fxsgw'', ''brigw'', ''prigw'' are recognized (newer versions may include more and/or updated class definitions). Also, any device is considered to be member of a class that has the device type as class-name. For example, an IP112 is in a class called ''ip112''.

A given device can be in multiple classes and will execute all update scripts available for these classes.

==== classes/class ====
Each ''class'' has a number of sub-tags of type ''model''. It contains the value replaced for the <code>#t</code> query arg. The models listed belong to the class.
; classes/class/@id : the name of the class

<syntaxhighlight lang="html5">
<classes>
<class id="gw">
<model>ip0010</model>
...
</class>
<class id="phone">
<model>ip110</model>
<model>ip232</model>
...
</class>
<class id="phone_oldui">
<model>ip110</model>
...
</class>
<class id="phone_newui">
<model>ip232</model>
...
</class>
</classes>
</syntaxhighlight>

==== nobootdev ====
Device types listed here do not receive boot code updates.
===== nobootdev/model =====
Each model tag defines a device type that shall not receive boot code updates.

<syntaxhighlight lang="html5">
<nobootdev>
<model>ipva</model>
<model>ipvadec</model>
<model>swphone</model>
<model>mypbxa</model>
<model>mypbxi</model>
</nobootdev>
</syntaxhighlight>

==== nofirmdev ====
Device types listed here do not receive firmware updates.
===== nofirmdev/model =====
Each model tag defines a device type that shall not receive firmware updates.

<syntaxhighlight lang="html5">
<nofirmdev>
<model>swphone</model>
<model>mypbxi</model>
</nofirmdev>
</syntaxhighlight>

==== filenames ====
Available from build 2014. Allows you to define alternate firmware and boocode names for use with the <code>{filename}</code> replacement (see the ''fwstorage'' tag), if required.

===== filenames/model =====
Each model defines a set of alternative file names for a certain device type.
; filenames/model/@id : the (lowercase) device type identfier (e.g. <code>ip112</code>). If this matches the device type of the calling device, the alternate file names are replaced
; filenames/model/@prot: the alternate firmware file name
; filenames/model/@boot: the alternate boot file name
<syntaxhighlight lang="html5">
<filenames>
<model id="mypbxa" prot="mypbx.apk"/>
</filenames>
</syntaxhighlight>

defines the firmware file name <code>mypbx.apk</code> for the device type <code>mypbxa</code>.

==== stdargs ====
Better don't touch :-)

==== customcerts ====
innovaphone hardware devices come with a device specific, trust-able ''device certificate''. However, in many situations it is desirable to roll-out customer-created ''custom certificates'' to all devices. The update server can do this. This will replace the shipped devices certificates both on hardware devices (where all such certificates are derived from innovaphone's certificate authority) as well as on soft devices which run with a self.-signed certificate by default (such as the software-phone or ''myPBX for Android/iOS'').

; customcerts/@dir : the name of the directory underneath your installation directory which stores device certificates. you should make sure that this directory cannot be accessed without proper authentication
; customcerts/@CAkeys : a file name pattern (e.g. <code>CAkey*</code>). All files in ''customcerts/@dir'' which match the pattern must contain DER or PEM encoded public keys which form the ''certificate chain'' of your CA (usually it is only one and the public key of your CA). One key per file. The files, when sorted by name, must contain the CA key itself in the last file (any intermediate certificates, if any, in the other files in correct order)
; customcerts/@CAtype : must be <code>manual</code> currently
; customcerts/@CAname : a comma-separated list of CA names. Devices presenting a certificate signed by one of these CAs will be considered as having a valid certificate. Otherwise, they wil be instructed to create a ''certificate signing request'' (CSR) for subsequent submission to your CA
; customcerts/@CAnamesep : defines the name separator for ''customcerts/@CAname''. The default is '<code>,</code>' and you must change it to a different value if one of your CAs includes a comma in its name
; customcerts/@renew : if set and not 0, certificates are replaced by new ones ''n'' days before they expire
; customcerts/@CAwildcard : normally, the update server will accept a certificate only if its CN matches the device's serial number. However, sometimes, so-called ''wildcard certificates'' such as <code>*.innovaphone.com</code> are used on a device (e.g. on a PBX or on a ''reverse proxy''). If set, the update server will also accept a certificate that contains a CN which equals the value of ''customcerts/@CAwildcard''. Note that the CN must match literally. For example, if ''''customcerts/@CAwildcard'' is set to <code>*.innovaphone.com</code> a CN like <code>host.innovaphone.com</code> is not accepted

When the update server determines that a device calls in with an un-trusted or expired certificate, it will have it create a signing-request for a new certificate. The requested certificate properties can be defined:

; customcerts/@CSRkey : the key size, e.g. <code>2048-bit</code>. Note that we do not recommend keys larger than 2048 bit (see [[Reference7:Certificate_management#Certificate_Key_Length_and_CPU_Usage]] for details)
; customcerts/@CSRsignature : the signature algorithm, e.g. <code>SH256</code>
; customcerts/@CSRdn-cn : the CN (''common name'') part used for the DN
; customcerts/@CSRdn-ou : the OU (''organizational unit'') part used for the DN
; customcerts/@CSRdn-o : the O (''organization'') part used for the DN
; customcerts/@CSRdn-l : the L (''locality'') part used for the DN
; customcerts/@CSRdn-st : the ST (''state or province'') part used for the DN
; customcerts/@CSRdn-c : the C (''country'') part used for the DN (note: ''CSRdn'' for many CAs, must be a 2-letter ISO country code)
; customcerts/@CSRsan-dns-1 : the first of up to three DNS names
; customcerts/@CSRsan-ip-1 : the first of up to two IP addresses

Within the set of CSR attributes, the following meta-words will be replaced:

* <code>{realip}</code> : the real IP address of the device as reported in the <code>ip=#i</code> query argument
* <code>{ip}</code> : the IP address of the device as seen by the update server
* <code>{proxy}</code> : the IP address of the reverse proxy the device used to reach the update server
* <code>{sn}</code> : the serial number of the device as reported in the <code>sn=#m</code> query argument (e.g. <code>009033030df0</code>)
* <code>{hwid}</code> : the hardware-id of the device as reported in the <code>sn=#m</code> query argument (e.g. <code>IP1200-03-0d-f0</code>)
* <code>{name}</code> : the ''Device Name'' (set in ''General/Admin'') of the device
* <code>{rdns}</code> : the DNS name found in a reverse DNS lookup for the real-ip address reported by the device (see ''{realip}'') above

<syntaxhighlight lang="html5">
<customcerts
dir="certs"
CAkeys="CAkey*"
CAtype="manual"
CAname="innovaphone-INNO-DC-W2K8-Zertifizierungsserver"
CAnamesep=","
CAwildcard="*.innovaphone.com"
CSRkey="2048-bit"
CSRsignature="SH256"
CSRdn-cn="{hwid}"
CSRdn-ou=""
CSRdn-o=""
CSRdn-l=""
CSRdn-st=""
CSRdn-c=""
CSRsan-dns-1="{name}.company.com"
CSRsan-dns-2="{hwid}.company.com"
CSRsan-dns-3="{rdns}"
CSRsan-ip-1="{realip}"
CSRsan-ip-2=""
renew="90" />
</syntaxhighlight>

==== queries ====
If queries are defined and applicable for the calling device, it will be instructed to send certain information to the update server which will be stored in the device status file kept on the server. Each piece of such information is defined using a separate ''query'' tag.

; queries/@scfg : defines the URL used by the device to send the information. Normally not changed from the default

==== queries/query ====
Defines one piece of information to be submitted to the update server.

; queries/query/@id : a unique name for the query
; queries/query/@title : a title for this piece of information shown in the device status

<syntaxhighlight lang="html5">.

<query id="media" title="Media">
<cmd>mod cmd MEDIA xml-info</cmd>
<applies>*</applies>
<show title="NAT">concat(/state/queries/media/info/nat/@result, ' (', /state/queries/media/info/nat/@public-addr, ')')</show>
<show title="Server">concat('STUN: ', /state/queries/media/info/@stun, ' TURN: ', /state/queries/media/info/@turn, ' (', /state/queries/media/info/@turn-user, ')')</show>
</query>


<query id="registration" title="Registration">
<cmd>mod cmd PHONE/USER phone-regs /cmd phone-regs</cmd>
<applies>phone</applies>
<show title="State: User/Number">concat(/state/queries/registration/info/reg[@id = "0"]/@state, ': ' , /state/queries/registration/info/reg[@id = "0"]/@h323, '/', /state/queries/registration/info/reg[@id = "0"]/@e164)</show>
<show title="PBX/ID">concat(/state/queries/registration/info/reg[@id = "0"]/@gk-addr, '/', /state/queries/registration/info/reg[@id = "0"]/@gk-id)</show>
</query>
</syntaxhighlight>

==== queries/query/cmd ====
The content of this tag defines the command to be executed on the device which outputs the requested information. These are ''mod cmd''s typically.

<syntaxhighlight lang="html5">

<cmd>mod cmd X509 xml-info</cmd>
</syntaxhighlight>

See [[Howto:Effect_arbitrary_Configuration_Changes_using_a_HTTP_Command_Line_Client_or_from_an_Update#Using_the_Mechanism_for_Device_Status_Queries ]] for details on how to find out which commands to use.

==== queries/query/applies ====
Defined queries are only executed by devices which belong to the class that is given as tag content. If the ''env'' atribute is set, the tag content is interpreted as an ''environment'' name which has to match.

; queries/query/applies/@env : if this attribute exists, the tag content is compared with the environments the device is in. Otherwise, it is compared with the classes it is in (unfortunately, you can not combine both)
<syntaxhighlight lang="html5">

<applies>phone</applies>
</syntaxhighlight>

==== queries/query/show====
If one or more ''show'' tags are defined for the ''query'' tag, the data will be shown in the device status page. The values shown are defined by the tag content which is an XPath expression selecting the data from the device state. The XPath expression always begins with <code>/state/queries/</code>''query-id'' (as defined by the ''id'' attribute in the query tag).

; queries/query/show/@title : used as title when the values are displayed in the status page

<syntaxhighlight lang="html5">
<show title="NAT">concat(/state/queries/media/info/nat/@result, ' (', /state/queries/media/info/nat/@public-addr, ')')</show>
</syntaxhighlight>

== Hints for writing your update snippets ==
Writing update scripts is largely undocumented and sometimes tricky. Here are some general guidelines.

=== Using <code>config add/del</code> ===
Many setting are done using <code>config change</code> commands. So these are very useful in update scripts too.

The straight forward method to find out which commands you need is as follows:
* get a device of the type in question and do factory reset
* save the configuration to a file
* do the desired settings using the normal web admin UI
* save the resulting configuration to another file
* compare the saved files

Usually, you want to set only specific parts of the configuration line. For example, assume you want to set the default coder to ''OPUS-WB''. Your saved configuration line might look like

config change PHONE SIG /prot SH323 /gk-addr pbx.innovaphone.com /gk-id innovaphone.com /tones 0 /lcoder OPUS-WB,20, /coder OPUS-WB,20,k1

To set only the coder settings, you would set the relevant options with the <code>config add</code> command as follows:

config add PHONE SIG /lcoder OPUS-WB,20,
config add PHONE SIG /coder OPUS-WB,20,k1

You can also remove specific options, as in

config rem PHONE SIG /tones

which would remove the <code>/tones 0</code> from the configuration line for <code>PHONE SIG</code>.

Note that the PHP update server will add the

config write
config activate
iresetn

at the end of the delivered script automatically, so you do not need to do it yourself. In fact, it is not recommended to have any reset command in your snippets.

==== <code>config change</code> Lines with associated Passwords ====
Sometimes, there is a password associated with certain configurations. Consider the STUN/TURN configuration:

config change MEDIA /stun stun.innovaphone.com /turn turn.innovaphone.com /turn-user innovaphone /turn-pwd 2 /nat-detect 61

The TURN password, being sensitive, needs to be encrypted in your configuration. This is why it is stored as a ''VAR'', which provides encryption support (see below):

vars create MEDIA/TURN-PWD pc ....

Unfortunately, the relationship between an option and an associated VAR needs to be guessed. You can be sure that the module name in the <code>config change</code> matches the modules name in the <code>vars create</code> command. However, the variable name must be guessed.

You can also set the password in your script using the <code>vars create</code>, however, you may also consider using a <code>mod cmd</code> (see below) such as e.g.

mod cmd MEDIA form /cmd form /del %2Fstun-slow /stun stun.innovaphone.com /turn turn.innovaphone.com /turn-user innovaphone /turn-pwd my-turn-pw /nat-detect 61

=== Using <code>vars create</code> ===

Sometimes it makes sense to use <code>vars create</code> commands. The syntax is

<code> vars create </code>''<name> <flags> <value>''

A ''<name>'' is a module name followed by a variable name, optionally followed by an index. For example, a phone will store the currently selected main registration as <code>vars create PHONE/ACTIVE-USER p </code>''<index>''. So the module is <code>PHONE</code> and the variable name is <code>ACTIVE-USER</code>. When the variable is multi-valued, an index is added to the name. For example, the registration settings for all but the first registration are stored as indexed variable, as in <code>vars create PHONE/USER-REG/00001 p </code>''<settings>'', where <code>00001</code> is the index (registrations count from 0 in this case).

There are a number of flags which can be combined, the most prominent used in update scripts are:
; p : permanent. The var is stored in flash memory (you will almost always use this flag in update scripts)
; b : binary. The var value is binary. Its ''<value>'' is given as a bin2hex string
; c : crypted. The var value needs to be encrypted and the ''<value>'' given is crypted
; x : crypted, plain value. The var needs to be encrypted but the ''<value>'' is given as plain (that is, un-encrypted) text. This allows you to set an encrypted variable without encrypting the desired value

; l : log. Creates trace output whenever this VAR is modified

; n : no-reset. If the 'n' flag is given, setting the variable will not trigger the 'reset needed' condition. Whether or not setting a variable has an effect without a reset depends on the module using the variable. Unfortunately, there is no documentation on which variables this works for, and we do not intend to provide such documentation. In the end, you have to try it out.

Please note that, unless the 'n' flag is given, using <code>vars create</code> will ''always'' set the internal ''reset needed condition'' in the device (regardless which ''<value>'' is set, even when the current value is set again). This means that a subsequent <code>resetn</code> or <code>iresetn</code> will always trigger a reset. So if you use it, make sure that you use the ''times/@check'' ([[#times | see above]]) to protect your script from re-executing the snippet (and thus rebooting the device) all the time.


=== Using <code>mod cmd</code> ===
See [[Howto:Effect arbitrary Configuration Changes using a HTTP Command Line Client or from an Update]] for a discussion of how to use <code>mod cmd</code> in update scripts.

== Writing your own Dynamic Scripting Code ==
NB: this feature is available from build 2020.

By default, the update server delivers update scripts which are composed from a number of static files (so-called ''snippets''). Sometimes it makes sense however, to create such snippets dynamically (e.g. based on a database lookup). Here is how to do this.

Dynamic scripting is implemented by a user-supplied custom <code>class CustomUpdateSnippet</code>. The code for this class must be placed in to the file <code>config/scripting.class.php</code>. As a starter, sample class code is available in <code>config/scripting.class-sample.php</code>.

<syntaxhighlight lang="php">
<?php

/**
* to provide your own runtime generated snippets, rename this file to 'scripting.class.php' and
* implement the member functions
* $property will have one member called
*/

class CustomUpdateSnippet extends UpdateSnippet {

/**
* snippet to deliver after standard text snippets
* @return array of string
*/
public function getPostSnippet() {
return parent::getPostSnippet();
}

/**
* snippet to deliver before standard text snippets
* @return array of strings
*/
public function getPreSnippet() {
return parent::getPreSnippet();
}

/**
* do we want to suppress the standard text snippets?
* @return boolean
*/
public function sendStandardSnippets() {
return parent::sendStandardSnippets();
}
}
?>
</syntaxhighlight>

The sample code overrides of the classes member functions just call the base classes which do nothing at all. So if you just copy the sample code into <code>scripting.class.php</code>, nothing will change. However, if <code>getPreSnippet()</code> returns an array of strings (the parent class function returns an empty array), each array member will be sent to the calling device ''before'' the standard snippets are sent. Likewise, if <code>getPostSnippet()</code> returns an array of strings (the parent class function returns an empty array), each array member will be sent to the calling device ''after'' the standard snippets are sent. If <code>sendStandardSnippets()</code> returns false, the standard snippets will not be sent.

To determine the dynamic snippets to send, the user-provided <code>class CustomUpdateSnippet</code> has access to the members of its base <code>class UpdateSnippet</code>, namely the <code>var $statexml</code> member. This member contains a <code>SimpleXMLElement</code> object with all state information available for the calling device.

Here is a sample state found in <code>$statexml</code> (as output by the <code>dump()</code> member function):

<syntaxhighlight lang="html5">
<?xml version="1.0"?>
<state seen="1522065435" requested="130774bootcode" phase="update">
<device sn="00-90-33-3e-0c-57" type="IP112" classes="phone, opus_phone, phone_newui, hstrace, ip112" ip="127.0.0.1" rp="false" phase="update"
environments="sifi, 172net" certstat="either certificate handling or state tracking not enabled - not doing any certificate checking" hwid="IP222-46-5c-77" realip="172.16.80.241" requestDownloaded="false"/>
<firmware requested="130986" requested-at="1522065435"/>
<bootcode requested-at="1522065435"/>
<config filename="scripts/all-all-all.txt" delivered="1522065426" version="1486559970"/>
</state>
</syntaxhighlight>

The most interesting elements in this XML are probably the attributes of the <code>state</code> and the <code>device</code> tags.

== Hints for using custom SSL Certificates ==

Using your own SSL certificates can be useful depending on the scenario.

We have two methods to accomplish this:

=== Standard scenario as described in this wiki article ===
The idea is that each certificate request is checked manually, edited and the UpdateServer is provided with the new device certificate.

=== Special scenario with automated certificate renewal ===
The idea is that every new/unknown (untrusted) device connects to the staging server. Here the device is released by manual checking/authorization by getting its first certificate. All further extensions can happen automatically afterwards.

'''Important: All important settings concerning file permissions, access and co must be used from the above article and are only skipped in this part!'''

We will create two Update-Server instances with the following configuration.

# Staging Server (HTTPS/443)
#*Put the sources in <code>/var/www/innovaphone/update</code>
#*Use your specific SSL configuration ''<customcerts>'' as described [[#customcerts | above]].
#*Use the following settings in the configuration of ''<times>'':
#*:<code>force https = "true"</code>
#*:<code>httpsport = "444"</code>
#*:<code>force trust = "true"</code>
#*:<code>httpsurlmod = "!update/i!!"</code>
#*Activate the query ''certificates'' as described [[#Delivering_Custom_Certificates | above]]
#*Configure the firmware update via the master tag as described [[#Delivering_Firmware_and_Boot_Code| above]]
#* '''Important''': Do not submit any further customer specific device configurations in the staging Server
# Final MTLS / 444 update server
#*Put the sources in <code>/var/www/innovaphone/mts</code>
#*Use your specific SSL configuration ''<customcerts>'' as described [[#customcerts | above]] with <code>renew = "x"</code>
#*Use the following settings in the configuration of ''<times>'':
#*:<code>force https = "true"</code>
#*:<code>httpsport = "444"</code>
#*:<code>force trust = "true"</code>
#*:<code>httpsurlmod = "!mtls/i!!"</code>
#*Activate the query ''certificates'' as described [[#Delivering_Custom_Certificates | above]]
#*Configure the firmware update via the master tag as described [[#Delivering_Firmware_and_Boot_Code | above]]
#*Store all customer specific device configurations

The meaning of the two different instances is:
*The staging server <code>https://[ip]/update/admin/admin.php</code> will generate the provisioning URLs for new devices.
*All new/unknown (untrusted) devices are only in the staging server.
**Here you can check the devices and provide them a valid certificate after check/authorization.
*With a valid certificate, the UpdateURL is automatically changed to the MTLS instance.
*As soon as a device connects via MTLS we trust this device and we can use an automatic extension of the certificates.
** Waiting CSR requests are in the configured folder ''certs'' in the notation <code>"[mac]-request.p10.pem"</code>
** If you operate your own CA, feel free to automate the reissue of the certificates via a sheduled Cronjob
*** Help for Linux: [[Howto:Creating_custom_Certificates_using_a_OpenSSL_Certificate_Authority]]
*** Help for Windows: [[Howto:Creating_custom_Certificates_using_a_Windows_Certificate_Authority]]
** If a signed certificate with the format <code>"[mac]-signedrequest.cer"</code> is placed in the certs folder, the certificate is automatically updated on the device.

== Optional Configurations on the Linux Application Platform ==
===Support for more Connections===
By default the LAP's web server lighttpd allows for 512 concurrent connections with 1024 open file descriptors. When you serve a huge number of devices with the update server, then this might be too low. You will see some devices not being able to contact the update server for a while. This should not be a real issue as the devices will retry. However, updating all devices may take long due to this.

In the lighttpd log (in <code>/var/log/lighttpd</code> on the LAP), you will see entries like this:

2017-10-16 13:45:18: (network_linux_sendfile.c.140) open failed: Too many open files
2017-10-16 13:45:18: (mod_fastcgi.c.3075) write failed: Too many open files 24
2017-10-16 13:45:18: (server.c.1434) [note] sockets disabled, out-of-fds
2017-10-16 16:23:25: (response.c.634) file not found ... or so: Too many open files /mtls/updatev2/web/innovaphone_logo_claim_fisch.png ->
2017-10-16 17:57:45: (server.c.1432) [note] sockets disabled, connection limit reached

If you experience such issues, proceed as follows:

* connect to the LAP with SFTP (e.g. using WinSCP)
* change directory to <code>/etc/lighttpd</code>
* edit <code>lighttpd.conf</code>
* search for the 2 lines which set <code>server.max-fds</code> and <code>server.max-connections</code>
* replace the standard values. We recommend to set the number of file descriptors to 4 times the number of requests when using the update server, e.g.
: old
:: server.max-fds = 1024
:: server.max-connections = 512
: new
:: server.max-fds = 8000
:: server.max-connections = 2000
* save the file
* restart linux (''Diagnostics/Reset/Reboot'')

Be sure to closely monitor the ''Diagnostics/Status'' page for a while after such configuration.

Also, when you update the LAP, you will have to re-do the changes (as always when you change something ''under the hood'').

=== Debug files rotation based on logrotate ===
If you have to debug during operation and a lot of devices access the PHP Update Server V2, you have to keep track of the debug files or automatically limit them. For this you can use logrotate on the innovaphone Linux AP. With logrotate you can apply time-based or size-based rules when files are packed and when they are deleted.
* open the LAP's file system using a SFTP client such as e.g. [https://winscp.net/eng/index.php WinSCP] (if you have not yet changed it, the default credentials will be <code>root/iplinux</code>, see [[Reference10:Concept_Linux_Application_Platform#Default_Credentials | Concept Linux Application Platform]]). Note that you must use SFTP rather than WebDAV, as WebDAV will not give access to the executable web server files.
* Under the path <code>/etc/logrotate.d</code> create a file e.g. <code>updateserver</code>.

<code>/etc/logrotate.d/updateserver</code>

In this file now enter the following content and save it.

<code>
/var/www/innovaphone/mtls/update/debug/*.txt {
size 5M
missingok
rotate 2
compress
delaycompress
notifempty
create 644 www-data www-data
}
</code>

This will include all *.txt files from the debug directory of the PHP Update Server V2 in the logrotate process of the operating system.

; size 5M : means every 5MB the file is rotated or zipped
; size 5k : means every 5kB the file is rotated or zipped
Alternatively, you can also rotate the file based on time
; daily : means that every day the file is rotated or zipped
; weekly : means that the file is rotated or zipped daily

; missingok : if a debug file does not exist, it will be ignored
; rotate n : files are removed before the last ones are deleted.
; compress : compresses the old debug files
; delaycompress : compresses the debug data only after it has been moved once
; notifempty : empty log files are not rotated
; create 644 www-data www-data : creates a new, empty debug file with appropriate permissions

== Update Server and Reverse Proxy ==
It is possible to implement access to the update server through a ''reverse proxy'' (RP). However, you have to keep some issues in mind:
* ''Mutual Transport Layer Security'' (MTLS) is not possible
: MTLS requires a direct TLS connection between the two parties. An RP however would terminate the TLS connection and entertain two independent connections to the parties. This breaks MTLS. If you want to use MTLS and serve external clients, you must therefore provide a direct access to the update server (that is an external IP address either directly or through port forwarding)
: see [[#If_you_want_to_setup_MTLS-restricted_Delivery_of_Update_Scripts]] for details
* When using the RP, you can choose to forward encrypted traffic (HTTPS) arriving from external to the update server using HTTP (unencrypted). The update server however eventually rewrites the update URL in the calling devices configuration. In order to do this, it determines the type of the internal connection. So if the connection from the RP to the update server is using HTTP, it would create a ''http://...'' URL. Otherwise it would create an ''https://..'' URL (also, it would be using the same port). This way, if the RP forwards requests to the update server with HTTP, the synthesized new URL for the calling client would use HTTP too, even though the original request was sent with HTTPS. This may or may not be what you want (as all of your clients would end up using non-encrypted traffic). Even worse, it might not work at all, if the RP does not accept HTTP for example.

== Related Articles ==
* [[Reference10:Concept_Update_Server]]
* [[Reference12r1:DHCP_client]]
* [[Reference10:Concept_Linux_Application_Platform]]
* [[Reference10:Concept_Provisioning]]
* [[Howto:PHP_based_Update_Server]] (old version)
* [[Howto:Creating_custom_Certificates_using_a_OpenSSL_Certificate_Authority]]
* [[Howto:Creating custom Certificates using a Windows Certificate Authority]]
* [[Howto:Effect arbitrary Configuration Changes using a HTTP Command Line Client or from an Update]]

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

Reference8:TAPI Service Provider

2024-11-04T17:23:54Z

Ckl: /* Related Articles */

The ''innovaphone PBX V8.0 based TAPI Service Provider'' (TSP) is an enhanced version of the [[ Reference7:Unified Win32 and x64 TAPI Service Provider | previous TSP version ]] that takes advantage of the [[ Reference8:SOAP API | new SOAP features ]] provided with version 8 PBX firmware. It implements - like the previous versions - TAPI Version 3.0 without MSP (Media Service Provider).

The [[Reference7:Unified Win32 and x64 TAPI Service Provider| previous TSP ]] still must be used for V7 PBX systems.

This article describes how to install and use it as well how to configure the PBX in order for the TSP to work properly.

==Applies To==
This information applies to
* innovaphone PBX V8.0 based TAPI Service Provider, Build 8001 and later
* innovaphone PBX V8 and later (that is, this Service Provider runs with PBX Firmware V8 and later)

==More Information==

=== Enhancements ===
; Support for V8 firmware [[Reference8:Administration/PBX/Objects#Devices | devices]] : Each user object device is represented as a TAPI line (all sharing an identical address, the objects extension a.k.a. ''Number'' property). This now allows to select individual registration devices when multiple devices are registered with the same PBX. Please note that in V8, [[ Reference8:Administration/PBX/Objects/Edit_Forks | mobility devices ]] are not shown and thus not represented by TAPI line device. This was introduced in V9 only.
; Support for presence based lines : These are TAPI lines shown which reflect the users presence state. Presence state ''open'' is mapped to a TAPI device status ''in service''. Presence activity ''on-the-phone'' is mapped to a virtual call in state ''connected''.
: '''NB''': V8 PBX Firmware did set presence activity ''on-the-phone'' for each user object having a call. Unfortunately, as this does create performance issues, this behaviour has been removed from V9 PBX Firmware. The ''presence line'' feature may be useless with V9 PBX when the application did rely on this particular V8 PBX behaviour.

===System Requirements===
The TSP will install on any Windows 32bit and x64 platform down to Windows XP/Server 2003. For older systems, you must use a deprecated [[Reference7:TAPI_Service_Provider | previous TSP version]]. For systems running PBX firmware version 6 or earlier, you must use the even older [[Reference:TAPI_Service_Provider | version 5 based TSP]]. Note that there is no x64 version of the version 5 TSP!

The TSP needs to maintain parallel connections to each individual PBX in the system. For larger systems (i.e. systems with a huge number of PBXs), this may create substantial load to the underlying windows machine. The number of parallel activities scheduled by the TSP is thus limited as a function of the available main memory and number of processors. In particular, a maximum of 20 activities per available processor is allowed (up to build 8088, the limit is 60/processor for later builds). If this limit is exceeded, the TSP will issue performance warnings of class WARNINGS in the TSP log file and system TAPI performance will be poor. Use a more capable machine then.

Microsoft Windows operating system version for desktop clients (as opposed to server systems) limit the number and performance of TCP/IP connections. This may lead to bad performance or occasional request failures. We generally recommend to use server operating systems for 3rd party TAPI installations thus.

No special PBX licenses are required to use the innovaphone TSP.

=== Download ===
The TSP will be available on the tab ''Software'' in the [https://store.innovaphone.com/ Store].

===Installation===
Windows cannot run a Win32 TSP on an x64 platform (although it can run Win32 applications on such platforms). This is why there are 2 versions of the setup, the x64 installer (<code>setup64-release.msi</code>) and the Win32 installer (<code>setup32-release.msi</code>.

The ''release'' setup packages provided will install the retail version. This is recommended for production purposes but provides no debug options whatsoever. To track down possible problems, support may instruct you to install the debug version.

The TSP may be installed on each machine where a desired TAPI based
application is to be run. If for example, Outlook is to be used, then
each client PC running Outlook may have the TSP installed. Although
this is typical for a 1st party configuration, all clients may have full
3rd party functionality, that is, they may control all existing lines.

As an alternative, the TSP can be installed on a single machine and a
3rd party TAPI server product (such as the IXI-Call Server available as
a separate product) may be used to provide the network clients with a
TAPI interface. Also, Microsoft’s Remote TAPI Server should work but is not being tested, so you use it on your own risk.

To install,
* select and download the <code>setup32-release.msi</code> install packages on 32bit platforms or the <code>setup64-release.msi</code> install package on 64bit platforms.
* double-click the install package to launch the installer
[[Image:Unified Win32 and x64 TAPI Service Provider - zipcontent.png]]
* accept the license agreement
* select the target folder
* complete the installer

When the installer has copied all files to the target machine, you need to add the TSP to the machine's TAPI system
* open the ''Telephone and Modem'' control panel
* Switch to the rightmost tab (''Extras'')
* Click on the ''Add...'' button
[[Image:Unified Win32 and x64 TAPI Service Provider - Control Panel Add.png]]
* Select the innovaphone TAPI provider driver
* Fill out the configuration dialogue
* Install the provider by clicking ''OK''

==== File Organization ====
Windows forces all TAPI service provider files to reside in Windows' ''System Folder''. This is the <code>system32</code> folder in your windows install directory (usually <code>C:\windows\system32</code>), even if you are running an x64 platform! The installer will thus copy these files (<code>tsp8.tsp</code> and <code>tsp8UI.dll</code>) in to this directory. All other files however will be copied to the <code>innovaphone AG\innovaphone® PBX V8 TAPI Service Provider</code> folder underneath your systems ''Program Files Folder''.

The subdirectories <code>Debug</code> and <code>Logs</code> are created. <code>Debug</code> contains the driver's debug version, <code>Logs</code> will receive the log files when a debug version is used.

On x64 platform systems, the Win32 version of the configuration DLL (<code>tsp8UI.dll</code>) will be installed to the windows ''Windows on Windows64 System Folder'' (<code>SysWOW64</code>).

====Upgrading to a newer Version====
When you attempt to upgrade the TSP from a previous version, the Windows
installer will first remove any previous installation. When the new
software is installed then, the TSP will be installed again into the
TAPI system.

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

====Upgrading from the old Win32-only Version====
If you upgrade from the older Win32-only versions of the TSP (soap-appl/tapi/7.00 or soap-appl/tapi/5.00), you must first remove the old TSP from ''telephone and modem'' control panel and uninstall the old product from the ''Software'' (or ''Programs and Functions'') control panel.

When you upgrade from the old V7 64-bit TSP (soap-appl/tapi/7.00-64), you should first update this older version to the latest build available.

This procedure ensures that during the upgrade your TAPI lines retain their internal identifiers and thus their meaning in your TAPI application's configuration.

==== Uninstalling the TSP ====
To uninstall the TSP proceed as follows
* Remove the TAPI driver from the TAPI system using ''Telephony and Modem Control Panel''
* close ''Telephony and Modem Control Panel''
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* remove the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

You will notice that Windows may fail to remove the driver files from the ''Windows System Directory''. To clean up remove <code>tsp8.tsp</code> and <code>tsp8UI.dll</code> from the <code>system32</code> folder as well as - on x64 systems - from the <code>SysWOW64</code> folder.

Also, if you did file tracing, any remaining debug files in the <code>Logs</code> folder are left over and need to be removed manually.

The TSP will create some entries in the windows registry which will not be removed on uninstall. It is recommended to leave these entries as is. Only if you are sure you will never install the TSP again on this system or you are sure you will never use it with the PBX installation you used so far, you may want to delete them from the registry.

==== Rolling out First Party TSPs to multiple PCs ====
Normally, when multiple users require CTI and hence TAPI functionality, the best way is to use a server based, multi-client 3rd party CTI application. This will share all functions among all client PCs. If this is not an option, e.g. because the TAPI application in use does not support it, you may want to consider using Microsoft's TAPI Server and remote TSP. See Microsoft's [http://technet.microsoft.com/en-us/library/cc786297%28v=ws.10%29.aspx Telephony service providers overview] and [http://technet.microsoft.com/en-us/library/cc770373.aspx Manage Telephony Servers] documents.

If you still want to use the native innovaphone TSP on a number of PCs (instead of once on a server), you can roll out the TSP using some of the [http://support.microsoft.com/kb/816102/EN-US software deployment schemes Microsoft Server provide]. In such a case, you will likely want to deploy identical configurations to all these PCs. While this theoretically can be done by distributing registry settings, there will be a problem with the PBX access credentials. These are stored in encrypted format in the registry and can only be decrypted on the PC on which they have been set. That is, deploying such registry settings to other PCs will result in a non-functional setup.

To work around this problem, you may store the credentials in clear text in the registry. To do so, you would put the ''Password'' in a REG_SZ value named <code>admin1-free</code> and the ''Account'' into a REG_SZ value named <code>admin2-free</code>. If such a value is found in the proper place in the registry, the values configured using the telephony control panel are ignored.

[[Image:TAPI Service Provider-tsp8-nocrypt.png]]

'''Keep in mind that having credentials in clear in the registry presents a security risk!'''

This feature is available in build 8079 and later.

=== Upgrade from Build 8164 or earlier ===
From build 8165, the TAPI configuration has been moved to a different registry location. This has been done because latest windows versions (namely, Windows 10) do not allow the TSP to access registry information in the location used so far (<code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>). To work around this issue, it is now stored in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>.

The TSP configuration dialogue however runs with user privileges (as opposed to the TSP which runs with limited service privileges). It can therefore read the old configuration information and copy it to the new location. From build 8165, the configuration dialogue will thus copy any old configuration information to the new location when it is opened. When you upgrade an existing installation and open the configuration dialogue, you will see no change. However, when the configuration is saved, it is then present in the new location.

'''To upgrade an installation from build 8164 or earlier (that is TAPI 'V8 TAPI Service Provider (32 and 64bit) - hotfix14'' available in the ''V8 applications hotfix20'' package or earlier), proceed as follows:'''
* stop the telephony service (e.g. <code>net stop tapisrv</code>)
* install the new TSP
* open the TSP configuration dialogue
* verify the configuration data
* save the configuration
* (re) start your TAPI application

If you fail to migrate the configuration as described, the TSP will start, but not work!

===Configuration===
The TSP configuration dialogue looks like this:

[[Image:Unified Win32 and x64 TAPI Service Provider - Config UI.png]]

* The ''VERIFY'' button will verify the configuration. Note that the ''Username'' drop down list will only be populated after a successful verify.
* The ''OK'' button will save the configuration.
* The ''CANCEL'' button will quit the configuration without saving any changes. If it is the initial configuration while you add the TSP via the telephone and modem control panel, the TSP will not be added

TAPI talks to the PBX using [[Reference7:SOAP_API | SOAP ]] which in turn uses HTTP for communication. Both secure (https) and non-secure (http) communication is supported. In any case, HTTP basic authentication is used.
To be able to connect to the PBX, the TSP needs to know proper credentials to use during HTTP authentication. These are referred to as ''PBX Account'' and ''PBX Password''. Also, a suitable ''TAPI User'' must be selected.

==== Controlling the Line Devices handled by TAPI ====

TAPI connects to your PBX as a PBX user referred to as ''TAPI User''. It will see all PBX objects that are members of groups in which the ''TAPI User'' is an active member. If the ''TAPI User'' is not an active member in any group, TAPI will see the ''TAPI User'' object only. This may be useful in a [http://en.wikipedia.org/wiki/Telephony_Application_Programming_Interface 1st party TAPI scenario]. PBX objects are represented as TAPI lines.

The PBX object you use as ''TAPI User'' needs to have at least ''Viewing only'' [[Reference:Administration/PBX/Objects/Edit Rights | PBX user rights]]. Its ''Long Name'' property is used as ''TAPI User Username'', its ''Name'' property as ''PBX Account'' and the password as ''PBX Password''. This is why the PBX object used as ''TAPI User'' must have a password configured.

===== 1st Party Configuration =====
In a 1st party scenario, the TSP will only work on a single PBX object. This will typically be a user's phone and thus the user itself will be used as the ''TAPI User''.

[[Image:Unified Win32 and x64 TAPI Service Provider - FirstParty.png ]]

In such a configuration the TSP is typically installed on the users PC and the CTI software is accessing TAPI directly (such as e.g. Microsoft Outlook does).

The TSP configuration dialogue will check for the number of lines seen. If it is only one, then it will issue a warning message:

[[Image:Unified Win32 and x64 TAPI Service Provider - OnlyOne.png]]

This is because 3rd party configurations are much more common and this situation often indicates a configuration problem. In a first party configuration, you can safely ignore this message.

===== 3rd Party Configuration =====
In a 3rd party configuration, the TSP will work with multiple PBX objects.

[[Image:Unified Win32 and x64 TAPI Service Provider - ThirdParty.png]]

Typically, you will share a single TSP instance on a server system for use by several users on their desktop PCs. This is done by virtue of a ''TAPI Server''. There are various TAPI server products available on the market, including but not limit to the Estos ProCall product and the remote TAPI server included in Microsoft Windows server operating systems.

In this scenario, it is recommended to create a pseudo PBX user object for use as the ''TAPI User''. This pseudo user is often called <code>_TAPI_</code>. You would create a dedicated group to control the list of PBX objects the TSP creates a line device for. This group is often called <code>tapi</code>.

==== Selective Call Forwards ====
Many CTI applications support distinct call forwards for internal and/or external calls. The TSP will translate such requests to a call forward on the PBX which has the [[Reference7:Administration/PBX/Objects/Edit_CFs | ''Only'' or ''Only not'' property]] set to the number of the trunk line. For this to work, it needs to know this number. To know the number, the trunk line PBX object must be seen by the TSP (see above). If this is not the case, the TSP configuration dialogue will issue a warning:

[[Image:Unified Win32 and x64 TAPI Service Provider - NoTrunk.png]]

In a vanilla first party scenario, this is obviously not the case. If you don't care, you can safely ignore this issue. Attempts to set such call forward will be rejected then as ''operation unavailable''.

In a Master/Slave PBX scenario where there is no Trunk Line object on the Master PBX, but only on the Slave PBXs, a workaround is required to suppress the warning and enable selective call forwarding on the Slave PBXs. In this case, create a dummy "Trunk Line" object on the Master PBX with the same extension number used by the "Trunk Line" objects on the Slave PBXs (usually 0).

==== Multi Site Configuration ====
In a system with multiple PBXs, the TSP needs to connect to each of the individual PBXs.

[[Image:Unified Win32 and x64 TAPI Service Provider - MultiSite.png]]

In this case, you would specify your master PBX as ''PBX Master''. There is no need to configure the complete PBX tree to the TSP as it is determined dynamically on runtime by analysing the PBX/Node objects in the master PBX and their registration status. If a registered PBX is found, this PBX is added to the list of active PBXs and a new connection is established. The PBX tree is built and maintained dynamically. A reconfiguration or restart of the TSP is not required on changes thus.
For this to work

* the PBX object used as ''TAPI User'' must exist in each PBX with same properties (including name and the password). You may want to use <code>_TAPI_</code> as ''Name''/''Long Name''. This object must be ''active'' member in a group (which you may want to call <code>tapi</code>). A password must be set. The object must have at least ''Viewing only'' rights
* the slave PBX-objects (or in older firmware versions the slave PBX Node-objects) must be visible to the TSP (that is, must be non-active member of the group the ''TAPI User'' object is an active member of, e.g. <code>tapi</code>) so that the slaves are made known to the TSP.

In a replicated scenario, you would create a ''TAPI user'' as recommended above and [[Reference8:Administration/PBX/Objects#Objects_with_empty_node_or_PBX | leave the ''PBX'' and ''Node'' properties empty ]]. This user should then be used as both ''PBX Account'' and ''TAPI User Username'' in the TAPI configuration dialog.

''Further relevant settings'':

You can disable slave detection by checking ''Do not monitor slaves'' property in the TSP configuration dialogue.

TAPI maintains an ''address'' property per line device. This usually is the lines extension. In a multi site configuration, the address property will be set to the ''Number'' property of the node the respective PBX object is configured in, plus the ''Number'' property of the object itself. So if an object has ''Number'' <code>42</code> and lives in node <code>801</code>, then its correspondence line device will have address <code>80142</code>. By checking the ''Use pure node extensions'' property in the TSP configuration dialogue, you change the algorithm so that only the objects own ''Number'' is used (<code>42</code> in our example).

==== Standby Configurations ====
In a system with standby PBX for the master PBX, you need to specify the ''PBX Standby'' IP address. This will be connected if the master is unavailable. Note that there is no need to explicitly configure slave-standby PBXs.

==== Working with multiple, unrelated PBXs ====
When working with multiple, unrelated PBXs (that is, PBXs that do ''not'' form a PBX tree as slaves and masters do), the TSP cannot derive the list of PBXs to track from the registration status. To support such a configuration, you will need to configure the extraneous master PBXs manually using regedit. Please note that using regedit may harm your system and may even cause inability to boot!

To find and edit the right registry entries, proceed as follows:

* open the key <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>
* open its subkey <code>Device</code>''n'' where ''n'' is the provider id of the installed innovaphone TSP (for builds before 8164 only)
* Open the <code>FQDN</code> key and add all extra PBXs
* For those PBXs that have a standby PBX, add a value to the <code>StandbyFQDN</code> key (please note: these are parallel lists. So master and standby need to have the same respective index in the <code>FQDN</code> and <code>StandbyFQDN</code> value lists)

The standard configuration UI will not show these extra values. However, it will also not touch them. So even if you use the standard UI to edit, only the first value in the lists will be changed and the remainder left unchanged. You can thus safely use the standard UI to edit all other values. As with multi site configurations, all PBXs need to be accessible using the same ''TAPI User''.

Please note that this method is deprecated and will likely be removed from future versions of the TSP.

==== Setting the Line Device Name ====
The TSP will derive the line device's name from the properties of the respective PBX object. By default the name will be the objects ''Long Name'' followed by the name of the PBX the user ought to register with in parentheses. So if the users ''Long Name'' is <code>Foo Bar</code> and the registration PBX is <code>branch1</code>, the line device will be called <code>Foo Bar [branch1]</code>. You can specify a different pattern by changing the ''TAPI Line Names'' property of the TSP configuration dialogue. The following replacement characters are available:

{|
|+
| Meta || Replacement
|+
| %c || The objects ''Long Name'' (cn)
|+
| %C || The objects ''Long Name'' (cn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Long Name''
|+
| %d || The objects ''Display Name'' (dn)
|+
| %D || The objects ''Display Name'' (dn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Display Name''
|+
| %h || The objects ''Name'' (h323 alias)
|+
| %H || The objects ''Name'' (h323 alias) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Name''
|+
| %t || The ''Name'' of the ''Device'' the line represents
|+
| %T || The ''Hardware Id'' of the ''Device'' the line represents (from build 8181)
|+
| %e || The objects extension (e164)
|+
| %E || The objects extension (e164) prefixed with the objects node number
|+
| %N || The line address as reported to TAPI
|+
| %n || host name (of master pbx)
|+
| %p || ''':'''''port-number'' (of master pbx's http access, empty if 80)
|+
| %P || raw port number of master pbx
|+
| %u || url-like user name ('''''user''@''host''''')
|+
| %U || user url as per draft-levin-iptel-h323-url-scheme-04 ('''h323:://''user''@''host'':''port''''')
|+
| %X || the PBX name the user is registered with (note that using this pattern may result in a change of the name when a standby situation occurs)
|+
| %x || the PBX name the user is reported by (note that using this pattern may result in a change of the name when the users ''PBX'' attribute changes)
|}

The default pattern is <code>%C (%x)</code>.



==== Miscellaneous Flags ====
; Show full E164 Numbers : when set, the TSP will announce the full calling number from the root when indicated by the PBX in the TAPI ''calling party name'' attribute. The number will be appended to the calling name with a <code>@</code>.
; Do not show parked Calls : will hide parked calls from the TAPI application (as some get confused and don't know how to handle them)
; Map PBX Devices to Lines : if set, the TSP will create one TAPI line for each individual [[Reference9:PBX/Objects#Devices|PBX device]] configured in a user object. See [[#Enhancements]] above. If you do not set this flag, see [[Support:How should TAPI line device be registered?]]
; Map Presence Status to TAPI Lines : if set, the TSP will create one extra TAPI line for each PBX device object. See [[#Enhancements]] above.
; No special Disconnect Behaviour : normally, lines monitored by TAPI will behave slightly different when a call is terminated. With no TAPI on the line, the call will be disconnected immediately (from a PBX point of view). In cases where the phone would play some tones after termination of the call (e.g. a busy tone when the call has never been connected to the far end), this state is simulated by the phone and not visible to TAPI. Therefore, it is not possible to use TAPI functions on this call any more (as it in reality does not exist any more). When this flag is set, monitored lines will not be treated specially. Available from hotfix 6. To prevent the IP-Phone to play any tones after the call is disconnected, the phone preferences option '''Go onhook if final call is released by remote side even if handset is lifted''' can be activated. This is the feature of the IP-Phone is useful in a e.g. call center at agent phones and can be configured here [[Reference11r1:Phone/Preferences]].
: To prevent an innovaphone IP-Phone from playing any tones after a call is disconnected, the phone preferences option '''Go onhook if final call is released by remote side even if handset is lifted''' can be activated. This feature is useful for agent phones in a call center for example and can be configured in [[Reference11r1:Phone/Preferences]]

===Trouble Shooting===
The TSP will (from build 8095) write messages of type INFO (''informational messages'') or WARNING (''Warnings/Errors'') to the windows event log. Such events are always logged to the application log and event source is the provider name (''innovaphone® PBX V8 TAPI Service Provider'').

==== Turning on Debugging ====
There are 2 versions of the TSP, debug and retail, which are both copied to the machine during setup. The retail version is installed into the system directories, whereas the debug version is stored in a separate directory. This is available through a short cut in the Start menu.

The TSP can produce a number of debugging messages which can be helpful to debug issues (in both ''retail'' and ''debug'' builds). By default, debug messages are written to the systems debug buffer mechanism (using OutputDebugString()). Such messages can be examined using standard debugging tools, such as for example <code>dbgview</code> which is [http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx available from Microsoft].

Debug messages have a class associated with it and the amount of messages written can be controlled by enabling or disabling specific classes. This is done by setting a bitmask in the registry value <code>TraceLevel</code> in the <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/> key.

The easiest way to set the TSP's debug level is with the ''TSP Control'' utility (''tsptray.exe'') which is installed with the TSP.

The available classes include

{|
| Bit in <code>TraceLevel</code> || Class
|-
| 0x00000001 || Minimum tracing
|-
| 0x00000002 || TAPI api traces
|-
| 0x00000020 || Basic telephony object creation/destruction
|-
| 0x00000040 || Thread creation/destruction
|-
| 0x00000080 || Request creation/destruction
|-
| 0x00000100 || call related messages
|-
| 0x00000200 || Call id map
|-
| 0x00000400 || Warnings/Errors
|-
| 0x00000800 || Worker thread execution
|-
| 0x00001000 || Full lock/unlock notifications
|-
| 0x00002000 || Win32 Critical section create/destroy
|-
| 0x00004000 || Agent proxy support
|-
| 0x00008000 || constructor/destructor debug
|-
| 0x00010000 || development debugs
|-
| 0x00100000 || verbose debugging
|-
| 0x00200000 || SOAP trace
|-
| 0x00400000 || SOAP message dumps
|-
| 0x01000000 || ATL debug
|-
| 0x02000000 || line related messages
|-
| 0x04000000 || informational messages
|-
| 0x10000000 || dump call infos
|-
| 0x20000000 || dump PBX infos
|-
| 0x80000000 || output log messages to file
|}

If <code>TraceLevel</code> is not set, it defaults to (hex) <code>04000400</code> in retail builds and to (hex) FFFFFFFF in debug builds. A nice value to use is (hex) <code>92200580</code>. The <code>TraceLevel</code> can be changed during runtime of the provider (it may take up to 10 seconds though for the setting to take effect). In normal scenarios there is no need to install the debug version.

Both ''informational messages'' and ''Warnings/Errors'' are always turned on (from build 8095).

: A problem has been reported on Server 2008 x64 systems which may also apply to others. On such systems, the value of <code>TraceLevel</code> may be reset to its default every 10 seconds. A workaround is to change the account the Telephony service is running in from its default (usually ''Network Service'') to e.g. ''Local System''.

===== Crash Dumps =====
From build 8063 the TSP will write crash dumps to the log directory (usually something like <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8 TSP\Logs</code>) in case of a trap. In release installs, these are not very useful. For debug builds though, they include helfpul information. Please provide these files (the can be zipped to a great extent) to support if requested. A crash dump file will be called something like <code>TSP8build-hour#minute-day.month#seqnr.dmp</code>.

===== Forcing a Crash Dump =====
In rare cases, it may be useful to force a TAPI crash for debug reasons. This can be done by issueing a <code>lineMakeCall</code> with called number <code>0815</code>, called-subaddress <code>4711</code> and called-name <code>!crash!</code> or simply calling <code>0815|4711^!crash!</code> from phone.exe.

==== Saving Log Messages to a File ====
The <code>0x80000000</code> value is special, as it does not denote a message class. Instead, it turns on log file writing, both in retail and debug versions. For this to work, the registry value <code>DoTraceFile</code> must be set to <code>1</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/> when the TSP starts. If this value is not present, it defaults to <code>1</code> in both retail and debug builds. Setting it to 0 disables log file writing regardless of any other setting. This may save some CPU cycles for installations with a real large number of lines.

The TSP will keep 24 log files (a days worth) by default. This value can be changed using the <code>NumLogFiles</code> value in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>. Older log files will be removed. Also, when the TSP shuts down, it by default will remove all log files it created so far. However, any TSP will only remove log files created by itself. This ensures that if the TSP or the system terminates prematurely, the log files will be kept even if a new instance is started and terminated later on. Form TSP V8 hotfix 8 on, this behaviour can be tweaked by setting the DWORD registry value <code>KeepLogFiles</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>:
{|
| 0 || default || remove all log files on termination
|-
| 1 || || keep the last ''n'' log files (depending on <code>NumLogFiles</code>) on termination
|-
| 2 || || keep all log files
|}

Larger systems (500 monitored lines and more) can slow down considerably when writing extensive logs.

==== Installing the Debug Version ====
To install the debug version, you first install the retail version as outlined above. You then copy the debug driver files from the <code>Debug</code> directory to your windows system directory <code>system32</code>. You may want to use the shortcut to the <code>Debug</code> folder which has been installed to the start menu for convenience.

For the copy to work, proceed as follows
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* copy the debug driver files to your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>.(if the copying fails, we recommend to deactivate the telephony service. But don’t forget to reset it to automatically if you are done copying). Overwrite the existing files: <code>installer.dll, installer.pdb, TSP8.pdb, TSP8.tsp</code>
* if the copy does not succeed or the debug driver is not shown n the modem control panel after, it might be that a TAPI application re-starts the windows telephony before you actually to the copy. If so, you can set the ''Startup type'' of the Windows ''Telephony'' service to <code>Disabled</code> instead of ''Manual'' in the services control panel (''services.msc''). You can then ''Stop'' the services, copy the file and finally set the services mode back to <code>Manual</code>

When you open ''Telephony and Modem Control Panel'' again, you should notice that the TSP driver name has changed to the debug version.

==== Switching back to the Retail Version ====
To go back from the debug to the release version, proceed as follows:
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* delete the debug driver files from your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>
* repair the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

Please note that simply re-installing the driver from the original .msi without removing it from the system directory will not work.

===References===
The test applications provided with this setup comes from [http://www.julmar.com Julmar Technology Inc].

=== Limitations ===

Please note that there currently is a limitation to 2000 users being in
all active groups of a particular user. Thus, you cannot configure more
than 2000 users to be handled by TAPI on a single PBX. This is a PBX
limitation (and applies for all PBX groups).

TAPI has a flat line model. That is, all line numbers (aka
''extensions'') are considered to live in a single name space. As a
result, lines with identical numbers cannot be distinguished in TAPI
(although they can exist). All extensions in all nodes of a PBX
numbering tree are represented as TAPI lines. When the TSP works with a
PBX that implements a hierarchical numbering tree, then some lines may
receive identical numbers (their node-local extension which may overlap
between nodes depending on the setting of the ''Use pure node extensions'' property). When a TAPI application uses these numbers to initiate
calls to such lines, the call will work or not work depending on the
calling lines position in the numbering tree (that is, lines within the
same node as the called line will be fine, others may fail).

The PBX's SOAP interface (on top of which the TSP is built) has no primitives to initiate a directed call pick-up based on a target number. The TSP will reject such requests with ''Operation not available''. Pickup by name (which is understood as a group name) or unspecific is supported though.

==== Citrix Environments ====
What happens is that all Citrix sessions share the same TAPI driver. This allows all users in the Citrix sessions to select "their" line from the set of all TAPI lines. Then everything works as desired. It is important to note that theoretically one user can select the line of another user.
You can use the "Microsoft Remote TAPI Server", to implement access rights for lines for separate Citrix sessions.

===Known Problems===

* The TSP is not tested with Microsoft’s Remote Tapi Server. While some installation have reported this to work fine, others have encountered problems. This scenario is not supported by innovaphone
* The TSP will read its configuration when it is loaded by the system. Thus, configuration changes require a re-load of the TSP. Unfortunately, there is no reliable way to force the system to unload the TSP, so you may have to reboot the system for changes to take effect. See the [[ Howto:Troubleshooting_the_TAPI_service_provider | TAPI trouble shooting article ]] for details
* The TSP will use HTTP basic authentication to talk the PBX. So if you disable basic authentication in the PBX's configuration, the TSP will not work. It is recommended to use HTTPS
* TAPI requires the TSP to assign a unique id to each line device. This ID must not change between re-boots of the system or between upgrades of the TSP. This is done by keeping a persistent table in the windows registry (in the <code>lineGUIDs</code> subkey of <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>) that maps the PBX's line GUID to a fixed integer value (known as ''permanent line id'' in TAPI speak). This key is retained even on uninstall. To get rid of it, you must remove it manually
* Microsoft installer fails to remove driver files installed to the windows system folder. This is why the TSP driver files are still present after an uninstall of the software. To get rid of them, remove <code>TSP8.tsp</code> and <code>TSP8UI.dll</code> from both ''%windir%''<code>\system32</code> and ''%windir%''<code>\sysWOW64</code>
* From Version 9, hotfix 1, the PBX firmware will not list objects tagged as [[Reference9:PBX/Objects#General_Object_Properties | ''hide from LDAP'' ]] in the result of a [[Reference9:Concept_SOAP_API#UserInfo.5B.5D_FindUser.28string_v501.2C_string_v700.2C_string_v800.2C_string_cn.2C_string_h323.2C_string_e164.2C_integer_count.2C_integer_next.29 | FindUser() ]] call. As a result, such objects will not be shown in the TAPI configuration dialogue ''Username'' drop-down. If you want to use such an object as ''TAPI User'' you can simply type in the name without selecting it from the drop down.
* Sometimes, setting configuration with ''TSP Control'' (not the telephone control panel dialogue) does not work due to windows' ''User Access Control (UAC)'', see [[Howto:TAPI_TSP_Control_Windows7]] for Details
* Various users have reported that first party TSP installations do not work reliably with Microsoft Outlook. Symptoms reported are spurious error pop-ups from Outlook although there was no real problem. We do not recommend first party installations anyway (see [[#Rolling_out_First_Party_TSPs_to_multiple_PCs]] for a reasoning), but these issues are related to Microsoft Outlook only. No such problems have been reported with other first party TAPI applications. Consider using solutions like Estos ProCall instead.
* The number of parallel threads used within the TSP is limited to max. 60 per CPU. As each connected PBX (amongst other things) is handled by a separate thread, if you have a large number of PBXs connected and only have a single CPU, you may run out of threads, resulting in a WARNING messages ''about to spawn new workerthread (n requests, m threads) -- but limit l exceeded''. This usually happens when you run the TSP on a virtualized platform such as vmWare and only dedicate a single CPU. Ignoring this warning results in sluggish behaviour.
* The TSP can work with dynamic PBXs too. However, the TSP needs to determine the slave PBXs IP addresses from the master. If the slave is a dynamic PBX and it is hosted on the same device as the master and it is registered to the master using 127.0.0.1, the TSP will only learn the 127.0.0.1 as the slave's IP address. Of course, connection to the slave PBX will fail then.

==== TAPI Operation with 3rd party Phones or innovaphone Phones registered with SIP ====
Various TAPI functions rely on use of the [[Reference:Remote Control Facility|Remote Control Facility]] message. This message is not supported in 3rd party phones and also not fully supported in innovaphone Phones when they are registered to the PBX using SIP. Full TAPI functionality is thus only available for innovaphone phones registered to the PBX using H.323.

Known Limitations:
* Accepting an incoming call (lineAnswer)
* Automatic initiation of an outgoing call in handsfree mode (instead, the calling phone first rings and starts the outgoing call upon of-hook)
* toggle between 2 calls active on a phone (lineSwapHold)
* initiation and termination of a 3PTY (lineCompleteTransfer with mode LINETRANSFERMODE_CONFERENCE, lineDrop on a conference call)

==== TAPI on Windows8 / Server 2012 ====

Windows8 doesn't let you disable ''User Access Control'' (UAC) completely. This has the disadvantage that ''TSP Control'' (tsptray.exe) cannot change system registry entries, which it needs to do to e.g. change debug settings for the TSP.

There are 2 ways around it:
# use the hidden ''Administrator'' account on Windows 8
# elevate the tsptray.exe application

To use the elevated ''Administrator'' account on Windows 8 you first need to un-hide it:
* log in to an account with administrator rights
* use the ''Windows-Key+X'' shortcut and select ''Command Prompt (Administrator)'' (''Eingabeaufforderung (Administrator)''). An elevated cmd prompt appears
* type <code>net user administrator /active:yes</code>
* the fully elevated ''Administrator'' account is now available and you can log-in to this account as usual
* '''Please make sure the account has a password set - by default, it does not!!'''

To elevate the tsptray.exe application;
* log in to an account with administrator rights
* start a windows explorer
* change directory to <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8-x64 TSP</code>
* right click on <code>tsptray.exe</code> and open the ''properties'' (''Eigenschaften'') menu
* switch to the ''Compatibility'' (''Kompatibilität'') tab
* tick the ''Run as administrator'' (''Program als Administrator ausführen'') check mark
* save the settings

Please note that Windows 8 will not let you run any "Metro App" in elevated mode!

===== HTTPS =====
The TSP will not be able to talk to the PBX using HTTPS with Windows8 or Server2012. This [[Reference8:Release_Notes_TAPI_V8#3722_-_HTTPS_SOAP_connections_did_not_work_on_Windows8_.2F_Server_2012|has been fixed]] with V8 TAPI Service Provider (32 and 64bit) - hotfix10.
===== .Net 3.5 missing on Server 2012 =====
Server 2012 has no support for .Net 3.5 by default. Even more, it cannot be installed just by downloading it. Instead, the ''NetFX3 Feature'' needs to be enabled. Here is how:

Microsoft Windows [Version 6.2.9200]
(c) 2012 Microsoft Corporation. Alle Rechte vorbehalten.

C:\Users\Administrator>dism /online /enable-feature /featurename:NetFX3 /all /Source:''<path to windows setup, e.g. d:>''\sources\sxs /LimitAccess

See also
* [http://blogs.technet.com/b/aviraj/archive/2012/08/04/windows-8-enable-net-framework-3-5-includes-net-2-0-and-3-0-i-e-netfx3-feature-in-online-amp-offline-mode.aspx?PageIndex=2 Windows 8: Enable .NET Framework 3.5]
* [http://msdn.microsoft.com/en-us/library/hh506443.aspx Installing the .NET Framework 3.5 on Windows 8]

==== TAPI dialer fails from Outlook when Lync client was/is installed ====
We have received reports that 1st-party TAPI dial-out from Outlook does not work anymore when a Lync client was installed. Some users report that this phenomenon occurred only after an upgrade to Windows 8. Reportedly, this can be [http://support.microsoft.com/kb/959625/en-us fixed by setting a registry key as outlined in Microsoft's knowledge-base]. You may want to give this a try. However, we have not seen this issue ourselves and thus can't comment on it further.

==== Slow Network Performance ====
TAPI is pretty sensitive to slow network performance. While the TSP is multi-threaded, some internal locking must be done so that slow requests to a PBX my block other pending requests, resulting in unpleasant performance. The TSP will create ''Windows Event Log'' entries of type ''slow SOAP call performance'' if this is detected. You should inspect your event log regularly and resolve the reason for such network performance.

Long PBX request round-trips may have a number of reasons:

; slow WAN performance : of course, if the WAN is slow or unstable, bad performance is the result
; inappropriate QoS : SOAP is using HTTP/HTTPS. In a QoS enabled network, call signalling and RTP may work fine, whereas HTTP/HTTPS is considered to be of no importance. You need to keep in mind that such QoS policy may lead to bad TAPI performance, as the SOAP traffic used by the TSP (being based on HTTP/HTTPS) may be delayed. You should assign SOAP traffic a similar priority as you do for VoIP signalling
; overloaded PBX : HTTP traffic is treated on a low priority level in the PBX. If the PBX runs near to 100% CPU load, while all RTP and VoIP signalling will work well still, HTTP traffic may get severely delayed. You should make sure your PBX runs well under 100% CPU load to get good TAPI performance. See [[Reference:Device Health Check]] for more details

==== TAPI on Windows 10 ====
In Windows 10, the TSP is not allowed any longer to read/write its own registry tree. For this reason, it is not possible to store or read the configuration. As a result, the TSP will not work. To fix this, you need to modify the registry access rights so that the TSP has read/write access to <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>.

Note on windows registry paths<ref name="regkey">
Due to a change in ''Windows Registry Access Rights'' in Windows 10, from Build 8165, the configuration is stored in
: <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>
(a place that is suitable for Windows 10 too). Before, the configuration was stored in
: <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>

See [[#Upgrade_from_Build_8164_or_earlier| Upgrade from Build 8164 or_earlier ]] above for more details.
</ref>:
<references/>

=== Tweaks ===
There are a few configuration options which should be used rarely. They can be enabled by setting an appropriate registry key.

Since Hotfix 15 the location to set the interop tweaks has been changed to <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>:

; ProcessorMask : REG_DWORD. If set, the TSP will use <code>SetProcessAffinityMask(GetCurrentProcess(), set)</code> to limit TSP execution to one or more of the existing processors. Set to <code>0xff</code> by default.

; LineTimeOut : REG_DWORD. Can be set to a number of seconds the TSP should wait for the determination of lines to finish (default 90). On a large PBX, or a PBX with slow slaves, the determination might not finish in the default time frame. If this happens, TAPI applications may show ''Line unnamed'' line entries in their line list. If this is a problem, set it to a larger value (e.g. <code>120</code>).

; IgnoreDevStatus : REG_DWORD. Some applications get confused if TAPI reports line to be disconnected or out-of-service dynamically. Setting this to a non-zero value will disable any such notification.

; ClearFwdOnSet : REG_DWORD. If set to a non-zero value, the TSP will clear all current call forward settings before a lineForward request is executed. This implies that all call forward settings are ''replaced'' by the new settings. Standard behaviour is to only modify the settings, that is, replace all current settings of the same type with the settings found in the lineForward request (for example, if there is only one setting in the request that defines a CFU, then the current CFU settings are replaced by the new one provided. All others, such as e.g. CFNR settings, are left untouched).

: Tapi spec is pretty clear on how this should work: ''The provider should "unforward everything" prior to setting the new forwarding instructions''. Even though, for historical reasons, ClearFwdOnSet=0 has been the default in all TAPI versions prior to V8 hotfix 6, from hotfix 6 on, the default changes to 1, as this has turned out to be the widely accepted interpretation.

; No3PTY : REG_DWORD. See [[Reference8:TAPI_Service_Provider#Notes_on_3PTY_Conferences | Notes_on_3PTY_Conferences]] below.

; HiddenRecordingNumber: REG_SZ. Active recording in an innovaphone PBX is implemented as an implicit 3PTY conference with the recording sink as one of the parties. These will be shown as usual in the TAPI callstate. However, some applications get confused as this results in a situation, where a normal endpoint (read: phone) has more than one active (i.e. ''not on hold'') call. To suppress such calls in the TAPI call states, you can set this tweak to the number of the recording sink as configured in the phone's recording configuration tab. If so, any outgoing call from an endpoint that is registered with a PBX user object with a called number that equals the setting of this tweak, will be suppressed. So if your recording sink has the number <code>44</code>, you would set this registry value to <code>44</code> (this is available from TAPI V8 hotfix 8). Please note that this feature actually suppresses any call info for such calls, however, it does not revert previously announced call infos. So if the call is initiated using ''overlapped dialling'', all call states will be shown until the called number matches the value of <code>HiddenRecordingNumber</code> and all subsequent call states will be suppressed. This will probably leave the call shown in ''dialling'' state. The feature should be used for destinations which are called using ''block dialling'' only thus.

; SilentHold : REG_DWORD. When a call is put on hold using <code>lineHold</code>, the held party will hear ''music on hold'' emitted by the PBX. The hold-initiator will hear a dialling tone (PBX firmware v11r2 and up, with older versions the initiator would hear ''music on hold''). When <code>SilentHold</code> is set to a non-zero value, the initiating party will hear silence - i.e. no dialling tone (this is available from TAPI V8 hotfix 8).



; NoDuplicateConnectedCalls : REG_DWORD. If set to 1, the TSP will never show more than one call per line to be active. Extra active calls will be shown as ''on-hold''. The situation occurs e.g. when a user initiates a 3PTY conference on the phone. This essentially is a bug fix for Microsoft's OCS client which forces any extra active call on-hold, thereby disturbing the 3PTY function. If your are using [http://www.estos.de/download/software/eccg.htm ESTOS' Call Control Gateway]: from version ''2.0.1.1474 - 05.11.2008'' there is a fix for this same problem available. This option thus is deprecated.

; UseFirstLeg2 : REG_DWORD. TAPI allows only for a single leg-2 info (redirection information in case of a call forward). If a call is forwarded mutliple times, by default the last redirection is shown in TAPI. If <code>UseFirstLeg2</code> is set to 1 however, the first redirection is shown.

; UseNameForDeviceGuid : REG_DWORD. The TSP will create a TAPI line for each ''Device'' of each PBX object (if ''MapDevices'' is set). The internal unique identifier includes the ''Hardware Id'' found in the ''Device''. If this changes, the TAPI line representing the ''Device'' is considered new and a new TAPI ''permanent line id'' is allocated. This may be annoying cause when a device serial number (e.g. for a telephone) is used as ''Hardware Id'', replacing the device creates a new TAPI line. If ''UseNameForDeviceGuid'' is set to 1, the TSP will use the ''Device''s ''Name'' instead (which usually not changes). While this might be more convenient, be aware that you ''must'' make sure that no PBX object has duplicate ''Name''s! Otherwise, TAPI will get confused. Available from build 8178

; ShowConfGUID : REG_DWORD. If set and not 0, the TSP will implicitly set each call's CallData to a string such as "<code>conf-guid:</code>''call-guid''". ''call-guid'' is a 66-byte Unicode16 string (32 hex characters plus terminating 0). Note that this will interfere with an application's use of the lineSetCallData function (tapi.h) and is therefore disabled by default. Available from build 8190

; NoFix : REG_DWORD. If set and not 0, the TSP will not trigger a full re-synchronization if it receives implausible state messages. Available from build 8197.

===List of supported TSPI functions===

The TSP supports the following TAPI Service Provider Interface Functions. Note that these do not map one to one with TAPI user functions. For more information, see the Microsoft TAPI documentation.

*TSPI_lineAnswer
*TSPI_lineBlindTransfer
*TSPI_lineClose
*TSPI_lineCloseCall
*TSPI_lineCompleteTransfer
*TSPI_lineDevSpecific
*TSPI_lineDevSpecificFeature
*TSPI_lineDial
*TSPI_lineDrop
*TSPI_lineForward
*TSPI_lineGenerateDigits
*TSPI_lineGetAddressCaps
*TSPI_lineGetAddressID
*TSPI_lineGetAddressStatus
*TSPI_lineGetCallAddressID
*TSPI_lineGetCallHubTracking
*TSPI_lineGetCallIDs
*TSPI_lineGetCallInfo
*TSPI_lineGetCallStatus
*TSPI_lineGetDevCaps
*TSPI_lineGetExtensionID
*TSPI_lineGetID
*TSPI_lineGetLineDevStatus
*TSPI_lineGetNumAddressIDs
*TSPI_lineHold
*TSPI_lineMakeCall
*TSPI_lineNegotiateExtVersion
*TSPI_lineNegotiateTSPIVersion
*TSPI_lineOpen
*TSPI_linePark
*TSPI_linePickup
*TSPI_lineRedirect
*TSPI_lineSelectExtVersion
*TSPI_lineSendUserUserInfo
*TSPI_lineSetAppSpecific
*TSPI_lineSetCallData
*TSPI_lineSetCallHubTracking
*TSPI_lineSetCallParams
*TSPI_lineSetCurrentLocation
*TSPI_lineSetDefaultMediaDetection
*TSPI_lineSetMediaMode
*TSPI_lineSetStatusMessages
*TSPI_lineSetupTransfer
*TSPI_lineSwapHold
*TSPI_lineUnhold
*TSPI_lineUnpark

*TSPI_providerConfig
*TSPI_providerCreateLineDevice
*TSPI_providerEnumDevices
*TSPI_providerGenericDialogData
*TSPI_providerInit
*TSPI_providerInstall
*TSPI_providerRemove
*TSPI_providerShutdown
*TSPI_providerUIIdentify
=====Notes on Consultation Calls=====
This TSP supports the <code>lineSetupTransfer</code> function. However, strictly speaking, this function is not needed and should not be used. It is merely intended for applications which do not offer a consultation call interface to the user when this function is not available. Instead, <code>TSPI_lineMakeCall</code> can be used where <code>lineSetupTransfer</code> would be otherwise. The notion of a special ''consultation call'' is an idiosyncrasy forced by legacy PBX technologies which were not able to transfer two arbitrary calls. In these scenarios, a potentially to-be-transferred call needed to be linked to the primary call. The PBX can transfer two arbitrary calls and thus there is no need for <code>lineSetupTransfer</code>. This ability is indicated by the <code>LINEADDRCAPFLAGS_TRANSFERMAKE</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE </code> flags. The transfer is then requested by using <code>TSPI_lineCompleteTransfer</code>.

=====Notes on 3PTY Conferences=====
The TSP supports the management of 3PTY conferences. These can be initiated by using <code>TSPI_lineCompleteTransfer</code> with <code>LINETRANSFERMODE_CONFERENCE</code> instead of <code>LINETRANSFERMODE_TRANSFER</code>. This is indicated by the flags <code>LINEADDRCAPFLAGS_CONFERENCEHELD</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE</code>. The 3PTY function is actually implemented by the innovaphone IP phones (such as IP2xx). Therefore, these capabilities are only advertised if the line is based on a PBX user object. Still, some lines where the capabilities are advertised cannot do 3PTY (such as e.g. DECT lines, analogue lines, 3rd party devices, ...). So the call to <code>TSPI_lineCompleteTransfer</code> will succeed but the conference will not be initiated and the subsequent call states will not indicate a conference (as there is no).

Also, if non-telephone devices are registered with a PBX user object and these device have multiple concurrent calls (e.g. a call center connected with a multi-channel XCapi), these will be viewed as 3PTY calls (as this is the way such calls appear to the TAPI: a line with more than one non-held call). If these calls are in fact no 3PTY, this may lead to confusing call indications from TAPI. It is better to register such objects as a PBX gateway object. Special treatment of 3PTY calls can be disabled by setting the registry flag <code>No3PTY</code> (from build 8087 onwards).

A 3PTY conference will create a new call handle for the conference. The only operation available for such a handle is <code>TSPI_lineDrop</code>. This will terminate the conference and restore the state active before the conference was initiated (that is, the phone that implemented the conference will now have 2 calls, one active and one on hold). This is indicated by not setting <code>LINEADDRCAPFLAGS_CONFDROP</code>.

A <code>lineDrop()</code> on one of the 2 ''real'' calls involved will of course cancel this call and thus remove the 3PTY.

======Notes on Intrusion Calls======
A special case of 3PTY is an intrusion call initiated by a [[Reference9:Phone/User/Function-Keys/Partner | partner function key]]. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the intrusion call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is an intrusion call).

======Notes on Recording Calls======
A special case of 3PTY is a recording call. This effectively creates an user-invisible 3PTY on the phone. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the recording call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is a recording call).

Recording calls are shown as normal conferences (unless <code>No3PTY</code> is set). This might be confusing to applications and/or users. See the <code>HiddenRecordingNumber</code> tweak above for a method to hide such calls.

=====Notes on parked Calls=====
The PBX can park calls from and to any existing PBX object, e.g. by virtue of [[Reference8:Configuration/Registration/Function-Keys/Park | specific feature keys]]. They are parked to/from a numeric ''park position''. In SOAP however, calls are parked to an object by providing the objects '''UserInitialize()''' handle and a park position. Parked calls are then reported as straight calls with a distinct signalling state (8). The park position is not conveyed as part of the '''CallInfo''' record. To unpark, '''[[Reference8:SOAP_API#integer_UserPickup.28int_user.2C_string_cn.2C_integer_call.2C_string_group.2C_int_reg.2C_InfoArray_info.29 | UserPickup]]''' can be used providing the parked calls call handle as '''call''' argument.

The TAPI specification is unclear on how the address information required to '''lineUnpark()''' a call can be obtained by an application (except that it is returned from '''linePark()''' if the call was parked using TAPI). The TSP thus indicates parked calls on a line with a call reason <code>LINECALLREASON_PARKED</code>. The caller id information is set to the parked calls call handle. This way, the application can take the caller id information and provide it to '''lineUnpark()''' to unpark a call. If the appication does not support this mode of operation but supports '''lineUnpark()''' and lets the user input the park identifier, the user can just provide the caller id information.

Some applications do not care for parked calls (by examining the call reason) and just blindly report these calls like ordinary connected calls (thereby confusing the user). To work around this problem, reporting parked calls can be turned off in the TSP configuration dialogue.

=====Notes on sending User to User Information =====
The TAPI specification for sending UserUserInfo closely resembles the way ISDN defines this service. Although the innovaphone PBX supports this service both with H.323 and SIP, it is ''not'' supported in this TSP. Instead, sending user to user information is implemented using H.323/SIP messaging. However, there are some important deviations and limitations caused hereby:
* data is ''not transparent''. That is, the TSP only allows for null-terminated unicode to be sent. The data must be of even length and the last two bytes must be null.
* data is ''not sent within the call'', but by initiating a separate call. This implies that the target number used to send the message carrying the data to is 'guessed' from the available call data. For example, if the call is in a connected state and a connected number is known, the message is sent to the connected number. If the call is in the ringback state, then either the called number or - if available - the redirection number is used and so forth.
* message calls are not indicated by the SOAP CallInfo records. As a result, messages sent with lineSendUserUserInfo cannot be received with TAPI
=====Notes on receiving User to User Information =====
From build 8200, the TSP will deliver incoming UUI on a call. Although lineSendUserUserInfo will still send H.323/SIP messages instead of native UUI, you can now receive incoming UUI (for example from ISDN) in a LINE_CALLINFO message.

=====Notes on sending proprietary innovaphone Remote Control Facilities =====
The SOAP [[Reference10:SOAP_API#UserRc.28integer_call.2C_integer_rc.29|UserRc]] function allows to send various [[Reference:Remote Control Facility|facility messages]] to an innovaphone phone device. In some cases, it is useful to be able to invoke this function through a standard TAPI mechanism. This can be achieved by using the TAPI '''lineBlindTransfer''' function. If the ''called party name'' provided as destination for the ''lineBlindTransfer'' (in ''lpszDestAddress'') has the magic value <code>USERRC</code>, then the ''called subaddress'' is converted to an integer and the result is sent as remote control facility to the call the blind transfer is applied for. For details on how to code the ''called party name'' and the ''called subaddress'' into ''lpszDestAddress'' see [http://msdn.microsoft.com/en-us/library/windows/desktop/ms726017%28v=vs.85%29.aspx Microsoft's ''Canonical Address'' specification]. This works from TAPI8 hotfix 4.

For example, initiating a blind transfer to <code>|16^USERRC</code> (empty address, subaddress 16 (that is, [[Reference:Remote Control Facility|''change to handset mode'']]), called name <code>USERRC</code>) will switch the phone having the call to be transferred into handset mode (and <code>|18^USERRC</code> will switch it back to handsfree mode). Of course, no actual transfer will happen in these cases (''lineBlindTransfer'' is merely used as a vehicle to send the facility to the proper call).

Such proprietary facility message can also be sent with ''lineMakeCall'' (that is, in SOAP's [[Reference10:SOAP_API#integer_UserCall.28integer_user.2C_string_cn.2C_string_e164.2C_string_h323.2C_int_reg.2C_InfoArray_info.2C_int_rc.2C_string_srce164.29|UserCall]] function). For example, setting up a call to <code>123|21^USERRC</code> will send an intrusion call to extension 123 and intrude any call that might be active there. This works from TAPI8 hotfix 6. Please note that the innovaphone TAPI service provider does not support TAPI's ''lineCompleteCall'' function with <code>LINECALLCOMPLMODE_INTRUDE</code> though (as TAPI's call model here does not fit with the PBX's call model). Please also note that intrusion calls look like 3PTY calls to TAPI (see [[#Notes_on_Intrusion_Calls|notes on intrusion calls]] above).

Remote control facilities are implemented by the telephone devices, so these functions are subject to the phone firmware in use.

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

== Related Articles ==
* [[Howto:Troubleshooting the TAPI service provider]]
* [[ReleaseNotes8:TAPI]]

Reference8:TAPI Service Provider

2024-11-04T17:22:55Z

Ckl: /* Notes on sending User to User Information */

Courseware:IT Advanced - 09 Custom certificates

2024-10-16T15:31:43Z

Ckl: Protected "Course14:IT Advanced - 09 Custom certificates" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Custom certificates | 142 }}

Courseware:IT Advanced - 09 Custom certificates

2024-10-16T15:31:34Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Custom certificates | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Custom certificates | 142 }}

Courseware:IT Advanced - 08 Using a custom DNS on your mobile phone

2024-10-16T15:30:29Z

Ckl: Protected "Course14:IT Advanced - 08 Using a custom DNS on your mobile phone" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Using a custom DNS on your mobile phone | 142 }}

Courseware:IT Advanced - 08 Using a custom DNS on your mobile phone

2024-10-16T15:30:19Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Using a custom DNS on your mobile phone | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Using a custom DNS on your mobile phone | 142 }}

Courseware:IT Advanced - 07 Public access to PBX resources (practice)

2024-10-16T15:28:34Z

Ckl: Protected "Course14:IT Advanced - 07 Public access to PBX resources (practice)" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Public access to PBX resources (practice)| 142 }}

Courseware:IT Advanced - 07 Public access to PBX resources (practice)

2024-10-16T15:28:24Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Public access to PBX resources (practice)| 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Public access to PBX resources (practice)| 142 }}

Courseware:IT Advanced - 06 Public Access to PBX Resources (theory) - optional

2024-10-16T15:26:46Z

Ckl: Protected "Course14:IT Advanced - 06 Public Access to PBX Resources (theory) - optional" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Public Access to PBX Resources (theory) - optional | 142 }}

Courseware:IT Advanced - 06 Public Access to PBX Resources (theory) - optional

2024-10-16T15:26:39Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Public Access to PBX Resources (theory) - optional | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Public Access to PBX Resources (theory) - optional | 142 }}

Courseware:IT Advanced - 05 Setting up the Apps

2024-10-16T15:25:02Z

Ckl: Protected "Course14:IT Advanced - 05 Setting up the Apps" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Apps | 142 }}

Courseware:IT Advanced - 05 Setting up the Apps

2024-10-16T15:24:41Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Apps | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Apps | 142 }}

Courseware:IT Advanced - 04 Setting up the Application Platform

2024-10-16T15:21:49Z

Ckl: Protected "Course14:IT Advanced - 04 Setting up the Application Platform" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Application Platform | 142 }}

Courseware:IT Advanced - 04 Setting up the Application Platform

2024-10-16T15:21:39Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Application Platform | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Application Platform | 142 }}

Courseware:IT Advanced - 03 The Application Platform

2024-10-16T15:20:36Z

Ckl: Protected "Course14:IT Advanced - 03 The Application Platform" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | The Application Platform | 142 }}

Courseware:IT Advanced - 03 The Application Platform

2024-10-16T15:20:29Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | The Application Platform | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | The Application Platform | 142 }}

Courseware:IT Advanced - 02 PBX - initial Configuration

2024-10-16T15:18:53Z

Ckl: Protected "Course14:IT Advanced - 02 PBX - initial Configuration" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | PBX - initial Configuration | 142 }}

Courseware:IT Advanced - 02 PBX - initial Configuration

2024-10-16T15:18:45Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | PBX - initial Configuration | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | PBX - initial Configuration | 142 }}

Courseware:IT Advanced - 01 innovaphone overall Product Design

2024-10-16T15:16:28Z

Ckl: Protected "Course14:IT Advanced - 01 innovaphone overall Product Design" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | innovaphone overall Product Design | 142 }}

Courseware:IT Advanced - 01 innovaphone overall Product Design

2024-10-16T15:15:53Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | innovaphone overall Product Design | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | innovaphone overall Product Design | 142 }}

Reference10:Concept SOAP API

2024-09-25T08:27:58Z

Ckl: /* Info record */

innovaphone®'s PBX web services, also known as SOAP API, while no longer actively extended, remains available and functional. A transition to WebSocket API, specifically the RCC API (https://sdk.innovaphone.com/13r3/doc/appwebsocket/RCC.htm), was introduced with version 13 firmware.

For ongoing development, we recommend utilizing [http://www.innovaphone.com/wsdl/pbx10_00.wsdl WSDL version 10 ''pbx10_00.wsdl''] (also available on the gateway <code>http://xx.xx.xx.xx/pbx10_00.wsdl</code>) in conjunction with this Wiki article. It's advisable to disregard the higher versions of WSDL for your development.

For upcoming developments the WebSocket API should be used, as it represents the current and future direction of our API development.

==Overview==

For an overview of the basic architecture, see the [[Reference:SOAP_API_%28pbx501.wsdl%29#Overview|corresponding chapter in the pbx501.wsdl related article]].

[[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. This [[http://www.innovaphone.com/wsdl/pbx10_00.wsdl 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 [[http://www.innovaphone.com/wsdl/pbx900.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.

=== SOAP URL ===
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 <code>http://172.16.0.1/PBX0/user.soap</code> or <code>https://172.16.0.1/PBX0-mydynpbxid/user.soap</code>.

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

====Initialize(string user, string appl, bool $v, bool $v501, bool v700, bool v800, bool vx1000, out int key)====

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

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

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

*'''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.

*'''string domain'''

the PBX domain if the Gatekeeper ID is used as domain

*'''boolean h323email'''

If true, the h323 name shall be used as primary email address when sending emails to this user.

*'''string email[]'''

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.

*'''Group groups'''

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

*'''Presence presence'''

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

*'''boolean cfg'''

If set to true indicates that the config of the user has changed

*'''string object'''

The type of the user object

*'''string 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.

*'''string node'''

The node of the object.

*'''string nodenum'''

The object nodes node number (prefix).

*'''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:

:*'''fake'''
: The value configured as 'Send Number'

*'''groups'''

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

:*'''bool active'''

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

*'''presence'''

The users presence status is stored in a '''Presence''' record which has the following elements:

:*'''string status'''

: either '''open''' or '''closed'''

:*'''string activity'''

: The users current activity (optional)

:*'''string note'''

: The user provided additional note (optional)

====integer UserInitialize(integer session, string user, bool xfer, bool disc, string hw)====

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

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

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

====int SetPresence(inno:Presence presence, bool im, string contact, string guid, string h323)====

Sets the presence of a PBX user.

* '''presence''':
:* '''inno:PresenceStatus''': the status '''closed'''/'''open''' or empty
:* '''inno:PresenceActivity''': the activity like '''busy'''
:* string '''note''': the presence note
* '''im''': from im client?
* '''contact''': the presence contact like '''tel:''', '''calendar:'''...
* '''guid''': the user guid
* '''h323''': the h323 name of the 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'''.

===Device===

For each User object multiple devices can be configured within the PBX. A device represents 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.

====Device[] Devices(int session, string user)====

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:

{|
|valign=top nowrap=true|'''hw'''
|The Hardware Id used to identify the device. This string is used to associate any calls to devices.
|-
|valign=top nowrap=true|'''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.
|}

===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:
{|border="2" cellspacing="4" cellpadding="3" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse;empty-cells:show;"
|+
| 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''.

Refer to the [[Howto:SOAP API PHP5 Sample Code#Working with Call States from CallInfo]] Article to learn how to work with the call state values.

*'''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)

:*'''leg2orig'''

: The 1st diverting user (if any, from on v9hf1)

:* '''leg1'''

: Indicates a call-forward/blind-xfer(?) to the calling end

:*'''ct'''

: The last user having transferred the call (if any)

:*'''parked-to'''

: The call was parked to the indicated endpoint. This is sent with the 'r-rel' message indicating the clearing of this call.

:*'''picking'''

: The call was picked by the indicated endpoint. Usually empty because sent with the new call which is created at the picking endpoint, but the fact that it is present indicates that this is a picked up call. The endpoint where this call is picked from is indicated with a ''ct'' No within the same call_info.
*'''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 call the reported call leg (all legs of a certain call share the same ''conference id''). Also, CDRs for a call show this ''conference id'' (''ref'' for [[Reference:Call_Detail_Record_CDR|gateway CDRs]], ''conf'' in the ''<event>'' tag for [[Reference10:Concept_Call_Detail_Record_CDR_PBX|PBX CDRs]]).
:*'''cause'''

: The latest [[Reference:ISDN_Cause_Codes | cause code ]] which has been notified on the call

===== CallInfo for Boolean Objects =====
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

====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. The following values for ''type'' are used (although more may appear at any time):
:; conf : the call conference guid
:; cause : a cause code related to the call, see [[Reference:ISDN Cause Codes]]
:; uui : a user-user-info sent or received on the call. The UUI is conveyed in the ''vals'' member (see below). Note that from 13r3 upwards, the UUI conveyed is url-encoded.

*'''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, int rc, string srce164)====

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 [[Reference8:SOAP_API#Remote_Control_Facilities|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.

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

====UserMediaTransfer (integer acall, integer bcall, boolean user, boolean peer)====

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.

====bool UserRedirect(integer call, string cn, string e164, string h323, InfoArray info, int rc)====
Places a call to the destination described by ''cn'', ''e164'' and ''h323'' and connects ''call'' to this destination. Argument ''info'' is currently ignored. ''rc'' can carry one of the remote control facilities listed in [[Reference:Remote Control Facility]] (see also [[{{NAMESPACE}}:Concept_SOAP_API#UserRc(integer_call,_integer_rc)|UserRc]] below).

Any call forwarding configured for the destination will be ignored. See [[Reference8:SOAP_API#bool_UserReroute.28integer_call.2C_string_cn.2C_string_e164.2C_string_h323.29|UserReroute()]] below.

Note: in 2009, the semantics of UserRedirect has accidentally been changed so that call forwarding will no longer be ignored. From 14r1 Service Release 4, the original behavior can be restored by specifying 999 as ''rc''.

====bool UserReroute(integer call, string cn, string e164, string h323)====
Performs a rerouting of the call. Call forwardings set for the destination will be obeyed.

Note: rerouting calls on a waiting queue or call broadcast object works only if the ''Execute Operator CFB/CFNR'' or ''Execute Group Member Diversions'' option is turned on.

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

====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, bool remote)====
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.

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

====integer UserPark(integer call, string cn, integer position)====
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.

====UserDTMF(integer call, bool recv, string dtmf)====
Sends DTMF digits on behalf of the user. If '''recv''' is set to ''true'' the DTMF is sent to the local user.

====UserUUI(integer call, bool recv, string uui)====
Sends User-User_information on behalf of the user. If '''recv''' is set to ''true'' the uui is sent to the local user.

====UserInfo(integer call, bool recv, string cdpn, string key, string dsp)====
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.

====UserRc(integer call, integer rc)====
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 [[#integer_UserCall.28integer_user.2C_string_cn.2C_string_e164.2C_string_h323.2C_int_reg.2C_InfoArray_info.2C_int_rc.2C_string_srce164.29|UserCall()]].

===Messaging===

====integer UserMessage(integer user, string e164, string h323, string msg, string src_e164, string src_h323 )====
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.

===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 v700, string v800, string vx1000, string cn, string h323, string e164, integer count, integer next, boolean nohide)====
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 20 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.

====bool UserFindDestination(integer user, string e164, string h323, out UserInfo user)====
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.

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

====string LocationUrl(string v501, string v700, string v800, string vx1000, string location, bool tls)====
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.

====string UserLocalNum(int user, string num)====
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.
;user:The id of the specified user
;num:The number to be localized into the spefified user's location
;result:The localized number, including escape prefixes

===Administration===
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.

====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 [[Howto:Using the SOAP Admin Function | 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]]

==Typical design of a PBX SOAP Application==
Please refer to the [[Reference:SOAP_API_%28pbx501.wsdl%29#Typical_design_of_a_PBX_SOAP_Application|pbx501.wsdl]] article for a discussion of the typical design of a SOAP application.

==References==
* [http://www.innovaphone.com/wsdl/pbx10_00.wsdl Version10-wsdl].

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:
* [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 7.00 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 8.00)
*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

==Known Issues==
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 [http://www.innovaphone.com/wsdl/pbx11_00.wsdl www.innovaphone.com/wsdl/pbx11_00.wsdl ]).

Note: This wdsl file is not available directly from the PBX (e.g. at <code>http://xx.xx.xx.xx/pbx11_00.wsdl</code>)

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.

==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]

Reference10:Concept SOAP API

2024-09-25T08:24:50Z

Ckl: /* Info record */

innovaphone®'s PBX web services, also known as SOAP API, while no longer actively extended, remains available and functional. A transition to WebSocket API, specifically the RCC API (https://sdk.innovaphone.com/13r3/doc/appwebsocket/RCC.htm), was introduced with version 13 firmware.

For ongoing development, we recommend utilizing [http://www.innovaphone.com/wsdl/pbx10_00.wsdl WSDL version 10 ''pbx10_00.wsdl''] (also available on the gateway <code>http://xx.xx.xx.xx/pbx10_00.wsdl</code>) in conjunction with this Wiki article. It's advisable to disregard the higher versions of WSDL for your development.

For upcoming developments the WebSocket API should be used, as it represents the current and future direction of our API development.

==Overview==

For an overview of the basic architecture, see the [[Reference:SOAP_API_%28pbx501.wsdl%29#Overview|corresponding chapter in the pbx501.wsdl related article]].

[[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. This [[http://www.innovaphone.com/wsdl/pbx10_00.wsdl 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 [[http://www.innovaphone.com/wsdl/pbx900.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.

=== SOAP URL ===
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 <code>http://172.16.0.1/PBX0/user.soap</code> or <code>https://172.16.0.1/PBX0-mydynpbxid/user.soap</code>.

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

====Initialize(string user, string appl, bool $v, bool $v501, bool v700, bool v800, bool vx1000, out int key)====

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

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

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

*'''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.

*'''string domain'''

the PBX domain if the Gatekeeper ID is used as domain

*'''boolean h323email'''

If true, the h323 name shall be used as primary email address when sending emails to this user.

*'''string email[]'''

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.

*'''Group groups'''

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

*'''Presence presence'''

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

*'''boolean cfg'''

If set to true indicates that the config of the user has changed

*'''string object'''

The type of the user object

*'''string 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.

*'''string node'''

The node of the object.

*'''string nodenum'''

The object nodes node number (prefix).

*'''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:

:*'''fake'''
: The value configured as 'Send Number'

*'''groups'''

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

:*'''bool active'''

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

*'''presence'''

The users presence status is stored in a '''Presence''' record which has the following elements:

:*'''string status'''

: either '''open''' or '''closed'''

:*'''string activity'''

: The users current activity (optional)

:*'''string note'''

: The user provided additional note (optional)

====integer UserInitialize(integer session, string user, bool xfer, bool disc, string hw)====

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

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

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

====int SetPresence(inno:Presence presence, bool im, string contact, string guid, string h323)====

Sets the presence of a PBX user.

* '''presence''':
:* '''inno:PresenceStatus''': the status '''closed'''/'''open''' or empty
:* '''inno:PresenceActivity''': the activity like '''busy'''
:* string '''note''': the presence note
* '''im''': from im client?
* '''contact''': the presence contact like '''tel:''', '''calendar:'''...
* '''guid''': the user guid
* '''h323''': the h323 name of the 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'''.

===Device===

For each User object multiple devices can be configured within the PBX. A device represents 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.

====Device[] Devices(int session, string user)====

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:

{|
|valign=top nowrap=true|'''hw'''
|The Hardware Id used to identify the device. This string is used to associate any calls to devices.
|-
|valign=top nowrap=true|'''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.
|}

===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:
{|border="2" cellspacing="4" cellpadding="3" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse;empty-cells:show;"
|+
| 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''.

Refer to the [[Howto:SOAP API PHP5 Sample Code#Working with Call States from CallInfo]] Article to learn how to work with the call state values.

*'''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)

:*'''leg2orig'''

: The 1st diverting user (if any, from on v9hf1)

:* '''leg1'''

: Indicates a call-forward/blind-xfer(?) to the calling end

:*'''ct'''

: The last user having transferred the call (if any)

:*'''parked-to'''

: The call was parked to the indicated endpoint. This is sent with the 'r-rel' message indicating the clearing of this call.

:*'''picking'''

: The call was picked by the indicated endpoint. Usually empty because sent with the new call which is created at the picking endpoint, but the fact that it is present indicates that this is a picked up call. The endpoint where this call is picked from is indicated with a ''ct'' No within the same call_info.
*'''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 call the reported call leg (all legs of a certain call share the same ''conference id''). Also, CDRs for a call show this ''conference id'' (''ref'' for [[Reference:Call_Detail_Record_CDR|gateway CDRs]], ''conf'' in the ''<event>'' tag for [[Reference10:Concept_Call_Detail_Record_CDR_PBX|PBX CDRs]]).
:*'''cause'''

: The latest [[Reference:ISDN_Cause_Codes | cause code ]] which has been notified on the call

===== CallInfo for Boolean Objects =====
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

====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. The following values for ''type'' are used (although more may appear at any time):
:; conf : the call conference guid
:; cause : a cause code related to the call, see [[Reference:ISDN Cause Codes]]
:; uui : a user-user-info sent or received on the call. The UUI is conveyed in the ''vals'' member (see below). Note that form 13r3 upwards, the UUI conveyed is url-encoded.

*'''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, int rc, string srce164)====

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 [[Reference8:SOAP_API#Remote_Control_Facilities|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.

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

====UserMediaTransfer (integer acall, integer bcall, boolean user, boolean peer)====

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.

====bool UserRedirect(integer call, string cn, string e164, string h323, InfoArray info, int rc)====
Places a call to the destination described by ''cn'', ''e164'' and ''h323'' and connects ''call'' to this destination. Argument ''info'' is currently ignored. ''rc'' can carry one of the remote control facilities listed in [[Reference:Remote Control Facility]] (see also [[{{NAMESPACE}}:Concept_SOAP_API#UserRc(integer_call,_integer_rc)|UserRc]] below).

Any call forwarding configured for the destination will be ignored. See [[Reference8:SOAP_API#bool_UserReroute.28integer_call.2C_string_cn.2C_string_e164.2C_string_h323.29|UserReroute()]] below.

Note: in 2009, the semantics of UserRedirect has accidentally been changed so that call forwarding will no longer be ignored. From 14r1 Service Release 4, the original behavior can be restored by specifying 999 as ''rc''.

====bool UserReroute(integer call, string cn, string e164, string h323)====
Performs a rerouting of the call. Call forwardings set for the destination will be obeyed.

Note: rerouting calls on a waiting queue or call broadcast object works only if the ''Execute Operator CFB/CFNR'' or ''Execute Group Member Diversions'' option is turned on.

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

====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, bool remote)====
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.

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

====integer UserPark(integer call, string cn, integer position)====
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.

====UserDTMF(integer call, bool recv, string dtmf)====
Sends DTMF digits on behalf of the user. If '''recv''' is set to ''true'' the DTMF is sent to the local user.

====UserUUI(integer call, bool recv, string uui)====
Sends User-User_information on behalf of the user. If '''recv''' is set to ''true'' the uui is sent to the local user.

====UserInfo(integer call, bool recv, string cdpn, string key, string dsp)====
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.

====UserRc(integer call, integer rc)====
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 [[#integer_UserCall.28integer_user.2C_string_cn.2C_string_e164.2C_string_h323.2C_int_reg.2C_InfoArray_info.2C_int_rc.2C_string_srce164.29|UserCall()]].

===Messaging===

====integer UserMessage(integer user, string e164, string h323, string msg, string src_e164, string src_h323 )====
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.

===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 v700, string v800, string vx1000, string cn, string h323, string e164, integer count, integer next, boolean nohide)====
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 20 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.

====bool UserFindDestination(integer user, string e164, string h323, out UserInfo user)====
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.

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

====string LocationUrl(string v501, string v700, string v800, string vx1000, string location, bool tls)====
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.

====string UserLocalNum(int user, string num)====
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.
;user:The id of the specified user
;num:The number to be localized into the spefified user's location
;result:The localized number, including escape prefixes

===Administration===
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.

====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 [[Howto:Using the SOAP Admin Function | 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]]

==Typical design of a PBX SOAP Application==
Please refer to the [[Reference:SOAP_API_%28pbx501.wsdl%29#Typical_design_of_a_PBX_SOAP_Application|pbx501.wsdl]] article for a discussion of the typical design of a SOAP application.

==References==
* [http://www.innovaphone.com/wsdl/pbx10_00.wsdl Version10-wsdl].

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:
* [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 7.00 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 8.00)
*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

==Known Issues==
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 [http://www.innovaphone.com/wsdl/pbx11_00.wsdl www.innovaphone.com/wsdl/pbx11_00.wsdl ]).

Note: This wdsl file is not available directly from the PBX (e.g. at <code>http://xx.xx.xx.xx/pbx11_00.wsdl</code>)

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.

==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]