Page tree
Skip to end of metadata
Go to start of metadata

The Graze API acts as an integration point for external services and exposes selected Moogsoft AIOps functionality to authorized external clients.

Architecture 

The Graze API is implemented as a set of servlets running in the Moogsoft AIOps Tomcat instance that handles external Graze requests, making the UI servlet calls directly via cross-contexts.

Tomcat Configuration

Tomcat must be configured to allow cross-context calls to be made by adding the following to the context.xml file in the Tomcat $APPSERVER_HOME/conf directory:

<Context crossContext="true">

API Definition

All Graze requests use the following URL format, where server is the hostname of the machine running the UI :

https://<server>/graze/v1/<request_type>

For example: 

https://localhost/graze/v1/authenticate

All requests (other than authenticate) require basic authentication header or a valid auth_token. A valid authenticate request must be successfully made before any Graze API request is used without a basic authentication header.

Inactive sessions will be logged out after one hour, and a new authenticate request must be made to get a new valid auth_token.

If you are making regular Graze requests within a one hour timeframe you are considered active and your session will not expire

Authentication Troubleshooting

If an error occurs during Graze login authentication, the following output is returned:

{"message":"User is not authenticated","statusCode":3001}

As a security precaution, no more specific information is returned. This prevents information being provided to potential attackers as to which part of the authentication failed (for example 'Password incorrect'). 

Entries in the log file catalina.out (at WARN level) provide more information on authentication errors:

  • The user is not assigned the Grazer Role:

    User [john] does not have graze permission
  • No user of that name:

    User [NotAUser] account unknown in database
  • Incorrect password:

    Password incorrect for user [graze]

Endpoints

Alerts

 addAlertCustomInfo

addAlertCustomInfo

A POST request that adds and merges custom information for a specified Alert.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

alert_id

Number

The Alert ID

custom_info

JSON Object

A JSON Object containing the custom information

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addAlertCustomInfo" -H "Content-Type: application/json; charset=UTF-8" -d '{"alert_id" : 9, "custom_info" : { "field1" : "value1" , "field2" : "value2" , "field3" : ["item1","item2","item3"] , "field4" : {"field4-1" : "value4-1","field4-2" : "value4-2"} }}'

Successful Return:

NO RESPONSE TEXT

 addAlertToSituation

addAlertToSituation

A POST request that adds a specified Alert to the specified Situation.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

alert_id

Number

The Alert ID

sitn_id

Number

The Situation ID

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addAlertToSituation" -H "Content-Type: application/json; charset=UTF-8" -d '{"alert_id" : 16, "sitn_id" : 7 }'

Successful Return:

NO RESPONSE TEXT

 assignAndAcknowledgeAlert

assignAndAcknowledgeAlert

A POST request that assigns and acknowledges the moderator to the Alert for a specified alert id and user id.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request
alert_id

Number

The Alert ID

user_id

Number

The User ID

username

 StringA valid username

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

 assignAlert

assignAlert

A POST request that assigns the moderator to the Alert for a specified alert id and user id.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

alert_id

Number

The Alert ID

user_id

Number

The User ID

username

 StringA valid username

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/assignAlert" -H "Content-Type: application/json; charset=UTF-8" -d '{"alert_id" : 7, "username" : "network1" }'

Successful Return:

NO RESPONSE TEXT

 closeAlert

closeAlert 

A POST request that closes a specified Alert.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

alert_id

Number

The Alert ID

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/closeAlert" -H "Content-Type: application/json; charset=UTF-8" -d '{"alert_id" : 7 }'

Successful Return:

NO RESPONSE TEXT

 deassignAlert

deassignAlert

A POST request that de-assigns the current moderator from the Alert for a specified alert id.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

alert_id

Number

The Alert ID

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/deassignAlert" -H "Content-Type: application/json; charset=UTF-8" -d '{"alert_id" : 7}'

Successful Return:

NO RESPONSE TEXT

 getAlertDetails

getAlertDetails

A GET request that returns details (such as Description, Severity, etc.) of a specified alert.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

alert_id

Number

The Alert ID

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Successful requests return a JSON object which contains alert details from the following:

Name

  Type

Description 

active_sitn_list

Number list

A list of Situation IDs of the active Situations to which this alert belongs

agent

String

The agent name associated with this alert*

agent_location

String 

The agent location associated with this alert*

alert_id

Number 

The alert ID

class

String 

The class associated with this alert*

count

Number

The number of times that this alert has occurred

custom_info

JSON Object

A JSON Object containing the custom information 

description

String 

The description associated with this alert*

entropy
NumberThe entropy value of the alert, the measure of probability that an alert will arrive in the system at any given time.
This is a value between 0 (very certain) and 1 (very uncertain).
external_id

String 

The external ID associated with this alert*

first_event_time

Number

The timestamp (in Unix epoch time) of the first occurrence of this alert

int_last_event_time

Number 

The internal Moogsoft AIOps timestamp (in Unix epoch time) of the last occurrence of this alert 

last_event_time

Number

The timestamp (in Unix epoch time) of the last occurrence of this alert

last_state_change

Number

The timestamp (in Unix epoch time) of the last status change of this alert

manager

String

The manager name associated with this alert*

owner

Number

The User ID of the user that this alert is assigned to 

severity

Number

The alert's severity as an integer:

0

Clear

Indeterminate 

2

Warning 

3

Minor 

4

Major 

5

Critical

signature

String

The unique alert identifier

significance

Number

The alert's severity as an integer:

0

Collateral

Related

2

Impacting

3

Causal

source

String

The source associated with this alert*

source_id

String

The source ID associated with this alert*

state

Number

Indicates the lifecycle state of the alert

type

String

The type associated with this alert*

* = These details are derived from the input event text field, via the LAMs.

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getAlertDetails" --data-urlencode "alert_id=3968"


Successful request return:

{
   "active_sitn_list":[1], 
   "agent":"TestBed",
   "agent_location":"localhost",
   "alert_id":10,
   "class":"WebMon",
   "count":2,
   "custom_info":null,
   "description":"Web Server HTTPD is DOWN",
   "external_id":"12345",
   "first_event_time":1416307126,
   "int_last_event_time":1416307188,
   "last_event_time":1416307131,
   "last_state_change":1416307144,
   "manager":"WebMon",
   "owner":2, "severity":0,
   "signature":"SIG:Web Server Down Trap:xldn1458pap:10",
   "significance":3,
   "source":"xldn1458pap",
   "source_id":"xldn1458pap",
   "state":9, 
   "type":"HTTPDDown"
}
 getAlertIds

getAlertIds

A GET request that returns the total number of Alerts, and a list of their Alert IDs for a specified Alert filter and a limit.

Request Arguments

Name

Type

Description 

auth_token
StringA valid  auth_token  returned from the  authenticate  request
query

String

A JSON or SQL like alert filter

limit

Number

The maximum number of alert ids to return

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Successful requests return a JSON object which contains Alert details from the following:

Name

  Type

Description 

total_alerts

Number

The total number of Alerts, or unique Alerts

alert_ids

Number list

A list of the Alert IDs

Example

Curl Command:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getAlertIds" --data-urlencode 'query=agent!=SYSLOG and description matches "AUTH-SERVICE"' --data-urlencode 'limit=20'


Successful request return:


{"total_alerts":20,"alert_ids":[78,234,737,1253,1459,1733,2166,2653,2855,3133,3414,3538,3729,3905,3991,4110,4160,4536,4692,4701]}

SQL-like Filters

You can now use SQL-like filter conditions similar to URL or Cookbook filters instead of JSON formatted filters:

Example curl request to get the first 20 alert_ids with query: agent != SYSLOG AND description matches 'AUTH-SERVICE':


curl -G -u graze:graze -k -v  "https://localhost/graze/v1/getAlertIds" --data-urlencode  'query=agent!=SYSLOG and description matches "AUTH-SERVICE"' --data-urlencode  'limit=20'

 removeAlertFromSituation

removeAlertFromSituation

A POST request that removes a specified Alert from the specified Situation.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

alert_id

Number

The Alert ID

sitn_id

Number

The Situation ID

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/removeAlertFromSituation" -H "Content-Type: application/json; charset=UTF-8" -d '{"alert_id" : 16, "sitn_id" : 7 }'

Successful Return:

NO RESPONSE TEXT

 setAlertAcknowledgeState

setAlertAcknowledgeState

A POST request that acknowledges or un-acknowledges the moderator to the Alert for a specified alert id and acknowledge state.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

alert_id

Number

The Alert ID

acknowledged

Number

The acknowledge state (0 for un-acknowledged, 1 for acknowledged)

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/setAlertAcknowledgeState" -H "Content-Type: application/json; charset=UTF-8" -d '{"alert_id" : 7, "acknowledged" : 1 }'

Successful return:

NO RESPONSE TEXT

 setAlertSeverity

setAlertSeverity

A POST request that sets the severity level for a specified Alert.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

alert_id

Number

The Alert ID

severity

Number

The Alert's severity as an integer:

0

Clear

Indeterminate 

2

Warning 

3

Minor 

4

Major 

5

Critical

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/setAlertSeverity" -H "Content-Type: application/json; charset=UTF-8" -d '{"alert_id" : 7, "severity" : 5 }'

