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.1.0
FortiSOAR™ Version Tested on: 6.4.0-1555
Authored By: Fortinet
Certified: Yes
Release Notes for version 1.1.0
Following enhancements have been made to the Foresight connector in version 1.1.0:
- Added the following new operations and playbooks:
- Get Comment
- Acquire Ticket
- Negotiate Ticket
- Resolved Ticket
- Start Ticket
- Updated the input parameters for the Create Ticket operation as follows:
- Changed the field type of the "Ticket Severity" parameter from a drop-down list to a 'text' field.
- Changed the field type of the "Ticket Priority" parameter from a drop-down list to a 'text' field.
- Changed the field type of the "Ticket Status" parameter from a drop-down list to a 'text' field.
- Changed the field type of the "Assignment Type" parameter from a 'text' field to a drop-down list, whose values are 'User' and 'Work Group'.
- Updated the input parameters for the Update Ticket operation as follows:
- Changed the field type of the "Ticket Severity" parameter from a drop-down list to a 'text' field.
- Changed the field type of the "Ticket Priority" parameter from a drop-down list to a 'text' field.
- Updated the input parameters for the Search Ticket operation as follows:
- Changed the field type of the "Ticket Status" parameter from a drop-down list to a 'text' field.
- Changed the field type of the "Ticket Severity" parameter from a drop-down list to a 'text' field.
- Added the following new parameters: "Modified Date", "Pagination", "Upper Limit", and "Lower Limit".
- Updated the input parameters for the Cancel Ticket operation as follows:
- Added the "Verification Note" parameter.
- Updated the output schema for the following operations:
- Create Ticket
- Search Ticket
- Update Ticket
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. |
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 version 4.10.0 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 |
| Get Comment |
Retrieves the list of all comments associated with the specified ticket ID based on the ticket ID you have specified. |
get_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 |
Closes 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 |
| Acquire Ticket |
Acquires a ticket in Foresight based on the ticket ID and other input parameters you have specified. |
ticket_action_acquire
Investigation |
| Negotiate Ticket |
Negotiates a ticket in Foresight based on the ticket ID and other input parameters you have specified. |
ticket_action_negotiate
Investigation |
| Resolved Ticket |
Resolves a ticket in Foresight based on the ticket ID and other input parameters you have specified. |
ticket_action_resolved
Investigation |
| Start Ticket |
Starts a ticket in Foresight based on the ticket ID and other input parameters you have specified. |
ticket_action_start
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 specify one of 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. You can choose between 'User' or 'Work Group' options.
If you choose User, then you must specify the following parameters:
- Assignment User: Email ID of the user who will be assigned to the ticket that you want to create in Foresight.
- Work Group Name: Name of the workgroup that will be assigned the ticket that you want to create in Foresight.
If you choose Work Group, then you must specify the following parameters:
- Work Group Name: Name of the workgroup that will be assigned the ticket that you want to create in Foresight.
|
| Ticket Priority |
Priority of the ticket that you want to create in Foresight. You can specify one of the following options: P1-Emergency, P2-Critical, P3-Major, or P4-Minor. |
| Requesting System |
Entity that is requesting the ticket that you want to create in Foresight. For example, CiscoSecurity. |
| 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:
{
"name": "",
"ticketId": "",
"type": "",
"category": "",
"subCategory": "",
"domain": "",
"subDomain": "",
"severity": "",
"priority": "",
"description": "",
"creator": "",
"createdTime": "",
"modifiedTime": "",
"status": "",
"eventDate": "",
"serviceType": "",
"assigneeType": "",
"requestingSystem": "",
"ticketMaster": "",
"attachCount": "",
"generationType": "",
"creatorWorkGroup": "",
"handledWorkgroupName": "",
"externalLink": ""
}
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 (created based on a category) that you want to search in Foresight. |
| Ticket Name |
Name or title of the ticket that you want to search in Foresight. |
| Ticket Type |
Type, which mainly represents the module or entity 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 specify one of the following options: Critical, High, Medium, or Low. |
| 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 Status |
Current status of ticket that you want to search in Foresight. You can specify one of the following options: New, Open, Reopen, Parked, Resolved, Cancelled, or Closed. |
| Modified Date |
Date and time when the ticket that you want to search in Foresight was modified. |
| Pagination |
Select this checkbox to apply pagination for the tickets searched in Foresight. If you select this option, then you must specify the following parameters:
- Upper Limit: Start index for searching for tickets in Foresight.
- Lower Limit: End index for searching for tickets in Foresight.
|
Output
The output contains the following populated JSON schema:
{
"name": "",
"ticketId": "",
"type": "",
"category": "",
"subCategory": "",
"domain": "",
"subDomain": "",
"severity": "",
"priority": "",
"description": "",
"creator": "",
"createdTime": "",
"modifiedTime": "",
"status": "",
"eventDate": "",
"serviceType": "",
"assigneeType": "",
"externalLink": "",
"requestingSystem": "",
"ticketMaster": "",
"attachCount": "",
"generationType": "",
"creatorWorkGroup": "",
"handledWorkgroupName": ""
}
operation: Update Ticket
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (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 specify one of the following options: Low, Medium, High, or Critical. |
| Ticket Priority |
Priority of the ticket that you want to update in Foresight. You can specify one of 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:
{
"name": "",
"ticketId": "",
"type": "",
"category": "",
"subCategory": "",
"domain": "",
"subDomain": "",
"severity": "",
"priority": "",
"description": "",
"creator": "",
"createdTime": "",
"modifiedTime": "",
"status": "",
"eventDate": "",
"serviceType": "",
"assigneeType": "",
"externalLink": "",
"requestingSystem": "",
"ticketMaster": "",
"attachCount": "",
"generationType": "",
"creatorWorkGroup": "",
"handledWorkgroupName": ""
}
operation: Add Comment
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (created based on a category) 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
The output contains the following populated JSON schema:
{
"status": ""
}
operation: Cancel Ticket
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (created based on a category) that you want to cancel in Foresight. |
| Verification Note |
Verification note that you require to add when you want to cancel a ticket in Foresight. |
| Requesting System |
Entity that is requesting the ticket that you want to cancel in Foresight. For example, CiscoSecurity. |
Output
The output contains the following populated JSON schema:
{
"status": ""
}
operation: Get Comment
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (created based on a category) whose associated comments you want to retrieve from Foresight. |
Output
The output contains the following populated JSON schema:
[
{
"creator": "",
"createdTime": "",
"comment": ""
}
]
operation: Close Ticket
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (created based on a category) 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
The output contains the following populated JSON schema:
{
"status": ""
}
operation: Reassign Ticket
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (created based on a category) 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
The output contains the following populated JSON schema:
{
"status": ""
}
operation: Acquire Ticket
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (created based on a category) that you want to acquire in Foresight. |
| Requesting System |
Entity that is requesting the ticket that you want to acquire in Foresight. For example, CiscoSecurity. |
| User Email ID |
Email ID of the user to whom this ticket will be re-assigned. |
Output
The output contains the following populated JSON schema:
{
"status": ""
}
operation: Negotiate Ticket
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (created based on a category) that you want to negotiate in Foresight. |
| Requesting System |
Entity that is requesting the ticket that you want to negotiate in Foresight. For example, CiscoSecurity. |
| Negotiate Reason |
Reason for which the specified ticket requires to be negotiated in Foresight. |
| Negotiate Type |
Negotiation type that you want to assign to the specified ticket. You can choose from Required More Detail or Date.
- If you choose 'Required More Detail', then in the Negotiate Detail field, you must enter the details for the negotiation.
- If you choose 'Date' then in the Negotiate Target Date field you must select the new target date for the ticket.
|
Output
The output contains the following populated JSON schema:
{
"status": ""
}
operation: Resolved Ticket
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (created based on a category) that you want to resolve in Foresight. |
| Requesting System |
Entity that is requesting the ticket that you want to resolve in Foresight. For example, CiscoSecurity. |
| Root Cause |
Reason for which the specified ticket requires to be resolved in Foresight. You can specify one of the following options: Hardware Malfunction, Software Bug, Operation Mistake, Setting Error, Delayed/False Alarm, No Fault Found, New Site Integration, CR/Planned Activity, System Design, Fault Diagnostics, Data Issue, Test, or Duplicate. |
| RCA Resolution |
Root Cause Analysis (RCA) for the ticket that you want to resolve in Foresight. You can specify one of the following options: Patch Application, Modify Configuration, Correct Procedure, Service Restart, Hardware Reboot, Hardware Replacement, Power off/on, Auto-Recovery, No Fault Found, Site Visit, Other (Please Specify), or Duplicate. |
| RCA Cause Details |
RCA cause details for the ticket that you want to resolve in Foresight. |
| RCA Resolution Details |
RCA resolution details for the ticket that you want to resolve in Foresight. |
| RCA Solution Type |
Solution type of the RCA for the ticket that you want to resolve in Foresight. You can specify either "Temporary Solution" or "Permanent Solution". |
| RCA Solution Details |
RCA solution details for the ticket that you want to resolve in Foresight. |
Output
The output contains the following populated JSON schema:
{
"status": ""
}
operation: Start Ticket
Input parameters
| Parameter |
Description |
| Ticket ID |
Unique identifier of the ticket (created based on a category) that you want to start in Foresight. |
| Requesting System |
Entity that is requesting the ticket that you want to start in Foresight. For example, CiscoSecurity. |
Output
The output contains the following populated JSON schema:
{
"status": ""
}
Included playbooks
The Sample - Foresight - 1.1.0 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.
- Acquire Ticket
- Add Comment
- Cancel Ticket
- Close Ticket
- Create Ticket
- Get Comment
- Negotiate Ticket
- Reassign Ticket
- Resolved Ticket
- Search Ticket
- Start 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 the connector upgrade and delete.
