Integration Agent configuration files

Each Integration Agent must have a unique ID across all collaborating Integration Agents. If you don't specify this parameter, a default agent ID is auto-generated in the format <computername>/<ip>:<service-gateway port>. For example: <id>workstation-198-bsmith/10.2.0.121:8081</id>

If you assign a custom agent ID, make sure that any < and & characters in the name are replaced with their XML entity names (in other words replace < with &lt; and & with &amp;). Any leading or trailing whitespace is removed.

Use the proxy-config settings if you need to configure the Integration Agent to communicate with xMatters via a proxy server. By default, the proxy-config section commented out, and the Integration Agent does not use a proxy server.

Sub-elements:

• <proxy-enabled>: Specifies whether the proxy configuration settings are enabled; this must be set to true for the Integration Agent to use the proxy settings.
• <proxy-host>: The IP address or hostname of the proxy server you want the Integration Agent to use.
• <proxy-port>: The port to use on the proxy server.
• <proxy-auth-username>: If required, the username used to authenticate with the proxy server. If the proxy server does not require authentication, this field must be commented out.
• <proxy-auth-password-path>: If required, the path (relative to this file) that refers to a file containing the password (encrypted via iapassword) to use to authenticate with the proxy server. If the proxy server does not require authentication, this field must be commented out.

If the proxy-auth-username and proxy-auth-password-path tags aren't commented out, the Integration Agent sends an authorization header to the proxy server, even if the tags are empty. If the tags are empty; the header contains only a ":" character, which can cause the proxy connection to be refused.

• <proxy-auth-ntlm-domain>: The domain name to use for the proxy server if it uses NTLM v1 authentication. If the proxy server does not use NTLM v1 authentication, omit this setting or leave it blank (NTLM v2 is not currently supported).

If you're using a wrapper.conf file which specifies proxy settings, those settings will override the proxy settings in IAConfig.xml. Use the wrapper.conf file that was shipped with the Integration Agent, as older wrapper files may not be forward-compatible.

The Integration Agent uses this account to register itself with xMatters and to send and receive incidents and responses. The specified account must exist as a Web Services User in xMatters, and must have the "Register Integration Agent", "Receive APXML", and "Send APXML" privileges.

Sub-elements:

• <user>: Login name (username) for the xMatters web service user account.
• <password>: Path (absolute or relative) to a file containing the login password for the account. The file is encrypted using the iapassword application, and must be created for the web service user (the default is ./.wspasswd).
• <company>: Company that includes the xMatters web service user account. This value can be left blank if the deployment does not have more than one company. The integration services that are provided by this Integration Agent belong to the specified Company.

The Integration Agent periodically sends a heartbeat request to xMatters to identify the integration services it provides. The heartbeat element settings identify the web server the Integration Agent should target with these registration attempts.

The URLs specified must point to the location of the AlarmPointWebService, and begin with https://. The URL cannot have a query or fragment component (the URL must be resolvable from the Integration Agent). For example:

https://xyzcustomer/api/services/AlarmPointWebService

Sub-elements:

• <primary-servers>: The primary location of each server's RegisterIntegrationAgent Web Service.

See the Health Monitor section in the full Integration Agent 5.2 guide for more information about the messages associated with these settings.

If enabled, only clients with IP addresses that match a listed address are allowed to submit requests to the Integration Agent. This includes the IP addresses of xMatters Application Server Nodes and users of APClient.bin.

Attributes and sub-elements:

• @enable: Controls whether requests are authenticated by IP address (values: true, false).
• <ip>: IP address identifying an authorized client. You can have 0 or more IP addresses. Addresses can include wildcards (for example, 192.168.168.* would authorize all IP addresses beginning with 192.168.168).

If enabled, only clients that provide the correct password are allowed to submit requests to the Integration Agent. This includes xMatters Application Server Nodes and users of APClient.bin.

Attributes and sub-elements:

• @enable: Controls whether requests are authenticated by password (values: true, false).
• <password>: Path (absolute or relative) to a file containing the access password. The file is encrypted using the iapassword application and must be created before you can use the Integration Agent (the default is ./.passwd).

This determines the behavior of xMatters when ExternalServiceRequest2's send() method is called and this Integration Agent is the target. We recommend that you don't change this setting without first talking to someone at support.xmatters.com.

The maximum number of seconds that this Integration Agent processes a client request before cancelling it with a timeout exception sent to the client (value: positive integer).

This applies to integration service requests, ExternalServiceRequest2 requests, and input and response action scripting. It is not possible to increase the timeout for individual integrations.

We strongly recommend that you do not increase this setting, since it can result in extended delays building up. See the information on script timeouts in the Input action scripting section in the full Integration Agent 5.2 guide for more information.

Web Services gateway exposed to the IAdmin utility.

Attributes:

• @ssl – whether administration requests should be encrypted (values: true, false).
• @host – value is always “localhost” (do not change).
• @port – must be an unused TCP port that is different from the ports of the other gateway elements (value: integer from 0 to 65535).