Successful return:

NO RESPONSE TEXT

Situations

 addSigCorrelationInfo

addSigCorrelationInfo

 A POST request that associates the external client with a specified Situation. This allows Moogsoft AIOps to filter events and send only those of interest to an external system.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

service_name

String 

The name of the external service (for example, ServiceNow)

resource_id

String 

The ID of the external service entity to associate with this Situation

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addSigCorrelationInfo" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 3, "service_name" : "my service 7", "resource_id" : "my resource 7"}'

Successful Return:

NO RESPONSE TEXT

 addSituationCustomInfo

addSituationCustomInfo

A POST request that adds and merges custom information for a specified Situation.

Note: This method has superseded the now deprecated method addCustomInfo.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

custom_info

JSON Object

A JSON Object containing the custom information

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addSituationCustomInfo" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 5, "custom_info" : { "field1" : "value1" , "field2" : "value2" , "field3" : ["item1","item2","item3"] , "field4" : {"field4-1" : "value4-1","field4-2" : "value4-2"} }}'

Successful Return:

NO RESPONSE TEXT

 addThreadEntry

addThreadEntry 

A POST request that adds a new entry to an existing thread in a Situation.

Threads are comments or 'story activity' on Situations.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

thread_name

String 

The name of the existing thread

entry

String 

The entry to add. For example, 'And another thing...' 

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see HTTP status and error codes

 assignAndAcknowledgeSituation

assignAndAcknowledgeSituation 

A POST request that assigns and acknowledges the moderator to the Situation for a specified situation id and user id.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

user_id

Number

The User ID

username

 StringA valid username

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

 assignSituation

assignSituation 

A POST request that assigns the moderator to the Situation for a specified Situation ID and user ID.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

user_id

Number

The User ID

usernameStringA valid username

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/assignSituation" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 7, "user_id" : 3 }'


Successful Return:

NO RESPONSE TEXT

 closeSituation

closeSituation

A POST request that closes a specified Situation that is currently open, and optionally closes Alerts in the Situation.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

resolution

Number

Determines what to do  with the Situation's Alerts:

0

Close no Alerts

Close all Alerts in this Situation

2

Close only Alerts unique to this Situation

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/closeSituation" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 7, "resolution" : 0 }'

Successful Return:

NO RESPONSE TEXT

 createSituation

createSituation

A POST request that creates a manual Situation. The Situation description is set with the description parameter. The following Situation settings are pre-set and not configurable here:

  • Status: Opened
  • Moderator: none assigned

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

description

String

The new Situation description

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object  with the following:

Name

Type

Description 

sitn_id

Number

The new Situation ID

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/createSituation" -H "Content-Type: application/json; charset=UTF-8" -d '{"description" : "This is my description 12345"}'


Successful request return:

{"sitn_id":2300}
 createThread

createThread

A POST request that creates a new thread for a specified Situation.

Threads are comments or 'story activity' on Situations.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The ID of the Situation having a new thread created

thread_name

String 

The name for the new thread


Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/createThread" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 1, "thread_name" : "My thread 0958"}'

Return:

NO RESPONSE TEXT

 deassignSituation

deassignSituation

A POST request that that de-assigns the current moderator from the Situation for a specified situation id.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID


Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/deassignSituation" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 7}'

Successful Return:

NO RESPONSE TEXT

 getActiveSituationIds

getActiveSituationIds

A GET request that returns the total number of active Situations, and a list of their Situation IDs. Active Situations are those that are not Closed, Resolved or Dormant.

Request Argument

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request


There are no other arguments, as this method returns data on all active Situations.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

total_situations

Number

The total number of active Situations 

sitn_ids

Number list

A list of the active Situation IDs


Example

Successful request return: 

{ 
   "total_situations":10, 
   "sitn_ids":[4, 5, 6, 12, 14, 15, 16, 17, 18, 19] 
}
 getSigCorrelationInfo

getSigCorrelationInfo

 A GET request that retreives all correlation information related to a specified Situation.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request.

sitn_id

Number

The Situation ID.

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X GET -u graze:graze -k -v "https://localhost/graze/v1/getSigCorrelationInfo?sitn_id=5" -H "Content-Type: application/json; charset=UTF-8"

Successful Return:

 [
     {
     "sig_id": 1, 
     "service_name": "Example1", 
     "external_id": "Example1",
     "properties": "{"Example1":"Example1"}
     },
     {
     "sig_id": 2,
     "service_name": "Example2",
     "external_id": "Example2",
     "properties": "{"Example2":"Example2"}
     }
   ]
 getSituationActions

getSituationActions

A GET request that returns the activies for Situations, ordered most recent last

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_ids

Array

Array of Situations that the activities are asked for

start
IntegerStarting from which row should data be included in results
limit
IntegerLimit for how many activities wanted in the output
actions

Array

List of actions_code

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing an array of the following:

Name

 Type

Description 

uid

Number

User id


action_code

Number list

Code for the action in that JSON object

descriptionStringDescription of the action
detailsStringDetails of the action
typeStringType of the action
sig_idIntegerThe situation id for that situation
timed_atIntegerTime stamp of the activity

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationActions" --data-urlencode 'sitn_ids=[1, 2, 3, 6]' --data-urlencode 'actions=[1]' --data-urlencode 'limit=3' --data-urlencode 'start=0'

Successful request return:

  "activities": [{
      "uid": 2,
      "action_code": 1,
      "description": "Situation Created",
      "details": {},
      "type": "event",
      "sig_id": 1,
      "timed_at": 1507039842
      }, {
      "uid": 2,
      "action_code": 14,
      "description": "Added Alerts To Situation",
      "details": {}
      "alerts": [1, 2]
      }]
      }
 getSituationAlertIds

getSituationAlertIds

A GET request that returns the total number of Alerts, and a list of their Alert IDs for a specified Situation. This can be either all Alerts or just those Alerts unique to the Situation.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

for_unique_alerts

Boolean

Indicates the Alerts to get from the Situation:
true = get only Alerts unique to the Situation
false = get all Alerts in the Situation (default)

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing the following:

Name

 Type

Description 

total_alerts

Number

The total number of Alerts, or unique Alerts 

alert_ids

Number list

A list of the Alert IDs

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationAlertIds"     --data-urlencode "sitn_id=1" --data-urlencode "for_unique_alerts=false"

Successful request return:

{"total_alerts":232,"alert_ids":[6,10,17,19,22,26,27,29,32,43,44,45,47,52,67,68,79,81,83,84,96,102,105,108,109,111,113,115,116,125,135,136,138,140,142,143,147,151,152,153,165,175,177,178,180,181,188,192,193,207,211,213,217,223,225,232,238,239,240,244,255,258,259,269,270,272,274,284,293,303,314,318,335,357,363,369,374,375,388,398,414,428,430,434,442,443,448,449,450,479,480,485,486,492,494,504,505,510,511,518,521,529,556,558,563,570,580,594,596,599,601,603,628,655,656,661,664,674,684,691,705,714,715,719,720,728,732,734,750,776,777,781,788,794,808,819,830,835,838,844,857,858,860,861,877,882,885,887,890,892,893,900,901,906,912,914,918,926,936,937,959,971,972,984,994,1004,1013,1016,1019,1020,1023,1033,1043,1045,1068,1076,1082,1083,1085,1099,1119,1124,1135,1137,1143,1147,1171,1185,1201,1207,1217,1225,1231,1238,1254,1271,1272,1274,1280,1282,1290,1292,1301,1320,1321,1322,1324,1326,1327,1331,1332,1333,1362,1379,1402,1414,1423,1433,1443,1454,1468,1472,1473,1481,1491,1510,1512,1517,1520,1522,1532,1534]}
 getSituationDescription

getSituationDescription

A GET request that returns the description for a specified Situation.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing the following:

Name

 Type

Description 

sitn_id

Number

The Situation ID

description

String

The text in the Situation's description field

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationDescription" --data-urlencode 'sitn_id=1'

Successful request return:

{"sitn_id" : "1", "description" : "SyslogLamCookbook source"}
 getSituationDetails

getSituationDetails

A GET request that returns details (such as Description, Status, etc.) of a specified Situation.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object which contains Situation details from the following:

Name

 Type

Description 

category

String

The Situation category. One of the following:

  •  Closed
  •  Created
  •  Detected
  •  Priority
  •  Spam
  •  Superseded
created_at

Number

The timestamp (in Unix epoch time) of the Situation creation time

custom_info

JSON Object

A JSON Object containing the custom information

description

String 

The Situation description

first_event_time

Number

The timestamp (in Unix epoch time) of the first Event used in creating this Situation

internal_priority

Number 

The Situation priority, calculated from the priorities of the Alerts in the Situation

last_event_time

Number

The timestamp (in Unix epoch time) of the last Event used in creating this Situation

last_state_change

Number

The timestamp (in Unix epoch time) of the last status change of this Situation

moderator_id

Number

The User ID of the user that this the moderator of this Situation

sitn_id

Number

The Situation ID

status

Number 

The Situation's status as an integer:

Opened 

2

Unassigned 

3

Assigned 

4

Acknowledged 

