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.
