Look what Java and SIP can do
 (SIP)Java = ∞
Home     News     Projects     Downloads     Support     Contact
SipExchange Home

Terminologies

SipExchange Overview

 SipExchange Basics

System Administration Howto

Feature  Development using SipExchange

External Call Control with SipExchange

To understand this section fully, please make sure that you have read the following topics first:
Table of Contents

Overview

As explained in the overview section, one of the primary functions of SipExchange is to setup and tear down SIP call sessions between two or more parties. It also provides the business logic for handling of features subscribed by the users of the system. Examples of subscriber features include "call forwarding", "call blocking", etc.  In this sense, SipExchange is a call processing engine similar to telephone switches and PBXs.  The call processing engine of SipExchange consists of a number of components. They are:
  1. Registration service: When a subscriber turns on the SIP phone, the phone registers with the SipExchange server. This is like a login procedure. The registration is handled as per procedures laid out by the SIP protocol. In addition to authenticating the user, the SipExchange server stores the contact address of the subscriber in a location database. A subscriber can be registered from multiple phones at multiple locations. The SipExchange server also handles the "unregistration" and expiry of registration. In this case, it removes the contact information from the location database.
  2. Location database: The location database provides a persistent storage for storing contact information for registered subscribers.
  3. Proxy service: The proxy service handles incoming call requests from subscribers and non-subscribers. When a session initiation request is received from a SIP phone, the proxy service locates the called user from the location database and forwards the request to the location(s) of the called user. Note that the proxy service does not forward sessions from a non-subscriber to a non-subscriber. Therefore, it can only handle calls to a subscriber and/or from a subscriber. During the processing of requests, SipExchange also handles the special cases for features subscribed to by the calling and called subscribers.
SipExchange provides hooks using which external agents can control how the proxy service handles the call setup. This process is called external call control. Using this mechanism, you can create your own features and services. For example, suppose you want to implement a "paging" feature. In this feature, when an user calls the address sip:operator@someaddress, the call is forwarded to one of the many operators who are currently logged in to the system. When no operators are available, the feature sends a page to one or more operators and when one of them logs in to the system, the call is forwarded to the operator. It is impossible to implement this service on switching equipment that does not provide external call control and where you have no way of adding this service yourself. Through external call control mechanisms, you can create some of these features yourself by providing the service logic for the feature and "plugging" it into the SipExchange server.

Service switching point and Service control point

SipExchange provides external call control hooks very similar to how existing Advanced Intelligent Network (AIN/IN) telephony solutions provide external call control hooks. In the AIN/IN concept, there are basically two components:
  1. Service switching point (SSP): The SSP provides the business logic for setting up and tearing down calls. While processing a call, the SSP makes a determination based on configuration that it needs to contact an external agent to determine how the call is to be handled. It sends a message over the signaling network to the external agent. The external agent sends a response specifying how the call should be handled, and the SSP alters the call flow accordingly.
  2. Service control point (SCP) : The SCP is the external call control agent and acts as the feature server. An SSP can contact different SCPs based on the configuration even while processing a single call.  
Lets take an example of how this model provides a feature like "call forwarding".  The SSP receives a request to route an incoming call to a subscriber. In the process of terminating the call to the called user, it looks up in the subscriber database to determine if the subscriber has a "terminating trigger" (explained shortly) condition attached to it. If this trigger condition is satisfied (met), the SSP sends a trigger message to the SCP with the subscriber and trigger information.  The SCP looks up in a database to determine if the subscriber has activated call forwarding. If not, it sends a "continue" response to the SSP. Otherwise it sends a "redirect" response to the SSP with the reroute address. On receiving a continue message, the SSP terminates the call to the called party. Otherwise, it redirects the call to the reroute address received from the SCP. As evident with this example, even though the SSP does not have call forwarding feature built into it, it is possible to provide the feature using the SCP as long as the SSP supports AIN-style triggering.

SipExchange provides the SSP functionality in this model of external call control. The SipExchange server can communicate with one or more SCPs using which it provides all the features. You can create your own SCPs to implement services and features that you need.

Triggers and trigger processing

As explained above, triggers are points in the call where the SipExchange server communicates with an external SCP in order to find out how to process the call. Certain calls may not encounter any trigger condition and may be processed using the standard call processing logic while other calls will encounter trigger conditions that are processed by the SCP to alter the call flow.

A trigger condition can be configured by system administrators from the SipConsole user interface. Broadly speaking, there are two types of trigger conditions that can be configured. They are:

  1. Subscriber triggers: For any subscriber(s), you can configure one or more subscriber triggers. When the call processing module processes a call from or to this subscriber, it checks if a trigger condition matches and if the trigger has been configured for the subscriber. The trigger conditions are explained in details below. If both these conditions are satisfied, the SipExchange server sends a trigger message to the SCP and alters the call flow based on the response from the SCP.
  2. Domain triggers: Similarly, for any domain(s), you can configure one or more domain triggers. When the call processing module processes a call from or to an user in this domain, it checks if a trigger condition matches and if the trigger has been configured for the domain. The trigger conditions are explained in details below. If both these conditions are satisfied, the SipExchange server sends a trigger message to the SCP and alters the call flow based on the response from the SCP.

