Splunk On-Call Client
The splunk-oncall-client
library contains a simple and convenient HTTP client for making requests to
the Splunk On-Call (VictorOps) REST API.
Table of contents
Installation
Using NPM:
$ npm install splunk-oncall-client
Using Yarn:
$ yarn add splunk-oncall-client
Usage
Initialize the client
The library exports a SplunkOnCallClient
class. All you need to do is instantiate it, and you're ready to go.
You'll need an API ID and API key provided by the Splunk On-Call service. You can provide these values as apiId
and apiKey
options or set these values as environment variables using SPLUNK_ONCALL_API_ID
and SPLUNK_ONCALL_API_KEY
.
By default, the client will use the SPLUNK_ONCALL_API_ID
and SPLUNK_ONCALL_API_KEY
environment variables if apiId
and apiKey
are not provided in the options.
Example import methods:
const SplunkOnCallClient = require('splunk-oncall-client');
const client = new SplunkOnCallClient({
apiId: 'API-ID',
apiKey: 'API-KEY'
});
import SplunkOnCallClient from 'splunk-oncall-client';
const client = new SplunkOnCallClient({
apiId: 'API-ID',
apiKey: 'API-KEY'
});
It is required to set the API ID and API key parameters as either environment variables or as options when instantiating the client. These parameters are necessary to execute SplunkOnCallClient
calls. If these parameters are not provided or cannot be determined, then an error is thrown.
Using environment variables in an application:
const SplunkOnCallClient = require('splunk-oncall-client');
// Set the API ID and key as environment variables.
process.env.SPLUNK_ONCALL_API_ID = 'SOME-API-ID';
process.env.SPLUNK_ONCALL_API_KEY = 'SOME-API-KEY';
const client = new SplunkOnCallClient();
Setting environment variables before running an application:
Linux:
$ SPLUNK_ONCALL_API_ID=SOME-API-ID SPLUNK_ONCALL_API_KEY=SOME-API-KEY node app.js
Windows:
> cmd /C "set SPLUNK_ONCALL_API_ID=SOME-API-ID && set SPLUNK_ONCALL_API_KEY=SOME-API-KEY && node app.js"
Options
These are the available options for creating a SplunkOnCallClient
instance. If the apiId
and apiKey
options are not provided, then the SPLUNK_ONCALL_API_ID
and SPLUNK_ONCALL_API_KEY
environment variables will be used instead.
Name | Default | Description |
---|---|---|
apiId |
undefined |
Splunk On-Call API ID |
apiKey |
undefined |
Splunk On-Call API Key |
timeout |
5000 |
Number of milliseconds before the request times out |
baseUrl |
https://api.victorops.com |
The base URL for the Splunk On-Call REST API |
fullResponse |
false |
Get the full response instead of just the body |
maxContentLength |
10000 |
The max size of the HTTP response content in bytes |
maxBodyLength |
2000 |
The max allowed size of the HTTP request body in bytes |
Examples
Create an instance:
const SplunkOnCallClient = require('splunk-oncall-client');
const client = new SplunkOnCallClient({
apiId: 'API-ID',
apiKey: 'API-KEY'
});
Get a list of users:
async function getUsers() {
try {
const users = await client.users.getUsers();
return users;
} catch(err) {
console.error(err);
}
}
Get a list of incidents:
async function getIncidents() {
try {
const incidents = await client.incidents.getIncidents();
return incidents;
} catch(err) {
console.error(err);
}
}
Create a new incident:
async function createIncident() {
try {
const resp = await client.incidents.createIncident({
summary: 'Test incident',
details: 'Something bad happened!!!',
userName: 'johndoe',
targets: [
{
type: 'User',
slug: 'johndoe'
}
],
isMultiResponder: true
});
return resp;
} catch(err) {
console.error(err);
}
}
Get a list of teams:
async function getTeams() {
try {
const teams = await client.teams.getTeams();
return teams;
} catch(err) {
console.error(err);
}
}
Documentation
The client instance has a named property for each of the public endpoints in the Splunk On-Call (VictorOps) REST API. Each endpoint property contains methods that correspond to the operations associated with the endpoint (according to the Splunk On-Call API). All named endpoint methods return a Promise
which resolves with the response data or rejects with an error. Below are the endpoints and operations included with the client.
Any endpoint operation that takes a query
argument expects the value to be an Object
that contains the query parameters for that particular endpoint operation. Please refer to the endpoint operation's documentation for the correct query parameters.
On-Call
-
client.oncall.getUserSchedule(user, query)
- Get a user's on-call schedule - Splunk On-Call Documentation -
client.oncall.getTeamSchedule(team, query)
- Get a team's on-call schedule - Splunk On-Call Documentation -
client.oncall.getOncallUsers()
- Get an organization's on-call users - Splunk On-Call Documentation -
client.oncall.createOncallOverride(policy, takeOncall)
- Create an on-call override (take on-call) - Splunk On-Call Documentation
Incidents
-
client.incidents.getIncidents()
- Get the current incident information - Splunk On-Call Documentation -
client.incidents.createIncident(details)
- Creates a new incident - Splunk On-Call Documentation -
client.incidents.ackIncidents(ackInfo)
- Acknowledge an incident or list of incidents - Splunk On-Call Documentation -
client.incidents.rerouteIncidents(rules)
- Reroute one or more incidents - Splunk On-Call Documentation -
client.incidents.resolveIncidents(resolveInfo)
- Resolve an incident or list of incidents - Splunk On-Call Documentation -
client.incidents.ackUserIncidents(ackInfo)
- Acknowledge all incidents for which a user was paged - Splunk On-Call Documentation -
client.incidents.resolveUserIncidents(resolveInfo)
- Resolve all incidents for which a user was paged - Splunk On-Call Documentation
Alerts
-
client.alerts.getAlert(uuid)
- Get information about an alert - Splunk On-Call Documentation
Reporting
-
client.reporting.getShiftChanges(team, query)
- Get a list of shift changes for a team - Splunk On-Call Documentation -
client.reporting.getIncidentHistory(query)
- Get/search incident history - Splunk On-Call Documentation
Users
-
client.users.getUsers()
- Get a list of users for an organization - Splunk On-Call Documentation -
client.users.addUser(user)
- Add a user to an organization - Splunk On-Call Documentation -
client.users.addUsers(users)
- Add users to an organization - Splunk On-Call Documentation -
client.users.deleteUser(user, replacement)
- Remove a user from an organization - Splunk On-Call Documentation -
client.users.getUser(user)
- Get the information for the specified user - Splunk On-Call Documentation -
client.users.updateUser(user, userInfo)
- Update the designated user - Splunk On-Call Documentation -
client.users.getTeams(user)
- Get the user's team membership - Splunk On-Call Documentation
User Contact Methods
-
client.contactMethods.getContactMethods(user)
- Get a list of all contact methods for a user - Splunk On-Call Documentation -
client.contactMethods.getContactDevices(user)
- Get a list of all contact devices for a user - Splunk On-Call Documentation -
client.contactMethods.deleteContactDevice(user, contactId)
- Delete a contact device for a user - Splunk On-Call Documentation -
client.contactMethods.getContactDevice(user, contactId)
- Get the indicated contact device for a user - Splunk On-Call Documentation -
client.contactMethods.updateContactDevice(user, contactId, contactDevice)
- Update a contact device for a user - Splunk On-Call Documentation -
client.contactMethods.getContactEmails(user)
- Get a list of all contact emails for a user - Splunk On-Call Documentation -
client.contactMethods.createContactEmail(user, contactEmail)
- Create a contact email for a user - Splunk On-Call Documentation -
client.contactMethods.deleteContactEmail(user, contactId)
- Delete a contact email for a user - Splunk On-Call Documentation -
client.contactMethods.getContactEmail(user, contactId)
- Get a contact email for a user - Splunk On-Call Documentation -
client.contactMethods.getContactPhones(user)
- Get a list of all contact phones for a user - Splunk On-Call Documentation -
client.contactMethods.createContactPhone(user, contactPhone)
- Create a contact phone for a user - Splunk On-Call Documentation -
client.contactMethods.deleteContactPhone(user, contactId)
- Delete a contact phone for a user - Splunk On-Call Documentation -
client.contactMethods.getContactPhone(user, contactId)
- Get a contact phone for a user - Splunk On-Call Documentation
User Paging Policies
-
client.userPagingPolicies.getPagingPolicies(user)
- Get paging policies for a user - Splunk On-Call Documentation
Personal Paging Policy Values
-
client.pagingPolicyValues.getNotificationTypes()
- Get the available notification types - Splunk On-Call Documentation -
client.pagingPolicyValues.getContactTypes()
- Get the available contact types - Splunk On-Call Documentation -
client.pagingPolicyValues.getTimeoutValues()
- Get the available timeout values - Splunk On-Call Documentation
Personal Paging Policies
-
client.personalPagingPolicies.getPagingPolicy(username)
- Get a user's paging policy - Splunk On-Call Documentation -
client.personalPagingPolicies.createPolicyStep(username, stepInfo)
- Create a paging policy step - Splunk On-Call Documentation -
client.personalPagingPolicies.getPolicyStep(username, step)
- Get a paging policy step - Splunk On-Call Documentation -
client.personalPagingPolicies.createPolicyStepRule(username, step, ruleInfo)
- Creates a rule for a paging policy step. - Splunk On-Call Documentation -
client.personalPagingPolicies.updatePolicyStep(username, step, stepInfo)
- Updates a paging policy step - Splunk On-Call Documentation -
client.personalPagingPolicies.deletePolicyStepRule(username, step, rule)
- Deletes a rule for a paging policy step - Splunk On-Call Documentation -
client.personalPagingPolicies.getPolicyStepRule(username, step, rule)
- Gets a rule for a paging policy step - Splunk On-Call Documentation -
client.personalPagingPolicies.updatePolicyStepRule(username, step, rule, ruleInfo)
- Updates a rule for a paging policy step - Splunk On-Call Documentation
Teams
-
client.teams.getTeams()
- Get a list of teams for your organization - Splunk On-Call Documentation -
client.teams.addTeam(teamInfo)
- Add a team to your organization - Splunk On-Call Documentation -
client.teams.removeTeam(team)
- Remove a team from your organization - Splunk On-Call Documentation -
client.teams.getTeam(team)
- Get the information for the specified team - Splunk On-Call Documentation -
client.teams.updateTeam(team, teamInfo)
- Update the information for the specified team - Splunk On-Call Documentation -
client.teams.getAdmins(team)
- Get the team admins for the specified team - Splunk On-Call Documentation -
client.teams.getMembers(team)
- Get the team members for the specified team - Splunk On-Call Documentation -
client.teams.addMember(team, memberInfo)
- Add a team member to the specified team - Splunk On-Call Documentation -
client.teams.removeMember(team, user, replacement)
- Remove a team member from the specified team - Splunk On-Call Documentation
Escalation Policies
-
client.escalationPolicies.getPolicies()
- Get a list of escalation policy information - Splunk On-Call Documentation -
client.escalationPolicies.createPolicy(policyInfo)
- Create an escalation policy - Splunk On-Call Documentation -
client.escalationPolicies.deletePolicy(policy)
- Delete a specified escalation policy - Splunk On-Call Documentation -
client.escalationPolicies.getPolicy(policy)
- Get a specific escalation policy - Splunk On-Call Documentation
Routing Keys
-
client.routingKeys.getRoutingKeys()
- List routing keys and associated teams - Splunk On-Call Documentation -
client.routingKeys.createRoutingKey(keyInfo)
- Create a new routing key with escalation policy mapping - Splunk On-Call Documentation
Scheduled Overrides
-
client.scheduledOverrides.getOverrides()
- List all the scheduled overrides for an organization - Splunk On-Call Documentation -
client.scheduledOverrides.createOverride(overrideInfo)
- Create a new scheduled override - Splunk On-Call Documentation -
client.scheduledOverrides.deleteOverride(publicId)
- Deletes a scheduled override - Splunk On-Call Documentation -
client.scheduledOverrides.getOverride(publicId)
- Get the specified scheduled override - Splunk On-Call Documentation -
client.scheduledOverrides.getAssignments(publicId)
- Get the specified scheduled override assignments - Splunk On-Call Documentation -
client.scheduledOverrides.deleteAssignment(publicId, policySlug)
- Delete a scheduled override assignment - Splunk On-Call Documentation -
client.scheduledOverrides.getAssignment(publicId, policySlug)
- Get the specified scheduled override assignments - Splunk On-Call Documentation -
client.scheduledOverrides.updateAssignment(publicId, policySlug, assignmentInfo)
- Update a scheduled override assignment - Splunk On-Call Documentation
Rotations
-
client.rotations.getRotationGroups(team)
- Get a list of all rotation groups for a team - Splunk On-Call Documentation
Webhooks
-
client.webhooks.getWebhooks()
- Get a list of all the webhooks for an organization - Splunk On-Call Documentation
Chat
-
client.chat.sendChat(chatInfo)
- Send a chat message - Splunk On-Call Documentation
Notes
-
client.notes.getNotes(incidentNumber)
- Get the notes associated with an incident - Splunk On-Call Documentation -
client.notes.createNote(incidentNumber, noteInfo)
- Create a new note for an incident - Splunk On-Call Documentation -
client.notes.deleteNote(incidentNumber, noteName)
- Delete a note - Splunk On-Call Documentation -
client.notes.updateNote(incidentNumber, noteName, noteInfo)
- Update an existing note - Splunk On-Call Documentation
Maintenance Mode
-
client.maintenanceMode.getModeState()
- Get an organization's current maintenance mode state - Splunk On-Call Documentation -
client.maintenanceMode.startMode(modeDef)
- Start maintenance mode for routing keys - Splunk On-Call Documentation -
client.maintenanceMode.endMode(modeId)
- End maintenance mode for routing keys - Splunk On-Call Documentation
Change Log
The CHANGELOG contains descriptions of notable changes.
License
This software is licensed under the Apache 2 license.