Fortinet Document Library

Version:


Table of Contents

1.0.0
Copy Link

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.

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

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.

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.