Web services gateway exposed to the xMatters web servers (integration service requests are submitted to child paths of this URL).

Attributes:

• @ssl – whether integration service requests should be encrypted (values: true, false).
• @port – must an unused TCP port that is different from the ports of the other gateway elements (value: integer from 0 to 65535).

HTTP gateway exposed to Management Systems (either directly or via APClient.bin).

Attributes:

• @ssl – whether Management System submissions should be encrypted (values: true, false). If set to true, Apclient.bin won't be able to send notifications to the Integration Agent. Only change this setting if you have integrations in which the management system sends APXML requests directly to the APClient gateway. See the APXML reference and APClient.bin sections in the full Integration Agent 5.2 guide for more information.
• @host – hostname (e.g., localhost) or IPv4 address (e.g., 127.0.0.1) of the Integration Agent.
• @port – must be an unused TCP port different from the ports of the other gateway elements (value: integer from 0 to 65535).

Where the Integration Agent sends emergency notification emails when a serious condition occurs (for example, network failure or low memory; see the Health Monitor section in the full Integration Agent 5.2 guide for details.

Attributes and sub-elements:

• @enabled – whether the Health Monitor is active (values: true, false). When set to true, the Health Monitor sends an email message to the specified email address every time an issue is detected or resolved.
• <contact> – the email address to which Health Monitor messages are sent, the email address from which to send Health Monitor messages, and the subject of the email message.
• <smtp-relay>/@host – hostname for the SMTP server through which the Integration Agent sends Health Monitor messages; must be resolvable from the Integration Agent server (value: hostname (e.g., localhost) or IPv4 address (e.g., 127.0.0.1)).
• <smtp-relay>/@port – port (typically 25) for the SMTP server through which the Integration Agent sends Health Monitor messages.

For integrations that use a workflow, this must be "applications".

The name of the integration service, which must be unique (regardless of letter case). Names must begin with a letter (a-z or A-Z), followed by any combination of letters (a-z or A-Z), numbers (0-9), or dashes ("-").

Only active integration services process requests, though all services are loaded (parsed and configured) regardless of state.

A suspended service allows requests to be added to its inbound queues, but the requests aren't processed until the service is active. Suspending a service initially is useful for debugging a configuration since parsing and validation are still performed.

For improved performance, integration services can concurrently process notification requests from your management system and callbacks from xMatters. Messages are grouped in two stages: first by priority then by apia_process_group token. Messages with the same apia_process_group token are processed sequentially in first come, first served order, while messages with different apia_process_group tokens are processed concurrently.

Sub-elements:

• <normal-priority-thread-count> – maximum number of normal priority groups that can be processed concurrently.
• <high-priority-thread-count> – maximum number of high priority groups that can be processed concurrently.

We recommend you don't change these to exceed their default values. Doing so can reduce throughput.

Integration service requests are implemented by corresponding methods in a JavaScript file specific to the integration. This element defines the location of the script and related properties.

Attribute and sub-element:

• @lang: value is always “js” (do not change).
• <file>: relative path (resolved against the directory containing this file) of the script implementing the service (and can be Linux- or Windows-formatted).

Integration service scripts have access to all classes and JARs stored in <IAHOME>/lib. However, to prevent conflicts and enhance security, you can specify that an integration service loads its own classes and resources from an unshared directory. The classpath element allows you to specify multiple paths that will be added to the integration service’s classpath during the processing of an integration service request.

Although this classpath augments the default classpath (which is available to all services), the augmented classpath is exclusive to this service.

JDBC drivers cannot be specified using this element; instead, they must be placed in <IAHOME>/lib/integrationservices where they will be automatically available without further configuration.

Sub-elements:

• <path>: 0 or more relative paths (resolved against the directory containing this file) that specify the location of JAR files, class files, or other resources. Each path may include * and ? wildcards to refer to multiple files or directories.

Notes:

• Subdirectories are not recursively searched.
• Trailing \ and / are ignored (e.g., “classes/test/” is the same as “classes/test”).

Integration services use the mapped-input element to define how an APClient map-data request is transformed into an APXML message. The first map-data token is always treated as an agent_client_id APXML token. Subsequent map-data tokens are transformed in order according to the following parameter sub-elements. If too few map-data tokens are supplied, the unused parameter subelements are ignored. Conversely, if too many map-data tokens are supplied, the unused tokens are ignored. .

Attributes and sub-elements:

• @method: resulting APXML message's method element value.
• @subclass: resulting APXML message’s subclass element value; this attribute is optional and if not specified, the resulting APXML message has no subclass element.
• <parameter>: 0 or more parameters, each defining an APXML token key, and ordered the same as the map-data tokens (beginning with the second map-data token). The resulting APXML token’s value derives from the corresponding map-data token. The optional type attribute can have values of auto, string, or numeric and defines the resulting APXML token’s type.