Fortinet Document Library

Version:


Table of Contents

1.0.1
Copy Link

About the connector

Foresight is a real-time analytics platform, which leverages and co-relates data from multiple sources, hence enabling discovery and valuable insights about the end-to-end network.

This document provides information about the Foresight connector, which facilitates automated interactions, with the Foresight server and API using FortiSOAR™ playbooks. Add the Foresight connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating or updating a ticket in Foresight or searches for tickets in Foresight.

Version information

Connector Version: 1.0.1

FortiSOAR™ Version Tested on: 5.1.0-464

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.0.1

Following enhancements have been made to the Foresight connector in version 1.0.1:

  • Added the following new operations and playbooks:
    • Cancel Ticket
    • Close Ticket
    • Reassign Ticket
    • Add Comment
  • Added a new configuration parameter "Auth Token" that is used to connect to the Foresight server.
  • Updated input parameters for the Update Ticket operation.

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-foresight

Prerequisites to configuring the connector

  • You must have the FQDN of Foresight server to which you will connect and perform automated operations and the API key and Authentication Token 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 Foresight connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Server Address FQDN of the Foresight server to which you will connect and perform automated operations.
API Key API key configured for your account for using the Foresight API.
Auth Token Authentication Token configured for your account for using the Foresight API.
Important: Do not include 'BASIC.'
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 onwards:  

Function Description Annotation and Category
Create Ticket Creates a ticket in Foresight based on the ticket name, description, type, and other input parameters you have specified. create_ticket
Investigation
Search Ticket Searches for all tickets or specific tickets in Foresight, based on the filter criteria such as the ticket ID, ticket severity, or other input parameters that you have specified. search_ticket
Investigation
Update Ticket Updates a ticket in Foresight based on the ticket ID, severity, and other input parameters you have specified. update_ticket
Investigation
Add Comment Adds a comment to a specified ticket in Foresight based on the ticket ID and other input parameters you have specified. comment_ticket
Investigation
Cancel Ticket Cancels a ticket in Foresight based on the ticket ID and other input parameters you have specified. ticket_action_cancel
Investigation
Close Ticket Cancels a ticket in Foresight based on the ticket ID and other input parameters you have specified. ticket_action_close
Investigation
Reassign Ticket Reassigns a ticket to a different user in Foresight based on the ticket ID, email address of the user to whom you want to reassign the ticket, and other input parameters you have specified. ticket_action_reassign
Investigation

operation: Create Ticket

Input parameters

Parameter Description
Ticket name Name or title of the ticket that you want to create in Foresight.
Ticket Description Description of the ticket that you want to create in Foresight.
Note: The ticket description field supports alphanumeric characters and has a maximum limit of 2000 characters.
Ticket Type Type, which mainly represents the module or entity of the ticket that you want to create in Foresight.
Ticket Category Category, which provides further bifurcation and is independent of the ticket type, of the ticket that you want to create in Foresight.
Ticket Sub Category Subcategory, which is dependent on the category you have specified, of the ticket that you want to create in Foresight.
Ticket Severity Severity of the ticket that you want to create in Foresight. You can choose from the following options: Critical, High, Medium, or Low.
Ticket Domain Domain of the ticket that you want to create in Foresight.
Ticket SubDomain Subdomain of the ticket that you want to create in Foresight.
Event Date Date when the event occurred that resulted in this ticket being raised.
Service Type Type of service of the ticket that you want to create in Foresight.
Assignment Type Type of assignment of the ticket that you want to create in Foresight.
Ticket Priority (Optional) Priority of the ticket that you want to create in Foresight. You can choose from the following options: High, Medium, or Low.
External Link (Optional) External link associated with the ticket that you want to create in Foresight.

Output

The output contains the following populated JSON schema:
{
     "assigneeType": "",
     "externalLink": "",
     "category": "",
     "status": "",
     "priority": "",
     "createdTime": "",
     "eventDate": "",
     "subDomain": "",
     "name": "",
     "domain": "",
     "severity": "",
     "modifiedTime": "",
     "type": "",
     "serviceType": "",
     "ticketId": "",
     "subCategory": "",
     "description": ""
}