5

Unacknowledged

6

Active

7

Dormant

8

Resolved 

9

Closed

story_id

Number 

The ID of the History story for this Situation

superseded_by

Number/Null

The ID of a Situation that supersedes this Situation, if there is one. Can be null

total_alerts

Number 

The number of all Alerts in this Situation

total_unique_alerts

Number

The number of Alerts unique to this Situation

Example

Curl Commands

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationDetails"     --data-urlencode "sitn_id=1"

Successful request return:


{
   "category":"Detected",
   "created_at":1415814620,
   "custom_info":null,
   "description":"Sigaliser situation",
   "first_event_time":1415814600,
   "internal_priority":0,
   "last_event_time":1415814619,
   "last_state_change":1415868947,
   "moderator_id":2,
   "sitn_id":3,
   "status":1,
   "story_id":3,
   "superseded_by":null,
   "total_alerts":1403,
   "total_unique_alerts":1403
}
 getSituationHosts

getSituationHosts

A GET request that returns a list of host names for a specified Situation, either for all the Alerts in the Situation or just for the unique Alerts.

Hosts are the names (defined in the alerts.source field in the database) for the sources of Events.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

for_unique_alerts

Boolean 

Indicates the Alerts to use to get the host names:
true = use only Alerts unique to the Situation
false = use all Alerts in the Situation (default)

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing the following:

Name

 Type

Description 

hosts

List

A list of the host names

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationHosts"         --data-urlencode "sitn_id=1" --data-urlencode "for_unique_alerts=false"

Successful request return:

{"hosts":["172.27.127.247-888","90.223.60.20-SSS","bm1.wnwx.isp.acme.com-OOO","vm3.sshyw.isp.acme.com-OOO"]}
 getSituationIds

getSituationIds

A GET request that that returns the total number of Situations, and a list of their Situation IDs for a specified situation filter and a limit.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

query

String

A JSON or SQL like situation filter

limit

Number 

The maximum number of situation ids to return

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing the following:

Name

 Type

Description 

total_situations

Number

The total number of Situations, or unique Situations

sitn_ids

Number listA list of the Situation IDs

Example

Curl Command:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationIds"         --data-urlencode 'query=description="test1" or queue = 5' --data-urlencode 'limit=20'

Successful request return:

{"total_situations":7,"sitn_ids":[87,121,128,278,523,1003,1519]}

SQL-like Filters

You can now use SQL-like filter conditions similar to URL or Cookbook filters instead of JSON formatted filters:

Example curl request to get the first 20 situation_ids with query: description = 'test1' OR queue = 5:


curl -G -u graze:graze -k -v  "https://localhost/graze/v1/getSituationIds"  --data-urlencode  'query=description="test1" or queue = 5' --data-urlencode  'limit=20'
 getSituationProcesses

getSituationProcesses

A GET request that returns a list of process names for a specified Situation.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Successful requests return a JSON object containing the following:

Name

Type

Description 

processes

List

A list of the Situation's process names

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationProcesses"     --data-urlencode 'sitn_id=1'

Successful request return, with a primary process name defined:

{"processes":["Knowledge Management","Online Transaction Processing","Web Content Management","40GbE","8-bit Unicode Transcoding Platform"]}
 getSituationServices

getSituationServices

A GET request that returns a list of external service names for a specified Situation.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing the following:

Name

Type

Description 

services

List

A list of the Situation's service names

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationServices"     --data-urlencode 'sitn_id=1'

Successful request return, with a primary service name defined:

{"services":["Cloud Management Platform","Geographic Information Systems","Knowledge Management","Online Transaction Processing","Storage Subsystem","Web Content Management","0-bit Emulation","40GbE","8-bit Unicode Transcoding Platform"]}
 getThreadEntries

getThreadEntries

A GET request that returns thread entries for a specified Situation. Threads are comments or 'story activity' on Situations (More information here).

You can select specific thread entries to return using start and limit values. If not, their default values return the first 100 entries. The entries returned are ordered by most recent first.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

thread_name

String

The name of the thread to get entries from

start 

Number 

The number of the first thread entry to return (default = 0)

limit

Number 

The maximum number of thread entries to return (default = 100) 

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing the following:

Name

Type

Description 

sitn_id

Number

The Situation ID

thread_name

String

The name of the thread that the entries are from

entries

List

A list of thread entries. See below

The entries list contains the following sub parameters:

Name

Type

Description 

user_id

Number

The user ID of the user that created the entry

time

Number

The timestamp (in Unix epoch time) of when the entry was created

entry_text

String

The text of the entry

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getThreadEntries"         --data-urlencode "sitn_id=358" --data-urlencode "thread_name=Support" --data-urlencode "start=0" --data-urlencode "limit=10"

Successful request return:

{"entries":[{"entry_text":"My second entry here","user_id":5,"time":1499424718},{"entry_text":"My entry here","user_id":5,"time":1499424710}],"sitn_id":358,"thread_name":"Support"}
 mergeSituations

mergeSituations

A POST request that merges two or more Situations, superseding the originals if required.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

situations

List

A list of Situation IDs of the Situations to be merged. The list must contain at least two numbers, and no duplicates

supersede_original

Boolean 

Determines what to do with the original Situations:
true = keep the original Situations
false = supersede the original Situations

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Successful requests return a JSON object containing the following:

Name

Type

Description 

sitn_id

Number

The Situation ID of the new, merged Situation

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/mergeSituations" -H "Content-Type: application/json; charset=UTF-8" -d '{"situations" : [1,2,3], "supersede_original" : false }'

Successful request return:

{"sitn_id":2315}
 removeSigCorrelationInfo

removeSigCorrelationInfo

 A DELETE request that removes all correlation information related to a specified Situation.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request.

sitn_id

Number

The Situation ID.

serviceNameStringThe service name (Optional)
externalIdStringThe external ID (Optional).

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/removeSigCorrelationInfo" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 3, "service_name" : "my service 7", "external_id" : "my resource 7"}'

A successful return is an HTTP 200 response.


 resolveSituation

resolveSituation

A POST request that resolves a specified Situation that is currently open.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/resolveSituation" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 5}'

Successful Return:

NO RESPONSE TEXT

 setSituationAcknowledgeState

setSituationAcknowledgeState

A POST request that acknowledges or un-acknowledges the moderator to the Situation for a specified situation id and acknowledge state.

Request Arguments

Name

Type

Description 

sitn_id

Number

The Situation ID

acknowledged

Number

The acknowledge state (0 for un-acknowledged, 1 for acknowledged)

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/setSituationAcknowledgeState" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 64, "acknowledged" : 1 }'

Successful return:

NO RESPONSE TEXT

 setSituationDescription

setSituationDescription

A POST request that sets the description for a specified Situation.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

description

String 

The description text to be applied to the Situation 

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/setSituationDescription" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 6, "description" : "This is my description 12345"}'

Successful Return:

NO RESPONSE TEXT

 setSituationProcesses

setSituationProcesses

A POST request that applies a list of processes to a specified Situation. 

Any other processes already associated with the Situation are removed.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

process_list 

List

A list of process names as text strings (for example, ["P1","P2"]).  If any processes supplied do not exist in the database, they are created and assigned to the Situation.

Return Parameter

Type

  Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/setSituationProcesses" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 7, "process_list" : ["Knowledge Management", "90nm Manufacturing"]}'

Successful return:

NO RESPONSE TEXT

 setSituationServices

setSituationServices

A POST request that applies a list of external services to a specified Situation. 

Any other services already associated with the Situation are removed.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

sitn_id

Number

The Situation ID

service_list 

List

A list of service names as text strings (for example, ["S1","S2"]).  If any services supplied do not exist in the database, they are created and assigned to the Situation.

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/setSituationServices" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 8, "service_list" : ["Knowledge Management", "90nm Manufacturing"]}'

Successful Return:

NO RESPONSE TEXT

User Management

 applyNewLicense

applyNewLicense

A POST request that allows an AIOps license to be added via Graze.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request.

license

String

A valid license key.

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object  with the following:


Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/applyNewLicence" -H "Content-Type: application/json; charset=UTF-8" -d '{"license" : "<your license key>"}'

Successful request return:

HTTP/2 200 
 createTeam

createTeam

A POST request that creates a new team.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

name

String

Mandatory - the new team (unique) name

alert_filterString

The team alerts filter. Either a SQL like filter or an JSON representation of the filter

servicesJSON ListList of the team services names or IDs
sig_filterStringThe situation filters. Either a SQL like filter or an JSON representation of the filter
landing_pageStringThe team default landing page
activeBooleanFalse if the team is inactive, true if the team is active. Default to true
descriptionStringThe team description
usersList of numbers or stringsThe team users (either IDs or usernames)

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object  with the following:

Name

Type

Description 

team_id

Number

The new team ID

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/createTeam" -H "Content-Type: application/json; charset=UTF-8" -d '{"name" : "my team name 1", "alert_filter" : "manager = \"my_manager\" and (class = \"my_class_12345\" or external_id = \"my_ext_12345\")", "services" : ["Identity Management","Yellow Pages"], "sig_filter" : "description = \"my_description_12345\" or queue = 50", "landing_page" : {"type":"situations","id":"open"}, "active" : true, "description" : "The team description 12345", "users" : ["user1","user2","user3"]}'


