Timer Function¶

Table of Contents¶

Release Notes
Overview
- Key Features
Requirements
Installation
- Install
- App Configuration
Function - Timer
Rules
Troubleshooting & Support

Release Notes¶

Version	Date	Notes
1.0.0	09/2022	Initial Release

Please note that this document was updated in March 2024 to clarify the use of num_workers and stomp_prefetch_limit in this app. See resilient Section Configurations for details.

Overview¶

Simple timer function to be used in the SOAR platform

App used in the SOAR platform. A workflow using this function will sleep for the specified amount of time. The function takes as input timer_time or timer_epoch as input. The function periodically checks the status of the calling workflow and will end function execution if the workflow has been terminated.

This app supports the IBM Security QRadar SOAR Platform and the IBM Security QRadar SOAR for IBM Cloud Pak for Security.

SOAR platform¶

The SOAR platform supports two app deployment mechanisms, App Host and integration server.

If deploying to a SOAR platform with an App Host, the requirements are:

SOAR platform >= 43.1.49.
The app is in a container-based format (available from the AppExchange as a zip file).

If deploying to a SOAR platform with an integration server, the requirements are:

SOAR platform >= 43.1.49.
The app is in the older integration format (available from the AppExchange as a zip file which contains a tar.gz file).
Integration server is running resilient-circuits>=46.0.0.
If using an API key account, make sure the account provides the following minimum permissions:

Name

Permissions

Org Data

Read

Function

Read

Name	Permissions
Org Data	Read
Function	Read

The following SOAR platform guides provide additional information:

App Host Deployment Guide: provides installation, configuration, and troubleshooting information, including proxy server settings.
Integration Server Guide: provides installation, configuration, and troubleshooting information, including proxy server settings.
System Administrator Guide: provides the procedure to install, configure and deploy apps.

The above guides are available on the IBM Documentation website at ibm.biz/soar-docs. On this web page, select your SOAR platform version. On the follow-on page, you can find the App Host Deployment Guide or Integration Server Guide by expanding Apps in the Table of Contents pane. The System Administrator Guide is available by expanding System Administrator.

Cloud Pak for Security¶

If you are deploying to IBM Cloud Pak for Security, the requirements are:

IBM Cloud Pak for Security >= 1.7.
Cloud Pak is configured with an App Host.
The app is in a container-based format (available from the AppExchange as a zip file).

The following Cloud Pak guides provide additional information:

App Host Deployment Guide: provides installation, configuration, and troubleshooting information, including proxy server settings. From the Table of Contents, select Case Management and Orchestration & Automation > Orchestration and Automation Apps.
System Administrator Guide: provides information to install, configure, and deploy apps. From the IBM Cloud Pak for Security IBM Documentation table of contents, select Case Management and Orchestration & Automation > System administrator.

These guides are available on the IBM Documentation website at ibm.biz/cp4s-docs. From this web page, select your IBM Cloud Pak for Security version. From the version-specific IBM Documentation page, select Case Management and Orchestration & Automation.

Proxy Server¶

The app does support a proxy server.

Python Environment¶

Both Python 3.6 and Python 3.9 are supported. Additional package dependencies may exist for each of these packages:

resilient-circuits>=46.0.0

Installation¶

Install¶

To install or uninstall an App or Integration on the SOAR platform, see the documentation at ibm.biz/soar-docs.
To install or uninstall an App on IBM Cloud Pak for Security, see the documentation at ibm.biz/cp4s-docs and follow the instructions above to navigate to Orchestration and Automation.

App Configuration¶

The following table provides the settings you need to configure the app. These settings are made in the app.config file. See the documentation discussed in the Requirements section for the procedure.

Config	Required	Example	Description
max_timer	Yes	`30d`	Max Timer sleep time. The input string is of format “time value” concatenated with a “time unit” character, where character is: ‘s’ for seconds, ‘m’ for minutes, ‘h’ for hours ‘d’ for days. For example: ’30s’ = 30 seconds; ‘40m’ = 40 minutes;

`[resilient]` Section Configurations¶

