Enhanced handling of XS requests
Starting with version 8.1.103.79, SIP Server can handle different HTTP error responses from SIP Feature Server for Dial Plan extended service (XS) requests in an enhanced way (to notify the origination?).
SIP Server sends an XS request to one of the SIP Feature Server URLs, starts the timer configured by the xs-post-timeout option, and waits for an Feature Server response. When the timeout expires, SIP Server sends an XS request to an alternative Feature Server URL. If SIP Server receives an error response (within the timer period?), it sends an XS request to an alternative Feature Server URL. In both cases, SIP Server sends an XS request to an alternative Feature Server URL only once.
When a Feature Server URL becomes out of service, SIP Server does not send subsequent requests to it until the Feature Server URL becomes in service. The Feature Server URL remains out of service, if the number of failed heartbeat requests exceeds the configured threshold (set in the xs-missed-heartbeat-threshold option), and that URL will not be selected for request processing, until it responds with a 200 OK message for a heartbeat request.
When none of the Feature Server URLs are available and, as a result, the Feature Server VOIP Service DN is placed out of service, SIP Server starts rejecting call requests with a 503 Service Unavailable response.
SIP Server running in primary mode switches over to backup mode if there is no active connection to any of the configured Feature Server URLs. If the switchover-on-xs-oos option is set true, SIP Server reports the SERVICE_UNAVAILABLE status to LCA/SCS to switch over to backup mode instead of rejecting requests. This behavior ensures availability of the dial plan resolution in case of network instabilities.
SIP Server starts the switchover process after the timeout defined by the time-before-switchover-on-xs-oos option expires.
To control how long an XS request is considered active, use the xs-request-timeout option. If no response is received within this timeout, the request is rejected immediately with a 503 Service Unavailable message.
All the above features can be enabled by setting the enable-enhanced-dialplan-handling option to true in the Feature Server VOIP Service DN (service-type=extended).
Configuration Options
enable-enhanced-dialplan-handling
CME object SIP Server Application (Standalone SIP Server) VOIP Service DN with service-type=sip-cluster-nodes (SIP Cluster) Section TServer Default Value: false Valid Values true, false Changes Take Effect: Immediately
Option defines whether the dial plan request enhanced handling feature should be enabled or not.
This includes:
Handling various error codes sent as response from Feature Server Retry XS requests once, on recoverable error responses from Feature Server Use a separate timeout 'xs-request-timeout' for each dial plan request, before which a response is expected. An option to configure timeout specific to the heartbeat requests xs-heartbeat-timeout Marking the URL as offline on heartbeat failures based on threshold set by xs-missed-heartbeat-threshold Reject any XS request or Switchover SIP Server to Backup mode, when no active Feature Server connection exists, based on option switchover-on-xs-oos
xs-request-timeout
VOIP Service DN with service-type=extended
Section TServer
Default Value: 8 Valid Values" 4-32 Changes Take Effect: For the next XS dial plan request
Option defines timeout for XS dial plan request to receive a response in seconds. Timeout starts when XS request is added to the queue and stops when response is received from Feature Server.
On timeout, the request will be rejected with corresponding reason for failure. Request timeout should be set atleast as twice as the post timeout option.
xs-post-timeout VOIP Service DN with service-type=extended Section TServer
Default Value: 4 Valid value: 2-16 Changes take effect: For the next XS dial plan request
Option defines timeout for XS dial plan request in transit in seconds. Timeout starts when XS request is send out and stops when response is received from Feature Server.
On timeout, the request will be either retried with alternate URL or rejected with corresponding error, if retry limit(1) has exceeded.
Post timeout should be set atmost as half as the request timeout option.
xs-heartbeat-timeout VOIP Service DN with service-type=extended
Section TServer Default Value: 5 Valid values: 2-120 Changes take effect: For the next XS heartbeat request
Option defines the timeout used only for XS heartbeat request in seconds.
Timeout starts when a XS heartbeat request is posted to an FS URL and stops when a response for heartbeat is received from Feature Server.
On timeout, the failure will be counted and the URL will be marked offline on reaching threshold defined by xs-missed-heartbeat-threshold
Heartbeat timeout should be set to a value greater than post timeout.
xs-missed-heartbeat-threshold
VOIP Service DN with service-type=extended
Section TServer
Default Value: 3 Valid values: 1 - 10 Changes take effect: Immediately
Option defines number of heartbeat requests failed to get a response, from a Feature Server URL, before marking corresponding URL as offline.
For standalone sip server, use the existing option 'xs-timeout-threshold' at SIP Server application level
switchover-on-xs-oos
SIP Server Application (Standalone SIP Server)
VOIP Service DN with service-type=sip-cluster-nodes (SIP Cluster)
Section TServer
Default Value: false Valid values: true, false Changes take effect: Immediately
When configured true. Specifies SIP Server action in case of losing connectivity with all the Feature Server URLs, configured in the XS VOIP Service DN. To mark a URL as offline, SIP Server use the 'xs-missed-heartbeat-threshold', which will wait for the number of missed heartbeats to reach this threshold. SIP Server will wait until all the configured Feature Server URLs become offline, before reporting SERVICE_UNAVAILABLE status to LCA/SCS in order to trigger switchover.
If set as false, SIP Server return '503 Service Unavailable' for all calls, until one of the Feature Server URLs becomes available. Switchover will not happen in this case and by default.
time-before-switchover-on-xs-oos CME object (Semi-hidden)Application (Standalone SIP Server)
VOIP Service DN with service-type=sip-cluster-nodes (SIP Cluster)
Section TServer Default Value: 1 Valid values 0-60 Changes take effect: Immediately
Used to calculate timeout for SIP Server to report SERVICE_UNAVAILABLE in scenario described by switchover-on-xs-oos option. When applicable XS VOIP Service DN detected OOS, SIP Server waits for this time interval, before reporting SERVICE_UNAVAILABLE. 0 means SERVICE_UNAVAILABLE will be reported immediately after XS VOIP Service DN detected as OOS
xs-pool-size CME object SIP Server Application (Support for Existing Option) VOIP Service DN with service-type=extended
Section TServer Default Value: 10 Valid values: Any number of connections that is possible for the system Changes take effect: For the next XS request
Option defines number of connections to one Feature Server URL. Setting in DN level will have high priority.
xs-heartbeat-interval CME object SIP Server Application (Support for Existing Option) VOIP Service DN with service-type=extended Section TServer
Default Value: 10 (incremented from earlier value of 4) Valid values 0-65535 Changes take effect: For the next XS request
Option defines heartbeat messages interval in seconds. Value 0 disables heartbeats. Setting in DN level will have high priority.
xs-reject-responses CME object VOIP Service DN with service-type=extended
Section TServer Default Value: 400,404,501 Valid values: Any valid error responses from FS Changes take effect: For the next XS request
Comma separated values. Option defines the responses from FS, that should be rejected without any retry using alternate FS connection
This should remain as a hidden option and exposed to customer only on requirement.
Feature Limitations
SIP Server will reject the dial plan requests with '503 Service Unavailable' response, instead of '603 Decline', when
1. Retry limit for a request exceeded. 2. None of the FS URLs are available to provide service.
In PEC, there could be scenarios where, SIP Server version and FS version mismatch.
In case, 1. FS version is having this improvement implemented, but SIP Server version does not have this feature.
SIP Server will return the original destination for dial plan, if FS returns any error code. There will not be any retry or specific error handling.
2. SIP Server version is having this improvement implemented, but FS version does not have this feature.
If this feature is enabled, SIP Server will use the retry mechanism and start a timer after adding a request to queue with value in xs-request-timeout. But, FS will not provide specific error codes such as 400,404,501 etc., instead it will send 500 for all errors. If this feature is not enabled, then SIP Server will return the original destination for dial plan, if FS returns any error code. There will not be any retry or specific error handling