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

The Graze API acts as an integration point for external services, such as ServiceNow. It 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:

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

where server is the hostname of the machine running the UI 

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" : "value2" , "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*

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" : "value2" , "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] 
}
 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.

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}
 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"]).  The process names must exist in the database. If not, they are ignored

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"]).  The service names must exist in the database. If not, they are ignored

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

 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

 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}
 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]}
 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"}]
 getUserTeams

getUserTeams

Fetches the teams 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

Workflow

 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/deleteMaintenanceWindow" -H "Content-Type: application/json; charset=UTF-8" -d '{"id":1}'

Successful Command:

NO RESPONSE TEXT

 getMaintenanceWindows

getMaintenanceWindows

A GET request that returns the maintenance windows based on the window id and how many should be fetched.


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}]}
 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

1 Comment

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