Geekly Articles each Day
📜 ⬆️ ⬇️

CommuniGate Pro Unified Communications Server API



Everyone who installed new complex systems in organizations was faced with the fact that software developers did not anticipate their specific need for an administrative or user interface.

In the case of communications, the need for additional processing of correspondence, calls and messages is usually added to this, as a rule, for the purpose of security, employee monitoring and statistics collection.
')
In this article, we will look at a set of tools that the CommuniGate Pro server has for


CLI


The command line interface is a standard way to manage many products. Convenient for automating administrative tasks. The format and the full description of the commands are beyond the scope of the article, but you can see them in the manual , we give just a few examples:

Poppwd access

The server has several ways to access the CLI. One of the most convenient for acquaintance with the commands can be considered the PWD module. With the standard server configuration, it is enough to type in the command line of the OS "telnet server.address 8106" (or "telnet server.address 106", depending on the OS and version). Initially, this module was simply the implementation of the 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


But there is no reason to dwell on one text command:

 listdomains 200 data follow (mymac.ru) listaccounts mymac.ru 200 data follow { pbx = macnt; postmaster = macnt; user1 = macnt; user2 = macnt; }

The word macnt in this answer means Multi-mailbox Account

HTTP access

CLI commands can also be executed by sending a simple POST or GET request with the parameter “command” to the address server.name:[http port] / CLI /.


Libraries

Since “naked” text access is not very convenient for practical tasks, we created Perl and Java libraries for working with CLI.

On our site there is a special section , where examples of CLI scripts for solving common problems are presented.

The execution of CLI commands is also possible in the XIMSS protocol (cliExecute command) and in the CG / PL program (the ExecuteCLI () function), which we will discuss in the corresponding sections.

Post and Signal Rules


Probably, assigning rules to an API can be called a stretch, but in Communigate Pro, the rules are used not only to redirect letters and calls between accounts and mailboxes, but also send letters to third-party programs (for example, various filters), run CG / PL programs, and even run scripts in the operating system - in general, are actively used for integration both by themselves and in conjunction with other APIs.

Signals in Communigate Pro call special objects that are used in real-time communications. A signal is a unit of Real-time communication. Various participants (SIP, XMPP clients, PBX applications, ...) send signals to each other to organize, terminate and update dialogs and other actions.


How the rules work

The rules are divided into three levels - server, domain and account level (account). Each of these levels has separate rules for signals and for mail.

Each rule has a name and priority, signal rules have another “When” condition. The higher the priority - the earlier, under the same other conditions, the rule will work. The “When” condition determines at what point the rule triggers — at what second of signal processing or when an error occurs with a specific code (Not responding, Busy, or other errors):





Mail order:

Signal processing order:

Examples of using

Domain forwarding restrictions:

All calls to recipients outside certain domains are redirected to the specified address:


Helper


The Communigate Pro implements the Helper protocol, which allows you to use programs external to the server for various tasks.

If certain conditions are met, for example, the mail rule runs a filter for the letter that processes or in the domain external authentication is triggered, the server starts the Helper program. After that, it starts sending the Helper protocol commands via the standard input and reads the answers from the standard output.