Successful request return:

{"team_id":16}
 createUser

createUser

A POST request that creates a new user.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

username

String

Mandatory - the new user (unique) login username

password
String

The new user password (only valid for DB realm)

active
Booleantrue if the user active, false if the user inactive, default to true
email
StringThe user email address
fullname
StringThe user full name
roles
JSON listThat list should contain either the list the role IDs or the role names. E.g "roles":["Super User"],
primary_group
String or NumberThe user primary group name or primary group id
department
String or numberThe user department id or name
joined
NumberThe time the user joined (in Unix time)
timezone
StringThe user timezone
contact_num
StringThe user phone number
session_expiry
NumberThe number of minutes after which the user session will expire. Default to system default
competencies
JSON list

A list with the user competencies. Each competency should have have name or cid and ranking. That is, something like:

[
	{"name":"SunOS", "ranking": 40},
	{"name":"SAP", "ranking": 50},
	{"name":"EMC", "ranking": 60}
]
teams
JSON list of numbers or stringsList of the user teams. The list should contains either the list of the teams ID or the teams name

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object  with the following:

Name

Type

Description 

user_id

Number

The new user ID

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/createUser" -H "Content-Type: application/json; charset=UTF-8" -d '{"username" : "johndoe1", "roles" : ["Super User", "Operator"], "password" : "johndoe1", "active" : true, "email" : "johndoe@moogsoft.com", "fullname" : "John Doe", "primary_group" : "Network", "department" : "Support", "joined" : 1494951621, "timezone" : "Europe/London", "contact_num" : "555-1234", "session_expiry" : null, "competencies" : [{"name":"SunOS", "ranking": 40},{"name":"SAP", "ranking": 50},{"name":"EMC", "ranking": 60}], "teams" : ["my team 1","my team 2","my team 3"], "properties" : null}'

Successful request return:

{"user_id":777}
 getTeam

getTeam

A GET request that returns a team's details by team ID or name.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request.

team_id

Integer

The unique ID of the team to retrieve information about.

nameStringThe name of a valid team to retrieve information about.

Return Parameters

Type

  Description

HTTP code

HTTP status or error code indicating request success or failure. 
For codes, see below.

Example

Curl Commands:


curl -G -u graze:graze -k -v "https://localhost/graze/v1/getTeam?team_id=1"
curl -G -u graze:graze -k -v "https://localhost/graze/v1/getTeam?name=Cloud DevOps"

Successful request return:


{
    "room_id": 1,
    "alert_filter": "",
    "user_ids": [
        3
    ],
    "sig_filter": "",
    "landing_page": null,
    "description": "Example Team",
    "active": true,
    "team_id": 1,
    "services": [],
    "users": [
        "admin"
    ],
    "name": "Cloud DevOps",
    "service_ids": []
}
 getTeamsForService

getTeamsForService

A GET request to return all teams related to the service with the specified ID or name.

Request Arguments

NameTypeDescription
auth_tokenStringA valid auth_token returned from the authenticate request.
service_idStringThe ID of the service.
nameStringThe name of the service.

Return Parameters

TypeDescription
HTTP codeHTTP status or error code indicating request success or failure. 
For codes, see below.

Example

Curl Commands:


curl -G -u graze:graze -k -v "https://localhost/graze/v1/getTeamsForService?service_id=1"
curl -G -u graze:graze -k -v "https://localhost/graze/v1/getTeamsForService?service_name=web"

Successful request return:


[
    {
        "room_id": 1,
        "alert_filter": "",
        "user_ids": [
            3
        ],
        "sig_filter": "",
        "name": "Cloud DevOps",
        "landing_page": "",
        "description": "Example Team",
        "active": true,
        "service_ids": [
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9,
            10,
            11
        ],
        "team_id": 1,
        "services": [
            "Commerce",
            "Compute",
            "CRM",
            "Database",
            "Mobile",
            "Networking",
            "Remote",
            "Social",
            "Storage",
            "Switch",
            "Web"
        ],
        "users": [
            "admin"
        ]
    }
]
 getTeamSituationIds

getTeamSituationIds

A GET request that returns the total number of Situations that are assigned to a team, and a list of their Situation IDs.

Request Argument

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

team_name

String

The name of an existing team

There are no other arguments, as this method returns data on all Situations assigned to a team.

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing the following:

Name

Type

Description 

total_situations

Number

The total number of Situations assigned to a team

sitn_ids

Number list

A list of Situation IDs of the Situations assigned to a team

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getTeamSituationIds" --data-urlencode "team_name=Cloud Devops"

Successful request return: 

{"total_situations":35,"sitn_ids":[20,21,39,55,85,119,145,180,208,233,244,275,305,358,460,461,485,518,574,575,592,616,666,695,696,740,800,892,919,960,992,993,1027,1047,1092]}
 getTeamSituationStats

getTeamSituationStats

A GET request that returns the number of active Situations assign to a team over time.

Request Argument

Name

Type

Description 

teams

Array

An array of team Ids - Optional : If no teams are provided, the endpoint will return data for the top 10 teams

from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

The name of the team 

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getTeamSituationStats" --data-urlencode 'teams=[1,2]'  --data-urlencode 'from=1513508950' --data-urlencode 'to=1513595370'


Output Example

Successful request return: 

[{
	"datapoints": [
		[2.0, 1513657700000],
		[9.0, 1513661300000],
		[1.0, 1513664900000],
		[4.0, 1513668500000],
		[3.0, 1513672100000],
		[2.0, 1513675700000],
		[2.0, 1513679300000],
		[9.0, 1513682900000],
		[1.0, 1513686500000]
	],
	"target": "Cloud DevOps"
}, {
	"datapoints": [],
	"target": "Database"
}]
 getUserInfo

getUserInfo

A GET request that returns information about a specified user.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

user_id

Number

The user ID of the user to get information about

usernameStringA valid username

Return Parameters

Type

  Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing the following:

Name

Type

Description 

user_id

Number

The user's ID

full_name

String

The full name of the user

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getUserInfo" --data-urlencode "user_id=57"

Successful request return:

{"full_name":"Lonnie Holmes","user_id":57}
 getUserRoles

getUserRoles

Fetches the user's roles from the database.

Request Argument

NameTypeDescription
auth_token

String

A valid auth_token returned from the authenticate request

user_id

Number

The user's ID

username

 StringA valid username

Return parameter

TypeDescription
NativeObjectA Javascript object containing Role id, Role name and Role description

Example

Curl Command:


curl -G -u graze:graze -k -v "https://localhost/graze/v1/getUserRoles" --data-urlencode "username=bigfish917"


Successful request return:

[{"id" : 2, "name" : "Administrator", "description" : "Administrator"}, {"id" : 4, "name" : "Operator", "description" : "Operator"}, {"id" : 5, "name" : "Customer", "description" : "Customer"}]
 getUsers

getUsers

Fetches a list of all users in the database.

Request Argument

NameTypeDescription
auth_token

String
(Mandatory)

A valid auth_token returned from the authenticate request

limitInteger
(Optional)

The maximum number of results to return. Default is 1000.

Return parameter

TypeDescription
NativeObject

A JSON list of all users, displaying uid, teams, fullname and username.

Example

Curl Command:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getUsers" --data-urlencode "limit=3"


Successful request return:

[
    {
        "uid": 3,
        "teams": [
            "Cloud DevOps"
        ],
        "fullname": "Administrator",
        "username": "admin"
    },
    {
        "uid": 6,
        "teams": [],
        "fullname": "Nagios",
        "username": "Nagios"
    },
    {
        "uid": 5,
        "teams": [],
        "fullname": "Webhook",
        "username": "Webhook"
    }
  ]
 getUserTeams

getUserTeams

Fetches the team names and IDs associated with the specified user ID or username.

Request Argument

NameTypeDescription
auth_token

String

A valid auth_token returned from the authenticate request

user_id

NumberA valid user ID
usernameStringA valid username

Return parameter

TypeDescription
NativeObjectA Javascript object containing Team id and Team name

Example

Curl Command:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getUserTeams"             --data-urlencode "username=admin"

Successful request return:

[{"id" : 11, "name" : "Team1"}, {"id" : 12, "name" : "Team2"}, {"id" : 2, "name" : "Team3"}, {"id" : 6, "name" : "Team4"}, {"id" : 10, "name" : "Team5"}]
 updateTeam

updateTeam

A POST request that modify an existing team.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

team_idNumberMandatory - The team ID
nameStringThe new team name. Exclude this attribute to leave Moogsoft AIOps as it is
alert_filterString

The new team alerts filter. Either a SQL like filter or an JSON representation of the filter. Exclude this attribute to leave Moogsoft AIOps as it is

