OpsGenie Java API

The OpsGenie SDK for Java provides a Java API for OpsGenie services, making it easier for java developers to build applications that integrate with OpsGenie. With the OpsGenie SDK for Java, developers get started in minutes with a single, downloadable package that includes the OpsGenie Java library. Developers can build Java applications on top of APIs that take the complexity out of coding directly against a web service interface. The library provides APIs that hide much of the lower-level plumbing, including authentication, request retries, and error handling.

Before you can begin, you must sign up for OpsGenie service, create an API Integration and get your API key. In order to use the OpsGenie SDK for Java, you will need the API key from the API Integration you created. The API key is used to authenticate requests to the service and identify yourself as the sender of a request.

The OpsGenie SDK for Java requires J2SE Development Kit 6.0 - OpenJDK 6 or above. You can download the latest Java software from http://developers.sun.com/downloads/. The SDK also requires Apache Commons (HTTP Client and Logging), and Jackson third-party packages, which are included in the third-party directory of the SDK. You can also use opsgenie-javasdk-all-<version>.jar as a single package with all dependencies included.

View OpsGenie Java SDK Javadoc

Java SDK for Maven and Gradle Users

Download Java SDK

OpsGenie Java SDK Source Code - GitHub


Client Configuration

The OpsGenie SDK for Java allows you to change the default client configuration, which is helpful when you want to:

  • Connect to the Internet through proxy
  • Tweak HTTP transport settings, such as connection timeout and request retries.
  • Specify TCP socket buffer size hints
 

Proxy Configuration

When constructing a client object, you can pass in an optional com.ifountain.opsgenie.client.util.ClientConfiguration object to customize the client's configuration. If you're connecting to the Internet through a proxy server, you'll need to configure your proxy server settings (proxy host, port and username/password) through the ClientConfiguration object.

 

Http Transport Configuration

Several HTTP transport options can be configured through the com.ifountain.opsgenie.client.util.ClientConfiguration object. Default values will suffice for the majority of users, but users who want more control can configure:

  • Socket timeout
  • Connection timeout
  • Maximum retry attempts for retry-able errors
  • Maximum open HTTP connections

Tcp Socket Buffer Size

Advanced users who want to tune low-level TCP parameters can additionally set TCP buffer size hints through the ClientConfiguration object. The majority of users will never need to tweak these values, but they are provided for advanced users.

Optimal TCP buffer sizes for an application are highly dependent on network and OS configuration and capabilities. For example, most modern operating systems provide auto-tuning logic for TCP buffer sizes, which can have a big impact on performance for TCP connections that are held open long enough for the auto-tuning to optimize buffer sizes.

Large buffer sizes (ex: 2MB) allow the OS to buffer more data in memory without requiring the remote server to acknowledge receipt of that information , so can be particularly useful when the network has high latency.

This is only a hint, and the OS may choose not to honor it. When using this option, users should always check the operating system's configured limits and defaults. Most OS's have a maximum TCP buffer size limit configured, and won't let you go beyond that limit unless you explicitly raise the max TCP buffer size limit.

 

Exception Handling

The following sections describe the different cases of exceptions that are thrown by the SDK and how to handle them appropriately

OpsGenieClientException

This is the main type of exception that you'll need to deal with when using the OpsGenie SDK for Java. This exception represents an error response from an OpsGenie service. For example, if you request to close an alert that doesn't exist, OpsGenie will return an error response and all the details of that error response will be included in the thrown OpsGenieClientException.

When you encounter an OpsGenieClientException, you know that your request was successfully sent to the OpsGenie service, but could not be successfully processed either because of errors in the request's parameters or because of issues on the service side.

IOException

This exception indicates that a problem occurred inside the Java client code, either while trying to send a request to OpsGenie or while trying to parse a response from OpsGenie. IOExceptions are more severe than OpsGenieClientExceptions and indicate a major problem that is preventing the client from being able to make service calls to OpsGenie. For example, the OpsGenie Java SDK will throw an IOException if no network connection is available when you try to call an operation on one of the clients.

The Java API Organization

The following packages in the OpsGenie SDK for Java provide the API:

  • com.ifountain.opsgenie.client: Provides the implementation APIs for OpsGenie operations. For example, it provides methods to create, close and get alerts, attach files, adding comments, etc.
  • com.ifountain.opsgenie.client.model: Provides the low-level API classes to create requests and process responses. For example, it includes the GetAlertRequest class to describe your get alert request, the CreateAlertRequest class to describe your alert create requests, etc.
  • com.ifountain.opsgenie.client.util: Provides some utility classes like ClientConfiguration, etc.

For more information about the OpsGenie SDK for Java API, go to Java API Reference.

