Time Series Chart Utilities v1.0.0

About the connector

When using the Time Series Chart Solution Pack, this connector is used by the included playbooks to facilitate the creation of data-over-time or time series charts. The included functions include building a list of DateTime-buckets, as well as various utilities to process the output of dataset queries for use by the Time Series Widget.

This document provides information about the Time Series Chart Utilities Connector, which facilitates the formatting of data for use with the Time Series Charts solution pack using FortiSOAR™ playbooks. Add the Time Series Chart Utilities Connector as a step in FortiSOAR™ playbooks and perform automated operations with Time Series Chart Utilities.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 7.3.2-2150

Time Series Chart Utilities Version Tested on: v1.0.0

Authored By: Fortinet

Certified: Yes

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

You can also use the yum command as a root user to install the connector:

yum install cyops-connector-time-series-chart-utilities

Prerequisites to configuring the connector

There are no prerequisites to configuring this connector.

Minimum Permissions Required

• Not applicable.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

None.

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations:

Function	Description	Annotation and Category
Assemble Query Time Windows	Builds a list of time windows, each with a start and end timestamp, from the beginning of a specified duration to the present based on the configuration of an instance of the Time Series Chart Widget. For example, for a chart with relative date Last 24 Hours and period Hourly, this function gives as output a list of 24 start-time and end-time pairs, corresponding to each hour in that period.	assemble_query_time_windows Utilities
Flatten Data Sets and Groups	Takes Data Set configuration information from a Time Series Chart Record and outputs the base query for each Data Set as well as the plot type and Data Set grouping information which is used when rendering the final chart	flatten_data_sets_and_groups Utilities
Format Data Set Output with Field-Grouped	When a Data Set is configured to be grouped based on a picklist field, this operation is used to format the Data Set's query results so that they can be rendered into a Time Series Chart	format_data_set_output_with_fieldgrouped Utilities
Combine Query Results into Data Columns	Combines Data Set query results, existing data from a chart being updated (where applicable), and the results of the "Assemble Query Time Windows" operation into a List structure which can be rendered by the Time Series Chart Widget	combine_query_results_into_data_columns Utilities

operation: Assemble Query Time Windows

Input parameters

Parameter	Description
Relative Date	Specify the full period which the corresponding Time Series Chart will reflect, expressed as JSON in the format {"differenceType": "days", "differenceValue": "-7"}.
Time Period	Specify the length of time used for each time window. The Relative Date span is divided into chunks of length corresponding to this parameter.
Date Format String	Specify the format used within your chart data JSON to express date values
Existing Times	Specify the list of time buckets already present in the chart if an existing Time Series Chart is being updated, rather than created for the first time. This is done to keep the time window spacings consistent between updates and prevent data from being missed due to small variances in playbook execution time.
Query Modified	Select this checkbox, i.e. set to True, to discard existing data from previous time windows and query the entire chart again. If not selected, time windows since the last time this chart was updated, are queried.

Output

The output contains the following populated JSON schema:
{
"mode": "",
"query_buckets": [
{
"end": "",
"start": ""
}
],
"first_index_to_keep": ""
}

operation: Flatten Data Sets and Groups

Input parameters

Parameter	Description
Data Sets	Specify the JSON-formatted data from the TimeSeries Chart widget configuration. Each Data Set has its query and list of filters, potentially with the results grouped based on a picklist field.

Output

The output contains the following populated JSON schema:
{
"types": {},
"groups": [],
"dataSets": [
{
"group": "",
"query": {
"sort": [],
"limit": "",
"logic": "",
"filters": [],
"aggregates": [
{
"alias": "",
"field": "",
"operator": ""
}
]
},
"title": "",
"isOpen": "",
"plotType": "",
"resource": "",
"mappingField": "",
"groupingField": ""
}
]
}

operation: Format Data Set Output with Field-Grouped

Input parameters

Parameter	Description
Query Results	Specify the output of a query step, which runs a Data Set's query once for each time bucket.
Time Buckets Queried	Specify a list of dictionaries representing the start and end timestamps of each time bucket queried.
Data Set Configuration	Specify the configuration options selected for this data set when configuring the Time Series Chart Widget

Output

No output schema is available at this time.

operation: Combine Query Results into Data Columns

Input parameters

Parameter	Description
Playbook Mode	Select this option to include previous results in the output, or to overwrite them.
First Index to Keep	Specify the first index from which to retain data. When updating an existing Time Series Chart, any data before this index is discarded, as it represents time windows that no longer fit within the duration of time that the updated chart shows.
Queried Time Buckets	Specify a list of dictionaries representing the start and end timestamps of each time bucket queried. When creating a new Time Series Chart, this includes all time buckets for the chart's entire duration. When updating an existing chart, only the time buckets which are more recent than the newest bucket already in the chart are represented here.
Query Results	Specify the results of the queries run for all data sets. This should be the output of the "Run Queries" Playbook step
Existing Data Columns	When appending data to an existing chart, this should be the data already present in the chart. Older data is removed, and new data is added to the end to represent more recent time buckets.

Output

No output schema is available at this time.

Included playbooks

The Sample - Time Series Chart Utilities - 1.0.0 playbook collection comes bundled with the Time Series Chart Utilities 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 Time Series Chart Utilities connector.

• Assemble Query Time Windows
• Combine Query Results into Data Columns
• Flatten Data Sets and Groups
• Format Data Set Output with Field-Grouped

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.