CommuniGate Pro APIs platform

CommuniGate Pro platform behaviour could be controled in different ways. From client side control, to access to the main communication modules and developing your own functionality based on standard protocols. Such solutions are stable and can handle a huge loads.

Command line interface is a standard method for controling many different products. It's useful for administrative tasks automatisation. Full command description and use cases you can find in manual, and here is some examples:

Poppwd access

There are several ways to access CLI on the server. One of the most easy way to familiarize with commands is PWD module. With standard server configuration you can just write next command in you OS's command line: telnet server.address 8106 or telnet server.address 106 depends on OS type. Initially this module was just a realisation for password change protocol - poppwd:

$ telnet localhost 8106
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
200 mymac.ru CommuniGate Pro PWD Server 6.0.5 ready <1.1381912847@mymac.ru>
user postmaster
300 please send the PASS
pass ******
200 login OK, proceed
newpass ******
200 Password updated

HTTP access

CLI commands could be executed by sending simple POST or GET request with command parameter to server.name:[http port]/CLI/

Libraries

As simple text commands are not very useful for complex tasks, we've created Perl and Java libraries to work with CLI.

You can run CLI commands in XIMMS protocol (command cliExecute) and in CG/PL program (function ExecuteCLI()).

Mail and signal rules

Rules can't be count as a full part of API, but CommuniGate Pro used not to redirect mails and calls between accounts and mailboxes, but transfers mails to external programs (for example different mail filters), running CG/PL program and even running OS scripts.

There is a special objects used in Real-time communications in CommuniGate Pro called Signals. Signal is a unit of a Real-time communication. Different participants (SIP, XMPP clients, PBX applications and etc.) send Signals to each other to organize or hang a call, or update dialog statuses and other actions.

How the rules work.

Rules are divided into three levels: server, domain and account. Every level have it's own separate rules for mail and signals.

Every rule have a Name and Proirity. Signal rules also have "When" condition. With same conditions rule will be appled sooner if it's Priority is higher. The moment when signal rule is applied (on some specific error like "Busy" or "No answer", or at specified moment after timeout) is defined by the "When" condition.

Messages processing order:

• All server rules are applied
• Messages which are addressed to local accounts after routing has been applied are processed by domain and account rules with the next order:
  • Domain rules with Priority >5
  • Account rules
  • Domain rules with Priority <=5

Signals processing order:

• Server rules with empty "When" field applied (they are applied imidietly)
• Messages which are addressed to local accounts after routing has been applied are processed by the rest of the server (with field "When" not empty), domain and account rules with the next order:
  • Server rules with Priority >5
  • Domain rules with Priority >5
  • Account rules
  • Domain rules with Priority <=5
  • Server rules with Priority <=5

Examples

Sending restrictions for messages going outside of the domain:

All calls with destanation outside of the domain are tranferred to the specified address:

There is a Helper protocol in the CommuniGate Pro server. It is allows to use external programs to performs different tasks.

Server runs Helper program when specified conditions are met (for example mail rule runs mail filter or external authentication in domain is triggered). After that, Helper starts to send commands through standard input and reads answers through standard output.

Here is an example of some common session for Helper protocol. I - input, O - output:

O: * My Helper program started
I: 00001 INTF 1
O: 00001 INTF 1
I: 00002 COMMAND parameters
O: 00002 OK
I: 00003 COMMAND parameters
I: 00004 COMMAND parameters
O: * processing 00003 will take some time
O: 00004 ERROR description
O: 00003 OK
I: 00005 QUIT
O: * processed: 5 requests. Quitting.
O: 00005 OK

Here INTF command negotiates protocol version, QUIT command ends the session, * is information message for server to make a record in log.

There is a specialization inside this protocol for:

• Message body processing
• External authentication
• Banner system implementation
• Adding RADIUS requests for authentication
• Cluster load balancing

All of them can be connected in WebAdmin interface here: Settings -> General -> Helpers.

