BigPanda

Authentication and Headers

With each request to the BigPanda API, you must include an HTTP header with the authentication token for your organization. You may also need to specify the content type of the data payload and/or the response payload.

 

For example:

"Authorization: Bearer ${token}" "Accept: application/json" "Content-Type: application/json; charset=utf8"

Authentication Tokens

Each organization has a unique bearer token for authenticating API requests. To access any API resource, every request must include this token as a value in the Authorization HTTP header.

To find your token in BigPanda, log in as an administrator and then click the Integrations tab at the top of screen. Open the instructions for the Alerts API. Your token appears in the example headers.

Content Types

Include the appropriate Content-Type and Accept headers to specify the representation of data sent to and retrieved from BigPanda. Most BigPanda APIs accept and respond with JSON content as the data payload. Refer to the API reference documentation for supported content types of each request.

 

Response Codes

BigPanda uses conventional HTTP response codes to indicate the success or failure of an API request. When a request is successful, BigPanda sends a response code to indicate that it received the message. If a request fails, the response code may help with troubleshooting an error.

 

This table lists some of the common response codes you may receive from the BigPanda API. Refer to the API reference documentation for specific response codes and errors, where applicable.

Response
Description

200 OK

Success.

201 Created

New resource created.

204 No Content

Request was successfully processed, and the server is not returning any content. For example, an event sent via the Alerts API was deduplicated.

400 Bad Request

Default code for invalid requests. For example, it is missing a mandatory field. Check the error message and ensure that the JSON includes the correct parameters.

401 Unauthorized

Token is invalid or missing. Check that the request includes the correct HTTP headers.

404 Not Found

Requested endpoint isn't available. Ensure that the request uses one of the API endpoints specified in the documentation.

409 Conflict

Request cannot be performed due to a conflict. For example, attempting to resolve an incident that's already resolved.

410 Gone

Requested resource is no longer available and has been removed permanently. Consult the documentation to see what endpoints are supported currently.

500 Internal Server Error

Default code for errors that occur due to problems on BigPanda servers. Retry the request after some time.

501 Not Implemented

Unsupported method.

 

Expandable Objects

Some objects contain the ID of a related object in their response properties. For example, an Incident may have associated Alert IDs. If the object is expandable, you can use the expand query parameter in your request to retrieve a full representation of it.

 

For example, append ?expand=alerts to the URI of an incident request to expand all the alert objects that the incident contains.

GET /incidents/{id}?expand=alerts

Objects that can be expanded are noted in the API reference documentation. Additionally, you can discover the identifiers for each expandable object by referencing the the expand property in the parent object. You can expand multiple objects at once by identifying multiple items in the expand array.

 

Synchronous and Asynchronous Calls

API requests for potentially long-running actions are performed asynchronously.

 

For example, uploading a mapping enrichment table. All asynchronous calls create a Job object and return the HTTP response code 202 Accepted and a location header. To obtain the actual result of the call, you have to check the job status by sending a GET request to the Job resource URL.

For example:

GET /enrichments/{id}/map/{job_id}

 

Notifications Webhook

The Notifications Webhook lets you share incidents with another application or service programmatically via a callback URL. Configure webhooks to build custom integrations with messaging, ticketing, or other collaboration systems.

 

Key Features

  • Enables custom integrations by sending high-level, correlated incidents from BigPanda to any Webhook receiver you configure.

  • Sends incident data to an external URL via HTTP POST request.

  • Supports custom authentication headers for data security.

  • Supports AutoSharing, manual sharing, and sharing updates.

Webhooks Explained

In general, Webhooks are a programmatic way to send information to an Internet address when an event occurs in an application. In BigPanda, the Notifications Webhook allows you to send incident information to a callback URL when an incident is shared and when the shared incident is updated.

How It Works

A Notifications Webhook integration creates a sharing channel from BigPanda to a callback URL of your choosing. When an incident is shared via the channel, BigPanda sends an HTTP POST request to the callback URL. The data payload of the request is the Incident object with the expanded representation of the Alertobjects it contains. The application or service that receives the request can then process the data according to any business logic it has configured for new shares from BigPanda. For example, if the callback URL is an API endpoint for a service desk application, you may configure the application to create a ticket for the team that handles incident escalations.

If a change occurs that triggers a sharing update for the incident, BigPanda sends another HTTP POST request to the callback URL, with the updated Incidentobject and Alert objects it contains. The application or service that receives the request can then process the data according to any business logic it has configured for updates to existing BigPanda shares. For example, if the callback URL is an API endpoint for a service desk application, you may configure the application to update the existing ticket for the shared incident.

You can use the Notifications webhook to build any number of custom collaboration integrations. As with other sharing channels, the same incident update can be shared through multiple webhook integrations.

Common Use Cases

The Notifications webhook is often used to integrate BigPanda with messaging, ticketing, or other collaboration systems. Some systems provide built-in API endpoints and scripting layers for receiving and transforming data according to custom business logic. Alternatively, you can build a custom API endpoint within your infrastructure or by using cloud services such as Amazon API Gateway and AWS Lambda.

Integrating Collaboration Systems With The Notifications Webhook

To build a custom integration with the Notifications webhook, you must configure the collaboration system to receive and use BigPanda incident data. Then, configure BigPanda to send the data.
Follow this general process to use the Notifications Webhook:

  1. Configure The API Endpoint To Receive The Webhook.
    Be sure to configure security settings for authenticating requests, such as API keys or user account credentials. Consider configuring responses with status codes to aid in testing and troubleshooting.

  2. Set Up The Receiving System To Use The Data.
    Apply custom business logic, transform the data, and/or perform actions in the system with custom code or settings. As necessary, configure data storage, include logic for receiving multiple requests about the same incident, and/or configure the API endpoint to trigger any custom code when data is received.

  3. Configure The Webhook Settings In BigPanda.
    Create a sharing channel from BigPanda to the application or service. Provide the callback URL and authentication headers that BigPanda will use to send the incident data.

  4. Test The Webhook.

  5. Configure Environments And AutoShare Rules To Use The Webhook Sharing Channel, As Necessary.

You can use the Incidents API to build a bidirectional integration with a collaboration system. For example, if you are building a webhook integration that creates a ticket in a service desk application, you may want to use the Incidents API to automatically resolve the BigPanda incident when the service desk ticket is closed.

 

BPQL Object Syntax

BigPanda uses a JSON Object form of its BPQL string for API body parameters. When using the API, this format needs to be followed where appropriate.

 

BigPanda's APIs utilizes the BPQL object syntax when used for querying, which should not be confused with the string formatted BPQL when searching or filtering inside the UI itself.

The below BPQL object cheatsheets explain how a conventional BPQL string is represented as a JSON object instead. Again, use this format whenever a certain API requires filling in a bpql parameter, like Create a Plan. 

{<operator>: [<tag>, <value/values>]}
Command
BPQL String
BPQL Object

equal =

host = prod-api-1

{ "=": [ "host", "prod-api-1" ]}

not equal !=

host != prod-api-1

{ "!=": [ "host", "prod-api-1" ]}

strong equal ===

host === prod-api-1

{ "===": [ "host", "prod-api-1" ]}

in operator IN

host IN [prod-api-1,prod-api-2]

{ "IN": [ "host", [ "prod-api-1", "prod-api-2" ]]]}

not in operator NOT IN

host NOT IN [prod-api-1,prod-api-2]

{ "NOT IN": [ "host", [ "prod-api-1", "prod-api-2" ]]]}

