Moogsoft Docs

Graze API

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 and getAlertIds. Overusing these endpoints 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.

Note

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

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

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

String

A 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

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

Example

Curl Command:

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

Successful Return:

NO RESPONSE TEXT

assignAndAcknowledgeAlert

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

String

A 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

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_id

Number

A single alert ID.

alert_ids

Number list

A list of alert IDs.

thread_entry_comment

String

Optional 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

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

getAlertActions

A GET request that returns the actions for alerts, ordered most recent last. You can use the from and to arguments to specify a period that you want to retrieve alert actions for. If you do not specify these, actions for all dates and times are returned.

Request Parameters

Name

Type

Required

Description

auth_token

String

No

A valid auth_token returned from the authenticate request.

alert_ids

Number list

No

List of alert IDs.

start

Integer

Yes

Starting row from which data should be included.

limit

Integer

Yes

Maximum number of actions you want to return.

actions

Number list

No

List of action codes. If no action codes are specified, all action codes are returned. See Alert Action Codes for a list of action codes and their descriptions. Only action codes 8 (Alert Resolved) and 9 (Alert Closed) are valid.

from

Number

No

Start time (in Unix epoch time) of the period you want to retrieve alert actions for.

to

Number

No

End time (in Unix epoch time) of the period you want to retrieve alert actions for.

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

uid

Number

User ID.

action_code

Number list

Code for the action in the JSON object. See Alert Action Codes for a list of action codes and their descriptions.

description

String

Description of the action.

details

String

Details of the action.

type

String

Type of action.

alert_id

Integer

Alert ID.

timed_at

Integer

Time stamp of the action.

Example

Example cURL command to return the first 50 actions for alert IDs 1, 2, 3, and 6 for action codes 8 (Alert Resolved) and 9 (Alert Closed):

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

Example cURL command to return the first 50 actions for action codes 8 (Alert Resolved) and 9 (Alert Closed) between Unix epoch times 1553861746 and 1553872546:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getAlertActions" --data-urlencode 'actions=[8, 9]' --data-urlencode 'limit=50' --data-urlencode 'start=0' --data-urlencode 'from=1553861746' --data-urlencode 'to=1553872546'

Successful return request:

[{ 
   "uid": 49, 
   "action_code": 8, 
   "description": "Alert Resolved", 
   "details": {}, 
   "alert_id": 1, 
   "timed_at": 1557504393 
   }, { 
   "uid": 49, 
   "action_code": 9, 
   "description": "Alert Closed", 
   "details": {}, 
   "alert_id": 1, 
   "timed_at": 1557504912 
   }
}]
getAlertDetails

A GET request that returns details, such as Description or Severity, 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

Number

The 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

1

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

1

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

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

String

A 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

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

resolveAlerts

A POST request that resolves one or more alerts.

Request Arguments

Name

Type

Required

Description

alert_ids

Number list

Yes

List of IDs of the alerts you want to resolve.

thread_entry_comment

String

No

Comment you want to add to the resolved alerts.

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

Boolean

Whether or not the alerts were resolved.

resolved_alerts

Number list

List of IDs of alerts that were resolved.

failed_alerts

Number list

List of IDs of alerts that failed to be resolved.

Example

Example cURL command to set alerts 45, 76, and 352 as resolved with the comment 'Resolved':

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/resolveAlerts" -H "Content-Type: application/json; charset=UTF-8" -d '{"alert_ids" : [45,76,352], "thread_entry_comment" : "Resolved"}'

Example return showing that alerts 45, 76 and 352 were successfully resolved and no alerts failed:

{"status":true,"resolved_alerts":[45,76,352],"failed_alerts":[]}
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

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

1

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

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

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

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

Threads are comments or 'story activity' on Situations.

This endpoint returns the entry ID of the newly created thread entry.

Request Arguments

Name

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

sitn_id

Number

Situation ID.

thread_name

String

Name of the existing thread.

entry

String

Description of the new entry you want to add to the thread. For example, 'And another thing...'.

resolving_step

Boolean

Whether or not the thread entry you are adding is a resolving step.

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 containing the following:

Name

Type

Description

entry_id

Number

ID of the new thread entry.

Example

