Configuring blackout policies

Use blackout policies to black out events originating from various devices. These policies help you black out events only, they are not applied to data. The following instructions help you to create, edit, copy, view, enable, disable, and delete blackout policies.

The following video (7:03) created by BMC Support describes how to create a blackout policy.

https://youtu.be/cvJCAuZr5cA

Example

Sarah is an administrator at Apex Global. She wants to black out maintenance-related events during a database maintenance period that runs twice a week and lasts for an hour from 2.00 AM to 3.00 AM. She can schedule the blackout by using the following settings:

To create a blackout policy

In BMC Helix Operations Management, navigate to Configuration > Blackout Policies page and click Create.
Specify a unique name, optional description, and precedence number for the policy.
Click in the Selection criteria field and make a selection.
Each time you make a selection, you are progressively prompted to make another selection. Perform the following steps to configure the selection criteria for the policy.
Values that you specify in the selection criteria are case-sensitive. For example, Message Equals test and Message Equals TEST are considered as different values.
Refer to the following image to understand the Selection criteria field.
Warning
Important
- A condition based on the class slot must be specified before any other condition. In the subsequent conditions, the list of slots changes based on the class specified. The subsequently displayed slots are subclasses of the parent class selected in the first condition.
  For example, in the following image, notice the list of slots specific to the selected Alarm class.
- If you specify multiple hosts, for example, more than 500, by using the Equals operator with OR in the condition, the blackout policy might not black out events because the condition would
  exceed the maximum character limit of 32,766. In this scenario, to black out events, consider specifying multiple hosts by using the Matches operator with the pipe (|) character in the condition. Make sure that the event slot values that you specify with the Matches operator do not exceed 1000 characters.
  For example,
  Matches:
  Host Matches 'HostA.bmc.com|HostB.bmc.com|HostC.bmc.com|HostD.bmc.com|
  HostE.bmc.com|HostF.bmc.com'
  Within:
  source_hostname within '['clm-host-within1.bmc.com','clm-host-within2.bmc.com','clm-hostwithin3.
  bmc.com']'
  Avoid:
  Host Equals 'HostA.bmc.com' OR Host Equals 'HostB.bmc.com' OR Host Equals
  'HostC.bmc.com' OR Host Equals 'HostD.bmc.com' OR Host Equals 'HostE.bmc.com' OR Host
  Equals 'HostF.bmc.com'
- The maximum limit of 32,766 characters for the Event Selection Criteria field includes the length of the incoming event slot data that is used in the event selection criteria. Therefore, if the Event Selection Criteria field exceeds the maximum limit during policy evaluation, the policy evaluation fails, and the policy is not applied to the event. You can see an error under the Others tab on the Event Details page.
- If you specify the Class slot with an opening parenthesis as the first condition in the criteria, you must use the closing parenthesis to complete the condition. The Class slot must be
  followed by the AND operator before the next condition.
- Event slot values that you specify in the criteria with the Contains operator are not case-sensitive.
  For example, if you use the following values, the blackout policy is applied to events:
  Value in the event selection criteria: Host Contains hostA
  Value in the ingested event: Host Contains HOSTA
  However, slot values that you specify with other operators, such as the Equals operator, are case-sensitive.
- If you add leading and trailing spaces in the list of string values or spaces before or after the list separator (,) with the Within operator, the blackout policy fails and does not black out events.
Click Add Policy Configuration and configure the blackout settings.
You can configure one of the following settings. You can also use Advanced Settings to specify a desired time zone.
- One Time: Can be used to black out event notifications during a specified time period only, such as a
  holiday, or during an expected change in your IT environment.
  Perform the following steps to configure this setting:
  1. Select the start date for the blackout and click Next.
    You can click the arrows to change the month and the year.
  2. Select the end date for the blackout and click Ok.
    You can click the arrows to change the month and the year.
  3. Select the time zone.
