Enhanced handling of XS requests
Starting with version 8.1.103.80, SIP Server can handle different HTTP error responses from SIP Feature Server for Dial Plan extended service (XS) requests in an enhanced way to address connection instabilities and provide a quality response to the origination side.
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 a 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.
This table summarizes SIP Server actions for handling certain error responses received from Feature Server.
| Error Code | Description | Action |
|---|---|---|
| 400 Bad Request | Invalid Request Format | SIP Server responds to a caller with the 503 message. It doesn't resend a request and doesn't mark the Feature Server URL as out of service. |
| 404 Not Found | Invalid API | SIP Server responds to a caller with the 503 message. It doesn't resend a request and doesn't mark the Feature Server URL as out of service. |
| 501 Not Implemented | Unsupported operation type | SIP Server responds to a caller with the 503 message. It doesn't resend a request and doesn't mark the Feature Server URL as out of service. |
| 503 Service Unavailable | Feature Server is unable to provide a response | SIP Server resends a request with an alternative Feature Server URL and marks the Feature Server URL that responded with 503 as out of service. |
| Any error response or Request Timeout | Feature Server internal error or unable to process a request | SIP Server resends a request with an alternative Feature Server URL and marks the Feature Server URL that responded with 503 as out of service, and responds to a caller with 503 on receiving an error or a timeout for retry. |
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 message.
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 to 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, SIP Server rejects the request 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
Setting: [TServer] section, the SIP Server Application (standalone SIP Server) or the VOIP Service DN with service-type=sip-cluster-nodes
Default Value: false
Valid Values: true, false
Changes Take Effect: After restart
When set to true, enables enhanced handling of Dial Plan extended service (XS) requests by SIP Server. This includes:
- Handling of various error codes sent as responses from Feature Server.
- Resending XS requests once on recoverable error responses from Feature Server.
- Setting a timeout (xs-request-timeout) for each dial plan request.
- Setting a timeout specific to the heartbeat requests (xs-heartbeat-timeout).
- Marking the URL as out of service on heartbeat failures based on the threshold set by xs-missed-heartbeat-threshold.
- Rejecting any XS request or switching SIP Server to backup mode when no active Feature Server URLs are available (the switchover-on-xs-oos option).
xs-request-timeout
Setting: [TServer] section, the VOIP Service DN with service-type=extended
Default Value: 8
Valid Values: 4-32
Changes Take Effect: For the next XS dial plan request
Specifies the timeout, in seconds, that SIP Server waits for a Feature Server response on an XS request. The timeout starts when the XS request is added to the queue and stops when a response is received from Feature Server. When the timeout expires, SIP Server rejects the XS request with a corresponding error. The request timeout must be at least twice as long as the xs-post-timeout option value.
xs-post-timeout
Setting: [TServer] section, the VOIP Service DN with service-type=extended
Default Value: 4
Valid Values: 2-16
Changes Take Effect: For the next XS dial plan request
Specifies the timeout, in seconds, for an XS request in transit. The timeout starts when the XS request is sent out and stops when a response is received from Feature Server. When the timeout expires, SIP Server either resends the XS request to an alternative Feature Server URL or rejects with a corresponding error if the limit of retries (more than 1) has exceeded. The post timeout must not be more than half of the xs-request-timeout option value.
xs-heartbeat-timeout
Setting: [TServer] section, the VOIP Service DN with service-type=extended
Default Value: 5
Valid Values: 2-120
Changes Take Effect: For the next XS heartbeat request
Specifies the timeout, in seconds, for an XS heartbeat request. The timeout starts when an XS heartbeat request is posted to a Feature Server URL and stops when a response for a heartbeat is received from Feature Server. When the timeout expires, SIP Server counts the number of failures and marks the URL as out of service if the threshold specified by the xs-missed-heartbeat-threshold option is reached. The heartbeat timeout must be greater than the xs-post-timeout option value.
xs-missed-heartbeat-threshold
Setting: [TServer] section, the VOIP Service DN with service-type=extended
Default Value: 3
Valid Values: 1-10
Changes Take Effect: Immediately
Specifies the maximum number of failed heartbeat requests that SIP Server receives from a Feature Server URL, before marking the corresponding URL as out of service.
switchover-on-xs-oos
Setting: [TServer] section, the SIP Server Application (standalone SIP Server) or the VOIP Service DN with service-type=sip-cluster-nodes
Default Value: false
Valid Values: true, false
Changes Take Effect: Immediately
Specifies the SIP Server action in case of losing connectivity with all Feature Server URLs. SIP Server marks a URL as out of service when the threshold of failed heartbeat requests set by the xs-missed-heartbeat-threshold option is reached. When set to true and all configured Feature Server URLs become out of service, SIP Server reports the SERVICE_UNAVAILABLE status to LCA/SCS to switch over to backup mode. When set to false, SIP Server responds with a 503 Service Unavailable message to all calls, until one of the Feature Server URLs becomes available.
time-before-switchover-on-xs-oos
Setting: [TServer] section, the SIP Server Application (standalone SIP Server) or the VOIP Service DN with service-type=sip-cluster-nodes
Default Value: 1
Valid Values: 0-60
Changes Take Effect: Immediately
Specifies the timeout, in seconds, that SIP Server waits before reporting the SERVICE_UNAVAILABLE status in a scenario described in the switchover-on-xs-oos option. When set to 0 (zero), SIP Server reports the SERVICE_UNAVAILABLE status immediately after the Feature Server VOIP Service DN is detected as out of service.
xs-pool-size
Setting: [TServer] section, the SIP Server Application (standalone SIP Server) or the VOIP Service DN with service-type=extended
Default Value: 10
Valid Values: Any number of connections that is possible for the system
Changes Take Effect: For the next XS request
Specifies the maximum number of connections to one Feature Server URL. The setting at a DN level takes priority.
xs-heartbeat-interval
Setting: [TServer] section, the SIP Server Application (standalone SIP Server) or the VOIP Service DN with service-type=extended
Default Value: 10
Valid Values: 0-65535
Changes Take Effect: For the next XS request
Specifies the heartbeat messages interval, in seconds. Value of 0 (zero) disables heartbeats. The setting at a DN level takes priority.
Feature Limitations
- SIP Server rejects the Dial Plan XS requests with a 503 Service Unavailable message instead of a 603 Decline message, when:
- A retry limit for a request is exceeded.
- None of the Feature Server URLs are available to provide a service.
- This feature depends on support from a specific version of SIP Feature Server. Consult corresponding documentation for the availability of this new feature in that component.