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 xMatters using FortiSOAR™ playbooks. Add the xMatters connector as a step in FortiSOAR™ playbooks and perform automated operations, such as getting events, updating events, and getting groups.
Version information
Connector Version: 1.0.0
Authored By: Fortinet
Certified: No
Installing the connector
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:
yum install cyops-connector-xmatters
For the detailed procedure to install a connector, click here
Prerequisites to configuring the connector
- You must have the URL of xMatters server to which you will connect and perform automated operations and credentials 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, select the xMatters connector and click Configure to configure the following parameters:
| Parameter |
Description |
| Server URL |
Server address of xMatters. |
| Username |
Username to access xMatters. |
| Password |
Password to access xMatters. |
| 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 and onward:
| Function |
Description |
Annotation and Category |
| Get Event List |
Get a list of events from xMatters. |
event_list
Investigation |
| Update Event |
Update event (change status of an event). |
event_update
Investigation |
| Get Device |
Returns information about a device in a Device object. |
get_device
Investigation |
| Get Groups |
Returns a list of Group objects that represent the groups in the system. |
get_groups
Investigation |
operation: Get Event List
Input parameters
| Parameter |
Description |
| Property Name |
The name of a form property. This value is not case-sensitive. |
| Property Value |
The value of a form property. This value is not case-sensitive. |
| Status |
The status of events that you want to return in the search results. |
| Priority |
The priorities of events that you want to return in the search results. |
| Offset |
The number of items to skip before returning results. |
| Limit |
The number of items to 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 to update. |
| Status |
Status of the event to update. |
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 |
The unique identifier or target name of the device to retrieve. The target name of a device is the username, followed by the | (pipe) character, 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 |
Term to search for devices. |
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 - 1.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.