{<operator>: [<sub_query#1>,<sub_query#2>,...]}
Command
BPQL String
BPQL Object

AND

host = prod-api-1 AND check = cpu

{ "AND": [{ "=": [ "host", "prod-api-1" ]}, { "=": [ "check", "cpu" ]}]}

OR

host = prod-api-1 OR check = cpu

{ "OR": [{ "=": [ "host", "prod-api-1" ]}, { "=": [ "check", "cpu" ]}]}

Special Values

For commands with special values, the value will be represented inside an object. Here are two examples.

Command
BPQL String
BPQL Object

wildcard *

host = prod-api-*

{ "=": [ "host", { "type": "regex", "value": "prod-api-*" }]}

Formal Regex Search

host = /prod-api-.*/

{ "=": [ "host", { "type": "formal-regex", "value": "prod-api-.*" }]}

 

How it Works

Use the Alerts API to build a custom integration between BigPanda and your monitoring system.

 

The Alerts API allows you to easily integrate a monitoring system with BigPanda. Monitoring systems generally send out events when problems are detected and when problems have been resolved (fixed).

The API works by receiving the events that your monitoring system sends. Incoming events sent via the REST API are processed according to the BigPanda alert correlation logic. Depending on the results of the correlation, the system then creates a new incident or updates an existing incident.

If the tool you are integrating with does not support HTTP headers, you can use the access_token URL parameter for authentication. For example:

https://api.bigpanda.io/data/v2/alerts?access_token=<YOUR TOKEN>

Available Methods

Methods
API Endpoint
Description

POST alerts

https://api.bigpanda.io/data/v2/alerts

Sends alert data to BigPanda for processing and correlation.

Custom Wrappers

BigPanda provides the following wrappers for calling the Alerts API from custom scripts.

  • Bash Shell utility
  • Python module
 

Integrating Monitoring Systems

You can use the Alerts API to build a custom integration between BigPanda and your monitoring system. If the monitoring system supports custom HTTP callbacks, the easiest way to integrate it is by using a webhook. If it doesn't, you can write a custom script.

 

Prerequisites

  • Obtain administrator access to BigPanda
  • Determine how your monitoring system triggers API calls—webhooks or custom script calls.

Using a Webhook to Integrate a Monitoring System

If the monitoring system supports custom HTTP callbacks, you can follow this general process to integrate it with BigPanda:

  1. In BigPanda, create an App Key.
    Each integration must have an App Key in BigPanda to identify it as a unique source.
  2. In your monitoring system, configure the webhook to send alerts to BigPanda.
  3. Test the integration by sending a test alert.

Using a Custom Script to Integrate a Monitoring System

If the monitoring system does not support webhooks, you can write a custom script. Follow this general process to integrate it with BigPanda:

  1. In BigPanda, create an App Key.
    Each integration must have an App Key in BigPanda to identify it as a unique source.
  2. Download one of the BigPanda-provided wrappers or use a custom wrapper.
    You must install the wrapper on a server that has access to the monitoring data.
    The server must be able to run the code. For example, to use the BigPanda Python module, Python must be installed and running on the server.
  3. Write a custom script to send alerts to BigPanda via the Alerts API.
  4. Configure your monitoring system to call your custom script.
  5. Test the integration by sending a test alert.
 

Best Practices

Follow these guidelines when building custom integrations with the BigPanda Alerts API.

 

When to Send Events

  • Send an event every time the status of an alert changes.
    For example, a new Critical alert is opened or a Critical alert becomes a Warning. The status of an alert typically changes when a metric goes above or below a certain threshold.
  • Send an OK resolution event when an alert is no longer active.
    BigPanda does not resolve alerts automatically. Alerts that have not been resolved remain open, and the corresponding incident also remains open and continues to appear in the incident feed.

Some monitoring tools don't trigger resolution events. In this case, you must manually resolve incidents to remove them from the incident feed. To avoid excessive manual work, consider ways to limit the new alerts from these systems to no more than a few per day.

  • Send an updated event when you need to change tag values for an alert.
    In some rare cases, you may want to send an event for an alert with the same status but a different value for one or more tags. For example, assume you have an alert with status of Warning and description of problem1. You can send a new Warning event with a description of problem2, and the alert status remains the same but the description is updated.

What Tags to Send

The attributes in your JSON payload become tags that you can use in BigPanda. When defining an integration with the Alerts API, send tags that:

  • Provide users with information about where the alert was triggered.
    It is common to include information such as the host or virtual node. Consider including additional information, such as cluster, data center, and server role, which can be very useful when investigating a problem.
  • Support the teams and processes in your organization.
    Consider how you plan to use tag values to define your Environments, AutoShare rules, and Analytics reports. For example, consider the teams' areas of responsibility, processes, or escalation paths.
  • Include links for additional information about the alert.
    For example, send a link to documentation (such as a runbook wiki) or investigation tools (such as a metrics dashboard). If one of the tag values starts with http, BigPanda automatically adds a link button for that alert.

How Many Events to Send (Load Limitations)

  • If an integration generates more than a few hundred event per hour, review the guidelines for when to send events and ensure that the integration is properly configured.
    Even with hundreds of thousands of monitoring metrics, status changes do not happen very often. If an integration exceeds this guideline, it may be sending duplicate or erroneous events to BigPanda.
  • Under maximum load, the API can support up to few hundred events per minute.
    If you think you need support for more than this limit, please contact BigPanda support to discuss your use case.
 

Alerts

Send alerts through the API.

 
posthttps://api.bigpanda.io/data/v2/alerts

Body Params

app_key
string
required

Application key, created in the first step of a BigPanda tutorial.

status
string
required

Status of the alert. One of [ ok, critical, warning, acknowledged ].

host
string

Main object that caused the alert. Can be the associated host or, if a host isn't relevant, a service or an application. If you want to include more than one of these fields, consider specifying the primary and secondary properties.

timestamp
date-time

(Optional) Time that the alert occurred in Unix format (UTC timezone). If the time is not specified, the value defaults to the current time.

check
string

(Optional) Secondary object or sub-item that caused the alert (often shown as an incident subtitle in BigPanda).

description
string

(Optional) Additional free-form text information about this alert.

cluster
string

(Optional) Server cluster or logical host-group from which the alert was sent. This value is used to correlate alerts into high-level incidents.

Additional attributes
string

(Optional) Additional information you want to have available in BigPanda. You can add any number of custom JSON attributes with a string value to the payload.

Parameters (Multiple Alerts)

If you want to send more than one alert in a single API call, you can modify the JSON payload to contain these main properties.

Field
Description

app_key

Application key, created in the first step of a BigPanda tutorial. When sending multiple alerts at the same time, you can specify the app_key one time instead of for each alert.

alerts

Array of alerts to send to BigPanda. Each item in the array contains the same fields as for an individual alert, except you do not need to specify the app_key.

curl -X POST -H "Content-Type: application/json" \
    -H "Authorization: Bearer <YOUR TOKEN>" \
    https://api.bigpanda.io/data/v2/alerts \
    -d '{ "app_key": "<YOUR APP KEY>", 
          "alerts": [{
               "status": "critical", 
               "host": "production-database-1", 
               "check": "CPU overloaded" 
           }, {
               "status": "critical", 
               "host": "production-database-2", 
               "check": "CPU overloaded" 
           }]
       }'

Sending multiple alerts with the REST API

BigPanda uses the timestamp to determine the latest status of an alert. If it is not included, BigPanda uses the time when the event is received. To ensure that BigPanda accurately reflects the current status, when sending multiple events, you must include the timestamp for each event or sort the alerts array by when the events occurred, in ascending order.

Parameters (Primary and Secondary Properties)

BigPanda treats certain properties as primary and secondary by default. In some cases, you may want to control which properties are treated as primary or secondary. For example, you may have an alert that is associated with both a host and an application, where the application is primary and the host is secondary. In these cases, use the primary_property and secondary_property properties.

UI Considerations

BigPanda uses the primary property to construct the titles and the secondary property to construct the subtitles of incidents.

{
  "status": "warning",
  "host": "production-database-1",
  "timestamp": 1402303570,
  "application": "Billing",
  "description": "CPU is above warning limit (40%)",
  "primary_property": "application",
  "secondary_property": "host"
}
 
curl -X POST -H "Content-Type: application/json" \
    -H "Authorization: Bearer <YOUR TOKEN>" \
    https://api.bigpanda.io/data/v2/alerts \
    -d '{ "app_key": "<YOUR APP KEY>", "status": "critical", "host": "production-database-1", "check": "CPU overloaded" }'
cls
$url = "https://api.bigpanda.io/data/v2/alerts"
$headers = @{"Authorization" = "Bearer <YOUR TOKEN>"}
$body = @{
app_key = <YOUR APP KEY>
status = "critical"
host = hostname
check = "CPU_HIGH"
}
$json = $body | ConvertTo-Json
$appResult = Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $json -ContentType 'application/json'
$appResult
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "app_key": "123",
  "status": "critical",
  "host": "production-database-1",
  "timestamp": 1402302570,
  "check": "CPU overloaded",
  "description": "CPU is above upper limit (70%)",
  "cluster": "production-databases",
  "my_unique_attribute": "my_unique_value"
}
 

How it Works

Use the Incidents API to retrieve incident data or update an existing incident.

 

The Incidents API allows you to build integrated functionality between an external ticketing or collaboration system and BigPanda. It provides the Incidents object, which represents a BigPanda incident containing correlated alerts from your integrated monitoring systems.

Use the Incidents API to retrieve, snooze, or resolve an incident in BigPanda.

Available Objects & Actions

The Incidents API provides these objects.

Object
Description
Supported Methods
API Endpoint

Alerts Object

Represents an alert that is contained in a BigPanda incident.

GET

https://api.bigpanda.io/resources/v1.0/incidents/{incident ID}/alerts/

Incidents Object

Represents an incident in BigPanda.

POST, GET

https://api.bigpanda.io/resources/v1.0/incidents

Use the Incidents API to perform these actions.

Action
Definition
Description

Resolve Incident

POST /incidents/{id}

Resolves a BigPanda incident by closing all related alerts in BigPanda.

Retrieve Incident

GET /incidents/{id}

Retrieves the requested BigPanda incident.

 

Incidents Objects

Defines the schema for an incident in BigPanda.

 

API Endpoint

https://api.bigpanda.io/resources/v1.0/incidents

Supported Methods

POST, GET

Parameters

The Incidents object schema includes the following attributes.

id

System-generated unique identifier for the incident.

"id": "1234a53b6789c12d3efg45h"

status

Current incident status, which is determined by the most severe status of the correlated alerts. One of [critical, warning, unknown, ok].

"status" : "critical"

active

Whether the incident contains at least one active alert and has not been manually resolved. An incident is automatically resolved when all the alerts are resolved.

"active": true

flapping

Whether at least one correlated alert has changed states frequently enough to be treated as flapping.

"flapping": false

resolved

Whether the incident is currently resolved (true) or active (false).

"resolved": false

snooze

Snooze options for the incident.

Attribute Description
snoozed Whether the incident is currently snoozed.
wake Time when the current snooze period expires, in Unix epochs.
autoCancel Whether the current snooze is automatically cancelled if a new alert is added, the severity of an existing alert increases, or the incident is resolved and then reopens.

"snooze" : {"snoozed" : false, "wake" : null, "autoCancel" : false}

startedOn

Time when the earliest correlated alert was received, in Unix epochs.

"startedOn": 1466416853

changedOn

Time of last change to incident that triggered applicable sharing updates, in Unix epochs.

"changedOn": 1466417169

updatedOn

