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.

As you would with any API, use caution when employing the Graze API. Excessive requests can impact overall system performance. Take special care when using getSituationIds() or getAlertIds() methods. Overuse of these APIs can have a negative impact on the backend datastore.

To work with a Graze API expert on your solution, you can engage Moogsoft Technical Services. Otherwise contact Moogsoft Support.

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.

Configure Tomcat

You must configure Tomcat 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 a 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 HTTP Status and Error Codes.

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 a 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

 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 HTTP Status and Error Codes.

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

 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 HTTP Status and Error Codes.

 closeAlert

closeAlert 

A POST request that closes one or more alerts.

Request Arguments

Name

 Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request.

alert_idNumberA single alert ID.
alert_idsNumber listA list of alert IDs.
thread_entry_commentStringOptional comment.

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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_ids" : [78,234,737],"thread_entry_comment" : "Closing as agreed during team discussion 1/1/2018" }'

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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 significance 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 the 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 HTTP Status and Error Codes.

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 a 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 HTTP Status and Error Codes.

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 unacknowledges 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 unacknowledged, 1 for acknowledged).

Return Parameter

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

 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 HTTP Status and Error Codes.

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

 assignTeamsToSituation

assignTeamsToSituation

A POST request that assigns one or more teams to a Situation. Once successfully run, Moogsoft AIOps marks the Situation as overridden and the Teams Manager Moolet can no longer modify its team assignment. See Teams Manager Moolet for more information.

The endpoint replaces any teams previously assigned to the Situation. You can also use it to unassign all teams from a Situation.

Request Arguments

Include either team_ids or team_names.

Name

 Type

Description 

sitn_id

Number

The Situation ID.

team_ids

List

A list of team IDs to assign to the Situation. Specify an empty list to unassign all teams from the Situation.

team_namesListA list of team names to assign to the Situation. Specify an empty list to unassign all teams from the Situation.

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Successful requests return a JSON object with one of the following, depending on the input:

Name

Type

Description

team_idsListA list of team IDs assigned to the Situation.
team_namesListA list of team names assigned to the Situation.

Examples

cURL command 1:

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

Return to cURL command 1:

{"team_ids" : [ 1,2 ]}

cURL command 2:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/assignTeamsToSituation" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 2 , "team_names" : [ "Team1", "Team2" ]}'

Return to cURL command 1:

{"team_names" : [ "Team1", "Team2" ]}

Unassign example:

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

Return to unassign example:

{"team_ids" : []}
 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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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"}'

Successful 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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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

getPrcLabels

A GET request that retrieves probable root cause (PRC) information for all alerts or specified alerts within a Situation.

Request Arguments

Name

 Type

Description 

auth_tokenStringA valid  auth_token  returned from the  authenticate  request.
sitn_id

Integer

The Situation ID.

alert_ids

Number list

A list of the alert IDs (optional).

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Example

cURL command:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getPrcLabels?sitn_id=1&alert_ids=[1,2,3,4]"

Successful return:

{
   "non_causal":
     [2,3],
   "unlabelled":
     [4],
   "causal":
     [1]
}
 getSigCorrelationInfo

getSigCorrelationInfo

 A GET request that retrieves 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 HTTP Status and Error Codes.

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

getSimilarSituationIds

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

Request Arguments

Name

 Type

Description 

sitn_idNumberID of the Situation that you want to retrieve similar Situations for.
auth_token

String

A valid auth_token returned from the authenticate request.

limit

Number 

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 HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

 Type

Description 

similiarity_ids

Number listList of IDs of the similar Situations.
sig_idNumberID of the Situation that you requested to retrieve similar Situations for.

Example

Example cURL request to get the first 10 Situation IDs that are similar to Situation ID 1043:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSimilarSituationIds" --data-urlencode 'sitn_id=1043' --data-urlencode 'limit=10'

Successful request return:

{"similarity_ids":[43,156,177,221,576,1026,1327], "sig_id":1043}
 getSimilarSituations

getSimilarSituations

A GET request that returns the details of similar Situations for a specified Situation, a filter and a limit.

Request Arguments

Name

 Type

Description 

sitn_idNumberID of the Situation that you want to retrieve similar Situations for.
auth_token

String

A valid auth_token returned from the authenticate request.

limit

Number 

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 HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

 Type