Actions

The OpsGenie SDK for Java provides the following actions that can be executed on OpsGenie service.

Create Alert

Creates alerts at OpsGenie

OpsGenieClient client = new OpsGenieClient();

CreateAlertRequest request = new CreateAlertRequest();
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setMessage("appserver1 down");
request.setDescription("cpu usage is over 60%");
request.setSource("nagios");
request.setEntity("appserver1");
request.setActions(Arrays.asList("ping", "restart"));
request.setTags(Arrays.asList("network", "operations"));
request.setRecipients(Arrays.asList("john.smith@acme.com"));
request.setTeams(Arrays.asList("ops_team","dev_team"));

CreateAlertResponse response = client.alert().createAlert(request);
String alertId = response.getId();

Close Alert

Closes alerts at OpsGenie.

OpsGenieClient client = new OpsGenieClient();
        
CloseAlertRequest request = new CloseAlertRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
CloseAlertResponse response = client.alert().closeAlert(request);
assert response.isSuccess();

Delete Alert

Deletes alerts at OpsGenie.

OpsGenieClient client = new OpsGenieClient();
        
DeleteAlertRequest request = new DeleteAlertRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
DeleteAlertResponse response = client.alert().deleteAlert(request);
assert response.isSuccess();

Get Alert

Retrieves specified alert details from OpsGenie

OpsGenieClient client = new OpsGenieClient();
        
GetAlertRequest request = new GetAlertRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
GetAlertResponse response = client.alert().getAlert(request);
String message = response.getAlert().getMessage();
String description = response.getAlert().getDescription();
List<string> recipients = response.getAlert().getRecipients();
List<string> teams = response.getAlert().getTeams();

List Alerts

Retrieves latest alerts with given limit at OpsGenie. If limit is not set it retrieves latest 20 alerts and 100 alerts max per request.

OpsGenieClient client = new OpsGenieClient();

ListAlertsRequest request = new ListAlertsRequest();
request.setApiKey("39d50168-24b3-4355-b285-b91060823dee");

ListAlertsResponse response = client.alert().listAlerts(request);
List<Alert> alerts = response.getAlerts();

List Alerts With Paging

Let's say we have 100 alerts at the system. We want to get 5 alerts per request and we want to start polling from the oldest alert.

Our first request will be like the following:

OpsGenieClient client = new OpsGenieClient();

ListAlertsRequest request = new ListAlertsRequest();
request.setApiKey("39d50168-24b3-4355-b285-b91060823dee");
request.setLimit(5);
request.setSortOrder(ListAlertsRequest.SortOrder.asc);
request.setSortBy(ListAlertsRequest.SortBy.createdAt);

ListAlertsResponse response = client.alert().listAlerts(request);
List<Alert> alerts = response.getAlerts();
long createdAt = alerts.get(alerts.size()-1).getCreatedAt();

Now, we have the latest "createdAt" value of the retrieved 5 alerts shown above. We will use the "createdAt" value at our next request to retrieve 6th to 10th alerts.

Our next request will be like the following:

OpsGenieClient client = new OpsGenieClient();

ListAlertsRequest request = new ListAlertsRequest();
request.setApiKey("39d50168-24b3-4355-b285-b91060823dee");
request.setLimit(5);
request.setSortOrder(ListAlertsRequest.SortOrder.asc);
request.setSortBy(ListAlertsRequest.SortBy.createdAt);
request.setCreatedAfter(createdAt); // createdAt value from the first request.

ListAlertsResponse response = client.alert().listAlerts(request);
List<Alert> alerts = response.getAlerts();
long createdAt = alerts.get(alerts.size()-1).getCreatedAt();

The next request will be the same as above.

Count Alerts

Count alerts at OpsGenie.

OpsGenieClient client = new OpsGenieClient();

CountAlertsRequest request = new CountAlertsRequest();
request.setApiKey("39d50168-24b3-4355-b285-b91060823dee");

CountAlertsResponse response = client.alert().countAlerts(request);
int count = response.getCount();

List Alert Logs

Retrieves latest alert logs with given limit at OpsGenie. If limit is not set it retrieves latest 100 logs. 100 is also max log to be retrieved per request.

OpsGenieClient client = new OpsGenieClient();

ListAlertLogsRequest request = new ListAlertLogsRequest();
request.setId("3009c832-f578-42dd-8404-776b392da7b6");
request.setApiKey("51508352-1c40-4d6a-9625-ac80b4dbb972");
request.setSortOrder(ListAlertLogsRequest.SortOrder.asc);
request.setLimit(5);

ListAlertLogsResponse response = client.alert().listAlertLogs(request);
List<AlertLog> alertLogs = response.getAlertLogs();
String lastKey = response.getLastKey();

