About the connector
xMatters integrates with your current business solutions, enabling you to leverage solutions you have already invested in, including ITSM tools, chat applications, and automation utilities. This allows you to stay on top of any notification in your organization.
This document provides information about the xMatters connector, which facilitates automated interactions with an xMatters server using FortiSOAR™ playbooks. Add the xMatters connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving events and group objects, and updating the status of events in xMatters.
Version information
Connector Version: 2.0.0
FortiSOAR™ Version Tested on: 5.1.0-464
Authored By: Fortinet
Certified: No
Release Notes for version 2.0.0
This version of the xMatters connector is certified. Version 1.0.0 of the xMatters connector was uncertified.
Installing the connector
From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:
yum install cyops-connector-xmatters
Prerequisites to configuring the connector
- You must have the URL of xMatters server to which you will connect and perform automated operations and credentials (username-password pair) to access that server.
- To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Connectors page, click the xMatters connector row, and in the Configure tab enter the required configuration details.
| Parameter |
Description |
| Server URL |
Server address of the xMatters server to which you will connect and perform automated operations. |
| Username |
Username to access the xMatters server to which you will connect and perform automated operations. |
| Password |
Password to access the xMatters server to which you will connect and perform automated operations. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
| Function |
Description |
Annotation and Category |
| Get Event List |
Retrieves a list of all events or specific events from xMatters, based on the input parameters you have specified. |
event_list
Investigation |
| Update Event |
Update the status of the specified event in xMatters, based on the event ID and status you have specified. |
event_update
Investigation |
| Get Device |
Retrieves information about a device in a Device object in xMatters, based on the device ID and status you have specified. |
get_device
Investigation |
| Get Groups |
Retrieves a list of Group objects that represent the groups in the xMatters system, based on the query you have specified. |
get_groups
Investigation |
operation: Get Event List
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.
| Parameter |
Description |
| Property Name |
Name of a form property based on which you want to retrieve the list of events from xMatters.
Note: This value is case insensitive. |
| Property Value |
Value of a form property based on which you want to retrieve the list of events from xMatters.
Note: This value is case insensitive. |
| Status |
Status of the events that you want to retrieve from xMatters. |
| Priority |
Priority of the events that you want to retrieve from xMatters. |
| Offset |
Offset is used to ‘skip’ a number of results, i.e., this is the index of the first item to return. By default, this value is set as 0. |
| Limit |
Maximum number of results, per page, that this operation should return. |
Output
The output contains the following populated JSON schema:
{
"total": "",
"count": "",
"data": ""
}
operation: Update Event
Input parameters
| Parameter |
Description |
| Event ID |
ID of the event whose status you want to update in xMatters. |
| Status |
Status that you want to set for the event you want to update in xMatters. You can choose from the following values: Active, Suspended, or Terminated. |
Output
The output contains the following populated JSON schema:
{
"submitter": "",
"priority": "",
"overrideDeviceRestrictions": "",
"requirePhonePassword": "",
"bypassPhoneIntro": "",
"eventId": "",
"escalationOverride": "",
"status": "",
"incident": "",
"links": "",
"id": "",
"created": ""
}
operation: Get Device
Input parameters
| Parameter |
Description |
| Device ID |
Unique identifier or target name of the device whose information you want to retrieve from xMatters. The target name of a device is the username, followed by the | (pipe) character, and then followed by the device name. |
Output
The output contains the following populated JSON schema:
{
"timeframes": {
"links": {
"self": ""
},
"total": "",
"count": "",
"data": [
{
"durationInMinutes": "",
"timezone": "",
"startTime": "",
"excludeHolidays": "",
"name": "",
"days": []
}
]
},
"owner": {
"links": {
"self": ""
},
"id": "",
"targetName": ""
},
"name": "",
"sequence": "",
"targetName": "",
"description": "",
"defaultDevice": "",
"id": "",
"recipientType": "",
"status": "",
"emailAddress": "",
"deviceType": "",
"testStatus": "",
"externallyOwned": "",
"delay": "",
"priorityThreshold": "",
"links": {
"self": ""
}
}
operation: Get Groups
Input parameters
| Parameter |
Description |
| Query |
Query using on which you want to retrieve the list of Group objects that represent the groups in the xMatters system. |
Output
The output contains the following populated JSON schema:
{
"links": {
"self": ""
},
"total": "",
"count": "",
"data": [
{
"description": "",
"observedByAll": "",
"site": {
"links": {
"self": ""
},
"id": ""
},
"recipientType": "",
"status": "",
"links": {
"self": ""
},
"allowDuplicates": "",
"id": "",
"externallyOwned": "",
"targetName": "",
"useDefaultDevices": ""
}
]
}
Included playbooks
The Sample - xMatters - 2.0.0 playbook collection comes bundled with the xMatters connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the xMatters connector.
- Get Device
- Get Event List
- Get Groups
- Update Event
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.