Description 

similarities

Array

A list with similarity details. For each similar Situation:

  • sim_sig_id: ID of the similar situation.
  • similarity: Similarity value.
  • resolving_steps_count: Number of resolving steps that the similar situation has.
similar_countNumberNumber of similar Situations.
sig_idNumberID of the Situation that you requested to retrieve similar Situations for.

Example

Example cURL request to get the first 20 Situation IDs that are similar to Situation ID 38:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSimilarSituations" --data-urlencode '"sitn_id"=38' --data-urlencode 'limit=20'

Successful request return:

{"similarities":[{"sim_sig_id":39,"similarity":1.0,"resolving_steps_count":0},{"sim_sig_id":40,"similarity":1.0,"resolving_steps_count":0}],"similar_count":2,"sig_id":38}
 getSituationActions

getSituationActions

A GET request that returns the activities 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 requested for.

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

Array

List of action codes.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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. See Situation Action Codes for a list of action codes and their descriptions.

descriptionStringDescription of the action.
detailsStringDetails of the action.
typeStringType of the action.
sig_idIntegerThe situation ID.
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 the 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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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"}
 getSituationIds

getSituationIds

A GET request 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 

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 HTTP Status and Error Codes.

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

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'

Successful request return:

{"total_situations":7,"sitn_ids":[87,121,128,278,523,1003,1519]}
 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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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

getSituationTopology

A GET request that returns a JSON object in NetJSON format that represents nodes affected by the Situation.

Request Arguments

Name

Type

Required

Description 

sitn_id

Number

Yes

Situation ID.

context

Number

No

Number, between 0 and 4, of contextual hops from the nodes directly affected within the Situation to other nodes to be included in the returned object. See Vertex Entropy for more information on contextual hops.

0 = only nodes directly affected by the Situation. Default.

4 = nodes that are up to four hops away from the nodes directly affected by the Situation.

propertiesList of stringsNo

List of the node properties to be returned. Valid properties are:

  • severity: Severity of the node.
  • prc: Whether this node is the probable root cause of the alert.
  • service: Service affected by the node.
  • context: Number of contextual hops between this node and a node directly affected by the Situation. A context of 0 means that the node is directly affected.
  • description: Description of the node.
  • vertex_entropy: Vertex Entropy of the node.
field_nameStringNo

Attribute of the alert that defines the node. The default is the alert 'source' but you can specify any valid alert field, including custom_info attributes. For example, field_name=custom_info.eventDetails.line.

Response

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure. See HTTP Status and Error Codes for details. 

Successful requests return a JSON object containing the following:

Name

Type

Description 

linksIntegerList of links associated with the Situation.
links.source

String

Source node of the link.

links.targetStringTarget node of the link.
nodes

Array

Array of nodes associated with the Situation and their properties. The nodes included depends on the setting of the request property context.

nodes.id

StringNode ID
nodes.propertiesArray

Object containing the properties requested.

See http://netjson.org/ for more information on the topology data format.

Example

The following topology diagram shows the nodes affected by Situation ID 14, with a context of 1. In this example, each node represents a host in a network and the Situation represents a network outage. It shows six nodes directly affected by the Situation, their color depending on their severity, and one node which is one hop away, shown in gray.

The following cURL request demonstrates a request to return nodes affected by the Situation and nodes that are one hop away. The returned object is to contain the properties of severity, Vertex Entropy, Probable Root Cause (PRC), service, and description.

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationTopology" --data-urlencode "sitn_id=14" "context=1" "properties"=["severity","vertex_entropy","prc","service","description"]

The successful response returns the following topology information for this Situation. The response always returns the node names in lower case. Note that there is no PRC value for the node that is not directly affected by the Situation. In this example, consider investigating node "host2835" as the cause of the Situation because it has a high severity and a high PRC.