Example cURL request to add a new entry to thread "Support" in Situation 3:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addThreadEntry" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 3, "thread_name" : "Support", "entry" : "Test Entry", "resolving_step" : true}'

Successful request return providing the ID of the thread entry that has been created:

{"entry_id":27}
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

String

A 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

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.

username

String

A 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

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_names

List

A 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_ids

List

A list of team IDs assigned to the Situation.

team_names

List

A 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

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.

1

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

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

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

createThreadEntry

Note

This endpoint has been superseded. Use addThreadEntry instead. All new functionality will be delivered in addThreadEntry.

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

Threads are comments or 'story activity' on Situations.

This endpoint returns a Boolean indicating whether or not the thread entry was created successfully.

Request Arguments

Name

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

sitn_id

Number

Situation ID.

thread_name

String

Name of the existing thread.

entry

String

Description of the new entry you want to create in the thread. For example, 'And another thing...'.

resolving_step

Boolean

Whether or not the thread entry you are creating is a resolving step.

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 containing the following:

Type

Description

Boolean

Whether or not the new thread entry was created successfully.

Example

Example cURL request to create a new entry in thread "Support" in Situation 3:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/createThreadEntry" -H "Content-Type: application/json; charset=UTF-8" -d '{"sitn_id" : 3, "thread_name" : "Support", "entry" : "Test Entry", "resolving_step" : true}'

Successful request return showing that the new thread entry was successfully created:

true
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

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

A GET request that returns thread entries for a specified Situation that have been marked as resolving steps. Threads are comments or 'story activity' on Situations. Operators can mark one or more thread entries as steps that were used to resolve a Situation.

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

Required

Description

auth_token

String

No

A valid auth_token returned from the authenticate request.

sitn_id

Number

Yes

Situation ID.

start 

Number

No

Number of the first thread resolving entry to return (default = 0).

limit

Number

No

Maximum number of resolving 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

Situation ID.

resolving_entries

List

A list of resolving thread entries. See below.

The resolving_entries list contains the following sub-parameters:

Name

Type

Description

entry_text

String

Text of the resolving entry.

user_id

Number

ID of the user that created the resolving entry.

thread_name

String

Name of the thread that the resolving entry is in.

time

Number

Timestamp (in Unix epoch time) of when the resolving entry was created.

entry_id

Number

ID of the resolving thread entry.

Example

Example cURL command requesting the first 100 resolving thread entries in Situation 358:

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

Example cURL command requesting the first 10 resolving thread entries in Situation 358:

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

Successful request return showing the three resolving thread entries in Situation 358:

{"sitn_id":358,
"resolving_entries":
[
{"entry_text":"hah","user_id":3,"thread_name":"Support","time":1549387456,"entry_id":1722},
{"entry_text":"asdfdsf","user_id":3,"thread_name":"Support","time":1549385762,"entry_id":1721},
{"entry_text":"sdfsdf\n","user_id":3,"thread_name":"Support","time":1549385747,"entry_id":1720}
]
}
mergeSituations

A POST request that merges multiple specified Situations. You can configure whether to the new Situation supersedes the original Situations or not using the supersede_original parameter.

Request Arguments

Name

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

situations

Integer

A comma-separated list of the Situations you want to merge.

supersede_original

Boolean

Determines whether the original merged Situations are superseded by the new 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 the following:

Name

Type

Description

sitn_id

Number

The new Situation ID.

Example

A cURL command:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/mergeSituations?auth_token=c4316d2cac524b96a1e4c787b68f7e3f&situations=%5B31%2C32%2C33%5D&supersede_original=false"

Successful request return:

{"sitn_id":30}
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_token

String

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

A GET request that returns thread entries that have been marked as resolving steps for a specified Situation. Threads are comments or 'story activity' on Situations. Operators can mark one or more thread entries as resolving steps.

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

Situation ID.

start 

Number

Number of the first thread resolving entry to return (default = 0). Optional.

limit

Number

Maximum number of resolving thread entries to return (default = 100). 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.

Successful requests return a JSON object containing the following:

Name

Type

Description

sitn_id

Number

Situation ID.

resolving_entries

List

A list of resolving thread entries. See below.

The resolving_entries list contains the following sub-parameters:

Name

Type

