Recurrence Rules

Some tasks in the Tenable Vulnerability Management API can be scheduled to occur at defined intervals. Recurrence rules define the interval at which the task repeats. Vulnerability Management implements recurrence rules per the RFC-5545 specification.

The interval is formatted as a string of three (for scans) or four (for exports) values delimited by semi-colons. These values are: the frequency (FREQ=ONETIME or DAILY or WEEKLY or MONTHLY or YEARLY), the interval (INTERVAL=1 or 2 or 3 ... x), the days of the week (BYDAY=SU,MO,TU,WE,TH,FR,SA), and the end date in datetime format (UNTIL=20300101T143000).

For example, for a scan that runs every three weeks on Monday, Wednesday, and Friday, the string would be FREQ=WEEKLY;INTERVAL=3;BYDAY=MO,WE,FR. If the scan is not scheduled to recur, this attribute is null. For more information, see rrules Format

Recurrence Rule Format

Depending on the endpoint, recurrence rules are specified in the rrules or recurrence_rule parameter. These parameters supports a string value in the following format:

FREQ=value;INTERVAL=value;BYDAY=value

This format consists of the following elements:

Element	Description	Supported Values
`FREQ`	Specifies how often you want the scan to repeat.	Supported frequency codes are: `ONETIME`—The scan launches a single time on the day and time specified in `startime`. `DAILY`—The scan launches daily on the day and time specified in `startime`. `WEEKLY`—The scan launches once a week on the day and time specified in `startime`. `MONTHLY`—The scan launches once a month on the day and time specified in `startime`. `YEARLY`—The scan launches once a year on the day and time specified in `startime`.
`INTERVAL`	Specifies how often you want the scan to repeat.	An integer representing how many of the specified unit of time should elapse between scans. For example, if you specify `3` for a weekly scan, the scan repeats every three weeks.
`BYDAY`	Specifies the day or days of the week on which you want the scan to repeat.	Supported month codes are: `SU`—Sunday `MO`—Monday `TU`—Tuesday `WE`—Wednesday `TH`—Thursday `FR`—Friday `SA`—Saturday If you want a scan to repeat on multiple days in the same week, you can use multiple month codes in a comma-delimited list. For example:`MO,WE,FR`.
`UNTIL`	Specifies the datetime of the last occurrence of the rule.	A value in datetime format that indicates when the schedule should end. Note: The `UNTIL` element is only valid for scheduled exports. You can not set an end date for scheduled scans, and the end date for scheduled exclusions is specified in the `endtime` parameter in the `schedule` object.

Examples

Format

Scheduled scans examples:

Scan Recurrence	rrules Value
Run once on Monday	FREQ=ONETIME;INTERVAL=0;BYDAY=MO
Run every week on Monday	FREQ=WEEKLY;INTERVAL=1;BYDAY=MO
Run every month on the specified Monday	FREQ=MONTHLY;INTERVAL=1;BYDAY=MO

Scheduled export examples:

Scan Recurrence	rrules Value
Run every week on Thursday until January 1st, 2030	FREQ=WEEKLY;BYDAY=TH;INTERVAL=1;UNTIL=20300101T143000
Run every month on the 30th	FREQ=MONTHLY;BYMONTHDAY=30;INTERVAL=1
Run every two weeks on Monday until January 1st, 2030	FREQ=WEEKLY;BYDAY=MO;INTERVAL=2;UNTIL=20300101T150000

Full Examples

For full examples including request bodies, see the following examples: