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?). Any XS request can be timed out and rejected by SIP Server. SIP Server can switch to backup mode if there is no active connection to any of the configured Feature Server URLs.
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 active, resulting in the Feature Server VOIP Service DN put out of service, SIP Server starts rejecting call requests with a 503 response.
On receiving error codes "400, 404, 501, 503" or number of request retries exceeded, SIP Server responds with '503' response without any retry. The FS URL should be marked offline on receiving '503' or after exceeding heartbeat failure threshold.
When a SIP Server running in Primary mode, does not have any active connection to any configured Feature Server URL, it should be moved to Backup mode
To control how long an XS request is considered active before it's considered failed, use the xs-request-timeout option.
Below are the new way of SIP Server handling certain error responses from FS instance. A new hidden option "xs-reject-responses" can be used to provide the responses to be rejected by SIP Server without retry. [TABLE] ---
If none of the FS URLs are available and marked Offline, any request for dial plan will be rejected with "503 Service Unavailable" by SIP Server. If the option "switchover-on-xs-oos" is set true, then instead of rejecting the requests, SIP Server will send SERVICE_UNAVAILABLE to SCS, so that it will move to backup mode. This behavior is to make sure dial plan resolution is available all the time and not affected by network disruptions.
SIP Server will start the switchover process after the timeout defined by "time-before-switchover-on-xs-oos". This timeout in seconds, is used to avoid switchover on short disconnection of FS URL.
Once a XS request for dial plan is created, a timer will be started with value set by option "xs-request-timeout". If no response is received within this timeout, the request will be rejected immediately with "503 Service Unavailable".
Heartbeat requests will be sent to a FS URL according to the interval set, irrespective of the URL already having a dial plan request to process. Previously, a heartbeat will be sent only when there is no dial plan request to be sent.
All the above features can be enabled by setting the option "enable-enhanced-dialplan-handling" to true in the Extended Services VOIP Service DN.
---
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