Description

entry_text

String

Text of the resolving entry.

user_id

Number

ID of the user that created the resolving entry.

thread_name

String

Name of the thread that the resolving entry is in.

time

Number

Timestamp (in Unix epoch time) of when the resolving entry was created.

entry_id

Number

ID of the resolving thread entry.

Example

Example cURL command requesting the first 100 resolving thread entries in Situation 358:

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

Example cURL command requesting the first 10 resolving thread entries in Situation 358:

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

Successful request return showing the three resolving thread entries in Situation 358:

{"sitn_id":358,
"resolving_entries":
[
{"entry_text":"hah","user_id":3,"thread_name":"Support","time":1549387456,"entry_id":1722},
{"entry_text":"asdfdsf","user_id":3,"thread_name":"Support","time":1549385762,"entry_id":1721},
{"entry_text":"sdfsdf\n","user_id":3,"thread_name":"Support","time":1549385747,"entry_id":1720}
]
}
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

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_id

Number

ID 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 list

List of IDs of the similar Situations.

sig_id

Number

ID 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

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_id

Number

ID 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_count

Number

Number of similar Situations.

sig_id

Number

ID 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

A GET request that returns the actions for Situations, ordered most recent last. You can use the from and to arguments to specify a period that you want to retrieve Situation actions for. If you do not specify these, actions for all dates and times are returned.

Request Arguments

Name

Type

Required

Description

auth_token

String

No

A valid auth_token returned from the authenticate request.

sitn_ids

Array

Yes

Array of Situation IDs that the actions are requested for.

start

Integer

Yes

Starting row from which data should be included in results.

limit

Integer

Yes

Number of actions you want to return.

actions

Array

No

List of action codes. If no action codes are specified, all action codes are returned. See Situation Action Codes for a list of action codes and their descriptions.

from

Number

No

Start time (in Unix epoch time) of the period you want to retrieve Situation actions for.

to

Number

No

End time (in Unix epoch time) of the period you want to retrieve Situation actions for.

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

description

String

Description of the action.

details

String

Details of the action.

type

String

Type of action.

sig_id

Integer

The Situation ID.

timed_at

Integer

Time stamp of the action.

Examples

Example cURL command to retrieve the first three actions for Situations 1, 2, 3 and 6:

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'

Example cURL command to retrieve the first 50 actions for Situations 1, 2, 3 and 6 between Unix epoch times 1553861746 and 1553872546:

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=50' --data-urlencode 'start=0' --data-urlencode 'from=1553861746' --data-urlencode 'to=1553872546'

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

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

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

A GET request that returns the hosts 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.

for_unique_alerts

Boolean

Optional setting to return hosts for Situations with unique alerts. Defaults to false.

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

hosts

JSON Object

An array of all hosts that sent alerts contained in the specified Situation.

Example

cURL command:

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

Successful request return:

{  
   hosts:[  
      "xldn1204pap",
      "xldn1215pap",
      "xldn1220pap",
      "vxldn1230pap",
      "xldn1241pap",
      "xldn1252pap",
      "xldn1271pap",
      "xldn1278pap",
      "xldn1297pap",
      "xldn1299pap"
   ]
}
getSituationDetails

A GET request that returns the details 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

hosts

JSON Object

An array of the details for the specified Situation.

Example

cURL command:

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

Successful request return:

{  
   "category":"Detected",
   "created_at":1415814620,
   "custom_info":null,
   "description":"Sigaliser situation",
   "first_event_time":1415814600,
   "internal_priority":0,
   "last_event_time":1415814619,
   "last_state_change":1415868947,
   "moderator_id":2,
   "sitn_id":3,
   "status":1,
   "story_id":3,
   "superseded_by":null,
   "total_alerts":1403,
   "total_unique_alerts":1403
}
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 list

A 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

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

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

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.

properties

List of strings

No

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_name

String

No

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.

For codes, see HTTP Status and Error Codes.

Successful requests return a JSON object containing the following:

Name

Type

Description

links

Integer

List of links associated with the Situation.

links.source

String

Source node of the link.

links.target

String

Target 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

String

Node ID

nodes.properties

Array

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.

29962200.png

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, anddescription.

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

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_id

Integer

Situation 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

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