Time of last change to incident, in Unix epochs.

"updatedOn": 1466417169

endedOn

Time when the incident was resolved, either manually or automatically when all alerts were resolved, in Unix epochs.

"endedOn": null

alerts

Array of the alerts that the incident contains.

Attribute Description
alertID System-generated unique identifier for the alert.

"alerts" : [ { "alertId": "57da76d24cdb1f3a54ce25a0", "alertId": "68eb89e35dca2g4b65df36b1", "alertId": "79fc79f46egh3h5c78rg78d2" } ]

 

Alert Object

Defines the schema for an alert that is contained in a BigPanda incident.

 

API Endpoint

https://api.bigpanda.io/resources/v1.0/incidents/{incident ID}/alerts/

Supported Methods

GET

Parameters

The Alerts object schema includes the following attributes.

Attribute
Description
Example

id

System-generated unique identifier for the alert.

"id": "57da76d24cdb1f3a54ce25a0"

status

Current state of the alert. One of [critical, warning, unknown, ok].

"status" : "critical"

active

Whether the alert has not been resolved.

"active": true

startedOn

Time when the alert was first received, in Unix epochs.

"startedOn": 146641685

changedOn

Time of last change to the alert status, in Unix epochs.

"changedOn": 1466417169

updatedOn

Time of last change to alert, in Unix epochs.

"updatedOn": 1466417169

endedOn

Time when the alert status was set to ok, in Unix epochs.

"endedOn": null

primary_property

Main object that cause the alert. See Primary property.

"primary_property": "host"

secondary_property

Secondary object or sub-item that caused the alert.

"secondary_property": "check"

source_system

Integrated monitoring system that sent the alert to BigPanda, in the following format: <source type>.<integration name>.

"source_system": "nagios.nagios_east"

description

Brief summary of the alert, for certain monitoring tools.

"description": "CRITICAL - Host Unreachable"

tags

Array of name-value pairs that represent alert properties.

Attribute Description
name Tag name in BigPanda.
value Tag value in BigPanda.

"tags":[ {"name":"host","value":"production-database-1"}, {"name":"check","value":"CPU load"} ]

 

Retrieve an Incident

Retrieves the requested BigPanda incident.

 
gethttps://api.bigpanda.io/resources/v1.0/incidents/id

Path Params

id
string
required

System-generated unique identifier for the incident.

Query Params

expand
string

Option to return the full representation of an expandable object.

 
curl -X GET https://api.bigpanda.io/resources/v1.0/incidents/1234a53b6789c12d3efg45h \
    -H "Authorization: Bearer ${token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
curl -X GET https://api.bigpanda.io/resources/v1.0/incidents/1234a53b6789c12d3efg45h?expand=alerts \
    -H "Authorization: Bearer ${token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.x 200 OK
{
  "id": "1234a53b6789c12d3efg45h",
  "status": "critical",
  "active": true,
  "flapping": false,
  "resolved": false,
  "snooze": {
    "snoozed": false,
    "wake": null,
    "autoCancel": false
  },
  "startedOn": "1466416853",
  "changedOn": "1466417169",
  "updatedOn": "1466417169",
  "endedOn": null,
  "alerts": [
    {
      "alertId": "57da76d24cdb1f3a54ce25a0",
      "alertId": "68eb89e35dca2g4b65df36b1",
      "alertId": "79fc79f46egh3h5c78rg78d2"
    }
  ],
  "links": {
    "rel": "self",
    "href": "https://api.bigpanda.io/resources/v1.0/incidents/1234a53b6789c12d3efg45h"
  },
  "expandable": [
       "alerts"
  ]
}
HTTP/1.x 200 OK
{
  "id": "1234a53b6789c12d3efg45h",
  "status": "critical",
  "active": true,
  "flapping": false,
  "resolved": false,
  "snooze": {
    "snoozed": false,
    "wake": null,
    "autoCancel": false
  },
  "startedOn": "1466416853",
  "changedOn": "1466417169",
  "updatedOn": "1466417169",
  "endedOn": null,
  "alerts": [
    {
         "id": "57da76d24cdb1f3a54ce25a0",
         "status": "critical",
         "active": true,
         "startedOn": "1466416853",
         "changedOn": "1466417169",
         "updatedOn": "1466417169",
         "endedOn": null,
         "tags":[{"object":"host","value":"production-database-1"}, {"object":"check","value":"CPU load"} ]
    },
    {
         "id": "68eb89e35dca2g4b65df36b1",
         "status": "warning",
         "active": true,
         "startedOn": "1466417169",
         "changedOn": "1466417169",
         "updatedOn": "1466417169",
         "endedOn": null,
         "tags":[{"object":"host","value":"production-database-1"}, {"object":"check","value":"Low memory"} ]
    },
    {
         "id": "79fc79f46egh3h5c78rg78d2",
         "status": "ok",
         "active": false,
         "startedOn": "1466416853",
         "changedOn": "1466417169",
         "updatedOn": "1466417169",
         "endedOn": "1466417169",
         "tags":[{"object":"host","value":"production-database-1"}, {"object":"check","value":"Slow queries"} ]
    }
  ],
  "expandable": [
       "alerts"
  ],
  "links": {
    "rel": "self",
    "href": "https://api.bigpanda.io/resources/v1.0/incidents/1234a53b6789c12d3efg45h"
  }
}
 

Resolve Incident

Resolves the requested BigPanda incident.

 
posthttps://api.bigpanda.io/resources/v1.0/incidents/id

Path Params

id
string
required

System-generated unique identifier for the incident.

Body Params

resolved
boolean

To resolve the incident, set the value to true.

comments
string

(Optional) Annotation providing additional information about the incident resolution; appears in the activity feed for the incident.

Closing an alert in BigPanda does not close the alert in the source system.

Recommended best practice

Before sending a request to resolve an incident, use Retrieve Incident to check whether it is already resolved. If you attempt to resolve an incident that is already resolved, the API will return an error code notifying you of the conflict.

curl -iv -X POST \
    -H "Authorization: Bearer ${token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ "resolved": true, "comments": "ServiceNow ticket was resolved" }' \
    "https://api.bigpanda.io/resources/v1.0/incidents/1e8495ed5fow65ieof018f8"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.x 204 No Content
HTTP/1.x 409 Conflict
 

Comment Incident

Resolves the requested BigPanda incident.

 
posthttps://api.bigpanda.io/resources/v1.0/incidents/id

Path Params

id
string
required

System-generated unique identifier for the incident.

Body Params

comments
string

Comment to be added to the incident.

 
curl -iv -X POST \
    -H "Authorization: Bearer ${token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ "comments": "ServiceNow ticket was resolved" }' \
    "https://api.bigpanda.io/resources/v1.0/incidents/1e8495ed5fow65ieof018f8"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.x 204 No Content
HTTP/1.x 409 Conflict
 

How it Works

Enrichment is the process of adding contextual information to alerts in BigPanda. Use the Enrichments API to define custom tags that help users understand incidents more quickly and enrich BigPanda functionality, including correlation patterns and maintenance plans.

 

The Enrichments API allows you to programmatically create custom tags that add contextual information to alerts. It supports the mapping enrichment technique, which creates custom tags by looking up values in a data mapping table.

You define an enrichment schema by using these API resources:

  • Enrichments object, which defines the enrichment technique and configuration details associated with that technique. For example, in a mapping enrichment, the configuration details include a description of the data mapping table.
  • Sub-objects that are specific to the enrichment technique. For a mapping enrichment, the Map endpoint allows you to upload and maintain a data mapping table.

The API works by evaluating all incoming alerts to see if they match an active enrichment definition. Matching alerts are enriched with custom tags according to the instructions in the enrichment definition.

Use Cases

You can use the Enrichment API to develop a common language between monitoring systems and to identify upstream and downstream dependencies between configuration items.

Cross-Source Relationships

Define common tags to identify when alerts from different monitoring sources are related to the same monitored object in your infrastructure. For example, you can define a mapping enrichment for cluster based on the Pingdom service. Then, define an extraction enrichment for cluster based on the Nagios host name. Now, a cross-source correlation pattern on the cluster tag can group related alerts from either system into the same incident.

Topology Metadata

Understand the physical and logical relationships between alerting objects and the rest of your infrastructure. For example, you can leverage a CMDB to identify when different objects have the same parent object (such as multiple hosts in the same cluster). Then, define correlation patterns for objects with the same parent, Environments that reflect your infrastructure, and/or maintenance plans that suppress alerts for objects downstream of an object under maintenance.

Operational Metadata

Help IT Operations teams categorize, prioritize, route, and remediate an incident. For example, you can leverage a team spreadsheet to add assignments, categories, and priorities to alerts. Then, define Environments, dashboards, and Analytics reports to ensure the right teams have visibility into issues and/or define AutoShare rules to automatically trigger escalation processes.

Available Objects & Actions

Object
Description
Supported Methods
API Endpoint

Enrichments Object

Defines the schema for an enrichment.

POST, GET, PATCH

https://api.bigpanda.io/resources/v1.0/enrichments

Use the Enrichments API to perform these actions.

Action
Definition
Description

Create Enrichment

POST /enrichments

Creates a new definition for an enrichment schema.

Update Enrichment

POST /enrichments/{id}

Activates or deactivates a specific enrichment definition.

Create Mapping Enrichment Table

POST /enrichments/{id}/map

Uploads a new data mapping table that follows a specific enrichment schema.

Update Mapping Enrichment Table Rows

PATCH /enrichments/{id}/map

Updates specific rows of an existing mapping enrichment table.

List All Enrichments