servicesJSON ListList of the team services names or IDs. Exclude this attribute to leave Moogsoft AIOps as it is
sig_filterStringThe situation filters. Either a SQL like filter or an JSON representation of the filter. Exclude this attribute to leave Moogsoft AIOps as it is
landing_pageStringThe team default landing page. Exclude this attribute to leave Moogsoft AIOps as it is
activeBooleanFalse if the team is inactive, true if the team is active. Default to true. Exclude this atttribute to leave Moogsoft AIOps as is
descriptionStringThe team description. Exclude this attribute to leave Moogsoft AIOps as it is
usersList of numbers or stringsThe team users (either IDs or usernames). Exclude this attribute to leave Moogsoft AIOps as it is

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/updateTeam" -H "Content-Type: application/json; charset=UTF-8" -d '{"team_id" : 16, "name" : "my team name RENAMED", "active" : true, "description" : "The team description", "users" : []}'

Successful Return:

NO RESPONSE TEXT

 updateUser

updateUser

A POST request that modify an existing user.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

username

String

Mandatory (optional if user id used) - username for user to be edited

uid
LongMandatory (optional if username used) - user id for user to be edited
password
String

Optional - The new user password (only valid for DB realm)

active
BooleanOptional - true if the user active, false if the user inactive, default to true
email
StringOptional - The user email address
fullname
StringOptional - The user full name
roles
JSON listOptional - That list should contain either the list the role IDs or the role names. E.g "roles":["Super User"],
primary_group
String or NumberOptional - The user primary group name or primary group id
department
String or numberOptional - The user department id or name
timezone
StringOptional - The user timezone
contact_num
StringOptional - The user phone number
session_expiry
NumberOptional - The number of minutes after which the user session will expire. Default to system default
competencies
JSON list

Optional - A list with the user competencies. Each competency should have have name or cid and ranking. That is, something like:

[
	{"name":"SunOS", "ranking": 40},
	{"name":"SAP", "ranking": 50},
	{"name":"EMC", "ranking": 60}
]
teams
JSON list of numbers or stringsOptional - List of the user teams. The list should contains either the list of the teams ID or the teams name

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/updateUser" -H "Content-Type: application/json; charset=UTF-8" -d '{"uid" : 5, "active" : true, "password" : "test", "roles" : ["Super User", "Operator"], "teams" : ["my team 1"], "competencies" : [{"name":"SunOS", "ranking": 40},{"name":"SAP", "ranking": 50},{"name":"EMC", "ranking": 60}], "session_expiry" : null, "properties" : null, "contact_num" : "555-123456", "timezone" : "Europe/London", "fullname" : "John Doe", "department" : "Support", "primary_group" : "Network", "email" : "test@test.com"}'

Successful request return:

NO RESPONSE TEXT

 authenticate

authenticate

A GET request that provides the auth_token required by all other Graze API requests which will not provide the basic authentication header. Graze users can have multiple concurrent Graze sessions with the same username and password.

Request Arguments

Name

 Type

Description 

username

String

A valid Moogsoft AIOps username

password

String 

The username's corresponding password

Return Parameter

Name

Type

Description 

auth_token

String

A session ID for use in subsequent requests

Example

Curl Command

curl -k -v "https://localhost/graze/v1/authenticate?username=graze&password=graze"

Return

{"auth_token":"878b3ec57d464aee80d09893221be8e8"}


All requests (other than authenticate) require a valid auth_token or basic authentication header. Therefore before any Graze API request is used, a valid authenticate request must be successfully made unless basic authentication headers will be used. 

Inactive sessions will be logged out after one hour, and a new authenticate request must be made to get a new valid auth_token.

If you are making regular Graze requests within a one hour timeframe you are considered active and your session will not expire

Dashboards and Reporting

 getTeamSituationStats

getTeamSituationStats

A GET request that returns the number of active Situations assign to a team over time.

Request Argument

Name

Type

Description 

teams

Array

An array of team Ids - Optional : If no teams are provided, the endpoint will return empty data

from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected
aggregation
StringCan be "none" (No aggregation of results) or "sum" (Aggregation of all teams provided)


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

The name of the team 

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getTeamSituationStats" --data-urlencode 'teams=[1,2]'  --data-urlencode 'from=1513508950' --data-urlencode 'to=1513595370' --data-urlencode 'aggregation=sum'


Output Example

Successful request return: 

[{
	"datapoints": [
		[2.0, 1513657700000],
		[9.0, 1513661300000],
		[1.0, 1513664900000],
		[4.0, 1513668500000],
		[3.0, 1513672100000],
		[2.0, 1513675700000],
		[2.0, 1513679300000],
		[9.0, 1513682900000],
		[1.0, 1513686500000]
	],
	"target": "Cloud DevOps"
}, {
	"datapoints": [],
	"target": "Database"
}]
 getSystemSituationStats

getSystemSituationStats

A GET request that returns the number of active Situations in the system over time.

Request Argument

Name

Type

Description 

from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"System"

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSystemSituationStats" --data-urlencode 'from=1513508950' --data-urlencode 'to=1513595370'


Output Example

Successful request return: 

[{
	"datapoints": [
		[2.0, 1513657700000],
		[9.0, 1513661300000],
		[1.0, 1513664900000],
		[4.0, 1513668500000],
		[3.0, 1513672100000],
		[2.0, 1513675700000],
		[2.0, 1513679300000],
		[9.0, 1513682900000],
		[1.0, 1513686500000]
	],
	"target": "Open Situations"
}]
 getMTTRStats

getMTTRStats

A GET request that returns the Mean Time To Resolve a situation in the system over time.

Request Argument

Name

Type

Description 

from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"mtt_resolve"

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getMTTRStats" --data-urlencode 'from=1513508950' --data-urlencode 'to=1513595370'


Output Example

Successful request return: 

[{
	"datapoints": [
		[2.0, 1513657700000],
		[9.0, 1513661300000],
		[1.0, 1513664900000],
		[4.0, 1513668500000],
		[3.0, 1513672100000],
		[2.0, 1513675700000],
		[2.0, 1513679300000],
		[9.0, 1513682900000],
		[1.0, 1513686500000]
	],
	"target": "mtt_resolve"
}]
 getMTTDStats

getMTTDStats

A GET request that returns the Mean Time To Detect a situation in the system over time.

Request Argument

Name

Type

Description 

from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"mtt_detect"

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getMTTDStats" --data-urlencode 'from=1513508950' --data-urlencode 'to=1513595370'


Output Example

Successful request return: 

[{
	"datapoints": [
		[2.0, 1513657700000],
		[9.0, 1513661300000],
		[1.0, 1513664900000],
		[4.0, 1513668500000],
		[3.0, 1513672100000],
		[2.0, 1513675700000],
		[2.0, 1513679300000],
		[9.0, 1513682900000],
		[1.0, 1513686500000]
	],
	"target": "mtt_detect"
}]
 getMTTAStats

getMTTAStats

A GET request that returns the Mean Time To Detect a situation in the system over time.

Request Argument

Name

Type

Description 

from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"mtt_acknowledge"

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getMTTAStats" --data-urlencode 'from=1513508950' --data-urlencode 'to=1513595370'


Output Example

Successful request return: 

[{
	"datapoints": [
		[2.0, 1513657700000],
		[9.0, 1513661300000],
		[1.0, 1513664900000],
		[4.0, 1513668500000],
		[3.0, 1513672100000],
		[2.0, 1513675700000],
		[2.0, 1513679300000],
		[9.0, 1513682900000],
		[1.0, 1513686500000]
	],
	"target": "mtt_acknowledge"
}]
 getReoccurringSituationStats

getReoccurringSituationStats

A GET request that returns the percentage of reoccurring situations in the system over time.

Request Argument

Name

Type

Description 

from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"Reoccurring Situation"

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getReoccurringSituationStats" --data-urlencode 'from=1513508950' --data-urlencode 'to=1513595370'


Output Example

Successful request return: 

[{
	"datapoints": [
		[2.0, 1513657700000],
		[9.0, 1513661300000],
		[1.0, 1513664900000],
		[4.0, 1513668500000],
		[3.0, 1513672100000],
		[2.0, 1513675700000],
		[2.0, 1513679300000],
		[9.0, 1513682900000],
		[1.0, 1513686500000]
	],
	"target": "Reoccurring Situation"
}]
 getReassignedSituationStats

getReassignedSituationStats

A GET request that returns the number of situations reassigned in the system over time.

Request Argument

Name

Type

Description 

from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"Reassigned Situation"

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getReassignedSituationStats" --data-urlencode 'from=1513508950' --data-urlencode 'to=1513595370'


Output Example

Successful request return: 

[{
	"datapoints": [
		[2.0, 1513657700000],
		[9.0, 1513661300000],
		[1.0, 1513664900000],
		[4.0, 1513668500000],
		[3.0, 1513672100000],
		[2.0, 1513675700000],
		[2.0, 1513679300000],
		[9.0, 1513682900000],
		[1.0, 1513686500000]
	],
	"target": "Reassigned Situation"
}]
 getServiceSituationStats

getServiceSituationStats

A GET request that returns the number of active Situations impacting a service over time.

Request Argument

Name

Type

Description 

services
ArrayAn array of services Ids - Optional : If no services are provided, the endpoint will return empty data
from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected
aggregation
StringCan be "none" (No aggregation of results) or "sum" (Aggregation of all services provided)


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

The name of the service 

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getServiceSituationStats" --data-urlencode 'services=[1,2]' --data-urlencode 'from=1513508950' --data-urlencode 'to=1513595370' --data-urlencode 'aggregation=sum'


