Page tree

This section lists a couple use case scenarios for the web service to create a blackout policy, and can help you effectively use the create API. Each scenario is explained using an example URL and subsequent response details.

Creating a blackout policy to block data for a specific time period

You can create a blackout policy to black out data from the PATROL Agent for a specific time period. Before creating a policy, you must create a time frame. For information about creating a time frame, see Creating a time frame.

URL to create a blackout policy to black out data for a specific time period

http://<TSPShostname:port#>/tsws/10.0/api/unifiedadmin/BlackoutPolicy/create

Input parameters to create a blackout policy to black out data for a specific time period

{
            "blackoutPolicy": {
                "id": "893274a7-b8c1-4501-b675-9b7d94827da0",
                "name": "BO11",
                "type": "blackout",
                "description": "",
                "tenant": {
                    "name": "tenant1",
                    "id": "tenant1"
                },
                "precedence": 999,
                "agentSelectionCriteria": "agentOS CONTAINS \"windows\" ",
                "associatedUserGroup": "BMCTenantAdmin",
                "owner": "test3",
                "timeframes": [
                    {
                        "name": "TF1",
                        "id": "fbb4d1f2-e32a-4b56-aa8c-67e9e0a448b2"
                    }
                ],
                "scope": "completeAgent",
                "blackoutTypes": [
                    "data",
                    "events",
                    "recoveryActions"
                ],
                "blackoutStartStopEvents": true,
                "enabled": true,
                "shared": false
            }
        }

For information about the input parameters, see List of input parameters for the create API.

JSON response

A blackout policy is created, and a sample response is as follows:

{
    "response": [
        {
            "name": "BO11", 
            "statusCode": "200", 
            "statusMsg": "Successfully created policy", 
            "policyId": "id_1"
        }
    ], 
    "statusCode": "200", 
    "statusMsg": "OK", 
    "responseTimeStamp": "2012-06-20T08:36:24", 
}

Creating a blackout policy to block an agent action from being executed for a monitor

You can create a blackout policy to block an Agent action from being executed for a specific monitor or an agent. Before creating a policy, you must create a time frame. For information about creating a time frame, see Creating a time frame.

Note

You can specify an agent by using a range of IP addresses starting from 10.10.10.0 to 10.10.10.100.

URL to create a blackout policy to block an agent action from being executed

http://<TSPShostname:port#>/tsws/10.0/api/unifiedadmin/BlackoutPolicy/create

Input parameters to create a blackout policy to block an agent action from being executed

{
{
            "blackoutPolicy": {
                "id": "6bc4cbbb-fc11-4929-bf78-6294fe1458e8",
                "name": "blackout-agent1",
                "type": "blackout",
                "description": "",
                "tenant": {
                    "name": "tenant1",
                    "id": "tenant1"
                },
                "precedence": 999,
                "agentSelectionCriteria": "agentOS CONTAINS \"windows\" ",
                "associatedUserGroup": "BMCTenantAdmin",
                "owner": "test3",
                "timeframes": [
                    {
                        "name": "TF-alwaysactive",
                        "id": "69170e4a-949b-45ba-b803-7854bf7e3509"
                    }
                ],
                "scope": "completeAgent",
                "blackoutTypes": [
                    "data",
                    "events",
                    "recoveryActions"
                ],
                "blackoutStartStopEvents": true,
                "enabled": true,
                "shared": true
            }
        }

The following table lists the parameters that you must provide with the URL.

List of required parameters that must be provided to access the create API

AttributesDescription
agentSelectionCriteria

Set of conditions based on which the agents are identified to apply the policy

The syntax is  "agentIdentifier operator \"value\""

where,

  • agentIdentifier refers to the agent attributes, based on which the agent is identified. The supported identifiers are as follows:
    • agentName—Host name of the computer on which the BMC PATROL Agent is installed
    • agentPort—Port number through which the Integration Service connects with the agent
    • agentVersion—Version of the BMC PATROL Agent
    • agentOS—Operating system of the computer on which the BMC PATROL Agent is installed
    • agentIP—IP address of the computer on which the BMC PATROL Agent is installed
    • agentTag—Tag name of the BMC PATROL Agent
    • integrationService—Display name of the Integration Service
    • childServer—Host name of the Child Server that is registered with Central Monitoring Administration
precedencePriority for the policy. The supported values are numbers between 0 and 999 with 999 being the lowest priority and 0 being the top priority. 

The default value is 999.
tenantDetails of the tenant who owns the policy. You can either provide name or the id of the tenant.
name

Name of the tenant who owns the policy. The supported values are as follows:

  • <nameOfTenant>—Indicates that the policy is applicable to the specified tenant
  • GLOBAL—Indicates that the policy is applicable to all agents
  • PROVIDER—Indicates that the policy is applicable to the cloud service provider and also to the agents that do not have any tenants
enabledIndicates whether the policy is enabled. The default value is true.
nameName of the policy
type

Type of the policy. The supported types are as follows:

  • blackout
  • monitoring
descriptionBrief description about the policy
timeframeDetails of the time frame. The time frame specifies the time period for the blackout policy to be active.
nameName of the time frame
scope

Scope of the blackout policy. The supported scopes are as follows:

  • completeAgent—Indicates that the policy is applied to all the monitors associated with the agent
  • monitorTypesAndInstances—Indicates that the policy is applied only to the specified monitors
blackoutTypes

Type of the blackout policy. The supported types are as follows:

  • data—Indicates that the policy is applicable only for the performance data
  • events—Indicates that the policy is applicable only for the event data
  • recoveryActions—Indicates that the policy is applicable only for the agent actions
monitorConfigListList of monitors for which you want to create the blackout policy
monitorTypeSpecificationSpecifies the details about the monitors
monitorType

Type of the monitor

You can use the solutions API to know the supported monitor types. For information about the solutions API, see Listing the available versions for a specific monitor solution.

solutionNameName of the monitoring solutions
solutionVersionVersion of the specified monitoring solutions
scope

Scope of the policy based on the monitor type. The supported options are as follows:

  • type—Indicates that the policy is applied to all the monitor instances of the specified monitor type
  • instances—Indicates that the policy is applied only to the specified monitor instances
monitorInstancesSpecifies the details about the monitor instances for which you want to create the policy
monitorInstanceSpecifies the details about a monitor instance
shared

Supports two values:

  • true - the policy can be shared among users of specific user group
  • false - the policy cannot be shared with anybody
associatedUserGroup Name of the user group with which you want to associate the policy

JSON response

A blackout policy is created, and a sample response is as follows:

{
    "response": [
        {
            "name": "blackout-agent1", 
            "statusCode": "200", 
            "statusMsg": "Successfully created policy", 
            "policyId": "id_1"
        }
    ], 
    "statusCode": "200", 
    "statusMsg": "OK", 
    "responseTimeStamp": "2012-06-20T08:36:24", 
}

Related topics

Creating a policy using web services

Managing policies using web services

Performing Central Monitoring Administration functions with web services