GET /enrichments

Lists all enrichment definitions that exist for an organization.

Retrieve Enrichment

GET /enrichments/{id}

Retrieves a specific definition for an enrichment schema.

Check Status of Upload Job

GET /enrichments-jobs/{job_id}

Checks the status of an asynchronous job to upload or update a mapping enrichment table.

 

Quick Start

You can add contextual information to incoming alerts by using the mapping enrichment technique, which creates custom tags by looking up values in a data mapping table. To define a mapping enrichment with the Enrichments API, you must first define the structure of your mapping table. Then, upload the current mapping data. Finally, maintain the mapping data as your team and infrastructure changes. This guide demonstrates how to add operational metadata for a hypothetical IT Operations team.

 

The mapping enrichment technique creates custom tags by looking up values in a data mapping table. You define a mapping enrichment with the Enrichments API by using these resources:

Mapping Enrichment Overview

  • Enrichments object—defines the schema for your data mapping table. The schema determines how the information in each column of the table will be used in the enrichment process—as a query field, to match a value in the incoming alert, or as a result field, to enrich the alert.

  • Map endpoint—allows you to upload and maintain a data mapping table that follows a given Enrichments schema.

The API works by evaluating all incoming alerts to see if they match an active mapping enrichment. When an alert matches the values in the query fields, it is enriched with the values in the result fields.

Prerequisites

  • Obtain the BigPanda token for your organization.
    Administrators can find the token by clicking the Integrations tab, and then opening the instructions for the Alerts API

  • Obtain the mapping data that you want to leverage (such as a CMDB, registry, or team spreadsheet).

  • (Recommended) Review the overview of enrichment.

Step 1: Define The Mapping Structure

For a mapping enrichment, the Enrichments object defines how the information in each column of the table will be used in the enrichment process:

Query field—to match a value in the incoming alert.

Result field—to enrich the alert.

For example, suppose that certain applications have an owner on the operations team and a standard runbook for remediating common problems. You would create an enrichment schema that maps the application names (query field) to their owners and runbook URLs (result fields).

To define the mapping structure for a new enrichment:

  1. Send a POST request to /enrichments.

    • Specify the type as mapping.

  2. For each column in your data table, specify the name and whether to use the values as a query_tag or a result_tag.

  3. For more information, see Create Enrichment.

  4. The request creates a new Enrichments object for this mapping enrichment schema.

This mapping schema is defined for a hypothetical sample environment. You can adapt the values as necessary to meet your infrastructure conventions and the needs of your teams.
Be sure to replace ${token} with the corresponding value for your organization.

  1. Copy the id value from the response body. You will use it to identify this schema when you upload and update the mapping data.

Step 2: Upload The Mapping Data

After you create an Enrichments object that defines its structure, you can upload the table of the mapping data. For example, suppose that the Billing and Sales applications both have owners and remediation procedures. You can upload a table with three rows—one row for the column names and one row for each application.

To upload the mapping data for an enrichment:

  1. Send a POST request to /enrichments/${id}/map.

  2. Send the mapping data as comma-separated values (CSV) in the body of the request or in a CSV file.

  3. Ensure the data follows the structure you defined in Step 1 and has the same column names.

  4. For more information, see Create Mapping Enrichment Table.

  5. The request initiates an asynchronous job to upload the table and creates a Job object to track its progress.

Replace ${id} with the value you copied from the response body in Step 1 and ${token} with the corresponding value for your organization.

The payload must end with an empty new line. Make sure there are no spaces before the closing quotation marks on the last line.

  1. Copy the trigger_uri value from the response body.
    You will use it to check the status of the upload.

  2. Send a GET request to the ${trigger_uri} to verify that the upload has completed successfully.
    For more information, see Check Status of Upload Job.

Replace ${trigger_uri} with the value you copied from the response body and ${token} with the corresponding value for your organization.

  1. (Recommended) Send test alerts to ensure that the mapping enrichment works as expected.
    For example, you can run the following command to send matching test alerts via the Alert API. For more information, see POST alerts.

Replace ${token} and ${app_key} with the corresponding values for your organization.

  1. Resolve any test alerts, as necessary.

Step 3. Maintain the Mapping Data

As your team and infrastructure changes, you may need to update the values for your mapping enrichment. For example, suppose the Accounts application has just come online, the Payroll application has a new owner, and the Sales application is no longer being used. Depending on what changes you want to make, you can either completely replace the existing table, change only specific rows in the table, or create a new enrichment to change the structure.

To completely replace the existing table but keep the same structure, repeat Step 2. Upload the Mapping Data, above.

To change only specific rows in the existing table:

  1. Send a PATCH request to/enrichments/${id}/map.

    • For each row, specify the operation to perform (create, update, delete, upsert) and the data required to perform the operation.

    • For more information, see Update Mapping Enrichment Table Rows.

    • The request initiates an asynchronous job to upload the table and creates a Job object to track its progress.

Replace ${id} with the value you copied from the response body in Step 1 and ${token} with the corresponding value for your organization.

  1. Copy the trigger_uri value from the response body.
    You will use it to check the status of the update.

  2. Send a GET request to the ${trigger_uri} to verify that the update has completed successfully.
    For more information, see Check Status of Upload Job.

Replace ${trigger_uri} with the value you copied from the response body and ${token} with the corresponding value for your organization.

  1. (Recommended) Send test alerts to ensure that the mapping enrichment works as expected.

  2. Resolve any test alerts, as necessary.

To change the structure of your mapping data:

  1. Deactivate the existing enrichment by sending a POST request to /enrichments/${id}.
    Set active to false.
    For more information, see Update Enrichment.

Replace ${id} with the value you copied from the response body in Step 1 and ${token} with the corresponding value for your organization.

  1. Create a new mapping enrichment, starting from Step 1: Define The Mapping Structure, above.

Post-Requisites

  • Continue to maintain the mapping data as team assignments change.

  • (Optional) Define Environments based on the custom tags.

  • (Optional) Define additional mapping enrichments.

 

Enrichment Objects

Defines the schema for an enrichment.

 

API Endpoint

https://api.bigpanda.io/resources/v1.0/enrichments

Supported Methods

POST, GET, PATCH

Parameters

The Enrichments object includes the following attributes.

Attribute
Description
Example

active

Whether the enrichment is applied to all incoming alert data.

"active": true

id

System-generated unique identifier for the enrichment.

"id": "1234a53b6789c12d3efg45h"

version

Internal version number of the current data mapping table for this enrichment. This number is incremented automatically each time the table is updated.

"version": 1

type

Enrichment technique used to create custom tags (mapping).

"type": "mapping"

config

Configuration details associated with the enrichment technique. For a mapping enrichment, this attribute contains a description of the data mapping table.

Attribute Description
map_name (Optional) Unique name that identifies the mapping schema.
fields Array of metadata that describes the mapping schema and enrichment instructions. See Map Configuration Fields.

Map Configuration Fields

The following attributes describe how to enrich alerts based on a given data mapping table.

Attribute
Description
Example

title

Column name in the data mapping table.

"title": "Alert owner"

type

How data in the column is used in the enrichment process:
query_tag—to match a value in the alert.
result_tag—to enrich a matching alert.
To ensure the enrichment instructions are unambiguous, the schema must not contain duplicate columns of the same type (for example, two result_tag columns for the cluster tag).

"type": "result_tag"

tag_name

(Optional) Override the column name with a different tag name in BigPanda.

`"tag_name": "check"

override_existing

(Optional) Whether to override an existing tag with this value, if applicable.

"override_existing": false

`

 

Create Enrichment

Creates a new definition for an enrichment schema.

 
posthttps://api.bigpanda.io/resources/v1.0/enrichments

Body Params

type
string

Enrichment technique used to create custom tags (mapping).

config
array of strings

Configuration details associated with the enrichment technique. See Enrichments Object.

active
boolean

(Optional) Whether the enrichment is applied to all incoming alert data. Default value is true.

Headers

location
string

URL to retrieve the enrichment via the API, which includes the unique system id.

Returns

Possible response codes include:

  • 201 Created—new schema definition was created successfully.
  • 400 Bad Request—schema definition was not created because the request was missing parameters or not properly formatted. The response body includes additional error information for debugging.
curl -i -X POST https://api.bigpanda.io/resources/v1.0/enrichments \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json; charset=utf8" \
    -d '{
            "type": "mapping",
            "config" : {
                "map_name": "operations team spreadsheet",
                "fields": [
                    {
                        "title": "application",
                        "type": "query_tag"
                    },
                    {
                        "title": "owner",
                        "type": "result_tag",
                        "override_existing": false
                    },
                    {
                        "title": "Runbook URL",
                        "type": "result_tag",
                        "tag_name": "wiki",
                        "override_existing": false
                    }
                ]
            }
       }'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 201 Created
Header:
    location: "https://api.bigpanda.io/resources/v1.0/enrichments/8ded2313-0ebd-42e5-a36c-120420674863"
Body:
    {
        "id": "8ded2313-0ebd-42e5-a36c-120420674863",
        "type": "mapping",
        "active": true,
        "version": 0,
        "config": {
            "map_name": "operations team spreadsheet",
            "fields": [
                   {
                        "title": "application",
                        "type": "query_tag",
                        "tag_name" : "application",
                        "override_existing" : true
                    },
                    {
                        "title": "owner",
                        "type": "result_tag",
                        "tag_name" : "owner",
                        "override_existing": false
                    },
                    {
                        "title": "runbook url",
                        "type": "result_tag",
                        "tag_name": "wiki",
                        "override_existing": false
                    }
                ]
            }
    }
 