To make pagination while getting logs:

  1. Make the request above. Notice that "lastKey" value response returned. You will use it in the second request.
  2. Make a second request like above, but make sure you populate the new requests lastKey field with the lastKey you obtained from first request. request.setLastKey(lastKey);

List Alert Notes

Retrieves latest alert notes with given limit at OpsGenie. If limit is not set it retrieves latest 100 notes. 100 is also max note to be retrieved per request.

OpsGenieClient client = new OpsGenieClient();

ListAlertNotesRequest request = new ListAlertNotesRequest();
request.setId("3009c832-f578-42dd-8404-776b392da7b6");
request.setApiKey("51508352-1c40-4d6a-9625-ac80b4dbb972");
request.setSortOrder(ListAlertNotesRequest.SortOrder.asc);
request.setLimit(5);

ListAlertNotesResponse response = client.alert().listAlertNotes(request);
List<AlertNote> alertNotes = response.getAlertNotes();
String lastKey = response.getLastKey();

To make pagination while getting notes:

  1. Make the request above. Notice that "lastKey" value response returned. You will use it in the second request.
  2. Make a second request like above, but make sure you populate the new requests lastKey field with the lastKey you obtained from first request. request.setLastKey(lastKey);

List Alert Recipients

Retrieves recipients of the specified alert in Opsgenie

OpsGenieClient client = new OpsGenieClient();

ListAlertRecipientsRequest request = new ListAlertRecipientsRequest();
request.setId("3009c832-f578-42dd-8404-776b392da7b6");
request.setApiKey("39d50168-24b3-4355-b285-b91060823dee");
ListAlertRecipientsResponse response = client.alert().listAlertRecipients(request);
Map<String, List<AlertRecipient>> groups = response.getGroups();
List<AlertRecipient> users = response.getUsers();

Acknowledge

Acknowledges alerts in OpsGenie

OpsGenieClient client = new OpsGenieClient();
        
AcknowledgeRequest request = new AcknowledgeRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
AcknowledgeResponse response = client.alert().acknowledge(request);
assert response.isSuccess();

Unacknowledge

Unacknowledges alerts in OpsGenie

OpsGenieClient client = new OpsGenieClient();

UnAcknowledgeRequest request = new UnAcknowledgeRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
UnAcknowledgeResponse response = client.alert().unAcknowledge(request);
assert response.isSuccess();

Snooze Request

Snooze request is used to snooze alerts in OpsGenie.

OpsGenieClient client = new OpsGenieClient();
client.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
SnoozeRequest request = new SnoozeRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
SnoozeResponse response = client.alert().snooze(request);
assert response.isSuccess();

Renotify

Renotifies the recipients about specified alert in OpsGenie

OpsGenieClient client = new OpsGenieClient();

RenotifyRequest request = new RenotifyRequest();
request.setId("3009c832-f578-42dd-8404-776b392da7b6");
request.setApiKey("39d50168-24b3-4355-b285-b91060823dee");
request.setSource("System");

List<RenotifyRecipient> recipients = new LinkedListRenotifyRecipient>();
RenotifyResponse response = client.alert().renotify(request);

Take Ownership

Takes the ownership of alerts in OpsGenie

OpsGenieClient client = new OpsGenieClient();
        
TakeOwnershipRequest request = new TakeOwnershipRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
TakeOwnershipResponse response = client.alert().takeOwnership(request);
assert response.isSuccess();

Assign

Assigns the ownership of alerts in OpsGenie

OpsGenieClient client = new OpsGenieClient();
        
AssignRequest request = new AssignRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
request.setOwner("sezgin.kucukkaraaslan@ifountain.com");
AssignResponse response = client.alert().assign(request);
assert response.isSuccess();

Add Alert Team

Add alert team request is used to add new teams to alerts in OpsGenie.

OpsGenieClient client = new OpsGenieClient();
client.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
AddAlertTeamRequest request = new AddAlertTeamRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setTeam("operations");
request.setUser("john.smith@acme.com");
request.setNote("We should warn operations team.");
request.setSource("java sdk");
AddAlertTeamResponse response = client.alert().addTeam(request);
assert response.isSuccess();

Add Recipient

Adds a new recipient to an alert in OpsGenie

OpsGenieClient client = new OpsGenieClient();
        
AddRecipientRequest request = new AddRecipientRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
request.setRecipient("sezgin.kucukkaraaslan@ifountain.com");
AddRecipientResponse response = client.alert().addRecipient(request);
assert response.isSuccess();

Add Note

Add notes to alerts in OpsGenie

OpsGenieClient client = new OpsGenieClient();
        