An example of some generalized session for the helper protocol (I - input to the program, 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, the INTF command coordinates the protocol version, and QUIT ends the session, * is an informational message to which the server does not respond, but writes it to the log.

Within this protocol, more specialized ones have been developed for:


All of them are connected on the Settings-> General-> WebAdmin Assistants interface.

All paths to executable files are counted from the base directory of Communigate Pro (directory with user data).

Processing the body of the letter

Mail handlers are triggered by a mail rule, for example:



A detailed description of the commands of this and other helpers can be found in the manual . The article will give only a general description.

Helpers of this type are used mainly to connect to the CGPro anti-virus and anti-spam engines .

External authentication

The helper protocol for external authentication is usually used if:


Examples of this type of helpers can be found on this page .

The remaining helpers

Banner system helpers provide the server with banners for XIMSS and other (for example HTTP) clients.
RADIUS helpers allow you to add additional checks to the authentication process using the RADIUS protocol.
Load sharing helpers manage the Load Balancer in the Communigate Pro cluster configuration .

WSSP


WSSP (Web Server-side Pages) is a language for Web page templates.
Before talking about WSSP, you need to put in a few words about the organization of Web skins on the server.

Each Web skin consists of three types of files:


Together with the Communigate Pro distribution kit comes a small set of standard (stock) Web interfaces. One of them is nameless (Unnamed), the others are named. These demonstration skins are stored in the Application folder of the server (the folder in the OS where the executable file is located) and therefore they are replaced when the server is updated. Administrators should not change the demonstration skins in their configurations, these changes may be lost when installing the update. Instead, you need to take advantage of the fact that the skin files form a hierarchy.

File hierarchy in skins

Each skin can be server, domain or standard.

When processing requests from the user's browser, the server usually needs to get files with specific names from the skin. Moreover, if the file is not found in the domain skin, then it is searched for in the server skin with the same name. And if not found in the server, then look for in stock. If the file is still not found and the current skin is named, then the file is searched for in nameless skins.

Thus, by uploading your own files to a nameless server skin, the server administrator can ensure that his files will be used, rather than the standard ones.

That is, with this approach, you can make small changes in the standard skins, and develop your own from scratch.

String files

The .data files contain text data (UFT-8) in the CG / PL format of the dictionary. These data are used by various server modules to form strings in the interface or as setting values.

These files also form a hierarchy, but already at the key level in the dictionary, that is, if a key is missing from the domain strings.data file, the server tries to find it in the server level strings.data file, etc.

English is the default language for strings in the interface. If the user's language (session) is different from English, the key values ​​from the language files (french.data, russian.data) replace the values ​​from the strings.data file.

Such a system allows including slightly modified interfaces (strings.data files) to include only those keys whose values ​​have been changed (for example, company name, brand names), and not their full set.

Query Processing

When the browser connects to the server using the HTTP protocol, the server retrieves the host name from the request and searches for a domain with that name. If the domain is found, the server finds the skin selected as the default Web interface for users of this domain. The login.wssp page is launched.

The wssp files consist of markup code (usually HTML) with some additional elements:

An example of such a document:
 <html> <body> <h1>   %%server%%.   %%ID%%.</h1> <!--%%IF EXISTS(lastLogin)-->     %%lastLogin%% <!--%%ENDIF--> </body> </html>

After processing by the server, all special constructions will be replaced with strings or arrays of strings from the “environment” - key values ​​from .data files in the skin, domain name or other objects in the server, settings values.

Any other files are simply given to the client.

Basic demonstration web interfaces can be considered as excellent illustrations of the capabilities of WSSP pages. But WSSP is quite limited in converting data formats or accessing various modules and performing any actions on the server. And here a more powerful tool comes to the rescue.

CG / PL


About the CG / PL language and the development of PBX applications on it, we have already told on Habré in this article .

In addition to PBX, it is actively used in the development of Communigate Pro Web interfaces. If you open the list of files even basic Web skin (Users-> Interfaces), then there will be 14 files with small CG / PL programs that process HTTP requests.

To call a CG / PL program to process an HTTP request, you need to write it in any text editor, save it as .wcgp and upload to any Web skin.

After this request to the URL of the form:

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

Run the program for execution.

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

Run on behalf of the account with pre-authentication

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

This request looks for the program only in the server Unnamed skin and runs postmaster (server administrator) on behalf of the user

As an example, consider a small script that executes the CLI command "listaccounts" and converts the result to JSON format:

 entry sysEntry is void(executeCLI("listaccounts mymac.ru")); accountList = Vars().executeCLIResult; SetHTTPResponseCode(200); SetHTTPResponseData(ObjectToJSON(accountList)); end entry;



Ximss


With such a large amount of functionality on the server side - voice, instant messages (including SMS), calendars, contacts, mail, file server service providers have some difficulties with writing a unified client. It is necessary to select or develop libraries implementing SIP, a set of * DAV protocols, SMTP, IMAP, XMPP. At the same time, the load on parsing messages and data formats from these protocols lies with the client.

As a solution to these problems, we developed the XIMSS protocol — the XML Interface to Messaging, Scheduling and Signaling.

All commands of this protocol are simple XML documents with transparent attributes. For example, this simple command will fork an 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) come to the XIMSS client in an easy-to-use format.

Also, this protocol allows you to perform all CLI commands available on the server - through it you can adjust all types of settings, including administrative

For a number of platforms, we have developed ready-made XIMSS libraries .

As examples of XIMSS client capabilities, we recommend the Pronto! Series of applications, whose Web versions (HTML5 and Flash) can be tried at our booth, bestvoip.ru .

Finally


Communigate Pro is a platform whose behavior can be regulated at different levels. From the client to access to the main communication modules and the development of its own functionality based on standard protocols. At the same time, the solution is stable and withstands heavy loads.

Although the input threshold for all Communigate APIs in aggregate may seem rather large, they cover most of the tasks of the administrators of communication services.

Source: https://habr.com/ru/post/197720/

More articles:


All Articles