Trigger types

The system currently supports the following types of triggers:

  1. MakeCall: This trigger can be assigned to a subscriber. When the subscriber (calling user) makes an outgoing call, this trigger is encountered.
  2. ReceivedCall: This trigger can be assigned to a subscriber. When the subscriber (called user) receives an incoming call, this trigger is encountered.
  3. CalledBusy: This trigger can be assigned to a subscriber. When the subscriber (called user) receives an incoming call and he/she declines the call or has the SIP phone set to busy mode, this trigger is encountered.
  4. CalledNoAnswer: This trigger can be assigned to a subscriber. When the subscriber (called user) receives an incoming call and he/she does not answer the call, this trigger is encountered.
  5. CalledNotAvailable: This trigger can be assigned to a subscriber. When the subscriber (called user) receives an incoming call and he/she is not registered, this trigger is encountered.
  6. CalledAddress: This trigger can be assigned to a domain. When a call is received for an user in this domain and the called user name matches a configured pattern, this trigger is encountered. Note that the called user name does not have to be provisioned as a subscriber. See the operator pool feature for an example of how this trigger might be used.

There are additional triggers planned for upcoming releases. The following diagrams illustrates when and how these triggers are encountered during call processing:



The above diagram displays how the call processing module processes incoming calls and under what circumstances, the triggers are encountered. the triggers are shown using red boxes.



The above diagram shows how a CalledBusy trigger is encountered.


The above diagram shows how a CalledNoAnswer trigger is encountered.

Trigger configuration

The subscriber and domain triggers are configured from the SipConsole. You can get a list of triggers configured for a domain or a subscriber by selecting the domain or the subscriber respectively and by clicking on the "Triggers" button. From the list screen, you can add or remove triggers. The following screen-shot shows the parameters that you can enter.



Here is a more detailed explanation of the parameters:
  1. Feature: Name of a feature that the SCP implements using this trigger. This information is sent to the SCP in the trigger message.
  2. Trigger: The type of the trigger as explained above.
  3. Order: An integer number indicating the order in which this trigger is processed. Basically, for a given trigger type, there may be one or more triggers assigned to the subscriber/domain to implement one or more features. The order specifies in which order the triggers are reported to the SCP. The smaller the number, the earlier the trigger is reported. When the SCP responds to the first trigger (explained later), it may either send a response asking the SSP to continue call processing or alter the processing of the call. If the continue response is received, the trigger next in the order is sent to this or another SCP. If the SCP responds with a directive to alter the call flow, the subsequent triggers are ignored. Basically, the order provides a way for one feature to take precedence over another.
  4. Parameter: A trigger-dependent parameter can be entered here. For most triggers, this may not have any significance except that this information is sent to the SCP in the trigger message and may be used by the SCP to provide a particular type of treatment. However, for the CalledAddress trigger, the pattern is specified using this field. As mentioned earlier, the pattern is matched against the called user id to determine if the trigger condition is encountered. For the CalledAddress trigger, the trigger must be entered in the form:

         pattern=some-regular-expression&param=some-param

    Replace some-regular-expression with the pattern defined using regular expressions and some-param is the parameter that you want to see sent to the SCP. Note the '&' between the pattern and param definition.
  5. Service Controller: The URL of the service controller. The URL specifies the SCP host name, port (optional) and the protocol using which the SCP communicates with the SSP. As explained in the trigger processing section, SipExchange uses the JBOSS remoting services for communication between the SSP and the SCP, and this URL follows the same URL scheme. Please refer to the feature guide for the feature you are administering to find out how you populate this field.

    As you can see, for each trigger, you can define a separate SCP. Therefore, it is possible to have more than one feature server, each providing one or more features.

Trigger processing

When a trigger is encountered, the trigger condition is reported to the SCP using a communications message. SipExchange uses JBOSS Remoting services for communication between the SSP and the SCP. 

Here is an explanation of JBOSS Remoting lifted from the web site:
The purpose of JBoss Remoting is to provide a single API for most network based invocations and related service that uses pluggable transports and data marshallers. The JBoss Remoting API provides the ability for making synchronous and asynchronous remote calls, push and pull callbacks, and automatic discovery of remoting servers. The intention is to allow for the addition of different transports to fit different needs, yet still maintain the same API for making the remote invocations and only requiring configuration changes, not code changes, to fit these different needs.
It provides the following types of transport:

  • Socket (SSL Socket)

  • RMI

  • HTTP(S)

  • Multiplex

  • Servlet