{
    "links": [
        {
            "source": "host2728",
            "target": "host2736"
        },
        {
            "source": "host2728",
            "target": "host1156"
        },
        {
            "source": "host2835",
            "target": "host2728"
        },
        {
            "source": "host2801",
            "target": "host2827"
        },
        {
            "source": "host2800",
            "target": "host2801"
        },
        {
            "source": "host2801",
            "target": "host2835"
        },
        {
            "source": "host2835",
            "target": "host2736"
        }
    ],
    "nodes": [
        {
            "id": "host2835",
            "properties": {
                "severity": 5,
                "prc": 0.9862626716344282,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.1794592472207979
            }
        },
        {
            "id": "host2736",
            "properties": {
                "severity": 4,
                "prc": 0.42722191049803876,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.08976540495989357
            }
        },
        {
            "id": "host2728",
            "properties": {
                "severity": 3,
                "prc": 0.007672752075071621,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.1794592472207979
            }
        },
        {
            "id": "host2827",
            "properties": {
                "severity": 5,
                "prc": 0.4262762946261391,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.05343516483103129
            }
        },
        {
            "id": "host2801",
            "properties": {
                "severity": 5,
                "prc": 0.42722511225514104,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.23927899629439717
            }
        },
        {
            "id": "host2800",
            "properties": {
                "severity": 5,
                "prc": 0.4269879766269776,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.05343516483103129
            }
        },
        {
            "id": "host1156",
            "properties": {
                "severity": null,
                "prc": null,
                "service": "",
                "context": 1,
                "description": "",
                "vertex_entropy": 0.05343516483103129
            }
        }
    ]
}
 getSituationVisualization

getSituationVisualization

A GET request that returns information on the origin and cause of a specified Situation.

Request Arguments

Name

Type

Required

Description 

auth_token

String

Yes

A valid  auth_token  returned from the authenticate  request.
sitn_id

Number

Yes

Situation ID.

Response

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

Type

Description 

sig_idIntegerSituation ID.
origin

String

Process that caused the Situation to be created, for example, cookbook or manual_merge.

cause

Object

Cause of the Situation. This varies depending on how the Situation was created.

Examples

A cURL request to return the information on the origin and cause of Situation ID 358:

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

A successful response for a Situation created by a Cookbook Recipe returns the following information:

{
    "origin": "cookbook",
    "cause": {
        "cookbook_name": "Default Cookbook",
        "recipe_id": 4,
        "cookbook_id": 7,
        "recipe_name": "Recipe 1",
        "reference_event_id": 6
    },
    "sig_id": 1
}

A successful response for a manually created Situation returns the following information:

{
    "origin": "Manual Creation",
    "cause": {"uid": 3},
    "sig_id": 6
}

A successful response when two Situations have been merged returns the following information:

{
    "origin": "Manual Merge",
    "cause": {
        "uid": 3,
        "merged_sigs": [
            8,
            7
        ]
    },
    "sig_id": 9
}

If there is no Situation visualization data, the response returns the following information:

{
    "additional": {
        "debugMessage": "com.moogsoft.servletutils.CGeneralServerException: com.moogsoft.services.CGeneralServiceException: No visualize data found for Situation ID [2323]"
    },
    "message": "Internal server error",
    "statusCode": 1000
}
 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 HTTP Status and Error Codes.

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"}
 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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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

 setPrcLabels

setPrcLabels

A POST request that sets the probable root cause (PRC) labels for specified alerts within a Situation. You must specify at least one alert ID and a PRC level for the alert.

You can mark alerts as causal, non_causal or unlabelled within a Situation. An alert can have different PRC levels within different Situations.

Request Arguments

Name

Type

Description 

sitn_id

Number

The Situation ID.

alert_ids

Number list

A list of the alert IDs.

causal
non_causal
unlabelled

ListPRC levels.

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Example

cURL command:

curl -POST -u graze:graze -k -v "https://localhost/graze/v1/setPrcLabels" --data-urlencode "sitn_id=1" --data-urlencode "causal=[1]" --data-urlencode "non_causal=[2,3]" --data-urlencode "unlabelled=[4]"

Successful return:

NO RESPONSE TEXT

 setSituationAcknowledgeState

setSituationAcknowledgeState

A POST request that acknowledges or unacknowledges the moderator to the Situation for a specified Situation ID and acknowledged state.

Request Arguments

Name

Type

Description 

sitn_id

Number

The Situation ID.

acknowledged

Number

The acknowledge state (0 for unacknowledged, 1 for acknowledged).

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 a Moogsoft 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 HTTP Status and Error Codes.

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 
 authenticate

authenticate

A GET request that provides the auth_token required by all other Graze API requests which do 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"