- Recurring: Can be used to black out event notifications for a specified time period on a recurring basis, such as during a regular maintenance window, or if your IT operators don't want to see event notifications during certain times of the day.
  Perform the following steps to configure this setting:
  1. In the Start time field, configure the time when the blackout period starts.
  2. Use one of the following fields to configure when the blackout period ends:
    - End Time: Use this option when you want the blackout period to end at a certain time.
      For example, the start time can be 4.00 AM and the end time can be 10.00 AM.
    - Duration: Use this option when you want to specify a duration for the blackout period. You can select one of the following units of duration:
      - Mins
      - Hrs
      - Days
        To select this option, make sure that you select either Weekly or Monthly as the recurrence pattern.
        For example, the start time can be 4.00 AM and the duration can be 2 days.
  3. Configure the recurrence pattern of the blackout period by using the following options:
    - Repeats: Select how often a schedule should run. The following options are available:
      - Daily: Select this option to run the blackout schedule daily.
        The maximum value can be 24 hours or 1440 minutes. With the Daily repeat option, you cannot select the Days option when configuring a blackout duration.
      - Weekly: Select specific days of the week when the blackout schedule should run.
        The maximum value can be 7 days, 168 hours, or 10080 minutes.
      - Monthly: Specify dates of the month when the blackout schedule should run.
        The maximum value can be 31 days, 744 hours, or 44640 minutes.
  4. Configure the range of recurrence of the blackout period by using the following options:
    - Start Date: Specify the date when you want the blackout to begin.
    - No End Date: Select this option if you don't want the blackout period to end, which means the blackout schedule executes perpetually.
    - End Date: Specify the date when you want the blackout to end.
    - End After: Specify the number of occurrences after which you want the blackout to end.
(Optional) In Blackout Actions, specify the action that you want to take during the blackout window. To learn about blackout actions; see Blackout policies.
Click Save.
(Optional) Select Enable Policy.
You can enable or disable the policy any time from the Blackout Policies.
Save the policy.

Example: Scheduling a continuous blackout policy for a long duration

Sarah, the administrator at Apex Global, wants to create a blackout policy with the following configurations:

Start time: 12 AM
Duration: 24 Hrs
Repeats: Daily
Start date: 01 April 2026
End date: 30 April 2026

For this scenario, we recommend that Sarah create a one-time policy with the following configurations:

Start time: 01 April 2026, 12 AM
End time: 30 April 2026, 11:59 PM
If Sarah needs the policy to be active for a longer duration, she can specify a date and time a few years in the future.

To edit a blackout policy

In BMC Helix Operations Management , navigate to Configuration > Blackout Policies page.
Perform one of the following actions:
- Select a disabled policy and click Edit.
  To edit an active policy, disable it first.
- From the Actions menu of a disabled policy, select Edit.
Edit the policy and save the changes.

To copy a blackout policy

In BMC Helix Operations Management, navigate to Configuration > Blackout Policies page.
Click the action menu of the policy that you want to copy and select Copy .
The Create Blackout Policy page is displayed with the configurations of the copied policy.
Modify the configurations according to your requirements to create a new policy quickly.

To view the list of blackout policies

In BMC Helix Operations Management, navigate to Configuration > Blackout Policies page to view the list of blackout policies and to search for them. Do not use single quotes while searching for a policy.

By default, you can see 25 policies on a single page. You can configure this number. Perform the following steps to configure the number of policies that you can see on the page:

If you have more than 25 policies in the system, scroll down to the end of the Blackout Policies page.
Click the box that shows 25 and select the number of policies that you want to see on the page. You can see the box only if you have more than 25 policies in the system.

By default, the policies are sorted by the last updated date and time (Modified By / On column). To sort on a different column, click the column heading.

To enable or disable a blackout policy

In BMC Helix Operations Management, navigate to Configuration > Blackout Policies page.
Perform one of the following actions:
- Select the policy and click Enable or Disable.
- From the Actions menu of a policy, select Enable or Disable.
- Edit the policy, and select or clear the Enable Policy checkbox.

To delete a blackout policy

In BMC Helix Operations Management, navigate to Configuration > Blackout Policies page.
Perform one of the following actions:
1. Select one or more policies, click Delete, and click OK.
  To delete an active policy, disable it first.
2. From the Actions menu of a disabled policy, select Delete, and click OK.

Important

Deleting a large number of policies is a maintenance activity and should be done in a controlled manner. Conctact BMC Support if you want to delete a large number of policies at once.