AddNoteRequest request = new AddNoteRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
request.setNote("We should find another solution.");
AddNoteResponse response = client.alert().addNote(request);
assert response.isSuccess();

Add Tags

Add tags to alerts in OpsGenie

OpsGenieClient client = new OpsGenieClient();

AddTagsRequest request = new AddTagsRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
request.setNote("We should find another solution.");
List<String> tags = new ArrayList<String>();
tags.add("support");
request.setTags(tags);
AddTagsResponse response = client.alert().addTags(request);
assert response.isSuccess();

Remove Tags

Remove tags from alerts in OpsGenie

OpsGenieClient client = new OpsGenieClient();

RemoveTagsRequest request = new RemoveTagsRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
request.setNote("We should find another solution.");
List<String> tags = new ArrayList<String>();
tags.add("support");
request.setTags(tags);
RemoveTagsResponse response = client.alert().removeTags(request);
assert response.isSuccess();

Add Details

Add details request is used to add properties to alert details in OpsGenie.

OpsGenieClient client = new OpsGenieClient();
client.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
AddDetailsRequest request = new AddDetailsRequest();
Map details = new HashMap();
details.put("prop1", "val1");
details.put("prop2", "val2");
request.setDetails(details);
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
AddDetailsResponse response = client.alert().addDetails(request);
assert response.isSuccess();

Remove Details

Remove details request is used to remove properties from alert details in OpsGenie.

OpsGenieClient client = new OpsGenieClient();
client.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
RemoveDetailsRequest request = new RemoveDetailsRequest();
List keys = new ArrayList();
keys.add("prop1");
keys.add("prop2");
request.setKeys(keys);
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
RemoveDetailsResponse response = client.alert().removeDetails(request);
assert response.isSuccess();

Execute Alert Action

Executes actions on alerts in OpsGenie

OpsGenieClient client = new OpsGenieClient();
        
ExecuteAlertActionRequest request = new ExecuteAlertActionRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
request.setAction("restartEntity");
ExecuteAlertActionResponse response = client.alert().executeAlertAction(request);
String result = response.getResult();

Attach

Attaches files to the alerts in OpsGenie.

OpsGenieClient client = new OpsGenieClient();
        
AttachRequest request = new AttachRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setUser("john.smith@acme.com");
request.setFile(new File("/home/john/performanceGraphs.zip"));
AttachResponse response = client.alert().attach(request);
assert response.isSuccess();

Escalate To Next Request

Escalate to Next request is used to immediately process the next available rule in the specified escalation.

OpsGenieClient client = new OpsGenieClient();
client.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
EscalateToNextRequest request = new EscalateToNextRequest();
request.setId("29c4d6f6-0919-40ec-8d37-4ab2ed2042c8");
EscalateToNextResponse response = client.alert().escalateToNext(request);
assert response.isSuccess();

Heartbeat Requests

Send heartbeat   is used send periodic heartbeat messages to OpsGenie. The heartbeat should be added to OpsGenie before sending a heartbeat, If a heartbeat with 10 minutes interval is added and OpsGenie does not get a heartbeat message within 10 minutes, OpsGenie creates an alert to notify the specified people.

For more information please refer to Heartbeat Monitoring  and Heartbeat API pages.

Java SDK supports most of the functionality listed in Heartbeat API page.

 

Add Heartbeat

Adds a heartbeat definition to OpsGenie

OpsGenieClient client = new OpsGenieClient();
AddHeartbeatRequest request = new AddHeartbeatRequest();
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setName("ServerX");

//optional props
request.setInterval(15);
request.setIntervalUnit(Heartbeat.IntervalUnit.minutes);
request.setEnabled(true);
request.setDescription("detailed description for this heartbeat");
AddHeartbeatResponse response = client.addHeartbeat(request);
String name = response.getName()

 

Send Heartbeat

Used send periodic heartbeat messages to OpsGenie

OpsGenieClient client = new OpsGenieClient();
        
HeartbeatRequest request = new HeartbeatRequest();
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setName("ServerX");
HeartbeatResponse response = client.heartbeat(request);
long heartbeatInMillis = response.getHeartbeat();

Copy Notification Rules Request

Copies a user's current notification rules to multiple other users.

For more information please refer to Copying Notification Rules To Other Users page.

OpsGenieClient client = new OpsGenieClient();

CopyNotificationRulesRequest request = new CopyNotificationRulesRequest();
request.setApiKey("ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079");
request.setFromUser("john.smith@acme.com");
request.setToUsers(Arrays.asList("mark.john@acme.com"));
request.setRuleTypes(Arrays.asList("New Alert", "Closed Alert"));
CopyNotificationRulesResponse response = client.copyNotificationRules(request);
assert response.isSuccess();