Retrieve Enrichment

Retrieves a specific definition for an enrichment schema.

 
gethttps://api.bigpanda.io/resources/v1.0/enrichments/id

Path Params

id
string
required

System-generated unique identifier for the enrichment.

Returns

Enrichments object for the specified enrichment, if a valid identifier was provided. Possible response codes include:

  • 200 OK
  • 404 Not Found—the specified enrichment id does not exist or the request URL is incorrect. You can list all enrichments to find the correct enrichment id.
curl -i -X GET https://api.bigpanda.io/resources/v1.0/enrichments/8ded2313-0ebd-42e5-a36c-120420674863 \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json; charset=utf8"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
{
    "id": "8ded2313-0ebd-42e5-a36c-120420674863",
    "type": "mapping",
    "active": true,
    "version": 0,
    "config": {
        "map_name": "operations team spreadsheet",
        "fields": [
               {
                    "title": "application",
                    "type": "query_tag",
                    "tag_name": "application",
                    "override_existing": true
                },
                {
                    "title": "owner",
                    "type": "result_tag",
                    "tag_name": "owner",
                    "override_existing": false
                },
                {
                    "title": "runbook url",
                    "type": "result_tag",
                    "tag_name": "wiki",
                    "override_existing": false
                }
            ]
        }
}
 

Update Enrichment

Activates or deactivates a specific enrichment definition.

 
posthttps://api.bigpanda.io/resources/v1.0/enrichments/id

Path Params

id
string
required

System-generated unique identifier for the enrichment.

Body Params

active
boolean

Whether the enrichment is applied to all incoming alert data.

Usage

The Enrichments API supports updating only the active attribute of an existing enrichment. If the structure of your mapping enrichment tables changes and you need to update the schema definition, you must deactivate the existing enrichment and create a new enrichment for the updated schema definition.

Returns

Response code indicating whether the enrichment was updated successfully. Possible response codes include:

  • 200 OK—the enrichment was updated successfully.
  • 400 Bad Request—the enrichment was not updated because the request was not properly formatted. The response body includes additional error information for debugging.
curl -i -X POST https://api.bigpanda.io/resources/v1.0/enrichments/8ded2313-0ebd-42e5-a36c-120420674863 \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json; charset=utf8" \
    -d '{
            "active": false
       }'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
{
    "id": "8ded2313-0ebd-42e5-a36c-120420674863",
    "type": "mapping",
    "active": false,
    "version": 0,
    "config": {
        "map_name": "operations team spreadsheet",
        "fields": [
               {
                    "title": "application",
                    "type": "query_tag",
                    "tag_name": "application",
                    "override_existing": true
                },
                {
                    "title": "owner",
                    "type": "result_tag",
                    "tag_name": "owner",
                    "override_existing": false
                },
                {
                    "title": "runbook url",
                    "type": "result_tag",
                    "tag_name": "wiki",
                    "override_existing": false
                }
            ]
        }
}
 

Delete Enrichment

Retrieves a specific definition for an enrichment schema.

 
deletehttps://api.bigpanda.io/resources/v1.0/enrichments/id

Path Params

id
string
required

System-generated unique identifier for the enrichment.

Returns

Status of deletion with a job_id of the asynchronous task.

  • 200 OK
curl -i -X DELETE https://api.bigpanda.io/resources/v1.0/enrichments/8ded2313-0ebd-42e5-a36c-120420674863 \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json; charset=utf8"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
{
    "status": "pending",
    "job_id": "58ab0c51cdacda29b7bf58e6_1494492216_indexcsv",
    "trigger_uri": "/enrichments/58ab0c51cdacda29b7bf58e6/map/    58ab0c51cdacda29b7bf58e6_1494492216_indexcsv"
}
 

List All Enrichments

Lists all enrichment definitions that exist for an organization.

 
gethttps://api.bigpanda.io/resources/v1.0/enrichments

Query Params

type
string

(Optional) Enrichment technique used to create custom tags (mapping).

Returns

Array of Enrichments objects for the organization. Possible response codes include:

  • 200 OK—returns the array of all matching enrichments.
  • 204 No Content—no enrichments match the request.
  • 400 Bad Request—the request was not properly formatted. The response body includes additional error information for debugging.
curl -i -X GET https://api.bigpanda.io/resources/v1.0/enrichments?type=mapping \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json; charset=utf8"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
[
    {
        "id": "8ded2313-0ebd-42e5-a36c-120420674863",
        "type": "mapping",
        "active": true,
        "version": 0,
        "config": {
            "map_name": "operations team spreadsheet",
            "fields": [
               {
                    "title": "application",
                    "type": "query_tag",
                    "tag_name": "application",
                    "override_existing": true
                },
                {
                    "title": "owner",
                    "type": "result_tag",
                    "tag_name": "owner",
                    "override_existing": false
                },
                {
                    "title": "runbook url",
                    "type": "result_tag",
                    "tag_name": "wiki",
                    "override_existing": false
                }
            ]
        }
    },
    {
        "id": "9bgi2584-9hft-59d7-w90c-955920635878",
        "type": "mapping",
        "active": true,
        "version": 2,
        "config": {
            "map_name": "CMDB",
            "fields": [
               {
                    "title": "host",
                    "type": "query_tag",
                    "tag_name": "host",
                    "override_existing": true
                },
                {
                    "title": "cluster",
                    "type": "result_tag",
                    "tag_name": "cluster",
                    "override_existing": false
                },
                {
                    "title": "tower",
                    "type": "result_tag",
                    "tag_name": "tower",
                    "override_existing": true
                },
                {
                    "title": "service",
                    "type": "result_tag",
                    "tag_name": "service",
                    "override_existing": true
                },
                {
                    "title": "runs on",
                    "type": "result_tag",
                    "tag_name": "downstream_cis",
                    "override_existing": true
                }
            ]
        }
    }
]
 

Create Mapping Enrichment Table

Uploads a new data mapping table that follows a specific enrichment schema.

 
posthttps://api.bigpanda.io/resources/v1.0/enrichments/id/map

Path Params

id
string
required

System-generated unique identifier for the enrichment schema definition.

data
string
required

Data mapping table that follows the enrichment schema. The request must include a header that specifies the Content-Type of the table (text/csv).

Usage

Use this action to create a new table for a mapping enrichment or to completely replace the existing table. Send the entire table as comma-separated values (CSV) in the body of the request or in a CSV file. The data table must meet these requirements:

  • The structure matches the mapping schema definition. For example, the column names must match the titles in the schema definition. Similarly, the table must include all of the columns in the definition.
  • The table contains at least two rows—the title row and at least one row of enrichment values.
  • Each row is unique; the table must not contain duplicate rows.
  • The field values do not exceed 32K in length.

Because it is a potentially long-running action, the table upload is performed asynchronously. Therefore, the immediate response indicates only whether the request was properly formatted and, if it was, provides a URL for checking the status of the upload. The entire table upload must complete successfully for the changes to take effect; the API does not support partial success.

A typical asynchronous upload negotiation consists of these steps:

  1. Upload the table.
    A Job object is created and a URL for checking the status is returned.
  2. Use the URL to periodically check the job status until it is set to done or failed.
  3. If the job was not successful, you can retry the request.
    If necessary, debug any connectivity issues or data formatting issues that may have contributed to the failed upload. For example, ensure the CSV file follows the enrichment schema definition.

Table as CSV in Request Body

The payload must end with an empty new line. Make sure there are no spaces before the closing quotation marks on the last line.

Table in Separate CSV File

The CSV file must use standard line feed characters for line endings and must end with an empty new line. Some programs use different line ending formats. If you receive the following error, you may need to convert the line endings or add an empty new line to your file.

Stream finished but there was a truncated final frame in the buffer

Returns

If the request is valid, the Job object for the table upload and the following header:

Item
Description

location

URL to check the status of the upload via the API, which includes the unique system id for the upload job.

Possible response codes include:

  • 202 Accepted—the table upload is in progress.
  • 400 Bad Request—the request was not properly formatted. The response body includes additional error information for debugging.
curl -i -X POST https://api.bigpanda.io/resources/v1.0/enrichments/8ded2313-0ebd-42e5-a36c-120420674863/map \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: text/csv; charset=utf8" \
    -d "application,owner,Runbook URL
        billing,Adina Terry,https://acme-wiki.com/billing+SOP
        sales,Madison Dor,https://acme-wiki.com/salesapp+SOP
"
curl -i -X POST https://api.bigpanda.io/resources/v1.0/enrichments/8ded2313-0ebd-42e5-a36c-120420674863/map \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: text/csv; charset=utf8" \
    -d @operationsTeamSpreadsheet.csv
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 202 Accepted
Header:
    location: "https://api.bigpanda.io/resources/v1.0/enrichments/8ded2313-0ebd-42e5-a36c-120420674863/map/8ded2313-0ebd-42e5-a36c-120420674863_1494492216_indexcsv"
Body:
    {
        "status": "pending",
        "job_id": "8ded2313-0ebd-42e5-a36c-120420674863_1494492216_indexcsv",
        "trigger_uri": "/enrichments/8ded2313-0ebd-42e5-a36c-120420674863/map/8ded2313-0ebd-42e5-a36c-120420674863_1494492216_indexcsv"
    }
 

Update Mapping Enrichment Table Rows

Updates specific rows of an existing mapping enrichment table.

 
patchhttps://api.bigpanda.io/resources/v1.0/enrichments/id/map

Path Params

id
string
required

System-generated unique identifier for the enrichment schema definition.