Successful request 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 are 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 does not expire.

 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 is 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 HTTP Status and Error Codes.

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, for example, "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. Defaults to the 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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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 returns data for the top 10 teams.

from
NumberThe time from when the data points will be collected. This is a timestamp from epoch in seconds.
to
NumberThe time until when the data points will be collected. This is a timestamp from epoch in seconds.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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)

Example

cURL command:

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'

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 HTTP Status and Error Codes.

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.

limit Integer
(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 modifies an existing team.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request.

team_idNumberThe team ID (required).
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 HTTP Status and Error Codes.

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 modifies an existing user.

Request Arguments

Name

Type

Description 

auth_token

String

A valid auth_token returned from the authenticate request.

username

String

Username for user to be edited. Required (optional if user ID is used).

uid
LongUser ID for user to be edited. Required (optional if username used).
password
String

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

active
Booleantrue if the user active, false if the user inactive. Defaults to true. Optional.
email
StringUser's email address. Optional.
fullname
StringUser's full name. Optional.
roles
JSON listA list that should contain either the list of the role IDs or the role names, for example, "roles":["Super User"]. Optional.
primary_group
String or NumberUser's primary group name or primary group ID. Optional.
department
String or numberUser's department ID or name. Optional.
timezone
StringUser's timezone. Optional.
contact_num
StringUser's phone number. Optional.
session_expiry
NumberNumber of minutes after which the user session will expire. Default to system default. Optional.
competencies
JSON list

A list with the user competencies. Optional. 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. Optional.

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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

Security Realms

 createSecurityRealm

createSecurityRealm

A POST request that creates a new security realm from an Identity Provider (IdP) URL. The request also adds the realm configuration you provide.

Warn any users who logged into Moogsoft AIOps using the default realm before using this request. The system may log out users when the new realm becomes active.

Request Arguments

Name

Type

Description

name

String
(Required)

Name of the security realm.
typeString
(Required)
Security realm type. This must be "SAML2".
activeBoolean
(Required)

Determines whether the new realm is active in Moogsoft AIOps on creation.

You can create an inactive realm for testing purposes. For example, you can verify if a security realm with that name already exists or if it fails.

configurationJSON Object
(Required)

JSON object containing the realm configuration. For information on the configuration properties, see Security Configuration Reference.

Upload your IdP metadata file using idpMetadata or specify the location of the file using idpMetadataUrl. For example:

  • "idpMetadataUrl":"http://<location_of_idp_metadata>"
  • "idpMetadata":"<raw_ipd_metadata.xml>"

Response

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Example

cURL command example to create a SAML realm that maps users to the default user mappings and has a maximum authentication lifetime of 60 seconds:

curl -X POST \
	-u graze:graze \ 
	-k -v "https://localhost/graze/v1/createSecurityRealm" \
	-d {"name"="mySamlRealm", "type"="SAML2","active="true","configuration"=
	{
	"idpMetadataUrl":"http://exampleIdP:18080/auth/realms/master/protocol/saml/descriptor",
	"defaultRoles":["Operator"],
	"defaultTeams":["Cloud DevOps"],
	"defaultGroup":"End-User",
	"existingUserMappingField":"username",
	"username":"$username",
	"email":"$email",
	"fullname":"$firstname $lastname",
	"maximumAuthenticationLifetime":60
	}
}

A successful request returns an HTTP 200 response.

 getSecurityRealm

getSecurityRealm

A GET request that returns a JSON object containing the names and configuration details of active security realms.

Request Arguments

None required.

Response

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Example

cURL command to return the configuration of any active security realm in Moogsoft AIOps:

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

Successful requests return a JSON object representing the active realms. The following example shows a test SAML realm and a Google realm:

{
	"Test Saml Realm": {
		"configuration":  {
			"defaultGroup":"EndUser",
			"realmType":"SAML2",
			"existingUserMappingField":"username",
			"spMetadataFile":"/usr/share/moogsoft/config/keycloak.my_sp_metadata.xml",
			"defaultRoles":["Operator"],
			"defaultTeams":["Cloud DevOps"],
			"fullname":"$FirstName $LastName",
			"email":"$Email",
			"idpMetadataFile":"/usr/share/moogsoft/config/keycloak.my_idp_metadata.xml",
			"username":"$Email",
			"maximumAuthenticationLifetime":60},
			"name":"Test Saml Realm",
			"active":true,
			"type":"SAML2"	
					 }
	,"Google realm": {
		"configuration": {
			"realmType":"GOOGLE"},
			"name":"Google realm",
			"active":true,"type":"GOOGLE"}
}
 updateSecurityRealm

updateSecurityRealm

A POST request that updates an existing security realm in the database.

Warn any users who logged into Moogsoft AIOps using the default realm before using this request. The system may log out users when the updated realm becomes active.

Request Arguments

Name

Type

Description

name

String
(Required)

Name of the security realm.
typeStringSecurity realm type. This must be "SAML2".
activeBooleanDetermines whether the new realm is active or not.
configurationJSON ObjectJSON object containing the realm configuration. You must include all mandatory configuration properties; otherwise the request returns an error. For information on the configuration properties, see Security Configuration Reference.

Response

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Example

cURL command to update a SAML realm with a new X509 certificate:

curl -X POST \
     -u graze:graze \
     -k -v "https://localhost/graze/v1/updateSecurityRealm" \
     -d {"name"="mySamlRealm"
     -d 'configuration=
     {
	 "idpMetadata":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\r\n<EntitiesDescriptor Name=\"urn:keycloak\" xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\"\r\nxmlns:dsig=\"http:\/\/www.w3.org\/2000\/09\/xmldsig#\">\r\n<EntityDescriptor entityID=\"http:\/\/moogsaml:18080\/auth\/realms\/master\">\r\n<IDPSSODescriptor WantAuthnRequestsSigned=\"true\"\r\nprotocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\">\r\n<KeyDescriptor use=\"signing\">\r\n<dsig:KeyInfo>\r\n<dsig:KeyName>l8ddhI8SroeNnlq0TkTxIj2VI-				    0bvr2QfG_o32jWeKI<\/dsig:KeyName>\r\n<dsig:X509Data>\r\n<dsig:X509Certificate>MIICmzCCAYMCBgFk8A9vMjANBgkqhkiG9w0BAQsFADARMQ8wDQYDVQQDDAZtYXN0ZXIwHhcNMTgwNzMxMTExNjQwWhcNMjgwNzMxMTExODIwWjARMQ8wDQYDVQQDDAZtYXN0ZXIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCOliZ3dBu696slYduAb1BMuvR1bMdTKVBMICWaEEcS8Rzw8gWthPQpw2e202LjOeu4VkTVmEEAUa2IrLS4QpYgyhOuzapcIGF4kB0ARebalWa7C9od9%2BeTqWgvXPrDOkzp7g%2B%2Ba5yvtKxE3ieUORPpACvLWcbkMwyb%2Be5V8%2Bz8n4263Uol8srSaxLsm\/oTozJNwbG%2BbzV8JQHU3xFV5nFbyNySvc%2B\/B7tDFZuJC5BMu6bwi\/rPqp5OMcuB1W%2BxCcX7IYPphnBjRWNyQJD3gRCkjrujISkTEcqpZEjR79isbofQaPDi5TSjglPD5rr0OWMVqv91a1\/pVN2y0y%2BRlT8HAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAAgRhWYKESVsTRAUVYzHYptd3\/eX47%2BTVXhjPO0ORLUJbHtfhgohtyejd6ohazkcSgMy6%2BwaeVojqq4Q\/tzCOW2EAqO9QOQdaBWOPxDXhJ9TGQJE2E28SS2Gg6paAMfRmtA7c6xXii%2BYfLo3PG1SSc\/sGe4KIPKflkqqDEqEeaY1olPZU2bLnpMSIui2nK1crE2%2Bt9apLWAGosah6scMGZ9vTrtOVrNuhB2LuU3cvRQWrUBaQuXQsBV7Q6a8lkrrZ6rjAIbO4vcEL4yjQpnA%2BhetuhBlGPQj6ntuhdnmoKmWYY97wk8eXwblhQxg8GUyfqabfOAKwiGAklxgkexm20M=<\/dsig:X509Certificate>\r\n<\/dsig:X509Data>\r\n<\/dsig:KeyInfo>\r\n<\/KeyDescriptor>\r\n\r\n<SingleLogoutService\r\nBinding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\"\r\nLocation=\"http:\/\/moogsaml:18080\/auth\/realms\/master\/protocol\/saml\" \/>\r\n<SingleLogoutService\r\nBinding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"\r\nLocation=\"http:\/\/moogsaml:18080\/auth\/realms\/master\/protocol\/saml\" \/>\r\n<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent<\/NameIDFormat>\r\n<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient<\/NameIDFormat>\r\n<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified<\/NameIDFormat>\r\n<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress<\/NameIDFormat>\r\n<SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\"\r\nLocation=\"http:\/\/moogsaml:18080\/auth\/realms\/master\/protocol\/saml\" \/>\r\n<SingleSignOnService\r\nBinding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"\r\nLocation=\"http:\/\/moogsaml:18080\/auth\/realms\/master\/protocol\/saml\" \/>\r\n<SingleSignOnService\r\nBinding=\"urn:oasis:names:tc:SAML:2.0:bindings:SOAP\"\r\nLocation=\"http:\/\/moogsaml:18080\/auth\/realms\/master\/protocol\/saml\" \/>\r\n<\/IDPSSODescriptor>\r\n<\/EntityDescriptor>\r\n<\/EntitiesDescriptor>",
     "defaultRoles":["Operator"],
     "defaultTeams":["Cloud DevOps"],
     "defaultGroup":"End-User",
     "existingUserMappingField":"username",
     "username":"$username",
     "email":"$email",
     "fullname":"$firstname $lastname",
     "maximumAuthenticationLifetime":60
     }'

cURL command to deactivate an active SAML realm:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/updateSecurityRealm" -d "name=mySamlRealm" -d "active=false"

Successful return:

A successful request returns an HTTP 200 response.

Dashboards and Reporting

 getMTTAStats

getMTTAStats

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

Request Argument

Name

Type

Description 

from
NumberThe time from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberThe time until when the data points will be collected. A timestamp from epoch in seconds.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"mtt_acknowledge"

datapoints

Number array

An array containing multiple nested arrays of datapoints (timestamp + value).

Example

cURL command:

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

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"
}]
 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