operation: Search Ticket

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
Ticket ID Unique identifier of the ticket, which is created based on the category that you want to search in Foresight.
Ticket name Name or title of the ticket that you want to search in Foresight.
Ticket Severity Severity of the ticket that you want to search in Foresight. You can choose from the following options: Critical, High, Medium, or Low.
Ticket Type Type, which mainly represents the module or entity of the ticket that you want to search in Foresight.
Ticket Priority Priority of the ticket that you want to search in Foresight. You can choose from the following options: High, Medium, or Low.
Ticket Status Current status of ticket that you want to search in Foresight. You can choose from the following options: New, Open, Reopen, Parked, Resolved, Cancelled, or Closed.
Ticket Category Category of the ticket that you want to search in Foresight.
Ticket Sub Category Subcategory of the ticket that you want to search in Foresight.
Ticket Domain Domain of the ticket that you want to search in Foresight.
Ticket SubDomain Subdomain of the ticket that you want to search in Foresight.
Service Type Service type of the ticket that you want to search in Foresight.
Assignment Type Assignment type of the ticket that you want to search in Foresight.
External Link External link that is associated with the ticket that you want to search in Foresight.

Output

The output contains the following populated JSON schema:
{
     "assigneeType": "",
     "externalLink": "",
     "category": "",
     "status": "",
     "priority": "",
     "createdTime": "",
     "eventDate": "",
     "subDomain": "",
     "name": "",
     "domain": "",
     "severity": "",
     "modifiedTime": "",
     "type": "",
     "serviceType": "",
     "ticketId": "",
     "subCategory": "",
     "description": ""
}

operation: Update Ticket

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket, which is created based on a category that you want to update in Foresight.
Ticket Severity Severity of the ticket that you want to update in Foresight. You can choose from the following options: Low, Medium, High, or Critical.
Ticket Priority Priority of the ticket that you want to update in Foresight. You can choose from the following options: P1-Emergency, P2-Critical, P3-Major, or P4-Minor.
Requesting system Entity that is requesting the ticket that you want to update in Foresight. For example, CiscoSecurity.
Event Date Date when the event occurred that resulted in this ticket being raised and which you want to update in the ticket in Foresight.
Ticket Description (Optional) Description of the ticket that you want to update in Foresight.
Note: The ticket description field supports alphanumeric characters and has a maximum limit of 2000 characters.
External Link (Optional) External link (s) that you want to add to the ticket that you want to update in Foresight.

Output

The output contains the following populated JSON schema:
{
     "assigneeType": "",
     "externalLink": "",
     "category": "",
     "status": "",
     "priority": "",
     "createdTime": "",
     "eventDate": "",
     "subDomain": "",
     "name": "",
     "domain": "",
     "severity": "",
     "modifiedTime": "",
     "type": "",
     "serviceType": "",
     "ticketId": "",
     "subCategory": "",
     "description": ""
}

operation: Add Comment

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket in Foresight to which you want to add a comment.
Requesting System Entity that is requesting the ticket to which you want to add a comment in Foresight. For example, CiscoSecurity.
Comment Text that you want to add as a comment to the specified ticket in Foresight.

Output

No output schema is available at this time.

operation: Cancel Ticket

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket that you want to cancel in Foresight.
Requesting System Entity that is requesting the ticket that you want to cancel in Foresight. For example, CiscoSecurity.

Output

No output schema is available at this time.

operation: Close Ticket

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket that you want to close in Foresight.
Requesting System Entity that is requesting the ticket that you want to close in Foresight. For example, CiscoSecurity.
Verification Note Verification note that you require to add when you want to close a ticket in Foresight.

Output

No output schema is available at this time.

operation: Reassign Ticket

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket that you want to ressign in Foresight.
Requesting System Entity that is requesting the ticket that you want to reassign in Foresight. For example, CiscoSecurity.
Assignment User Email address of user to whom you want to assign the ticket in Foresight.
Important: If you select the Reassign action, then this field is mandatory.
Reassignment Remark Reassignment remark that you require to add when you want to reassign a ticket to another user in Foresight.

Output

No output schema is available at this time.