data
array of strings
required

Array of operations to perform on the table in this transaction.

Headers

location
string

URL to check the status of the update via the API, which includes the unique system id for the update job.

Usage

Use this action to update specific rows in an existing mapping enrichment table. To completely replace the existing table, see Create Mapping Enrichment Table. For each row, send the operation to perform and the values required to perform the operation. You can send up to 100 operations per request. The API supports these operations:

  • create—adds a new row in the table. Requires values for every column in the row. If the row already exists, this operation will fail.
  • update—updates an existing row in the table. Requires values for every column in the row.
  • delete—removes an existing row from the table. Requires values for the query fields only. If the row does not exist, this operation will succeed but the version count will not be incremented.
  • upsert—adds a new row, if the row doesn't exist, or updates the row, if it already exists. Requires values for every column in the row.

Because it is a potentially long-running action, the table update is performed asynchronously. Therefore, the immediate response indicates only whether the request was properly formatted and, if it was, provides a URL for checking the status of the upload. The entire table update must complete successfully for the changes to take effect; the API does not support partial success.

A typical asynchronous upload negotiation consists of these steps:

  1. Send the update request.
    A Job object is created and a URL for checking the status is returned.
  2. Use the URL to periodically check the job status until it is set to done or failed.
  3. If the job was not successful, you can retry the request.
    If necessary, debug any connectivity issues or data formatting issues that may have contributed to the failed upload. For example, ensure the CSV file follows the enrichment schema definition.

Returns

Possible response codes include:

  • 202 Accepted—the table update is in progress.
  • 400 Bad Request—the request was not properly formatted or the number of requested operations exceeds 100. The response body includes additional error information for debugging.
curl -i -X PATCH https://api.bigpanda.io/resources/v1.0/enrichments/8ded2313-0ebd-42e5-a36c-120420674863/map \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json; charset=utf8" \
    -d '[
           {
               "op": "create",
               "value": {
                   "application": "accounts",
                   "owner": "Merle Kayden",
                   "Runbook URL": "https://acme-wiki.com/accts+runbook"
               }
           },
           {
               "op": "upsert",
               "value": {
                   "application": "payroll",
                   "owner": "Jackie Celeste",
                   "Runbook URL": "https://acme-wiki.com/payroll+app+SOP"
               }
           },
           {
               "op": "delete",
               "value": {
                   "application": "sales"
               }
           }
    ]'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 202 Accepted
Header:
    location: "https://api.bigpanda.io/resources/v1.0/enrichments/8ded2313-0ebd-42e5-a36c-120420674863/map/58ab0c51cdacda29b7bf58e6_1494497755_update"
Body:
    {
        "status": "pending",
        "job_id": "58ab0c51cdacda29b7bf58e6_1494497755_update",
        "trigger_uri": "/enrichments/8ded2313-0ebd-42e5-a36c-120420674863/map/58ab0c51cdacda29b7bf58e6_1494497755_update"
    }
 

Retrieve Mapping Enrichment

Retrieves a specific mapping enrichment table with the ability to show results by page numbers.

 
gethttps://api.bigpanda.io/resources/v1.0/enrichments/id/map

Path Params

id
string
required

System-generated unique identifier for the enrichment schema definition.

Query Params

page
int32

The specific page number.

per_page
int32

Number of results to show for each page. Default is 100.

Usage

Use this action to retrieve a specific mapping enrichment table. This only applies to Mapping Enrichments and not for standard Enrichments.

The result yields a total_count field that represents the total number of mapping entries and the list of items in the table.

Optional pagination parameters may be included to refine the results further. If used, these parameters are to be formatted at the end of the link:

GET /enrichments/{ID}/map?page&per_page

Returns

Possible response codes include:

  • 200 OK—the table exists in the response.
  • 404 Not Found—the table was not found. Also occurs when a non-mapping enrichment is attempted for retrieval.
curl -X GET https://api.bigpanda.io/resources/v1.0/enrichments/123456/map 
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.x 200 OK
Headers:
    Link: <https://api.bigpanda.io/resources/v1.0/enrichments/123456/map?page=2&per_page=100>;
    rel="next", <https://api.bigpanda.io/resources/v1.0/enrichments/123456/map?page=5&per_page=100>; rel="last"
    <https://api.bigpanda.io/resources/v1.0/enrichments/123456/map?page=1&per_page=100>; rel="first"
Body:
    {
        "total_count": 473,
        "items": [
            {
                "host": "prod-api-1",
                "owner": "shai"
            },
            {
                "host": "prod-api-2",
                "owner": "shai"
            },
            ...
        ]
    }
 

Check Status of Upload Job

Checks the status of an asynchronous job to upload or update a mapping enrichment table.

 
gethttps://api.bigpanda.io/resources/v1.0/enrichments/-jobs/job_id

Path Params

id
string
required

System-generated unique identifier for the enrichment schema definition.

job_id
string
required

System-generated unique identifier for the asynchronous job.

Headers

status
string

Current status of the job, includes pending, started, done, and failed.

job_id
string

System-generated unique identifier for the asynchronous job.

trigger_uri
string

URI to check the status of the job.

start_time
string

Time the action was requested, in Unix epochs.

end_time
string

Time the job completed, in Unix epochs.

Usage

Jobs are objects that manage asynchronous tasks for potentially long-running actions, such as uploading or updating a mapping enrichment table. When these actions are performed, a new job is created, and the API returns the Job object and a location header with the URL for checking the status.

When performing actions that use jobs, follow these steps:

  1. Make a request (for example, upload a mapping enrichment table).
    The associated Job object is created and a URL for checking the status is returned.
  2. Use the URL to periodically check the job status until it is set to done or failed.
  3. If the job was not successful, you can retry the request.
    If necessary, debug any connectivity issues or data formatting issues that may have contributed to the failed upload. For example, ensure the CSV file follows the enrichment schema definition.

Returns

Possible response codes include:

  • 200 OK—the job is complete. The status attribute in the response body indicates whether the job was successful.
  • 202 Accepted—the job is in progress.
curl -i -X GET https://api.bigpanda.io/resources/v1.0/enrichment-jobs/8ded2313-0ebd-42e5-a36c-120420674863_1494492216_indexcsv \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json; charset=utf8"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
{
    "status": "done",
    "job_id": "8ded2313-0ebd-42e5-a36c-120420674863_1494492216_indexcsv",
    "start_time": 1494492216,
    "end_time": 1494492218,
}
 

How It Works

Maintenance Plans allow for the suppression of events. Use the Maintenance Plans API to define time windows that parallel infrastructure changes of respective monitored services.

 

Beta Feature

Please note that this feature is available through the Beta program only and is not released for general availability. If you would like to request access to the Beta program and use this feature, please contact support@bigpanda.io

The Maintenance Plan API supports two new resources to control the maintenance windows: plans (required) and schedules (optional).

Plans are configured with BPQL queries and, once activated, will filter/suppress events that matches the criteria. Origin tags supplied by a monitoring source and automatically generated enriched tags by the Enrichment API are also supported for querying. User created tags from the Custom Tags Editor are not supported.

Schedules define a start and stop time frame which can be applied to a Plan. Once a Schedule is deactivated, the Plan will cease to continue filtering. If a Plan does not have a Schedule defined, it will start immediately and run indefinitely - until an administrator manually deletes the plan or updates it to inactive.

Use Cases

You can use the Maintenance Plan API to keep in sync with infrastructure changes and parallel your monitoring activity accordingly. For example, the set of servers under a certain host, i.e. Billing, is scheduled to undergo upgrades for a duration of one week. Due to the non-operational nature of the servers during this time, all alerts generated by them will be unnecessary for monitoring.
Instead of having these alerts continue to stream into the feed and disrupt workflow, create a matching Plan with the query host = "billing*" and a Schedule of one week in the same time frame as the upgrades. This will suppress the irrelevant alerts from ever entering the feed.

Available Objects & Actions

Object
Description
Supported Methods
API Endpoint

Plans Objects

Defines the schema for configuring a plan and schedule.

POST, GET, PATCH, DELETE

https://api.bigpanda.io/resources/v1.0/plans

Use the Plans API to perform these actions.

Actions

Create Plan — Creates a new schema definition for creating a plan.

Create Schedule — Creates a new schema definition for creating a schedule.

Create Plan with Schedule and Custom Tags — Creates a new schema definition for creating a plan with schedule and custom tags.

Retrieve Plan — Retrieves a specific schema definition for a created plan.

Update Plans — Updates a specific plan to stop maintenance period immediately.

List All Plans — Lists all plan schema definitions that exist for an organization.

Delete Plan — Lists all plan schema definitions that exist for an organization.

 

Quick Start

You can suppress alerts that meet a defined query with the Plans API. A time window for when the suppression will start and end can be defined by the addition of a Schedule. This guide will walk through the steps to create a maintenance plan based on an example scenario.

 

Prerequisites

Step 1: Define The Schedule

As an example scenario, suppose that a company's servers and devices under its San Jose host are undergoing upgrades and will yield false alerts from procedural reboots and state changes. The associated monitoring tools will inevitably see these changes as alerts and stream them into BigPanda. To prevent the cluttering of workflow, you would create a plan to capture the relevant devices under the San Jose host and suppress their alerts and a schedule to capture the timeframe of the maintenance period.

Start by creating a schedule to define the specific start and end timeframe:

  1. Send a POST request to /schedules.

  2. The start and end parameters follow the Unix epoch format.

  3. For more information, see Create a Schedule 

