In this section
Acknowledge alert
Acknowledges an alert.
Attach incident to alert
Attaches an incident to an alert.
Create alert escalation policy
Creates an alert escalation policy. The policy is a predefined action to be taken when an alert is not acknowledged.
Notes
- resources: Used to define different resources to apply the escalate alert policy.
- escalations: Used to define the users for escalated alerts notifications.
- escalationType:
- AUTOMATIC_UNTIL_ACKNOWLEDGED_CLOSED_SUPPRESSED_TICKETED: Automated notifications via recipient users until acknowledged, closed, suppressed, or ticketed.
- AUTOMATIC_UNTIL_ACKNOWLEDGED_CLOSED_SUPPRESSED: Automated notifications via recipient users until acknowledged, closed, or suppressed.
- MANUAL – Contact users directly as required.
- filterCriteria – Use the following request structure for ‘Alert : Occurrence Frequency’.
- occurrences – Any integer.
- frequency – Any integer.
- frequencyType – hours or days or weeks
Create alert on a resource
Creates a single alert on a resource.
Notes
- A list of event IDs is generated when alerts are created. This list is valid for 30 days.
- Use the event IDs to search and get alert details.
Creation of a new resource depends on the following:
- A new resource is created and new device group, service group, and location are assigned.
- A new resource is created and existing device group, service group, and location are assigned.
- An already existing resource cannot be assigned to a new or existing Device Group, Service Group and Location.
Create alerts on resources
Creates multiple alerts on resources.
Notes
- A list of event IDs is generated when alerts are created. This list is valid for 30 days.
- Use the event IDs to search and get alert details.
Create and get alert correlation policy
Creates and gets alert correlation policies.
Create daily recurring schedule
Creates a daily recurring schedule.
Create partner and client rosters
Creates partner-level and client-level rosters.
Disable alert escalation policy
Disables an alert escalation policy.
Enable alert escalation policy
Enables an alert escalation policy.
Enable and disable first response policy
Enables and disables the first response policy.
End scheduled maintenance window
Ends a scheduled maintenance window.
Notes
- User can end only active schedule maintenance windows.
- Active schedule maintenance windows that are one-time maintenance windows move to a completed state. Recurring maintenance windows move to pending state.
Get alert comments
Gets alert comments.
Get alert details
Gets alert details.
Notes
For an inference alert, resource name and client ID are provided in the response. For an RCA alert, device ID, Name, and IP address are provided in the response.
Get alert details by alert ID
Gets alert details by alert ID.
Get alert details by event ID
Gets alert details by event ID.
Notes
- A list of event IDs is generated when alerts are created. This list is valid for 30 days.
- Use the event IDs to search and get alert details.
Get alert details by incident ID
Gets alert details by incident ID.
Get alert escalation policies
Gets the alert escalation policies attached to an alert.
Notes
There are special characters that can be used in a query string: (+) represents the next field and must be URL-encoded. (:) represents equals. An example is key : value. Space characters must be URL-encoded. Date format must be yyyy-MM-ddTHH:mm:ssZ (GMT).
Query Variables
| Query Variable | Values | Description |
|---|---|---|
| name | NA | Alert Escalation policy name. Only identical policies in query string name are displayed. |
| allList | true, false | This string is applicable to a partner user to fetch client policies as well. By default, OpsRamp provides partner alert escalation policies if allList is not provided in the query string. - Provide allList: true to fetch partner and client alert escalation policies. - Provide allList: false to fetch only partner alert escalation policies. |
| startCreationDate | NA | Search for policies created within a certain time frame. Provide a start date. An example: 2017-05-05T13:25:15 0000 |
| endCreationDate | NA | Provide an end date. An example: 2017-05-08T10:30:40 0000 |
| startUpdationDate | NA | Search for policies updated within a certain time frame. Provide a start date. An example: 2017-06-10T09:20:10 0000 |
| endUpdationDate | NA | Provide an end date. An example: 2017-06-15T08:10:30 0000 |
Use "scope" and "allClients": true to differentiate between partner and client level policies.
Partner-level policy:
"uniqueId"in scope is specified as msp_id"allClients": trueindicates the policy is a partner level policy
Client-level policy:
"uniqueId"in scope is specified as"client_id".
Get alert escalation policy
Gets the escalation policy attached to an alert.
Get alert status history
Gets alert status history.
Get alert view by view ID
Gets an alert view of a user.
Get alert views
Gets a list of alert views.
Get alerts for alert-triggered time
Gets the alert occurrences based on the alert-triggered time.
Notes
There are special characters that can be used in a query string:
- (+) represents the next field and must be URL-encoded.
- (:) represents equals. An example is key : value.
- Space characters must be URLencoded.
- Date format must be yyyy-MM-ddTHH:mm:ssZ (GMT).
The process for pagination
The API provides the results in descending order of alert-triggered date. The latest alert appears first based on the alert-triggered time. The process for handling any number of occurrences include the following:
- Get all occurrences of an alert.
- Get alert occurrences of an alert that is triggered within a specific duration.
- Traverse through each page of occurrences.
Get All occurrences of an alert
To fetch all alert occurrences irrespective of the alert-triggered time, provide the URI:
/tenants/{tenantId}/alerts/{alertId}/occurrences
Get Alert occurrences of an alert that is triggered within a specific duration
To fetch raw alerts triggered within a specific duration, provide the start time and end time. To fetch raw alerts triggered between January 13th 2017 to February 13th 2017, provide the startTime of 2017-01-13T00:00:00 0000 and an endTime of 2016-02-13T00:00:00 0000. This is the URI for that request:
/tenants/{tenantId}/alerts/{alertId}/occurrences?queryString=startTime:2017-01-13T00:00:00 0000+endTime:2017-02-13T00:00:00 0000
Traverse through each page of occurrences
There is a limit of 100 results per page. If an alert has 120 occurrences, the latest 100 results will appear in the first page. To traverse to the second page, use the endDate from the first page and provide it as the endTime in the query string. The second page will return the remaining 20 alerts.
Use these fields when traversing through additional pages as long as nextPage: true:
| Field | Description |
|---|---|
| results | List of raw alerts data. |
| pageSize | The page size that represents the total number of results to display on the page. The default page size is 100. |
| nextPage | This flag helps determine when the search is complete. If nextPage: false, the search is done. to traverse through the rest of the pages. |
| descendingOrder | Alerts appear in a descending order. The latest triggered alert appears on the top. |
| startDate | Indicates the alert-triggered time of the first result on the page. |
| endDate | Indicates the alert-triggered time of the last result on the page. To traverse through the other pages, provide endDate from previous page and provide it as endTime in queryString. |
Get organization rosters
Gets the rosters in an organization.
Special Characters
There are special characters that can be used in a query string:
- (+) represents the next field and must be URL-encoded.
- (:) represents equals. An example is
key : value. - Space characters must be URL-encoded.
- Date format must be yyyy-MM-ddTHH:mm:ssZ (GMT).
Differentiate Rosters
To differentiate between partner-level and client-level rosters:
- Client level roster: If
clientand client details are provided. - Partner-level roster: If
allClients: trueis provided.
Get resources of schedule maintenance windows
Gets the list of devices (or device groups or sites) of a scheduled maintenance window.
Get sub-alert types
Gets the sub-alert types.
Get supported alert types
Gets the list of supported alert types.
Manage alert correlation policy
Enables, disables, and creates an observed mode on an alert correlation policy.
Manage alert correlation policy by ID
Update, gets, and deletes an alert correlation policy by ID.
Manage alert escalation policy
Gets, update, and delete alert escalation policy information.
Manage first response policy by ID
Updates, gets, and deletes a first response policy by ID.
Manage first response policy details
Creates and views first response policydetails.
Manage rosters
Updates, gets, and deletes rosters.
Manage schedule maintenance window resources
Adds and deletes schedule maintenance window resources.
Manage scheduled maintenance windows
Updates, gets, and deletes scheduled maintenence windows.
Post action on an alert
Posts an action on an alert.
Notes
When unacknowledge or unsuppress is specified, the alert status becomes either open or ticketed (if there is an incident ID associated with the alert).
Search alerts
Searches alerts.
Query Variables
| Query Variable | Value | Description |
|---|---|---|
| states | Ok, Warning, Critical, Info | Current status of the alert. |
| startDate | yyyy-MM-ddTHH:mm:ssZ | Filter the alert with alert base. startDate denotes the from date. Example: 2016-02-24T09:19:47 0000 (GMT) |
| endDate | yyyy-MM-ddTHH:mm:ssZ | endDate denotes to date. Example: 2016-02-26T10:20:47 0000 (GMT) |
| priority | P0, P1, P2, P3, P4, P5 | Priority of the alert. Example: P0, P1. Separate the values with a comma. |
| uniqueId | NA | ID of the alert. |
| deviceStatus | manage, unmanage, all | Status of the device. |
| resourceType | LOAD_BALANCER, SQS, EBS, DEVICE, SNS, REDSHIFT, SERVICE | Type of resource. |
| resourceIds | NA | ID of a resource. Example: DEV0000015754,148e892d-84ce-496c-a123-f91e1a8a3f7d. |
| actions | ACKNOWLEDGED, TICKETED, CLOSED, IGNORE, SUPPRESSED, OPEN, PURGED, CORRELATED | Actions performed on the alert. Example: ACKNOWLEDGED, TICKETED. |
| alertTypes | Monitoring, Maintenance, Appliance, Agent, Scheduled Maintenance, Obsolete, Integration Failure, all | Types of Alerts. Example: Maintenance, Appliance, Agent. |
| metrics | NA | Metric type of the alert. Example: PING, SNMP Response. |
| duration | 1, 7, 30 | Duration of alert. Duration is represented in Number of Days Example: 1, 7. |
| alertTimeBase | updated, created | Search for the alert based on the updated or created time of an alert. Example: updated. |
| clientIds | NA | ID of clients. Example: client_1, client_2. Separate the IDs with a comma. |
| ticketId | NA | ID of the ticket to which the alert is attached. Example: INC0000000001. |
| apps | NA | Apps from which the alert is generated. Example: Email, Nagios |
Variables for statusHistory
The statusHistory parameter uses the following variables:
| Variable | Description | Example |
|---|---|---|
| createdBy | Filter alerts based on createdUser. | system |
| acknowledgedBy | Filter alerts based on acknowledgedUser. | superadmin |
| suppressedBy | Filter alerts based on suppressedUser. | superadmin |
| ticketedBy | Filter alerts based on ticketedUser. | opsramp_system_user |
| closedBy | Filter alerts based on closedUser. | superadmin |
| startAcknowledgedTime | 2015-08-10T05:39:51 0000 | |
| endAcknowledgedTime | 2015-08-10T05:39:51 0000 | |
| startSuppressedTime | 2015-08-10T05:39:51 0000 | |
| endSuppressedTime | 2015-08-10T05:39:51 0000 | |
| startTicketedTime | 2015-08-10T05:39:51 0000 | |
| endTicketedTime | 2015-08-10T05:39:51 0000 | |
| startClosedTime | 2015-08-10T05:39:51 0000 | |
| endClosedTime | 2015-08-10T05:39:51 0000 |
Notes
- Special characters to use in the query string are:
- (+) indicates next field and must be URL-encoded.
- (:) indicates Equals. An example is key: value.
- (,) indicates multiple values for a key. An example is priority: P0,P1
- Space characters must be URL-encoded.
Search scheduled maintenance windows
Gets the scheduled maintenance windows under a specific tenant.
Notess
There are special characters that can be used in a query string:
- (+) represents the next field and must be URL-encoded.
- (:) represents equals. An example is key : value.
- Space characters must be URL-encoded.
- Date format must be yyyy-MM-ddTHH:mm:ssZ (GMT).
Query Variables
| Query Variable | Description |
|---|---|
| uniqueId | Schedule Maintenance window unique ID. |
| name | Schedule Maintenance name. |
| startDate | Start date of schedule maintenance. Example: 2016-08-12T10:55:27 0000 |
| endDate | Expiry date of schedule maintenance. Example: 2016-09-15T18:55:27 0000 |
| deviceUniqueId | Device ID |
| Name | Name. |
| deviceGroupId | Device group ID. |
| deviceGroupName | Device group name. |
| siteId | Site ID. |
| siteName | Site name. |
| startCreationDate | Filter schedule maintenance windows created within a date range. Provide from creation date. Example: 2016-07-24T06:48:40 0000 |
| endCreationDate | Filter schedule maintenance windows created within a date range. Provide to creation date. Example: 2016-07-26T06:48:40 0000 |
| startUpdationDate | Filter schedule maintenance windows updated within a date range. Provide from update date. Example: 2016-07-24T06:48:40 0000 |
| endUpdationDate | Filter schedule maintenance windows updated within a date range. Provide to update date. Example: 2016-07-26T06:48:40 0000 |
| status | Filter with scheduled maintenance window status. For example, to get all scheduled maintenance windows that are completed, provide status: Completed in the query string. Supported statuses: Active, Pending, Suspended, and Completed. |
Suspend scheduled maintenance window
Suspends a scheduled maintenance window.
Notes
- Only active schedule maintenance windows can be suspended.
- Dates in date range consider date as yyyy-MM-dd and ignore the time HH: mm: ss.
- Send dates (start date & end date) in GMT format.
Update incident with alert ID
Updates an incident with an alert ID