Output Example

Successful request return: 

[{
	"datapoints": [
		[2.0, 1513657700000],
		[9.0, 1513661300000],
		[1.0, 1513664900000],
		[4.0, 1513668500000],
		[3.0, 1513672100000],
		[2.0, 1513675700000],
		[2.0, 1513679300000],
		[9.0, 1513682900000],
		[1.0, 1513686500000]
	],
	"target": "Service A"
}, {
	"datapoints": [],
	"target": "Service B"
}]
 getStatusSituationStats

getStatusSituationStats

A GET request that returns the number of situations by status.

Request Argument

Name

Type

Description 

status
ArrayAn array of status ids. Optional, if not given, returns default set of statuses: Opened, Unassigned, Assigned, Acknowledeged, Unacknowledeged, Resolved.
from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected
aggregation
StringCan be "none" (No aggregation of results) or "sum" (Aggregation of all statuses provided)


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

The name of the status

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getStatusSituationStats" --data-urlencode 'from=1515943678' --data-urlencode 'to=1516030078' --data-urlencode 'status=[1, 2]' --data-urlencode 'aggregation=sum'


Output Example

Successful request return: 

[{
	"datapoints": [
		[92.0, 1516008478000],
		[666.0, 1516030078000]
	],
	"target": "Opened"
}, {
	"datapoints": [
		[1.0, 1515947278000],
		[35.0, 1515958078000],
		[63.0, 1515976078000],
		[241.0, 1515994078000],
		[4.0, 1516015678000]
	],
	"target": "Assigned"
}]
 getSeveritySituationStats

getSeveritySituationStats

A GET request that returns the number of situations by severity.

Request Argument

Name

Type

Description 

severity
ArrayAn array of severity ids. Optional, if not given, returns default set of severities: Clear, Indeterminate, Warning, Minor, Major, Critical.
from
NumberA timestamp from epoch in seconds - The time from when the data points will be collected
to
NumberA timestamp from epoch in seconds - The time until when the data points will be collected
aggregation
StringCan be "none" (No aggregation of results) or "sum" (Aggregation of all severities provided)


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

The name of the status

datapoints

Number array

A array containing multiple nested arrays of datapoint (timestamp + value)


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSeveritySituationStats" --data-urlencode 'from=1516216020' --data-urlencode 'to=1516282420' --data-urlencode 'severity=[0, 1]' --data-urlencode 'aggregation=sum'


Output Example

Successful request return: 

[{
	"datapoints": [
		[92.0, 1516008478000],
		[666.0, 1516030078000]
	],
	"target": "Major"
}, {
	"datapoints": [
		[1.0, 1515947278000],
		[35.0, 1515958078000],
		[63.0, 1515976078000],
		[241.0, 1515994078000],
		[4.0, 1516015678000]
	],
	"target": "Minor"
}]

Workflow

 addProcess

addProcess 

A POST request that adds a new process to the database.

Processes are external business entities related to business activities that are affected by the incidents that Moogsoft AIOps captures in Situations.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

name

String

The process name

description

String

The process description. Optional

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addProcess" -H "Content-Type: application/json; charset=UTF-8" -d '{"name" : "new proc 1", "description" : "This is my description 12345"}'

Successful return:

NO RESPONSE TEXT

 addService

addService 

A POST request that adds a new external service to the database.

An external service is a business entity monitored by Moogsoft AIOps via Event streams.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

name

String

The service name

description

String

The service description. Optional

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addService" -H "Content-Type: application/json; charset=UTF-8" -d '{"name" : "new svc 1", "description" : "This is my description 12345"}'

Successful Return:

NO RESPONSE TEXT

 createMaintenanceWindow

createMaintenanceWindow

A POST request that creates a maintenance window period that filters Alerts.

Request Argument

ParameterTypeDescription
auth_token

String

A valid auth_token returned from the authenticate request

nameStringThe name of the window
descriptionStringDescription of the window
filterStringJSON or SQL like filter for which alerts to match. The filter must be in the correct Moog JSON format. i.e. the same format as used in Alert and Situation filters in the DB
start_date_timeEpoch Seconds (Number)Time to start the window from. The start_date_time property must be in epoch time and may be up to 5 years in the future
durationSeconds (Number)Duration of the window in seconds. The minimum duration is 1 second and the maximum is 5 years
forward_alertsbooleanSet this to True if the Alert in the maintenance mode should be forwarded to the next Moolet in the chain
recurring_periodNumberHow many days/weeks/months to wait before this recurs. The recurring_period property must be 1 - no other value will be accepted
recurring_period_unitsNumberDecides what the recurring period counts in 0 = minutes, 1 = hours, 2 = days, 3 = weeks, 4 = months.
The recurring_period_units property has allowed values of 2 (daily), 3 (weekly) or 4 (monthly) - no other values will be accepted


Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

SQL-like Filters

You can now use SQL-like filter conditions similar to URL or Cookbook filters instead of JSON formatted filters:

The 'filter' parameter now accepts a string (SQL-format filter) instead of an object (old style JSON-format filter).

Curl Command:

Example curl request to create a window with filter: source = 'server1' AND external_id IN ('value1', 'value2', 'value3'):

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/createMaintenanceWindow" -H "Content-Type: application/json; charset=UTF-8" -d '{"name":"window1", "description":"window1 description here", "filter": "source = \"server1\" and external_id in (\"value1\", \"value2\", \"value3\")", "start_date_time":1473849237, "duration": 55800, "forward_alerts":false}'

Successful requests return a JSON object  with the following:

Name

Type

Description 

window_id

Number

The new Situation ID

{"window_id":16}
 deleteMaintenanceWindows

deleteMaintenanceWindows

A POST requests that deletes a maintenance window.

ParameterTypeDescription
auth_token

String

A valid auth_token returned from the authenticate request

idNumberThe id of the window to delete


Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure
For codes, see below

Example

Curl Command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/deleteMaintenanceWindows" -H "Content-Type: application/json; charset=UTF-8" -d '{"id":1}'

Successful Command:

NO RESPONSE TEXT

 getIntegrationConfig

getIntegrationConfig

A GET request that exports the configuration and mapping needed for an integration in JSON format.
The exported JSON file can be saved as a duplicate configuration of the original integration.
For example, you can modify and save the returned object as webhook_lam_custom.conf. Run it with this command:


$MOOGSOFT_HOME/bin/webhook_lam --config=webhook_lam_custom.conf


Request Arguments


ParameterTypeDescription
auth_token

String

A valid auth_token returned from the authenticate request

integration_idNumberA unique identifier given to each integration by Moogsoft AIOps.


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Example

Curl Command:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getIntegrationConfig?integration_id=1"

Successful requests return a JSON object:

{
    "config": {
        "filter": {
            "presend": "WebhookLam.js"
        },
        "process": "webhook_lam_webhook1",
        "conversions": {
            "sevConverter": {
                "output": "INTEGER",
                "lookup": "severity",
                "input": "STRING"
            },
            "stringToInt": {
                "output": "INTEGER",
                "input": "STRING"
            }
        },
        "mapping": {
            "catchAll": "overflow",
            "rules": [
                {
                    "name": "signature",
                    "rule": "$signature"
                },
                {
                    "name": "source_id",
                    "rule": "$source_id"
                },
                {
                    "name": "external_id",
                    "rule": "$external_id"
                },
                {
                    "name": "manager",
                    "rule": "$manager"
                },
                {
                    "name": "source",
                    "rule": "$source"
                },
                {
                    "name": "class",
                    "rule": "$class"
                },
                {
                    "name": "agent",
                    "rule": "$LamInstanceName"
                },
                {
                    "name": "agent_location",
                    "rule": "$agent_location"
                },
                {
                    "name": "type",
                    "rule": "$type"
                },
                {
                    "name": "severity",
                    "rule": "$severity",
                    "conversion": "sevConverter"
                },
                {
                    "name": "description",
                    "rule": "$description"
                },
                {
                    "name": "agent_time",
                    "rule": "$agent_time",
                    "conversion": "stringToInt"
                }
            ]
        },
        "agent": {
            "name": "webhook_lam_webhook1"
        },
        "monitor": {
            "address": "localhost",
            "authentication_cache": true,
            "use_ssl": false,
            "auto_port_assign": true,
            "authentication_type": "basic",
            "rpc_response_timeout": 20,
            "lists_contain_multiple_events": true,
            "proxy": "https://freida7/events/webhook_webhook1",
            "accept_all_json": true,
            "port": 51000,
            "name": "Webhook Lam Monitor (Webhook1)",
            "num_threads": 5,
            "rest_response_mode": "on_receipt",
            "class": "CRestMonitor"
        },
        "constants": {
            "severity": {
                "0": 2,
                "moog_lookup_default": 1,
                "3": 5,
                "5": 4,
                "CLEAR": 0,
                "2": 3,
                "MAJOR": 4,
                "CRITICAL": 5,
                "MINOR": 3,
                "INDETERMINATE": 1,
                "1": 2
            }
        }
    }
}
 getMaintenanceWindows

getMaintenanceWindows