curl -iX POST https://api.bigpanda.io/resources/v1.0/schedules \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(token)" \
  -d '{
    "name": "San Jose Host Maintenance Schedule",
    "starts_on": 1491265491,
    "ends_on": 1491294307,
    "active": true
  }'

Be sure to replace ${token} with the corresponding value for your organization.

  1. Copy the id value from the response body.
    You will use it as a parameter when creating a plan in the next step.

Step 2: Define The Plan With Schedule

Create a plan to isolate the suppression of alerts to only the devices affected during the maintenance period - the San Jose host. See the Plans Object page for more information on the Plan Objects

To define a new plan:

  1. Send a POST request to /plans.

    • Specify the name of the plan.

    • Specify the schedule to associate with the plan. The id value is copied from Step 1.

  2. Specify the bpql object to query. In this case, we want to filter "San Jose" hosts to capture the relevant devices.

    • Specify the active parameter to true to enable the plan.

    • For more information, see Create a Plan

curl -iX POST https://api.bigpanda.io/resources/v1.0/plans \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(token)" \
  -d '{
        "name": "San Jose Maintenance Plan",
        "schedule": "590b72b91f0000130063753c"
        "bpql": {"=": ["host", "prod-san-jose"]},
        "active": true
  }'

This mapping schema is defined for a hypothetical sample environment. You can adapt the values as necessary to meet your infrastructure conventions and the needs of your teams.

Like in Step 1, be sure to replace ${token} with the corresponding value for your organization.

  1. (Recommended) Send test alerts from the San Jose host and ensure that they are suppressed and the plan works as expected.

Post-Requisites

 

Plan Object

Defines the schema for configuring a plan and schedule.

 

API Endpoint

https://api.bigpanda.io/resources/v1.0/plans

Supported Methods

POST, GET, PATCH, DELETE

Parameters

The Plan object schema includes the following attributes.

Attribute
Description
Type
Example

id

System-generated unique identifier for a maintenance plan

String

"id" : "1234a53b6789c12d3efg45h"

name

User defined name for a plan

String

"name" : "Plan-SJC"

description

User defined summation of the maintenance plan

String

"description" : "Maintenance Plan for the SJC servers to be upgraded"

bpql

The BPQL object to query

JSON

"bpql" : "=" : "prod-sjc-5"

exclude_status

A list of alert status values that will be excluded from the maintenance plan. With new plans, the example value is applied by default unless exclude_status is explicitly declared in the payload.

Array of Strings

"exclude_status" : [ "Ok" ]

active

Indicates that the plan is active and will be processed on the start time

Boolean

"active" : "true"

created_on

Date and time the plan was created in ISO 8601 format

Long

"created_on" : 1493922189

created_by

The ID of the user who created the plan

String

"created_by" : "Administrator 1"

updated_on

Date and time the plan was last updated in ISO 8601 format

Long

"updated_on" : 1372854204

updated_by

The ID of the user who last updated the plan

String

"updated_by" : "Administrator 2"

schedule

The ID of the schedule associated to the plan

String

"schedule" : "590b68f31f00001d0063753b"

custom_tags

Metadata about the plan in an array of key-value pairs

Attribute Description Type
name Ordered pair tuple name. String
value Object value. String

Array of Objects

"custom_tags" : [ { "name" : "app", "value" : "esp"} ]

 

Create a Plan

Creates a new schema definition for creating a plan.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.bigpanda.io/resources/v1.0/plans

Body Params

name
string
required

User defined name for a plan

active
boolean
required

Indicates that the plan is active and will be processed on the start time

bpql
json
required

The BPQL object to query

custom_tags
array of objects

Metadata about the plan in an array of key-value pairs

name
value
schedule
string

The Schedule ID

exclude_status
array of strings

Alert statuses to exclude from suppression (values - "Ok", "Critical", "Warning", "Unknown")

description
string

A description of the plan

BPQL Object Syntax

When Creating a Plan, one of the body parameters to fill in is the bpql. As this is within BigPanda's API, the specific BPQL Object Syntax should be referenced.

Please do not confuse this with the UI centric string formatted BPQL.

Plan ID

Noting down the ID string in the output will be helpful if you want to manually stop the maintenance period. This can also be retrieved with a GET call at any time

Returns

Possible response codes include:

  • 201 Created—new schema definition was created successfully.
  • 400 Bad Request—schema definition was not created because the request was missing parameters or not properly formatted. The response body includes additional error information for debugging.
curl -iX POST https://api.bigpanda.io/resources/v1.0/plans \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(token)" \
  -d '{
        "name": "Folsom Patch",
        "bpql": {"=": ["host", "prod-api-1"]},
        "active": true,
        "description": "Patching Folsom server farm",
        "custom_tags" : [{ 
        	 "name": "server_farm", 
           "value": "folsom" 
          }]
  }'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 201 Created
Content-Type: application/json
Date: Thu, 04 May 2017 14:28:41 GMT
location: /plans/590b3a991f00002000637538
Server: nginx
Content-Length: 393
Connection: keep-alive
 
{
"id" : "590b3a991f00002000637538",
"name" : "Folsom Patch",                   
"active" : true,                         
"plan_type" : "normal",                  
"created_by" : "External System",
"created_on" : 1493908121,
"updated_by" : "External System",
"updated_on" : 1493908121,
"custom_tags" : [{ 
   "name": "server_farm", 
   "value": "folsom" 
}],
"bpql" : {
"=" : [ "host", "prod-api-1" ]
},
"description" : "Patching Folsom server farm",
"exclude_status" : [ "Ok" ],
"schedule" : null
}
 

Retrieve a Plan

Retrieves a specific schema definition for a created plan.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.bigpanda.io/resources/v1.0/plans/id

Path Params

id
string
required

System-generated unique identifier for the plan.

Returns

Plans object for the specified enrichment if a valid identifier was provided. Possible response codes include:

  • 200 OK
  • 404 Not Found—the specified enrichment id does not exist or the request URL is incorrect. You can list all plans to find the correct enrichment id.
curl -iX GET https://api.bigpanda.io/resources/v1.0/plans/590b3a991f00002000637538 \
  -H "Content-Type: application/merge-patch+json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(token)"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 04 May 2017 17:22:55 GMT
Server: nginx
Content-Length: 394
Connection: keep-alive
 
{
"id" : "590b3a991f00002000637538",
"name" : "Folsom Patch",
"active" : true,
"plan_type" : "normal",
"created_by" : "External System",
"created_on" : 1493908121,
"updated_by" : "External System",
"updated_on" : 1493918026,
"custom_tags" : [{
   "name": "server_farm", 
   "value": "folsom" 
  }],
"bpql" : {
"=" : [ "host", "prod-api-1" ]
},
"description" : null,
"exclude_status" : [ "Ok" ],
"schedule" : null
}
 

Retrieve All Plans

Lists all plan schema definitions that exist for an organization.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.bigpanda.io/resources/v1.0/plans

Query Params

active
boolean

Return active plans. Only active=true is supported at this time.

Usage

The Plans API supports retrieval of all active plans or all plans. The desired output is obtained by appending ?active=true to the GET definition. Omitting this will yield all plans, both active and inactive.

Returns

Plans object for the specified enrichment, if a valid identifier was provided. Possible response codes include:

  • 200 OK
  • 400 Bad Request—the request was not properly formatted. The response body includes additional error information for debugging.
curl -iX GET https://api.bigpanda.io/resources/v1.0/plans \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(token)"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 04 May 2017 17:09:10 GMT
Server: nginx
Content-Length: 397
Connection: keep-alive
 
[ {
"id" : "590b3a991f00002000637538",
"name" : "Folsom Patch",
"active" : true,
"plan_type" : "normal",
"created_by" : "External System",
"created_on" : 1493908121,
"updated_by" : "External System",
"updated_on" : 1493909097,
"custom_tags" : [ ],
"bpql" : {
"=" : [ "host", "prod-api-1" ]
},
"description" : null,
"exclude_status" : [ "Ok" ],
"schedule" : null
}, {
"id" : "590b40d71f00001300637539",
"name" : "EG Patch",
"active" : false,
"plan_type" : "normal",
"created_by" : "External System",
"created_on" : 1493909719,
"updated_by" : "External System",
"updated_on" : 1493914688,
"custom_tags" : [ ],
"bpql" : {
"=" : [ "host", "prod-api-2" ]
},
"description" : null,
"exclude_status" : [ "Ok" ],
"schedule" : null
}, {
"id" : "590b552f1f0000200063753a",
"name" : "EG Test",
"active" : false,
"plan_type" : "normal",
"created_by" : "External System",
"created_on" : 1493914927,
"updated_by" : "External System",
"updated_on" : 1493915073,
"custom_tags" : [ ],
"bpql" : {
"=" : [ "host", "prod-api-3" ]
},
"description" : null,
"exclude_status" : [ "Ok" ],
"schedule" : null
} ]
 

Update a Plan

Updates a specific maintenance plan

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://api.bigpanda.io/resources/v1.0/plans/id

Path Params

id
string
required

System-generated unique identifier for the plan.

Body Params

name
string

User defined name for a plan

active
string

Indicates that the plan is active and will be processed on the start time

bpql
json

The BPQL object to query

excluded_status
array of strings

Alert statuses to exclude from suppression (values - "Ok", "Critical", "Warning", "Unknown")

schedule
string

The Schedule ID

Returns

Response code indicating whether the plan was updated successfully. Possible response codes include:

  • 204 No Content—the plan was updated successfully.
  • 400 Bad Request—the plan was not updated because the request was not properly formatted. The response body includes additional error information for debugging.
  • 404 Not Found—the plan failed to update because the plan ID provided could not be found.