Included playbooks

The Sample - Foresight - 1.0.1 playbook collection comes bundled with the Foresight 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 Foresight connector.

  • Add Comment
  • Cancel Ticket
  • Close Ticket
  • Create Ticket
  • Reassign Ticket
  • Search Ticket
  • Update Ticket

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

Foresight is a real-time analytics platform, which leverages and co-relates data from multiple sources, hence enabling discovery and valuable insights about the end-to-end network.

This document provides information about the Foresight connector, which facilitates automated interactions, with the Foresight server and API using FortiSOAR™ playbooks. Add the Foresight connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating or updating a ticket in Foresight or searches for tickets in Foresight.

Version information

Connector Version: 1.0.1

FortiSOAR™ Version Tested on: 5.1.0-464

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.0.1

Following enhancements have been made to the Foresight connector in version 1.0.1:

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-foresight

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 Foresight connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Server Address FQDN of the Foresight server to which you will connect and perform automated operations.
API Key API key configured for your account for using the Foresight API.
Auth Token Authentication Token configured for your account for using the Foresight API.
Important: Do not include 'BASIC.'
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 onwards:  

Function Description Annotation and Category
Create Ticket Creates a ticket in Foresight based on the ticket name, description, type, and other input parameters you have specified. create_ticket
Investigation
Search Ticket Searches for all tickets or specific tickets in Foresight, based on the filter criteria such as the ticket ID, ticket severity, or other input parameters that you have specified. search_ticket
Investigation
Update Ticket Updates a ticket in Foresight based on the ticket ID, severity, and other input parameters you have specified. update_ticket
Investigation
Add Comment Adds a comment to a specified ticket in Foresight based on the ticket ID and other input parameters you have specified. comment_ticket
Investigation
Cancel Ticket Cancels a ticket in Foresight based on the ticket ID and other input parameters you have specified. ticket_action_cancel
Investigation
Close Ticket Cancels a ticket in Foresight based on the ticket ID and other input parameters you have specified. ticket_action_close
Investigation
Reassign Ticket Reassigns a ticket to a different user in Foresight based on the ticket ID, email address of the user to whom you want to reassign the ticket, and other input parameters you have specified. ticket_action_reassign
Investigation

operation: Create Ticket

Input parameters

Parameter Description
Ticket name Name or title of the ticket that you want to create in Foresight.
Ticket Description Description of the ticket that you want to create in Foresight.
Note: The ticket description field supports alphanumeric characters and has a maximum limit of 2000 characters.
Ticket Type Type, which mainly represents the module or entity of the ticket that you want to create in Foresight.
Ticket Category Category, which provides further bifurcation and is independent of the ticket type, of the ticket that you want to create in Foresight.
Ticket Sub Category Subcategory, which is dependent on the category you have specified, of the ticket that you want to create in Foresight.
Ticket Severity Severity of the ticket that you want to create in Foresight. You can choose from the following options: Critical, High, Medium, or Low.
Ticket Domain Domain of the ticket that you want to create in Foresight.
Ticket SubDomain Subdomain of the ticket that you want to create in Foresight.
Event Date Date when the event occurred that resulted in this ticket being raised.
Service Type Type of service of the ticket that you want to create in Foresight.
Assignment Type Type of assignment of the ticket that you want to create in Foresight.
Ticket Priority (Optional) Priority of the ticket that you want to create in Foresight. You can choose from the following options: High, Medium, or Low.
External Link (Optional) External link associated with the ticket that you want to create in Foresight.

Output

The output contains the following populated JSON schema:
{
     "assigneeType": "",
     "externalLink": "",
     "category": "",
     "status": "",
     "priority": "",
     "createdTime": "",
     "eventDate": "",
     "subDomain": "",
     "name": "",
     "domain": "",
     "severity": "",
     "modifiedTime": "",
     "type": "",
     "serviceType": "",
     "ticketId": "",
     "subCategory": "",
     "description": ""
}