A GET request that returns maintenance windows based on the window ID and how many should be fetched. Only returns active recurring windows and scheduled windows, not expired maintenance windows.


Request Arguments

ParameterTypeDescription
auth_token

String

A valid auth_token returned from the authenticate request

startNumberThe start point for where to fetch windows from (ie, 0 to start at the first, 10 to start at the 11th)
limitNumberThe number of windows to fetch


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:


curl -G -u graze:graze -k -v "https://localhost/graze/v1/getMaintenanceWindows" --data-urlencode 'start=0' --data-urlencode 'limit=20'


Successful request return:

{"windows":[{"filter":"{ \"column\": \"type\", \"op\": 10, \"value\": \"KnownErrorType1234\", \"type\": \"LEAF\" }","duration":3600,"recurring_period":1,"del_flag":false,"forward_alerts":false,"last_updated":1499425460,"name":"My window 1","updated_by":5,"description":"My description 1","id":1,"recurring_period_units":3,"start_date_time":1499425427},{"filter":"{ \"column\": \"description\", \"op\": 10, \"value\": \"FireInServerRoom\", \"type\": \"LEAF\" }","duration":3600,"recurring_period":0,"del_flag":false,"forward_alerts":false,"last_updated":1499425489,"name":"My second window","updated_by":5,"description":"Technical details here","id":2,"recurring_period_units":0,"start_date_time":1499425462}]}
 findMaintenanceWindows

findMaintenanceWindows

A GET request that returns maintenance windows that matches a filter.


Request Arguments

ParameterTypeDescription
auth_token

String

A valid auth_token returned from the authenticate request

filterStringSQL or JSON filter
limitNumberThe number of windows to fetch (default to 100)


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Example

Curl Command:


curl -G -u graze:graze -k -v "https://localhost/graze/v1/findMaintenanceWindows" --data-urlencode 'filter=description matches "My"' --data-urlencode 'limit=2'


Successful request return:

{"windows":[{"filter":"{ \"column\": \"type\", \"op\": 10, \"value\": \"KnownErrorType1234\", \"type\": \"LEAF\" }","duration":3600,"recurring_period":1,"del_flag":false,"forward_alerts":false,"last_updated":1499425460,"name":"My window 1","updated_by":5,"description":"My description 1","id":1,"recurring_period_units":3,"start_date_time":1499425427},{"filter":"{ \"column\": \"description\", \"op\": 10, \"value\": \"FireInServerRoom\", \"type\": \"LEAF\" }","duration":3600,"recurring_period":0,"del_flag":false,"forward_alerts":false,"last_updated":1499425489,"name":"My second window","updated_by":5,"description":"Technical details here","id":2,"recurring_period_units":0,"start_date_time":1499425462}]}
 getSeverities

getSeverities

A GET request that returns the list of possible severities and severity IDs.

No Requested Arguments


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

severity_id

Number

The Id of the severity 

name

String

The severity name


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSeverities" 


Output Example

Successful request return: 

[{
	"name": "Clear",
	"severity_id": 0
}, {
	"name": "Indeterminate",
	"severity_id": 1
}, {
	"name": "Warning",
	"severity_id": 2
}, {
	"name": "Minor",
	"severity_id": 3
}, {
	"name": "Major",
	"severity_id": 4
}, {
	"name": "Critical",
	"severity_id": 5
}]
 getProcesses

getProcesses

A GET request that returns the list of processes.

Request Arguments

Name

Type

Description 

auth_token
String
(Mandatory)
A valid auth_token returned from the authenticate request
limit
Integer
(Optional)
The maximum number of results that are returned. Default is 1000.


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

process_id

Number

The ID of the process

name

String

The name of the process

description
StringThe description of the process.


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getProcesses" 


Output Example

Successful request return: 

[
    {
        "process_id": 1,
        "name": "Example1",
        "description": "Example1"
    },
    {
        "process_id": 2,
        "name": "Example2",
        "description": "Example2"
    },
    {
        "process_id": 3,
        "name": "Example3",
        "description": "Example3"
    }
]
 getServices

getServices

A GET request that returns the list of services.

Request Arguments

Name

Type

Description 

auth_token
String
(Mandatory)
A valid auth_token returned from the authenticate request
limit
Integer
(Optional)
The maximum number of results that are returned. Default is 1000.


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

service_id

Number

The Id of the service 

service_name

String

The service name


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getServices" 


Output Example

Successful request return: 

[{
	"service_id": 15,
	"service_name": "Service A"
}, {
	"service_id": 4,
	"service_name": "Service B"
}]
 getStats

getStats

A GET request that list all endpoints available with their description.

No Requested Arguments


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getStats" 


Output Example

Successful request return: 

[{
	"endpoint": "getTeamSituationStats",
	"description": "returns the number of active situations assign to a team over time",
	"display_name": "Open Situations by Team",
	"parameters": {
		"teams": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getTeams",
				"value": "team_id"
			},
			"type": "mapped",
			"required": false
		},
		"from": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		},
		"to": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		}
	}
}, {
	"endpoint": "getServiceSituationStats",
	"description": "returns the number of active situations impacting a service over time",
	"display_name": "Open Situations by Service",
	"parameters": {
		"teams": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getTeams",
				"value": "team_id"
			},
			"type": "mapped",
			"required": false
		},
		"from": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		},
		"services": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getServices",
				"value": "service_id"
			},
			"type": "mapped",
			"required": false
		},
		"to": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		}
	}
}, {
	"endpoint": "getSystemSituationStats",
	"description": "returns the number of active situations in the system over time",
	"display_name": "Open Situations",
	"parameters": {
		"from": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		},
		"to": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		}
	}
}, {
	"endpoint": "getStatusSituationStats",
	"description": "returns the number of active situations with specified status over time",
	"display_name": "Situations by Status",
	"parameters": {
		"teams": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getTeams",
				"value": "team_id"
			},
			"type": "mapped",
			"required": false
		},
		"from": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		},
		"to": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		},
		"status": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getStatuses",
				"value": "status_id"
			},
			"type": "mapped",
			"required": false
		}
	}
}, {
	"endpoint": "getSeveritySituationStats",
	"description": "returns the number of active situations with specified severity over time",
	"display_name": "Open Situations by severity",
	"parameters": {
		"severity": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getSeverities",
				"value": "severity_id"
			},
			"type": "mapped",
			"required": "false"
		},
		"teams": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getTeams",
				"value": "team_id"
			},
			"type": "mapped",
			"required": false
		},
		"from": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		},
		"to": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		}
	}
}, {
	"endpoint": "getMTTAStats",
	"description": "returns the mean time to acknowledge a situation over time",
	"display_name": "Mean Time To Acknowledge situations",
	"parameters": {
		"teams": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getTeams",
				"value": "team_id"
			},
			"type": "mapped",
			"required": false
		},
		"from": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		},
		"to": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		}
	}
}, {
	"endpoint": "getMTTDStats",
	"description": "returns the mean time to detect a situation over time",
	"display_name": "Mean Time To Detect situations",
	"parameters": {
		"teams": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getTeams",
				"value": "team_id"
			},
			"type": "mapped",
			"required": false
		},
		"from": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		},
		"to": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long",
			"required": true
		}
	}
}, {
	"endpoint": "getMTTRStats",
	"description": "returns the mean time to resolve a situation over time",
	"display_name": "Mean Time To Resolve situations",
	"parameters": {
		"teams": {
			"mapping": {
				"display_value": "name",
				"endpoint": "getTeams",
				"value": "team_id"
			},
			"type": "mapped",
			"required": false
		},
		"from": {
			"description": "A timestamp from epoch in seconds",
			"type": "Long ",
			"required ": true
		},
		"to ": {
			"description ": "A timestamp from epoch in seconds ",
			"type ": "Long ",
			"required ": true
		}
	}
}, {
	"endpoint ": "getReassignedSituationStats ",
	"description ": "returns the number of situations that have been reassigned over time ",
	"display_name ": "Reassigned situations ",
	"parameters ": {
		"teams ": {
			"mapping ": {
				"display_value ": "name ",
				"endpoint ": "getTeams ",
				"value ": "team_id "
			},
			"type ": "mapped ",
			"required ": false
		},
		"from ": {
			"description ": "A timestamp from epoch in seconds ",
			"type ": "Long ",
			"required ": true
		},
		"to ": {
			"description ": "A timestamp from epoch in seconds ",
			"type ": "Long ",
			"required ": true
		}
	}
}]
 getStatuses

getStatuses

A GET request that returns the list of active teams.

No Requested Arguments


Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below


Successful requests return a JSON object containing the following:

Name

Type

Description 

status_id

Number

The Id of the status 

name

String

The status name


Input Example

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getStatuses" 


Output Example

Successful request return: 

[{
	"status_id": 1,
	"name": "Opened"
}, {
	"status_id": 2,
	"name": "Unassigned"
}, {
	"status_id": 3,
	"name": "Assigned"
}, {
	"status_id": 4,
	"name": "Acknowledged"
}, {
	"status_id": 5,
	"name": "Unacknowledged"
}, {
	"status_id": 6,
	"name": "Active"
}, {
	"status_id": 7,
	"name": "Dormant"
}, {
	"status_id": 8,
	"name": "Resolved"
}, {
	"status_id": 9,
	"name": "Closed"
}, {
	"status_id": 10,
	"name": "SLA Exceeded"
}]
 getSystemSummary