Situation ID.

thread_name

String

Name of the thread to get entries from.

start 

Number

Number of the first thread entry to return (default = 0).

limit

Number

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

entries

List

A list of thread entries. See below.

sitn_id

Number

Situation ID.

thread_name

String

Name of the thread that the entries are from.

The entries list contains the following sub-parameters:

Name

Type

Description

entry_text

String

Text of the entry.

user_id

Number

User ID of the user that created the entry.

time

Number

Timestamp (in Unix epoch time) of when the entry was created.

entry_id

Number

ID of the thread entry.

Example

Example cURL command requesting the first 10 thread entries on thread "Support" in Situation 358:

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 showing the two thread entries on thread "Support" in Situation 358:

{"entries":
[
{"entry_text":"Test Entry","user_id":4,"time":1549455051, "entry_id" : 2},
{"entry_text":"Test Entry",  "user_id":4, "time":1549455053, "entry_id" : 1}
],
"sitn_id":358,"thread_name":"Support"
}
getTopPrcDetails

A GET request that retrieves the top most likely causal alerts, based on their Probable Root Cause value, for a specified Situation ID.

You can select the maximum number of causal alerts to return using a limit value. If not specified, the endpoint only returns the alert with the highest root cause probability.

The entries returned are ordered with the highest root cause probability first, irrespective of whether they have been labelled causal or are unlabelled. Alerts marked as symptoms are excluded from the return.

Request Argument

Name

Type

Required

Description

sitn_id

Integer

Yes

ID of the Situation you want to retrieve the Probable Root Cause details for.

limit

Integer

No

Maximum number of causal or unlabelled alerts to return.

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 multiple sets of the following data:

Name

Type

Description

rc_probability

Number

Root cause probability of the alert.

rc_label

Integer

Label defining whether the alert is causal or not:

  • 1 = causal

  • 0 = unlabelled

  • -1 = symptom

description

String

Description of the alert.

alert_id

Integer

Alert ID.

Request Example

A cURL request to retrieve the top three causal alerts with the highest root cause probability in Situation 145:

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getTopPrcDetails" --data-urlencode 'sitn_id=145' --data-urlencode 'limit=3'

Response Example

A successful response returns the top three causal or unlabelled alerts:

{
    "alerts": [
        {
            "rc_probability":0.9933107459030244,
            "description":"Web Server HTTPD is DOWN",
            "rc_label":1,
            "alert_id":53
        },
        {
            "rc_probability":0.9933092393241993,
            "description":"Web Server HTTPD is DOWN",
            "rc_label":1,
            "alert_id":8
        },
        {
            "rc_probability":0.22480057080448923,
            "description":"Web Server HTTPD is DOWN",
            "rc_label":0,
            "alert_id":39
        }
    ]
}
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.

serviceName

String

The service name (optional).

externalId

String

The 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

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

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

List

PRC 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

setResolvingThreadEntry

A POST request that sets or clears a thread entry in a Situation as a resolving step.

Threads are comments or 'story activity' on Situations.

This endpoint returns a Boolean indicating whether the thread entry was successfully set or cleared as a resolving step.

Request Arguments

Name

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

entry_id

String

ID of the thread entry.

resolving_step

Boolean

Whether you are setting or clearing the thread entry as a resolving step.

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 containing the following:

Type

Description

Boolean

Whether or not the thread entry was successfully set or cleared as a resolving step.

Example

Example cURL request to set thread entry 28 as a resolving step:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/setResolvingThreadEntry" -H "Content-Type: application/json; charset=UTF-8" -d '{"entry_id" : 28, "resolving_step" : true}'

Successful request return showing that the thread entry was successfully set as a resolving step:

true
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

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

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

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

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

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.

Note

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

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_filter

String

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

services

JSON List

List of the team services names or IDs.

sig_filter

String

The situation filters. Either a SQL like filter or an JSON representation of the filter.

landing_page

String

The team default landing page.

active

Boolean

False if the team is inactive, true if the team is active. Default is true.

description

String

The team description.

users

List of numbers or strings

The 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

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

Boolean

true if the user active, false if the user inactive, default to true.

email

String

The user email address.

fullname

String

The user full name.

roles

JSON list

