Fortinet Document Library

Version:


Table of Contents

2.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 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.

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

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.

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.