Type your warning message here.

Auditing user actions on a blackout policy

As a tenant administrator, use the BMC Helix Audit Dashboard in BMC Helix Dashboards to view the audit trail of activities that users perform on blackout policies. You can audit the following activities on a blackout policy:

Create a blackout policy
Update a blackout policy
Delete a blackout policy
Enable a blackout policy
Disable a blackout policy

Scenario

Sarah is an administrator at Apex Global. She has configured a blackout policy to black out maintenance events during planned downtimes. However, she can see maintenance events on the Events in BMC Helix Operations Management despite an active blackout policy. To troubleshoot this issue, she can now use the BMC Helix Audit Dashboard in BMC Helix Dashboards to view the audit trail of all activities that users perform on blackout policies. Viewing the audit trail helps Sarah to track the history of changes made to the policies and achieve improved user accountability, compliance with organization policies, and system security.

For more information, see Auditing configuration changes in BMC Helix Dashboards.

The following image displays the audit trail of blackout policies in the BMC Helix Audit Dashboard. Note that the selected resource type is Blackout Policy. Click the link in the Operation column to view the values before and after you perform an activity on a blackout policy.

Audit trail for blackout policies label.png

Best practices to decide blackout configurations

Use these best practices to avoid blackout configurations that can lead to unexpected results or disabled blackout policies.

Blackout policies support the following schedule types:

One-time blackout
This schedule type is a continuous blackout from a start date and time to an end date and time. This type is best used for long, continuous blackout periods with no repeating patterns. Long blackout periods could be for days or weeks.
Recurring blackout
This schedule type is a repeating blackout that has a repeating pattern. This type requires the following configurations:
- Repeat pattern - where you can select one of the following patterns:
  - Daily
  - Weekly. You can select one or more days, for example, Monday - Saturday.
  - Monthly. You can select a date range, such as 1-20, or specific dates, such as 1,2,4, and so on.
- Start and end time - where you can select the start time and one of the following configurations to end the blackout period:
  - End time
  - Duration. This configuration is recommended for a long period within a recurrence.

Choosing between configuring a one-time and a recurring blackout policy

Refer to the following recommendation about choosing a one-time or recurring configuration for the blackout policy:

Create a one-time blackout policy to achieve a continuous blackout period with no gaps.
Examples:
- A continuous blackout period for maintenance from April 10, 09:00 to April 24, 18:00.
- A blackout period that must stay active continuously for several days or weeks.
Create a recurring blackout policy to achieve a repeating pattern of blackout periods. A recurring blackout is designed for repeating windows with a consistent pattern.
Examples:
- Every weekday night
- Every Friday evening
- The first 20 days of the month

Important

To achieve the best results, avoid always-on recurring configurations.

Example

A blackout policy is configured to remain continuously active using the Daily + 24-hour recurring schedules. This configuration can lead to unexpected behavior. The system might schedule the policy activation and deactivation jobs very close together, which can cause the following result:

The activation job runs and the deactivation job runs immediately afterward (or vice versa).
The policy is enabled and disabled in rapid succession.

In this case, if your goal is a continuous blackout policy for a long period, use a one-time blackout schedule with the correct start and end date and time.

To achieve the best results, avoid the following recurring configurations:

Daily recurring + Duration = 24 hours (indefinite blackout)
Weekly recurring + select all days + Duration = 24 hours (the same as daily + 24 hours)

Choosing between an end time and a duration for a recurring blackout policy

For a recurring blackout schedule type, refer to the following best practices when you want to choose between an end time and a duration:

Use the End Time configuration when the blackout period does not extend beyond 23 hours 59 minutes.
The End Time configuration has a limit of 23 hours and 59 minutes. Because of the 1-minute gap between the limit and 24 hours, a multiple-day scenario cannot be covered with this configuration.
Use the Duration configuration when the blackout period extends beyond 24 hours.
You can configure the duration for days, hours, or minutes. The maximum duration depends on one of the repeat patterns that you select:
- Daily: up to 24 hours
- Weekly: up to 168 hours (7 days)
- Monthly: up to 744 hours (31 days)