In this section

Acknowledge alert

Acknowledges an alert.

Activate user

Activates a user.

Only suspended schedule maintenance windows can be resumed.

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 VariableValuesDescription
nameNAAlert Escalation policy name. Only identical policies in query string name are displayed.
allListtrue, falseThis 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.
startCreationDateNASearch for policies created within a certain time frame. Provide a start date. An example: 2017-05-05T13:25:15 0000
endCreationDateNAProvide an end date. An example: 2017-05-08T10:30:40 0000
startUpdationDateNASearch for policies updated within a certain time frame. Provide a start date. An example: 2017-06-10T09:20:10 0000
endUpdationDateNAProvide 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": true indicates 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:

  1. Get all occurrences of an alert.
  2. Get alert occurrences of an alert that is triggered within a specific duration.
  3. 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:

FieldDescription
resultsList of raw alerts data.
pageSizeThe page size that represents the total number of results to display on the page. The default page size is 100.
nextPageThis flag helps determine when the search is complete. If nextPage: false, the search is done. to traverse through the rest of the pages.
descendingOrderAlerts appear in a descending order. The latest triggered alert appears on the top.
startDateIndicates the alert-triggered time of the first result on the page.
endDateIndicates 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 client and client details are provided.
  • Partner-level roster: If allClients: true is 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 VariableValueDescription
statesOk, Warning, Critical, InfoCurrent status of the alert.
startDateyyyy-MM-ddTHH:mm:ssZFilter the alert with alert base. startDate denotes the from date.
Example: 2016-02-24T09:19:47 0000 (GMT)
endDateyyyy-MM-ddTHH:mm:ssZendDate denotes to date.
Example: 2016-02-26T10:20:47 0000 (GMT)
priorityP0, P1, P2, P3, P4, P5Priority of the alert.
Example: P0, P1. Separate the values with a comma.
uniqueIdNAID of the alert.
deviceStatusmanage, unmanage, allStatus of the device.
resourceTypeLOAD_BALANCER, SQS, EBS, DEVICE, SNS, REDSHIFT, SERVICEType of resource.
resourceIdsNAID of a resource.
Example: DEV0000015754,148e892d-84ce-496c-a123-f91e1a8a3f7d.
actionsACKNOWLEDGED, TICKETED, CLOSED, IGNORE, SUPPRESSED, OPEN, PURGED, CORRELATEDActions performed on the alert.
Example: ACKNOWLEDGED, TICKETED.
alertTypesMonitoring, Maintenance, Appliance, Agent, Scheduled Maintenance, Obsolete, Integration Failure, allTypes of Alerts.
Example: Maintenance, Appliance, Agent.
metricsNAMetric type of the alert.
Example: PING, SNMP Response.
duration1, 7, 30Duration of alert. Duration is represented in Number of Days
Example: 1, 7.
alertTimeBaseupdated, createdSearch for the alert based on the updated or created time of an alert.
Example: updated.
clientIdsNAID of clients.
Example: client_1, client_2. Separate the IDs with a comma.
ticketIdNAID of the ticket to which the alert is attached.
Example: INC0000000001.
appsNAApps from which the alert is generated. Example: Email, Nagios

Variables for statusHistory

The statusHistory parameter uses the following variables:

VariableDescriptionExample
createdByFilter alerts based on createdUser.system
acknowledgedByFilter alerts based on acknowledgedUser.superadmin
suppressedByFilter alerts based on suppressedUser.superadmin
ticketedByFilter alerts based on ticketedUser.opsramp_system_user
closedByFilter alerts based on closedUser.superadmin
startAcknowledgedTime2015-08-10T05:39:51 0000
endAcknowledgedTime2015-08-10T05:39:51 0000
startSuppressedTime2015-08-10T05:39:51 0000
endSuppressedTime2015-08-10T05:39:51 0000
startTicketedTime2015-08-10T05:39:51 0000
endTicketedTime2015-08-10T05:39:51 0000
startClosedTime2015-08-10T05:39:51 0000
endClosedTime2015-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 VariableDescription
uniqueIdSchedule Maintenance window unique ID.
nameSchedule Maintenance name.
startDateStart date of schedule maintenance.
Example: 2016-08-12T10:55:27 0000
endDateExpiry date of schedule maintenance.
Example: 2016-09-15T18:55:27 0000
deviceUniqueIdDevice ID
NameName.
deviceGroupIdDevice group ID.
deviceGroupNameDevice group name.
siteIdSite ID.
siteNameSite name.
startCreationDateFilter schedule maintenance windows created within a date range. Provide from creation date.
Example: 2016-07-24T06:48:40 0000
endCreationDateFilter schedule maintenance windows created within a date range. Provide to creation date.
Example: 2016-07-26T06:48:40 0000
startUpdationDateFilter schedule maintenance windows updated within a date range. Provide from update date.
Example: 2016-07-24T06:48:40 0000
endUpdationDateFilter schedule maintenance windows updated within a date range. Provide to update date.
Example: 2016-07-26T06:48:40 0000
statusFilter 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