NumberThe time from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberThe time until when the data points will be collected. A timestamp from epoch in seconds.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"mtt_detect"

datapoints

Number array

An array containing multiple nested arrays of datapoints (timestamp + value).

Example

cURL command:

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

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"
}]
 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
NumberThe time from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberThe time until when the data points will be collected. A timestamp from epoch in seconds.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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)

Example

cURL command:

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

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

getReassignedSituationStats

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

Request Argument

Name

Type

Description 

from
NumberTime from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberTime until when the data points will be collected. A timestamp from epoch in seconds.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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)

Example

cURL command:

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

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

getReoccurringSituationStats

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

Request Argument

Name

Type

Description 

from
NumberTime from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberTime until when the data points will be collected. A timestamp from epoch in seconds.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"Reoccurring Situation"

datapoints

Number array

An array containing multiple nested arrays of datapoints (timestamp + value).

Example

cURL command:

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

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"
}]
 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 returns empty data.
from
NumberTime from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberTime until when the data points will be collected. A timestamp from epoch in seconds.
aggregation
String

Can be one of:

  • "none" - No aggregation of results.
  • "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 HTTP Status and Error Codes.

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)

Example

cURL command:

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'

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"
}]
 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 a default set of severities: Clear, Indeterminate, Warning, Minor, Major, Critical.