operation: Search Ticket

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
Ticket ID Unique identifier of the ticket, which is created based on the category that you want to search in Foresight.
Ticket name Name or title of the ticket that you want to search in Foresight.
Ticket Severity Severity of the ticket that you want to search in Foresight. You can choose from the following options: Critical, High, Medium, or Low.
Ticket Type Type, which mainly represents the module or entity of the ticket that you want to search in Foresight.
Ticket Priority Priority of the ticket that you want to search in Foresight. You can choose from the following options: High, Medium, or Low.
Ticket Status Current status of ticket that you want to search in Foresight. You can choose from the following options: New, Open, Reopen, Parked, Resolved, Cancelled, or Closed.
Ticket Category Category of the ticket that you want to search in Foresight.
Ticket Sub Category Subcategory of the ticket that you want to search in Foresight.
Ticket Domain Domain of the ticket that you want to search in Foresight.
Ticket SubDomain Subdomain of the ticket that you want to search in Foresight.
Service Type Service type of the ticket that you want to search in Foresight.
Assignment Type Assignment type of the ticket that you want to search in Foresight.
External Link External link that is associated with the ticket that you want to search in Foresight.

Output

The output contains the following populated JSON schema:
{
     "assigneeType": "",
     "externalLink": "",
     "category": "",
     "status": "",
     "priority": "",
     "createdTime": "",
     "eventDate": "",
     "subDomain": "",
     "name": "",
     "domain": "",
     "severity": "",
     "modifiedTime": "",
     "type": "",
     "serviceType": "",
     "ticketId": "",
     "subCategory": "",
     "description": ""
}

operation: Update Ticket

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket, which is created based on a category that you want to update in Foresight.
Ticket Severity Severity of the ticket that you want to update in Foresight. You can choose from the following options: Low, Medium, High, or Critical.
Ticket Priority Priority of the ticket that you want to update in Foresight. You can choose from the following options: P1-Emergency, P2-Critical, P3-Major, or P4-Minor.
Requesting system Entity that is requesting the ticket that you want to update in Foresight. For example, CiscoSecurity.
Event Date Date when the event occurred that resulted in this ticket being raised and which you want to update in the ticket in Foresight.
Ticket Description (Optional) Description of the ticket that you want to update in Foresight.
Note: The ticket description field supports alphanumeric characters and has a maximum limit of 2000 characters.
External Link (Optional) External link (s) that you want to add to the ticket that you want to update in Foresight.

Output

The output contains the following populated JSON schema:
{
     "assigneeType": "",
     "externalLink": "",
     "category": "",
     "status": "",
     "priority": "",
     "createdTime": "",
     "eventDate": "",
     "subDomain": "",
     "name": "",
     "domain": "",
     "severity": "",
     "modifiedTime": "",
     "type": "",
     "serviceType": "",
     "ticketId": "",
     "subCategory": "",
     "description": ""
}

operation: Add Comment

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket in Foresight to which you want to add a comment.
Requesting System Entity that is requesting the ticket to which you want to add a comment in Foresight. For example, CiscoSecurity.
Comment Text that you want to add as a comment to the specified ticket in Foresight.

Output

No output schema is available at this time.

operation: Cancel Ticket

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket that you want to cancel in Foresight.
Requesting System Entity that is requesting the ticket that you want to cancel in Foresight. For example, CiscoSecurity.

Output

No output schema is available at this time.

operation: Close Ticket

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket that you want to close in Foresight.
Requesting System Entity that is requesting the ticket that you want to close in Foresight. For example, CiscoSecurity.
Verification Note Verification note that you require to add when you want to close a ticket in Foresight.

Output

No output schema is available at this time.

operation: Reassign Ticket

Input parameters

Parameter Description
Ticket ID Unique identifier of the ticket that you want to ressign in Foresight.
Requesting System Entity that is requesting the ticket that you want to reassign in Foresight. For example, CiscoSecurity.
Assignment User Email address of user to whom you want to assign the ticket in Foresight.
Important: If you select the Reassign action, then this field is mandatory.
Reassignment Remark Reassignment remark that you require to add when you want to reassign a ticket to another user in Foresight.

Output

No output schema is available at this time.

Included playbooks

The Sample - Foresight - 1.0.1 playbook collection comes bundled with the Foresight 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 Foresight 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.