The [resilient] section allows you to configure app wide settings. For the Timer function, there are two settings that are relevant and should be paid significant attention to get proper function from the app. The setting num_workers determines the maximum number of threads that the app will dispatch at the same time. This allows for concurrent timers to run. Importantly, however, the setting stomp_prefetch_limit must also be set a number greater than or equal to the value set for num_workers. Without this addition, you may experience timer delays in the function.

Function - Timer¶

This function implements a timer (sleep) function that when called from a workflow will cause the workflow to pause for the specified amount of time. The function takes one of two parameters as input: timer_time or timer_epoch.

screenshot: fn-timer

Inputs:

Name	Type	Required	Example	Tooltip
`timer_epoch`	`datetimepicker`	No	`-`	Epoch specifying the time the timer should end
`timer_time`	`text`	No	`60s`	Specify time to wait as a string value/units where units is ‘s’ for seconds, ‘m’ for minutes ‘h’ for hours and ‘d’ for days. For example: 60 seconds : “60s”; 45 minutes : “45m”; 12 hours : 12h

One of these two parameters are required to be set in order to use this function.

Setting `timer_epoch` programmatically¶

Notice in the Inputs section above that one option is to use timer_epoch. This setting is useful for setting a timer that will expire at a specific date and time in the future. The example workflow included with this app gives a very useful way to use this with playbook or rule activation forms where the SOAR built-in type datetimepicker is used to visually select a time on a calendar at which the timer will expire. This, along with timer_time will fit most use cases for this function.

There may be times, however, where you may want to describe a timer that will expire at a set time from when the playbook is executed with more precision than is permitted using timer_time. In busy timer environments, the function itself may take a few seconds to start in the app, thus losing precision from the timer_time input. In these cases, it is recommended to use an approach like the one below which marks the time at the point that the input script is run and uses the datetime module in Python to create a “time delta” to describe a time in the future relative to input script runtime that can be used for the timer_epoch function input value. (Note that this requires some conversion to fit the expected datetimepicker format.)

Example: set a timer to expire in 2 days, 4 minutes, and 5 seconds after the input script is run using timer_epoch

import datetime

# Get current time
current_time = datetime.datetime.now()
# Use timedelta to add time
# Options are:
#   (days, seconds, microseconds, milliseconds, minutes, hours, weeks)
target_time = current_time + datetime.timedelta(days=2, minutes=4, seconds=5)
# Set timer_epoch by converting to epoch time and casting to an int to match datetimepicker format
inputs.timer_epoch = int(target_time.timestamp()*1000)

Outputs:

NOTE: This example might be in JSON format, but results is a Python Dictionary on the SOAR platform.

results = {
  "content": {
    "Workflow Status": {
      "end_date": 1661960247501,
      "instance_id": 1407,
      "is_terminated": true,
      "reason": "The workflow was manually terminated by a user.",
      "start_date": 1661960193764,
      "status": "terminated"
    }
  },
  "inputs": {
    "timer_epoch": 1661986800000
  },
  "metrics": {
    "execution_time_ms": 177,
    "host": "christohersmbp2.cambridge.ibm.com",
    "package": "fn-timer",
    "package_version": "1.0.0",
    "timestamp": "2022-08-31 11:37:41",
    "version": "1.0"
  },
  "raw": null,
  "reason": null,
  "success": true,
  "version": 2.0
}

Example Pre-Process Script:

# Get the timer values from the rule properties custom field
list_time_values = rule.properties.timer_parallel_timers

# Get the list of 2 timer values
time_list = list_time_values.split(',')

# Use the first timer for this function
inputs.timer_time = time_list[0]

Example Post-Process Script:

None

Rules¶

Rule Name	Object	Workflow Triggered
Timer Epoch	incident	`timer_epoch`
Timer in Parallel	incident	`timer_in_parallel`

Troubleshooting & Support¶

Refer to the documentation listed in the Requirements section for troubleshooting information.

For Support¶

This is a IBM Community provided App. Please search the Community ibm.biz/soarcommunity for assistance.