Basically, it allows Java objects to be passed between the client and the server using one of the above protocols for transport. The SipExchange server acts as the client and the SCP acts as the server. The client "invokes" a service on the server and the server "responds" back after serving the request embedded in the invoke. The invocation is similar to a remote procedure call and internally, "serialized" Java objects containing detailed information about the invoke and the response are exchanged between the client and the server. The underlying serialization and messaging is transparent to the client and the server application.
Invocation request
  While invoking the SCP service, the SipExchange server sends the following information to the SCP:
  1. Feature
  2. Trigger type
  3. Parameter
  4. Calling subscriber information from the subscriber database, if the caller is a subscriber
  5. Called subscriber information from the subscriber database, if the called party is a subscriber
  6. Calling domain name if the caller belongs to a domain that the SipExchange server is serving
  7. Called domain name if the called party belongs to a domain that the SipExchange server is serving
  8. Trigger-specific parameter, if any
  9. SIP message that caused the invocation.
Response
The SCP may respond with one of the following options:
  1. Continue: The SCP uses this response to tell the SipExchange server that it must continue processing the call. The SipExchange server continues to process the call as if the trigger was never encountered. The call may have more than one trigger associated with this trigger point. In that case, the call processing service processes the invocation for the next trigger. While continuing to process the call, if it encounters additional trigger conditions, each invocation is sent to an SCP as required by the trigger.
  2. Terminate: The SCP uses this response to tell the SipExchange server that it must terminate (end) the call. The SipExchange server sends a response to that effect. The status code and reason phrase sent in the SIP response message are those received from the SCP in the SCP response message.
  3. Re-route: The SCP uses this response to tell the SipExchange server that it must forward or redirect the call to another address or to multiple addresses. The SipExchange server acts accordingly. The difference between the forwarding and rerouting is that in the latter case, the SipExchange server sends a REDIRECT SIP response to the calling party.
There are additional response types planned in the upcoming releases including the capability to play voice announcements to the caller, collect digits and provide other media services. This will extend the scope of what type of services an SCP can provide even further.

Feature examples

Now that we understand how SipExchange call processing and external call control works, let's take a few examples of features that can be developed using this feature.

Call forwarding

The call forwarding feature allows a subscriber to set a forwarding address. When a forwarding address is set, all calls to this subscriber are forwarded to the address. When reset, the call is terminated to the subscriber as usual.

  1. A ReceivedCall trigger is added to the subscriber who has subscribed to the call forward feature. The service controller parameter contains the URL for the SCP providing the service logic for this service.
  2. The trigger parameter (see above) serves to designate the address to which calls for this subcriber are to be forwarded. The service provider leaves this blank when assigning the trigger to the subscriber. It will be set at a later time by the subscriber. Whenever it is blank (no forward-to address is present), call forwarding is disabled.
  3. When the subscriber enables call forwarding, the parameter value is set to the address(es) to which his/her incoming calls are to be forwarded. Of course, some sort of user interface has to be provided for the subscriber to activate and deactivate this feature. It could be a web-based user interface or it could be done from a SIP phone which, itself, can be another external call control feature. The call forwarding feature can be deactivated by clearing out the address(es). We will provide in an upcoming release a web-based user interface for subscribers to use so that they can self-provision their features.
  4. When SipExchange receives a call for this subscriber, it encounters the ReceivedCall trigger and invokes the SCP service. The SCP looks at the parameter. If the parameter is blank, it sends a continue response. Otherwise, it sends a re-route response containing the rerouted addresses.
  5. On receiving the reroute response, the SIpExchange server reroutes the call to the appropriate addresses. On receiving the continue response (call forwarding is deactivated), it continues to terminate the call to the called subscriber.

Operator pool

Using the operator pool feature, you can define an address like sip:operator@cafesip.org which is not an address of any subscriber but is more like a pool of users. The feature forwards matching calls to an user belonging to the pool.
  1. A CalledAddress trigger is added to the domain that needs this feature. The service controller parameter contains the URL for the SCP providing the service logic for this service.
  2. The trigger parameter (see above) is used to store the called user pattern "operator" (or whatever you are calling the operator pool) as well as a list of address(es) to which calls are forwarded when the trigger is encountered.
  3. When SipExchange receives a call to the address "operator", it encounters the CalledAddress trigger and invokes the service on the SCP. The SCP looks at the parameter to determine the address(es) to which the call is to be re-routed. It sends the re-route response accordingly.
  4. On receiving the reroute response, the SIpExchange server reroutes the call to the address(es) specified by the SCP. The phone rings for all the users belonging to the specified addresses. The first user answering the call gets to talk, and ringing stops on all the other phones that were specified.

Developing your own external call control service

This topic is explained in more details in the Feature Development Guide.

Search this website 


Send questions or comments about this web site to webmaster@cafesip.org.
Copyright © 2005, CafeSip.org.
Licensed under the CafeSip License.
The CafeSip.org projects, web site and web facilities have been sponsored by QUIK Computing