from
NumberTime from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberTime until when the data points will be collected. A timestamp from epoch in seconds.
aggregation
String

Can be one of:

  • "none" - No aggregation of results.
  • "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 HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

The name of the status.

datapoints

Number array

An array containing multiple nested arrays of datapoints (timestamp + value).

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'

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"
}]
 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 a default set of statuses: Opened, Unassigned, Assigned, Acknowledged, Unacknowledged, Resolved.
from
NumberTime from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberTime until when the data points will be collected. A timestamp from epoch in seconds.
aggregation
String

Can be one of:

  • "none" - No aggregation of results.
  • "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 HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

The name of the status.

datapoints

Number array

An array containing multiple nested arrays of datapoints (timestamp + value).

Example

cURL command:

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'

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

getSystemSituationStats

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

Request Argument

Name

Type

Description 

from
NumberThe time from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberThe time until when the data points will be collected. A timestamp from epoch in seconds.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

Type

Description 

target

String

"System"

datapoints

Number array

An array containing multiple nested arrays of datapoints (timestamp + value).

Example

cURL command:

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

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

getTeamSituationStats

A GET request that returns the number of active Situations assigned 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 returns empty data.

from
NumberThe time from when the data points will be collected. A timestamp from epoch in seconds.
to
NumberThe time until when the data points will be collected. A timestamp from epoch in seconds.
aggregation
String

