This topic explains the routing parameters and algorithm for External Service Message and External Service Request 2 script objects.
An ExternalServiceRequest2 or ExternalServiceMessage created in an xMatters Action Script is routed to an external service (e.g., a Management System) via the integration agent or k responsible for interfacing to the external service. This routing is based on the following parameters of the ExternalServiceRequest2 or ExternalServiceMessage:
The service provider corresponds to the registered name of the targeted integration point (i.e., the ID of the integration agent or k). By default, an integration agent is automatically named based on the hostname/IP address of its server and its service gateway port (e.g., system_abc/123.456.789.01:8081). ks are similarly named except they exclude the port.
An integration agent can be explicitly named via the <id> element of its IAConfig.xml:
<integration-agent version="1.0" xmlns="http://www.alarmpoint.com/schema">
<!--
| Each IA must have an ID that is unique within the same xMatters deployment.
|
| The ID is trimmed of leading/trailing whitespace and may be left blank,
| in which case an auto-generated ID of the form <computer-name>/<ip>:<service port>
| will be used.
+-->
<id>agent_xyz</id>
Similarly, a k can be explicitly named via the id attribute of its APAgent.xml:
<alarmpoint-agent version="1.0" mode="enterprise" id="agent_xyz">
The service name corresponds to the registered name of the targeted integration within the integration point.
If the targeted integration is within an integration agent, the service name identifies an Integration Service and has the form <domain>|<name> where the values correspond to those specified in the Integration Service's configuration file:
<integration-service version="1.0" xmlns="http://www.alarmpoint.com/schema">
<!--
| Each service belongs to an event domain and must have a unique
| (case-sensitive) name within the domain. In other words, the
| combination of domain and name forms a unique id for the service.
+-->
<domain>integrity</domain>
<name>help_desk</name>
In this example, the service name is "integrity|help_desk".
In order for xMatters to route an ExternalServiceRequest2 or ExternalServiceMessage, a service name must be provided; however, the service provider is optional. If the event used to create an ExternalServiceRequest2 or ExternalServiceMessage was injected by an integration agent or k, the routing parameters are automatically set so that the ExternalServiceRequest2 or ExternalServiceMessage is routed back to its source integration agent or k. This default behaviour can be overridden by explicitly setting the routing parameters after the ExternalServiceRequest2 or ExternalServiceMessage is created. Additionally, if the event was not injected by an integration agent or k (e.g., the event was injected via web services or the Quick Message panel), the routing parameters must be explicitly set as described in the next section.
After creating an ExternalServiceRequest2 or ExternalServiceMessage from an event object, the Action Script can call the setServiceProvider and setServiceName methods to specify or override the routing parameters as shown in the following example:
01 @serviceRequest = @event::createExternalServiceRequest2()
02 @serviceRequest::setServiceProvider("agent_xyz")
03 @serviceRequest::setServiceName("integrity|help desk")
04 $serviceRequest.request_text = "custom request to management system"
05 @serviceRequest::send()
In this example, the ExternalServiceRequest2 is targeted to Integration Service "integrity|help desk" provided by integration agent "agent_xyz". The same methods are used to target a k integration, but the values will differ (e.g., the service name) to match the k configuration.
An xMatters Action Script routes an ExternalServiceRequest2 or ExternalServiceMessage to an integration point by calling the ::send() method. xMatters first determines whether the ExternalServiceRequest2 or ExternalServiceMessage is targeting an integration agent or k by checking if the service name parameter contains a pipe (|). If so, the targeted integration is assumed to be provided by an integration agent; otherwise, the targeted integration is assumed to be provided by a k. The determination of the targeted integration point type is "assumed" since it is done irrespective of whether the targeted integration service is actually provided by the integration point.
NOTE: Because the targeted integration point type is determined based solely upon the service name parameter, an ExternalServiceRequest2 or ExternalServiceMessage that initially targets an integration agent will never fallback to a k, and vice-versa.
If the targeted integration point is an integration agent, xMatters first attempts to send the ExternalServiceRequest2 or ExternalServiceMessage to the targeted integration agent as identified by the service provider parameter. If this integration agent is not currently registered as being "active" or does not provide the targeted Integration Service as identified by the service name parameter, xMatters will successively and in random order try to send the ExternalServiceRequest2 or ExternalServiceMessage to *any* integration agent that provides the targeted Integration Service.
NOTE: If an integration agent's IAConfig.xml contains an <external-service-request> element with a mode attribute value of "direct", an ExternalServiceRequest2 is sent to the integration agent by a direct web service request; otherwise, an ExternalServiceRequest2 is sent indirectly via the integration agent's web service polling mechanism. An ExternalServiceMessage is always sent to an integration agent indirectly.
If the targeted integration point is a k, a similar routing occurs whereby the ExternalServiceRequest2 or ExternalServiceMessage is preferentially sent to the targeted k with eventual fallback to any k providing the targeted integration.
The ExternalServiceRequest2 or ExternalServiceMessage ::send() method always succeeds (i.e., it does not explicitly indicate failure) even if no integration point is available. An xMatters Action Script can detect if an ExternalServiceRequest2 failed to be routed by implementing a response timeout as shown in the following example:
01 @serviceRequest = @event::createExternalServiceRequest2()
02 $serviceRequest.request_text = "pingdevice"
03 $serviceRequest.device = $event.device
04 @serviceRequest::send()
05 $timeout = 10
06 UNTIL($serviceRequest.completed, $timeout)
07 @external_response = @serviceRequest::getResponse()
08 IF ($serviceRequest.completed)
09 @phone::play("phrase", $external_response.pingresult)
10 ELSE11 @phone::play("phrase", "Ping timed out")
12 ENDIF
In this example, if the ExternalServiceRequest2 cannot be routed to an integration point, the UNTIL statement (line 06) will timeout and the xMatters will play the "Ping timed out" phrase.
NOTE: In the case of an ExternalServiceMessage, there is no indication of whether the delivery was successful.
External Service Message Object