That list should contain either the list the role IDs or the role names, for example, "roles":["Super User"].

primary_group

String or Number

The user primary group name or primary group ID.

department

String or number

The user department ID or name.

joined

Number

The time the user joined (in Unix time).

timezone

String

The user timezone.

contact_num

String

The user phone number.

session_expiry

Number

The 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 strings

List of the user teams. The list should contains either the list of the teams ID or the teams name.

Return Parameters

Type

Description

HTTP code

HTTP status or error code indicating request success or failure.

For codes, see 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

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.

name

String

The 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

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

Request Arguments

Name

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

service_id

String

The ID of the service.

name

String

The name of the service.

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

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

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

Number

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

to

Number

The 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

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.

username

String

A 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

Fetches the user's roles from the database.

Request Argument

Name

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

user_id

Number

The user's ID.

username

String

A valid username.

Return parameter

Type

Description

NativeObject

A 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

Fetches a list of all users in the database.

Request Argument

Name

Type

Description

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

Type

Description

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

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

Request Argument

Name

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

user_id

Number

A valid user ID.

username

String

A valid username.

Return parameter

Type

Description

NativeObject

A 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

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_id

Number

The team ID (required).

name

String

The new team name. Exclude this attribute to leave Moogsoft AIOps as it is.

alert_filter

String

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.

services

JSON List

List of the team services names or IDs. Exclude this attribute to leave Moogsoft AIOps as it is.

sig_filter

String

The 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_page

String

The team default landing page. Exclude this attribute to leave Moogsoft AIOps as it is.

active

Boolean

False if the team is inactive, true if the team is active. Default to true. Exclude this atttribute to leave Moogsoft AIOps as is.

description

String

The team description. Exclude this attribute to leave Moogsoft AIOps as it is.

users

List of numbers or strings

The 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

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

Long

User ID for user to be edited. Required (optional if username used).

password

String

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

active

Boolean

true if the user active, false if the user inactive. Defaults to true. Optional.

email

String

User's email address. Optional.

fullname

String

User's full name. Optional.

roles

JSON list

A 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 Number

User's primary group name or primary group ID. Optional.

department

String or number

User's department ID or name. Optional.

timezone

String

User's timezone. Optional.

contact_num

String

User's phone number. Optional.

session_expiry

Number

Number 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 strings

List 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

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

Warning

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.

type

String

(Required)

Security realm type. This must be "SAML2".

active

Boolean

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

configuration

JSON 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 HTTP200response.

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

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

Warning

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.

type

String

Security realm type. This must be "SAML2".

active

Boolean

Determines whether the new realm is active or not.

configuration

JSON Object

JSON 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

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

Request Argument

Name

Type

Description

from

Number

The time from when the data points will be collected. A timestamp from epoch in seconds.

to

Number

The 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

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

Request Argument

Name

Type

Description

from

Number

The time from when the data points will be collected. A timestamp from epoch in seconds.

to

Number

The 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

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

Request Argument

Name

Type

Description

from

Number

The time from when the data points will be collected. A timestamp from epoch in seconds.

to

Number

The 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

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

Request Argument

Name

Type

Description

from

Number

Time from when the data points will be collected. A timestamp from epoch in seconds.

to

Number

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

"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

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

Request Argument

Name

Type

Description

from

Number

Time from when the data points will be collected. A timestamp from epoch in seconds.

to

Number

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

"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

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

Request Argument

Name

Type

Description

services

Array

An array of services IDs (optional). If no services are provided, the endpoint returns empty data.

from

Number

Time from when the data points will be collected.A timestamp from epoch in seconds.

to

Number

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

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

Request Argument

Name

Type

Description

severity

Array

An array of severity IDs. Optional. If not given, returns a default set of severities: Clear, Indeterminate, Warning, Minor, Major, Critical.

from

Number

Time from when the data points will be collected. A timestamp from epoch in seconds.

to

Number

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

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

Request Argument

Name

Type

Description

status

Array

An array of status IDs. Optional. If not given, returns a default set of statuses: Opened, Unassigned, Assigned, Acknowledged, Unacknowledged, Resolved.

from

Number

Time from when the data points will be collected.A timestamp from epoch in seconds.

to

Number

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

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