Can be one of:

  • "none" - No aggregation of results.
  • "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 HTTP Status and Error Codes.


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).

Example

cURL command:

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'

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

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 HTTP Status and Error Codes.

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 HTTP Status and Error Codes.

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. The maintenance window filters alerts caused by a known period of maintenance.

Request Arguments

NameTypeDescription
auth_token

String
(Optional)

A valid auth_token returned from the authenticate request.

nameString
(Required)
Name of the maintenance window.
descriptionString
(Required)
Description of the maintenance window.
filterString
(Required)
JSON or SQL-like filter for alerts to match. The filter must be in JSON format, that is, the same format used in alert and Situation filters in the database.
start_date_timeEpoch Seconds (Number)
(Required)
Start time of the maintenance window. This must be in epoch time and may be up to 5 years in the future.
durationSeconds (Number)
(Required)
Duration of the maintenance window in seconds. The minimum duration is 1 second and the maximum is 157784630 seconds ( 5 years).
forward_alertsBoolean
(Required)

Defines whether or not alerts should be forwarded to the next Moolet in the processing chain.

recurring_periodNumber
(Optional)

Whether or not this is a recurring maintenance window. Set this to:

  • 1 for a recurring maintenance window.
  • 0 for a one-time maintenance window.

If not specified, defaults to 0. If you set this property to 1, you must specify recurring_period_units.

recurring_period_unitsNumber
(Optional)
Specifies the recurring period of the maintenance window, in days, weeks or months. Defaults to 0 if recurring_period is set to 0 . V alid values are:
  • 2 = daily
  • 3 = weekly
  • 4 = monthly

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Successful requests return a JSON object with the following:

Name

Type

Description 

window_id

Number

The new maintenance window ID.

Example

Example cURL request to create a window, which recurs once a month (from its start_date_time), with a filter where the source is 'server1' and the external ID is one of 'value1', 'value2', or '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, "recurring_period": 1, "recurring_period_units": 4}'

Example cURL request to create a one-time  maintenance window, which is filtered when the source is equal to 'hostWhichIsDown':

curl "https://<YOUR_HOSTNAME>:8080/graze/v1/createMaintenanceWindow" -H "Content-Type: application/json; charset=UTF-8" --insecure -X POST -v --data '{"auth_token": "<YOUR_GRAZE_AUTH_TOKEN>", "name": "my_window_1", "description": "This is my description", "filter": { "column": "source", "op": 0, "value": "hostWhichIsDown", "type": "LEAF" }, "start_date_time": 1473849237, "duration": 55800, "forward_alerts": false}

Successful request return:

{"window_id":16}
 deleteMaintenanceWindows

deleteMaintenanceWindows

A POST request that deletes a maintenance window.

ParameterTypeDescription
auth_token

String

A valid auth_token returned from the authenticate request.

idNumberID of the maintenance window to delete.

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Example

Example cURL request to delete a maintenance window:

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

Successful return:

NO RESPONSE TEXT

 findMaintenanceWindows

findMaintenanceWindows


A GET request that returns maintenance windows that match 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 (defaults to 100).

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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}]}
 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 HTTP Status and Error Codes.

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 maintenance windows, not expired or deleted 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, that is, 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 HTTP Status and Error Codes.

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

getProcesses

A GET request that returns the list of processes.

Request Arguments

Name

Type

Description 

auth_token
StringA valid  auth_token  returned from the  authenticate  request. Required.
limit
IntegerThe maximum number of results that are returned. Optional. Default is 1000.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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.

Example

cURL command:

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

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
StringA valid auth_token returned from the authenticate request. Required.
limit
IntegerThe maximum number of results that are returned. Optional. Default is 1000.

Return Parameters

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

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.

Example

cURL command:

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

Successful request return:

[{
	"service_id": 15,
	"service_name": "Service A"
}, {
	"service_id": 4,
	"service_name": "Service B"
}]
 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 HTTP Status and Error Codes.

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.

