HMP Elements supports the concept of multiple carrier destinations when placing a single call. If one particular carrier, border controller, PBX or other type of endpoint is offline, then HMP Elements will direct the outgoing call to a backup list of servers to ensure call delivery. This eliminates the need for you to code your own mechanism to handle a call that fails at a primary destination. Moreover, HMP Elements will monitor each endpoint by sending OPTIONS requests to those destinations and optionally send you emails to inform you of service failures.
When using this feature, you can configure HMP Elements with a single group of destinations or multiple named groups of destinations.
Defining Destinations
To define your destinations you simply add the following to your HmpElementsServer.exe.config file. You can define as many destinations as you would like.
<setting name="Destinations" serializeAs="Xml">
<value>
<Destinations>
<Destination>
<Name>Carrier1</Name>
<Host>11.22.33.44:5060</Host>
</Destination>
<Destination>
<Name>Carrier2</Name>
<Host>somecarrier.com</Host>
<Destination>
</Destinations>
</value>
</setting>
Defining Destination Groups
At this point you create a Destination Group or Groups depending on your needs. The log file will keep a record of the status of the endpoints as they are polled with the OPTIONS requests.
<setting name="DestinationGroups" serializeAs="Xml">
<value>
<DestinationGroups>
<DestinationGroup>
<Name>IVL</Name>
<Destination>Carrier1</Destination>
<Destination>Carrier2</Destination>
<LogFile>IVL.LOG</LogFile>
<LogLevel>1</LogLevel>
<DestinationHuntMode>Sequential</DestinationHuntMode>
</DestinationGroup>
</DestinationGroups>
</value>
</setting>
Adding Email Alerts (Optional)
Its also a good idea to set the email settings so that if dialing to one endpoint fails you get an alert:
<setting name="EmailTo" serializeAs="String">
<value> support@mydomain.com</value>
</setting>
<setting name="EmailFrom" serializeAs="String">
<value> support@mydomain.com</value>
</setting>
<setting name="EmailUser" serializeAs="String">
<value> support@mydomain.com</value>
</setting>
<setting name="EmailPassword" serializeAs="String">
<value>xxxxxxxxxxxxxx</value>
</setting>
<setting name="EmailSmtpServer" serializeAs="String">
<value>smtp.gmail.com</value>
</setting>
<setting name="EmailSmtpPort" serializeAs="String">
<value>587</value>
</setting>
Usage
To set the default group, edit your VoiceElementsServer.exe.config file and set the default destination host.
<setting name="HmpDefaultDestinationHost" serializeAs="String">
<value>DestinationGroup.IVL</value>
</setting>
Where IVL is the name of the group that you created.
After that you can simply dial out as usual:
ChannelResource.Dial("3035551212);
The system will take care of the rest.
Multiple Groups
You can also setup multiple groups, and through a specific group, other than the default by using the “@” symbol like this:
ChannelResource.Dial("30355512125@DestinationGroup.OtherGroupName")
Dialing Without a Group
If you decide to dial out and you don’t want to use the default group, you can still dial an endpoint manually:
ChannelResource.Dial("30355512125@11.22.33.44:5060")
Destination Hunt Mode
Valid modes are:
- Sequential – All calls are directed to the primary destination. Calls are only directed to subsequent destinations when the primary is offline.
- RoundRobin – All calls are directed to each destination, one at a time, in an attempt to load balance the traffic. Destinations that are offline are skipped.
Note: Versions 10.2.2.0 and up support Sequential mode, and 10.2.3.14 supports both Sequential and RoundRobin modes.
Configuration Options
Sip Options
When configured to send an OPTIONS request, the system expects back a 200 OK from the destination. The system will also accept a 405 Method Not Allowed as a success. You can add and/or remove specific results to further refine the behavior of the system by using the OptionsOk tag:
// The following example adds two more response codes (503 and 603) that represent a success
<Destination>
<Name>Carrier1</Name>
<Host>11.22.33.44:5060</Host>
<OptionsOk>503</OptionsOk>
<OptionsOk>603</OptionsOk>
</Destination>
// Using the NOT symbol as in the following example removes the 405 Method Not Allowed from the default list
<Destination>
<Name>Carrier1</Name>
<Host>11.22.33.44:5060</Host>
<OptionsOk>!405</OptionsOk>
</Destination>
In addition to what is considered a successful response, you can also configure what is considered as a BUSY state for the destination. The defaults for BUSY are 486 Busy Here, and 480 Temporarily Not Available. The busy state will temporarily suspend sending a call to the destination until the destination returns to sending an OK to the OPTIONS request. You can add and/or remove specific results to further refine the behavior of the system by using the OptionsBusy tag:
// The following example adds two more response codes (500 and 501) that represent a busy state
<Destination>
<Name>Carrier1</Name>
<Host>11.22.33.44:5060</Host>
<OptionsBusy>500</OptionsBusy>
<OptionsBusy>501</OptionsBusy>
</Destination>
// Using the NOT symbol as in the following example removes the 480 Temporarily Not Available from the default list
<Destination>
<Name>Carrier1</Name>
<Host>11.22.33.44:5060</Host>
<OptionsBusy>!408</OptionsBusy>
</Destination>
When using the RoundRobin mode, you can control which response codes you wish to have the system retry on a different destination. The defaults are:
- 403 Forbidden
- 480 TemporarilyNotAvailable
- 486 BusyHere
- 488 NotAcceptableHere
- 500 InternalServerError
- 501 NotImplemented
- 502 BadGateway
- 503 ServiceUnavailable
- 504 ServerTimeOut
- 505 SipVersionNotSupported
- 513 MessageTooLarge
- 600 BusyEverywhere
- 603 Decline
- 604 DoesNotExistAnywhere
- 606 NotAcceptable
You can add and/or remove specific results to further refine the behavior of the system by using the DialingRollForward tag:
// The following example adds an additional response code (401 Unauthorized) that represent
<Destination>
<Name>Carrier1</Name>
<Host>11.22.33.44:5060</Host>
<DialingRollForward>500</DialingRollForward>
<DialingRollForward>501</DialingRollForward>
</Destination>
// Using the NOT symbol as in the following example removes the 403 Forbidden from the default list
<Destination>
<Name>Carrier1</Name>
<Host>11.22.33.44:5060</Host>
<DialingRollForward>!403</DialingRollForward>
</Destination>
Finally, you can set the Reporting Options that will notify you via email given certain conditions of a destination. This is done by using the ReportingOption tag. The default options are InService and OutOfService. You can also specify Busy:
// The following example adds the reporting option Busy
<Destination>
<Name>Carrier1</Name>
<Host>11.22.33.44:5060</Host>
<ReportingOption>Busy</ReportingOption>
</Destination>
// Using the NOT symbol as in the following example removes the reporting option InService from the default list
<Destination>
<Name>Carrier1</Name>
<Host>11.22.33.44:5060</Host>
<ReportingOption>!InService</ReportingOption>
</Destination>
Disable OPTIONS reqeusts
To disable sending OPTIONS requests to your destinations, add the following to each destination definition in your config file:
<DestinationMonitorMode>Off</DestinationMonitorMode>