Request Argument

Name

Type

Description

from

Number

The time from when the data points will be collected. A timestamp from epoch in seconds.

to

Number

The 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

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

Number

The time from when the data points will be collected. A timestamp from epoch in seconds.

to

Number

The 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

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

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

A POST request that creates a maintenance window. The maintenance window filters alerts caused by a known period of maintenance.

Request Arguments

Name

Type

Description

auth_token

String

(Optional)

A valid auth_token returned from the authenticate request.

name

String

(Required)

Name of the maintenance window.

description

String

(Required)

Description of the maintenance window.

filter

String

(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_time

Epoch Seconds (Number)

(Required)

Start time of themaintenancewindow. This must be in epoch time and may be up to 5 years in the future.

duration

Seconds (Number)

(Required)

Duration of the maintenance window in seconds. The minimum duration is 1 second and the maximum is 157784630 seconds (5 years).

forward_alerts

Boolean

(Required)

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

recurring_period

Number

(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_units

Number

(Optional)

Specifies the recurring period of the maintenance window, in days, weeks or months. Defaults to 0 ifrecurring_periodis set to0.Valid 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 filterwhere thesource 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 thesource 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}
deleteMaintenanceWindow

A POST request that deletes a single maintenance window.

Parameter

Type

Required

Description

auth_token

String

No

A valid auth_token returned from the authenticate request.

id

Number

Yes

ID of the maintenance window you want 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 maintenance window 123:

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

Successful return:

NO RESPONSE TEXT

deleteMaintenanceWindows

A POST request that deletes maintenance windows that match the specified filter.

Parameter

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

filter

String

ID 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

cURL request to delete maintenance windows that match the filter where the ID is 3 or 4:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/deleteMaintenanceWindows" -H "Content-Type: application/json; charset=UTF-8" -d '{"filter":"id in (3,4)"}'

Example cURL request to delete maintenance windows that match the filter where the host is "CSF_RD_243:

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

Successful return:

NO RESPONSE TEXT

findMaintenanceWindows

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

Request Arguments

Parameter

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

filter

String

SQL or JSON filter.

limit

Number

The 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

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

Parameter

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

integration_id

Number

A 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 aJSON 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

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

Parameter

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request.

start

Number

The start point for where to fetch windows from, that is, 0 to start at the first, 10 to start at the 11th.

limit

Number

The 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

Example cURL command to return the first 20 maintenance windows:

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

Successful 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

A GET request that returns the list of processes.

Request Arguments

Name

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request. Required.

limit

Integer

The 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

String

The 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

A GET request that returns the list of services.

Request Arguments

Name

Type

Description

auth_token

String

A valid auth_token returned from the authenticate request. Required.

limit

Integer

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

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,
        "name": "Service A"
}, {
        "service_id": 4,
        "name": "Service B"
}]
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

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

A GET request that returns a list of statuses that can apply to Situations and their 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 an array of JSON objects 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

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.

running

Boolean

Indicates whether the process is running or not:

  • true = running

  • false = not running

service_name

String

The service name.

display_name

String

The name of the service in the configuration.

type

String

The type of the service, for example, lam, servlets, moog_farmd.

passive

Boolean

Indicates whether the service is passive in a HA environment:

  • true = passive

  • false = active

stoppable

Boolean

Indicates whether or not the service can be stopped:

  • true = stoppable

  • false = not stoppable

ha_conf

JSON Object

A Json blob containing the HA configuration.

additional_health_info

JSON Object

Additional 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

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_sitn

Number

The average number of events per situation.

avg_alerts_per_sitn

Number

The average number of alerts per situation.

service_count

Number

The number of services currently in Moogsoft AIOps.

open_sigs_unassigned

Number

The 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

A POST request that updates an existing maintenance window.

Request Arguments

Name

Type

Description

window_id

String

(Required)

ID of the existing maintenance window.

auth_token

String

(Optional)

A valid auth_token returned from the authenticate request.

name

String

(Optional)

Name of the maintenance window.

description

String

(Optional)

Description of the maintenance window.

filter

String

(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_time

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

duration

Seconds (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_period

Number

(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_units

Number

(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

You can send POST parameters as form-urlencoded or as application/json 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.

404

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