CommuniGate Pro Base directory (directory with user's data) is used as a start point for path to application files.

Message body processing

Message body processing is started by mail rule like this:

This and other Helpers detailed description could be found in manual.

This types of Helpers are mostly used to connect anti-virus and anti-spam engines to CommuniGate Pro.

External authentication

Helper protocol for external authentication is communly used if:

• You need to use authentication method unsopported by server
• Some account are stored in other system like Active Directory
• You need a complex routing
• You need an external control for services or account settings

You can fing examples of Helpers on this page.

Other Helpers

Banner system Helpers offer server's banners for XIMMS, HTTPS and other clients.

RADIUS Helpers offer append an additional checks into RASIUS protocol authentication process.

Load distribution Helpers control Load Balancer in cluster configuration of CommuniGate Pro.

WSSP (Web Server-side Pages) is a language for Web page templates.

Every Web skin contains three types of files:

• Static files such as graphics, styles, etc.
• WSSP files
• Language and Strings files

Standard installation of CommuniGate Pro contains a set of stock Web interfaces. One of them is Unnamed, the others are named. This demonstration skins are stored in Application directory of the server and are replaced with the server's update. Administrators shouldn't change demonstrations skins. This changes could be lost during update operation. Instead you should use skin files hierarchy.

Hierarchy in skin files

Every skin could server's, domain's or stock.

Server usually gets files with specific names when browsers requests are processed. If this file wasn't found in Domain skin, it'll be searched in server's skin with the same name. If it wasn't found in server's skin, then the search will countinue in the stock skin. If it still wasn't found and the current skin is named, search will continue in unnamed skins.

Thus Administrator can achieve using custom files instead of stock by uploading files into unnamed skin.

Using this method you can make small changes in skins as well as develop your own skin from scratch.

String files

.data files contain text data (UTF-8) in CG/PL Dictionary format. This data is used by different server's modules to form strings in the interface or as settings value.

This files form hierarchy on the level of keys on dictoinary. So if the key doesn't exists in strings.data file of the domain, server will try to find it in strings.data file on the server's level etc.

Eanglish is a default language for strings. If the users (session) language is differet, keys values from language files (french.data, russian.data) are replaced with values from strings.data file.

Such system could include only customized keys in strings.data files in slightly changed skins instead of full set of keys.

Request processing

When browser connects to the server by HTTP protocol, server extracts host name from request and searches domain with this name. If domain found server loads skin selected as a default Web interface skin for this domain. login.wssp page is launched.

Wssp files contain of marking code (usually HTML) with some additional elements:

• text bounded from two sides with % symbol (%%element%%)
• structures with format like this -

Example of such document:

<html>
<body>

<h1>Welcome to %%server%%. Your login %%ID%%.</h1>

<!--%%IF EXISTS(lastLogin)-->
Last login on %%lastLogin%%
<!--%%ENDIF-->

</body>
</html>

All special constructions will be replaced by strings or strings massives, domain names, settings values and other objects from server after servers processings. This strings are gathered from "environment" - keys values from .data files in the skin.

Any other files just passed to the client.

Stock demonstration web interfaces are good example of WSSP capabilities. But WSSP is limited in cases of data convertion or module requests to perform tasks on the server. In such cases you'll need more capable tool.

It's used in CommuniGate Pro Web interface developing desides PBX apllications. There are 14 files with small CG/PL applications in the defailt base Web skin (Users -> Interfaces ).

You'll need to create an application in any text editor, save it as .wcgp and upload into any Web skin.

Then you'll be able to use a link:

http://domain.name:[port]/programFile.wcgp/?Skin=skin_name

To run this application.

http://domain.name:[port]/auth/programFile.wcgp/?Skin=skin_name

Will run on behalf of previously authenticated user.

http://domain.name:[port]/sys/programFile.wcgp

This request searches application only in server's unnamed skin and runs on behalf of postmaster account.

Here is a small example of application running CLI command "listaccounts" and converting the result to JSON format:

entry sysEntry is

void(executeCLI("listaccounts mymac.ru"));
accountList = Vars().executeCLIResult;

SetHTTPResponseCode(200);
SetHTTPResponseData(ObjectToJSON(accountList));

end entry;

Providers usually have some difficulties to develop a unified client because of the huge server's functionality (voice, instant messages including SMS, calendars, contacts, mail, sile storage). It's nessesary to find or develop libraries with SIP, SMTP, IMAP, XMPP and a set of *DAV protocols. The load on the analasis of messtages and data formats from this protocols liest on the client.

As a solution for this problems we've developed XIMMS protocol. The XML Interface to Messaging, Scheduling and Signaling.

All commands of this protocol are simple XML documents with obvious atributes. For example a simple command that redirects (fork) incoming call to two users:

C:<callRedirect id="A018" callLeg="inp003" >
        <To>user1@example.com</To><To>user2@example.com</To>
  </callRedirect>
S:<response id="A018"/>

All data formats (MIME, vCard) are received by XIMMS client in a usable way.

Also this protocol allows to run all CLI commands available on the server. You can change any settings on the server with this protocol.

We've developed XIMMS libraries for some platforms.

As an example of XIMMS client capabilities we recommend Samoware application which you can try on our test stand at demo.communigate.ru.

One protocol instead of 10

You can solve any task with one XIMMS protocol in CommuniGate Pro. Viewing mail, calendars and contacts, making calls and even server administration without nessesary to study a huge number of international standards.

SMTP (Simple Mail Transfer Protocol) SIP (Session Initiation Protocol) XMPP (Extensible Messaging and Presence Protocol) SMPP (Short Message Peer to Peer Protocol) IMAP (Internet Message Access Protocol) POP and RPOP (Post Office Protocol) FTP (File Transfer Protocol) WebDAV (WWW Distributed Authoring and Versioning) LDAP (Lightweight Directory Access Protocol) SNMP (Simple Network Management Protocol)