getSystemSummary

A GET request that returns a summary of current Alerts and Situations in Moogsoft AIOps.

Request Argument

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

There are no other arguments, as this method returns data on all Alerts and Situations.

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object system_summary, containing Moogsoft AIOps statistics in the following:

Name

Type

Description 

open_sitns

Number

The number of open Situations in Moogsoft AIOps

open_sitns_down

Number

The number of open Situations that are trending down

open_sitns_up

Number 

The number of open Situations that are trending up 

avg_events_per_sitnNumberThe average number of events per situation
avg_alerts_per_sitnNumberThe average number of alerts per situation
service_count

Number 

The number of services currently in Moogsoft AIOps

open_sigs_unassignedNumberThe number of situations unassigned
total_events

Number 

The total number of Events currently in Moogsoft AIOps


Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSystemSummary"

Successful request return:

{"system_summary":{"total_events":61676,"open_sitns":571,"avg_events_per_sitn":305,"open_sitns_up":565,"open_sitns_down":2,"avg_alerts_per_sitn":16,"open_sigs_unassigned":310,"timestamp":1499425056}}
 getSystemStatus

getSystemStatus

A GET request that returns current system status information for all processes.

Request Argument

Name

  Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request

There are no other arguments, as this method returns data on all processes.

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure 
For codes, see below

Successful requests return a JSON object containing the following:

Name

Type

Description 

component

String

Represents the name of a component within the process. May not be present, depending on the process

instance

String

The instance name

last_heartbeat

Number

The timestamp (in Unix epoch time) of the last process heartbeat. 0 is a special value indicating that a heartbeat has never been received

missed_heartbeats

Number

The number of missed process heartbeats. -1 is a special value indicating that a heartbeat has never been received

process_name

String

The process name

processes

List

A list of the processes, with status information

reserved

Boolean

Indicates whether the process is reserved:
true = a reserved process
false = process not reserved
A reserved process is a process that is usually required for Moogsoft AIOps to be working properly

runningBoolean

Indicates whether the process is running or not:

true = running

false = not running

service_nameStringThe service name
display_nameStringThe name of the service in the configuration
typeStringThe type of the service (e.g lam, servlets, moog_farmd)
passiveBoolean

Indicates whether the service is passive in a HA environment:

true = passive

false = active

stoppableBoolean

Indicates whether the service can be stopped or not:

true : stoppable

false : not stoppable

ha_confJSON ObjectA Json blob containing the HA configuation

Example

Curl Command

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSystemStatus"

Successful request return:

{
	"processes": [{
		"running": true,
		"sub_components": {
			"moogpoller": {
				"run_on_startup": true,
				"instance": "",
				"service_name": "apache-tomcat",
				"display_name": "servlets",
				"type": "servlets",
				"last_heartbeat": 1491385834300,
				"passive": false,
				"running": true,
				"component": "moogpoller",
				"reserved": true,
				"stoppable": true,
				"missed_heartbeats": 0,
				"ha_conf": {
					"cluster": "MOO",
					"instance": "",
					"default_leader": true,
					"start_as_passive": false,
					"only_leader_active": false,
					"group": "servlets"
				}
			},
			"moogsvr": {
				"run_on_startup": true,
				"instance": "",
				"service_name": "apache-tomcat",
				"display_name": "servlets",
				"type": "servlets",
				"last_heartbeat": 1491385825246,
				"passive": false,
				"running": true,
				"component": "moogsvr",
				"reserved": true,
				"stoppable": true,
				"missed_heartbeats": 0,
				"ha_conf": {
					"cluster": "MOO",
					"instance": "",
					"default_leader": true,
					"start_as_passive": false,
					"only_leader_active": false,
					"group": "servlets"
				}
			}
		},
		"instance": "",
		"reserved": true,
		"service_name": "apache-tomcat",
		"stoppable": true,
		"missed_heartbeats": 0,
		"display_name": "servlets",
		"type": "servlets",
		"last_heartbeat": 1491385834300,
		"ha_conf": {
			"cluster": "MOO",
			"instance": "",
			"default_leader": true,
			"start_as_passive": false,
			"only_leader_active": false,
			"group": "servlets"
		},
		"passive": false
	}, {
		"running": false,
		"instance": "",
		"last_missed_heartbeat": 1491385820601,
		"reserved": false,
		"stoppable": false,
		"missed_heartbeats": 10,
		"display_name": "test_lam",
		"type": "lam",
		"last_heartbeat": 1491382820601,
		"additional_health_info": {
			"thread_pool_queue_size": 0,
			"published_events": {
				"last_5_minutes": 130,
				"last_10_minutes": 130,
				"last_minute": 130
			}
		},
		"ha_conf": {
			"cluster": "MOO",
			"instance": "",
			"default_leader": true,
			"start_as_passive": false,
			"only_leader_active": true,
			"group": "test_lam"
		},
		"passive": false
	}, {
		"sub_components": {
			"SituationMgr": {
				"run_on_startup": true,
				"instance": "",
				"last_missed_heartbeat": 1491385821669,
				"service_name": "moogfarmd",
				"display_name": "moog_farmd",
				"type": "moog_farmd",
				"last_heartbeat": 1491382821669,
				"passive": false,
				"running": false,
				"component": "SituationMgr",
				"reserved": true,
				"stoppable": true,
				"missed_heartbeats": 10,
				"ha_conf": {
					"cluster": "MOO",
					"instance": "",
					"default_leader": true,
					"start_as_passive": false,
					"only_leader_active": true,
					"group": "moog_farmd"
				}
			},
			"AlertBuilder": {
				"run_on_startup": true,
				"instance": "",
				"last_missed_heartbeat": 1491385821669,
				"service_name": "moogfarmd",
				"display_name": "moog_farmd",
				"type": "moog_farmd",
				"last_heartbeat": 1491382821669,
				"passive": false,
				"running": false,
				"component": "AlertBuilder",
				"reserved": true,
				"stoppable": true,
				"missed_heartbeats": 10,
				"ha_conf": {
					"cluster": "MOO",
					"instance": "",
					"default_leader": true,
					"start_as_passive": false,
					"only_leader_active": true,
					"group": "moog_farmd"
				}
			},
			"TeamsMgr": {
				"run_on_startup": true,
				"instance": "",
				"last_missed_heartbeat": 1491385821669,
				"service_name": "moogfarmd",
				"display_name": "moog_farmd",
				"type": "moog_farmd",
				"last_heartbeat": 1491382821669,
				"passive": false,
				"running": false,
				"component": "TeamsMgr",
				"reserved": true,
				"stoppable": true,
				"missed_heartbeats": 10,
				"ha_conf": {
					"cluster": "MOO",
					"instance": "",
					"default_leader": true,
					"start_as_passive": false,
					"only_leader_active": true,
					"group": "moog_farmd"
				}
			}
		},
		"instance": "",
		"last_missed_heartbeat": 1491385821669,
		"service_name": "moogfarmd",
		"display_name": "moog_farmd",
		"type": "moog_farmd",
		"last_heartbeat": 1491382821669,
		"additional_health_info": {
			"event_processing_metric": 0.65
		},
		"passive": false,
		"running": false,
		"reserved": true,
		"stoppable": true,
		"missed_heartbeats": 10,
		"ha_conf": {
			"cluster": "MOO",
			"instance": "",
			"default_leader": true,
			"start_as_passive": false,
			"only_leader_active": true,
			"group": "moog_farmd"
		}
	}, {
		"running": false,
		"instance": "",
		"reserved": false,
		"service_name": "restclientlamd",
		"stoppable": true,
		"display_name": "rest_client_lam",
		"type": "lam",
		"ha_conf": {
			"cluster": "MOO",
			"instance": "",
			"group": "rest_client_lam"
		}
	}]
}	

POST parameters

form-urlencoded

POST parameters can be sent as form-urlencoded parameters. To do this, the content type must be set to 
application/x-www-form-urlencoded. If the character set is not set then UTF-8 will be assumed.

Curl Command:

"https://localhost/graze/v1/resolveSituation?auth_token=b40244fd79aa46fba76c60c56d538c49&sitn_id=10" --insecure -X POST -v

application/json

POST parameters can be supplied as JSON within the body of the request. To do this, the content type must be set to application/json. If the character set is not set then UTF-8 will be assumed.

Curl Command:

"https://localhost/graze/v1/resolveSituation" -H "Content-Type: application/json; charset=UTF-8" --insecure -X POST -v --data '{"auth_token" : "b40244fd79aa46fba76c60c56d538c49","sitn_id" : 10}'

HTTP status and error codes

The Graze API returns the following HTTP status and error codes for successful and unsuccessful requests:

HTTP Code

 Meaning

200

Successful request

400

Incorrectly formatted request

401

A request with an invalid or expired auth_code

403    

Forbidden request

500

Failed request, for example due to an invalid sitn_id

2 Comments

  1. This isn't what it does. It fetches the teams for the specified user.

  2. username=admin
    The example specifies username=?, whereas the request arguments table specifies user_id=?