curl -iX PATCH https://api.bigpanda.io/resources/v1.0/plans/${id} \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer ${token}" \
  -d '{
        "active": false
    }'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 204 No Content
Date: Thu, 04 May 2017 17:13:04 GMT
location: /plans/590b3a991f00002000637538
Server: nginx
Connection: keep-alive
HTTP/1.x 404 Not Found
{
  "status" : "failure",
  "error" : "Could not find plan with id: 590b3a991f00002000637538"
}
 

Delete a Plan

Delete a specific plan and remove it from the system.

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.bigpanda.io/resources/v1.0/plans/id

Path Params

id
string
required

System-generated unique identifier for the plan.

Returns

Response code indicating whether the enrichment was updated successfully. Possible response codes include:

  • 204 No Content—the plan was deleted successfully.
  • 404 Not Found—the plan failed to delete because the plan ID provided could not be found.
curl -iX DELETE https://api.bigpanda.io/resources/v1.0/plans/${id} \                         
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer $(token)"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 204 No Content
Date: Thu, 04 May 2017 17:13:04 GMT
location: /plans/594908d45300001200a94f88
Server: nginx
Connection: keep-alive
HTTP/1.x 404 Not Found
{
  "status" : "failure",
  "error" : "Could not find plan with id: 594908d45300001200a94f88"
}
 

How it Works

Schedules are a secondary feature to the Plans API and allow for the defining of explicit start and stop times.

 

Beta Feature

Please note that this feature is available through the Beta program only and is not released for general availability. If you would like to request access to the Beta program and use this feature, please contact support@bigpanda.io

The required Plans resource of the Maintenance Plan API can be augmented with the optional Schedules resource. Defining Schedules will allow for control of when a Maintenance Plan should start and stop. Otherwise, a Maintenance Plan will run indefinitely unless manually deleted or set to inactive by an administrator.

Please see the Plans API for more holistic information around the Use Cases and Actions.

 

Schedule Object

Defines the schema for configuring a schedule.

 

API Endpoint

https://api.bigpanda.io/resources/v1.0/schedules

Supported Methods

POST, GET, PATCH

Parameters

The Schedules object schema includes the following attributes.

Attribute
Description
Type
Example

id

System-generated unique identifier for a schedule

String

"id": "590b68f31f00001d0063753b"

name

User defined name for a schedule

String

"name": "Weekend Maintenance for Plan-SJC"

description

User defined summation of the schedule

String

"description": "Scheduling the Maintenance window for the weekend."

starts_on

Date and time the schedule starts in Unix epoch

Long

"starts_on": 1493989407

ends_on

Date and time the schedule ends in Unix epoch

Long

"ends_on": 1495089407

duration

The calculated time between the ends_on and starts_on in seconds

Long

"duration": 100000

created_on

Date and time the schedule was created in Unix epoch

Long

"created_on": 1493922189

created_by

The ID of the user who created the schedule

String

"created_by": "Administrator 1"

updated_on

Date and time the plan was last updated in Unix epoch

Long

"updated_on": 1372854204

updated_by

The ID of the user who last updated the schedule

String

"updated_by": "Administrator 2"

active

Indicates if the schedule is active and will be processed on the start time

Boolean

"active": true

 

Create a Schedule

Creates a new schema definition for creating a schedule.

 
posthttps://api.bigpanda.io/resources/v1.0/schedules

Body Params

name
string

User defined name for a schedule.

starts_on
date

Date and time the schedule starts in Unix epochs.

ends_on
date

Date and time the schedule ends in Unix epochs.

active
boolean

Indicates if the schedule is active and will be processed on the start time.

Epoch Time

When setting the start and end times in Unix epochs, here is a helpful website with guidance on the formatting: https://www.epochconverter.com/#tools

Plan ID

Noting down the ID string in the output will be helpful if you want to create a plan with the schedule. This can also be retrieved with a GET call at any time.

Returns

A summarization detail with additional schedule objects, where applicable.

Possible response codes include:

  • 201 Created—new schema definition was created successfully.
  • 400 Bad Request—schema definition was not created because the request was missing parameters or not properly formatted. The response body includes additional error information for debugging.
curl -iX POST https://api.bigpanda.io/resources/v1.0/schedules \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(token)" \
  -d '{
    "name": "Weekend Maintenance",
    "starts_on": 1491265491,
    "ends_on": 1491294307,
    "active": true
  }'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 201 Created
Content-Type: application/json
Date: Thu, 04 May 2017 17:46:27 GMT
location: /schedules/590b68f31f00001d0063753b
Server: nginx
Content-Length: 349
Connection: keep-alive
 
{
"id" : "590b68f31f00001d0063753b",
"name" : "Weekend Maintenance",            
"active" : true,                          
"type" : "maintenance",                    
"created_by" : "External System",
"created_on" : 1493919987,
"updated_by" : "External System",
"updated_on" : 1493919987,
"starts_on" : 1493989407,
"ends_on" : 1494089407,
"description" : null,
"duration" : 100000
}
 

Retrieve a Schedule

Retrieves a specific schema definition for a created schedule.

 
gethttps://api.bigpanda.io/resources/v1.0/schedules/id

Path Params

id
string
required

System-generated unique identifier for the schedule.

Returns

Schedules object for the specified enrichment, if a valid identifier was provided. Possible response codes include:

  • 200 OK
  • 404 Not Found—the specified enrichment id does not exist or the request URL is incorrect. You can list all plans to find the correct enrichment id.
curl -iX GET https://api.bigpanda.io/resources/v1.0/schedules/${id} \
  -H "Content-Type: application/merge-patch+json; charset=utf-8" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(token)"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 04 May 2017 17:49:48 GMT
Server: nginx
Content-Length: 353
Connection: keep-alive
 
[ {
"id" : "590b68f31f00001d0063753b",
"name" : "Weekend Maintenance",
"active" : true,
"type" : "maintenance",
"created_by" : "External System",
"created_on" : 1493919987,
"updated_by" : "External System",
"updated_on" : 1493919987,
"starts_on" : 1493989407,
"ends_on" : 1494089407,
"description" : null,
"duration" : 100000
} ]
 

Retrieve All Schedules

Retrieves the schema definition for all schedules.

 
gethttps://api.bigpanda.io/resources/v1.0/schedules

Returns

Schedules object for the specified enrichment, if a valid identifier was provided. Possible response codes include:

  • 200 OK
  • 404 Not Found—the specified enrichment id does not exist or the request URL is incorrect. You can list all plans to find the correct enrichment id.
curl -iX GET https://api.bigpanda.io/resources/v1.0/schedules \
  -H "Authorization: Bearer $(token)"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 04 May 2017 17:49:48 GMT
Server: nginx
Content-Length: 353
Connection: keep-alive
 
[ {
"id" : "590b68f31f00001d0063753b",
"name" : "Weekend Maintenance",
"active" : true,
"type" : "maintenance",
"created_by" : "External System",
"created_on" : 1493919987,
"updated_by" : "External System",
"updated_on" : 1493919987,
"starts_on" : 1493989407,
"ends_on" : 1494089407,
"description" : null,
"duration" : 100000
} ]
 

Update a Schedule

Updates a specific maintenance schedule

 
patchhttps://api.bigpanda.io/resources/v1.0/schedules/id

Path Params

id
string
required

System-generated unique identifier for the plan.

Body Params

name
string

User defined name for a plan

active
string

Indicates that the plan is active and will be processed on the start time

starts_on
int64

Date and time the schedule starts in Unix epoch

ends_on
int64

Date and time the schedule ends in Unix epoch

description
string

User defined summation of the schedule

Returns

Response code indicating whether the plan was updated successfully. Possible response codes include:

  • 204 No Content—the plan was updated successfully.
  • 400 Bad Request—the plan was not updated because the request was not properly formatted. The response body includes additional error information for debugging.
  • 404 Not Found—the plan failed to update because the plan ID provided could not be found.
curl -iX PATCH https://api.bigpanda.io/resources/v1.0/schedules/${id} \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer ${token}" \
  -d '{
        "active": false
    }'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 204 No Content
Date: Thu, 04 May 2017 17:13:04 GMT
location: /schedules/590b72b91f0000130063753c
Server: nginx
Connection: keep-alive
HTTP/1.x 404 Not Found
{
  "status" : "failure",
  "error" : "Could not find plan with id: 590b3a991f00002000637538"
}
 

Delete a Schedule

Delete a specific schedule and remove it from the system.

 
deletehttps://api.bigpanda.io/resources/v1.0/schedules/id

Path Params

id
string
required

System-generated unique identifier for the schedule.

Returns

A summarization detail with additional schedule objects, where applicable.

Possible response codes include:

  • 204 No Content—the schedule was deleted successfully.
  • 404 Not Found—the schedule failed to delete because the schedule ID provided could not be found.
curl -XDELETE https://api.bigpanda.io/resources/v1.0/schedules/${id} \                     
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer $(token)"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 204 No Content
Date: Thu, 04 May 2017 17:13:04 GMT
location: /schedules/59c8c2fd520000120091d285
Server: nginx
Connection: keep-alive
HTTP/1.x 404 Not Found
{
  "status" : "failure",
  "error" : "Could not find schedule with id: 59c8c2fd520000120091d285"
}
 

Getting Started

This page will help you get started with Maintenance Plans V2.

 

This is where you show your users how to set it up. You can use code samples, like this:

$http.post('/someUrl', data).success(successCallback);

alert('test');

Try dragging a block from the right to see how easy it is to add more content!