Example

cURL command:

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

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
}]
 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 HTTP Status and Error Codes.

Example

cURL command:

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

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 HTTP Status and Error Codes.

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.

Example

cURL command:

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

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"
}]
 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 HTTP Status and Error Codes.

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, for example, lam, servlets, moog_farmd.
passiveBoolean

Indicates whether the service is passive in a HA environment:

  • true = passive
  • false = active
stoppableBoolean

Indicates whether or not the service can be stopped:

  • true = stoppable
  • false = not stoppable
ha_confJSON ObjectA Json blob containing the HA configuration.
additional_health_infoJSON ObjectAdditional health information. The pools section includes health information for processes with an internal pool.

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"
			}
		"additional_health_info": {
			"pools": {
				"MoogPoller": [{
				"removed": 0,
				"ration": 0.0,
				"busy": 0,
				"resource_type": "com.mysql.jdbc.JDBC4Connection",
				"checkout_per_second": 0.0,
				"free": 10,
				"avg_checkedout_seconds": 0.0,
				"capacity": 10
				}],
				"Message sender pool": [{
				"removed": 0,
				"ration": 0.0,
				"busy": 0,
				"resource_type": "com.moogsoft.mooms.CMoomsMessageSender",
				"checkout_per_second": 0.09997000899730081,
				"free": 10,
				"avg_checkedout_seconds": 0.002,
				"capacity": 10
				}]
			}
	}]
}	
 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 HTTP Status and Error Codes.

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

updateMaintenanceWindow

A POST request that updates an existing maintenance window.

Request Arguments

NameTypeDescription
window_idString
(Required)
ID of the existing maintenance window.
auth_token

String
(Optional)

A valid auth_token returned from the authenticate request.

nameString
(Optional)
Name of the maintenance window.
descriptionString
(Optional)
Description of the maintenance window.
filterString
(Optional)
JSON or SQL-like filter for alerts to match. The filter must be in JSON format, that is, the same format used in alert and Situation filters in the database. You cannot change the filter of an active maintenance window.
start_date_timeEpoch Seconds (Number)
(Optional)
Start time of the maintenance window. This must be in epoch time and may be up to 5 years in the future. You cannot change the start_date_time of an active maintenance window.
durationSeconds (Number)
(Optional)
Duration of the maintenance window in seconds. The minimum duration is 1 second and the maximum is 157784630 seconds (5 years).
forward_alerts Boolean
(Optional)

Whether or not alerts are forwarded to the next Moolet in the processing chain. If you change this from false to true, only alerts received after the change are forwarded.

recurring_periodNumber
(Optional)

Whether or not this is a recurring maintenance window. Set this to:

  • 1 for a recurring maintenance window.
  • 0 for a one-time maintenance window.

If you change this from 0 to 1, you must specify recurring_period_units.

recurring_period_unitsNumber
(Optional)

Specifies the recurring period of the maintenance window, in days, weeks or months. If you set recurring_period to 0, you must set recurring_period_units to 0 . Valid values are:

  • 0 = a one-time maintenance window
  • 2 = daily
  • 3 = weekly
  • 4 = monthly

Return Parameter

Type

 Description

HTTP code

HTTP status or error code indicating request success or failure.
For codes, see HTTP Status and Error Codes.

Examples

Example cURL request to update all the parameters in the existing maintenance window 351:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/updateMaintenanceWindow" -H "Content-Type: application/json; charset=UTF-8" -d '{"window_id":351, "name":"Updated name", "description":"Updated Description", "filter":"source = \"server1\"", "start_date_time":1546433400, "duration":3600, "forward_alerts":false, "recurring_period":1, "recurring_period_units":3}'

Example cURL request to update the existing maintenance window 27 so that it will not occur again:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/updateMaintenanceWindow" -H "Content-Type: application/json; charset=UTF-8" -d '{"window_id":27, "recurring_period":0, "recurring_period_units":0}'

Successful return:

A successful request returns an HTTP 200 response.

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 is 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 is 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.

404Not found, for example, the sitn_id could not be found because it does not exist.

500

Failed request, for example, due to an invalid sitn_id.

3 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=?
  3. We can still give the single alert_id  (for backwards compatibility) so needs to be added back in