Editing situations

This example describes how to use the PATCH /situations endpoint to edit situations.

When using this endpoint, you must provide the following information for each situation to update:
  • The name of the defined situation. Specify this information in the name parameter.
  • The date when the situation was last modified. Specify this information as a timestamp value in the lstdate parameter. Because this value is updated each time the situation is edited, you must update the value with each PATCH /situations request.
    Note: This timestamp value is used as a locking mechanism to prevent multiple requests from updating the situation at the same time. For information about the format of the timestamp, see Using time values for requests.
    Tip: You can obtain this value by using the GET /situations endpoint; the lstdate parameter is returned as part of the response.
  • A request body that specifies the situation information to modify. The properties that can be updated are described in Request body for situation editing.

The format of the request differs depending on if you are editing a single situation or multiple situations in your request, as described in the following sections.

Editing one situation per request

When using the PATCH /situations endpoint to edit a single situation, you can use query parameters to specify the situation name and the date when the situation was last modified, as follows:
https://host:port/api/v1/situations?name=situation_name&lstdate=date_last_updated
where situation_name is the name of the situation to modify and date_last_updated is the timestamp when the situation was last modified.
Include in the request body the situation information to modify. The properties that can be updated are described in Request body for situation editing.
Note: When you specify the situation name and last-modified date in query parameters, do not include the NAME and LSTDATE properties in the request body.

Editing multiple situations in a request

When using the PATCH /situations endpoint to edit multiple situations in a single request, you must use the NAME and LSTDATE properties in the request body for each situation to update.

The format of the path is as follows:
https://host:port/api/v1/situations
Include in the request body the information to modify for each situation, specified as a separate object for each situation. For example:
[
  {
     "NAME" : "sit1", 
     "REEV_DAYS": "1", 
     "LSTDATE" : "01293012930293"
  }, 
  { 
     "NAME" : "sit2", 
     "REEV_DAYS": "1", 
     "LSTDATE" : "01293012930293" }
]

The properties that can be updated are described in Request body for situation editing.

Request body for situation editing

The following example shows the format of the request body for situation editing requests and includes all supported properties:
{
  "NAME": "string",
  "LSTDATE": "string"
  "ADVISE": "string",
  "AUTOSTART": "string",
  "CMD": "string",
  "PDT": "string"
  "REEV_DAYS": "string",
  "REEV_TIME": "string"
  "SITINFO": {
    "TFWD": "string",
    "SEV": "string",
    "TDST": "string",
    "ATOM": "string",
    "COUNT": "string"
  },
  "TEXT": "string",
  "REFLEXACTION_OPTIONS": {
    "EACH_ROW" : "string",
    "EACH_INTERVAL" : "string",
    "WHERE" : "string"
  },
  "DISTRIBUTION": [
    "string"]
}

Include the NAME and LSTDATE properties to identify the situation only when editing multiple situations in a single request.

For the remainder of the properties, include only those properties that you want to update for the respective situation.

The following table describes the supported properties and provides the relevant location in the Tivoli Enterprise Portal (TEP).

Table 1. Request body properties for situation editing
Property Description Location in TEP Situation Editor
NAME The name of the defined situation.

This property is required for each situation when you are updating multiple situations in a request.

 Formula tab, Name field
LSTDATE The timestamp when the situation was last modified.

Because this value is updated each time the situation is edited, you must update the value with each PATCH /situations request.

This property is required for each situation when you are updating multiple situations in a request.

  
TEXT Situation description.

Valid values: character string, max length 64 bytes

 Formula tab, Description field
PDT Formula containing the thresholds to be tested by the situation.

Valid values: character string

"PDT": "*IF *VALUE ALL_THREADS.Plan *EQ K06PLAN *AND *VALUE ALL_THREADS.Plan *EQ K07PLAN"
 Formula tab, Formula fields
SITINFO Situation definitions that are eligible for editing.

The SITINFO object includes various properties in JSON object format, as follows:

  "SITINFO": {
    "TFWD": "string",
    "SEV": "string",
    "TDST": "string",
    "ATOM": "string",
    "COUNT": "string"
  }
When making updates to these properties, you must include all the SITINFO properties that are defined for the situation. You can obtain the SITINFO definitions by using the GET /situations endpoint. For example, consider a situation with the following definitions:
"SITINFO": {
    "SEV": "Harmless",
    "TDST": "0",
    "COUNT": "1"
    }
To change the value of the COUNT property from 1 to 2, you must include all of the defined properties, as follows:
"SITINFO": {
    "SEV": "Harmless",
    "TDST": "0",
    "COUNT": "2"
    }

For a description of each of the SITINFO properties, see Table 2.

 Formula and EIF tabs
REEV_DAYS

REEV_TIME

 Sampling interval. You can change it to as seldom as once in 999 days or as often as 30 seconds.
Valid values:
  • For REEV_DAYS, in ddd format, specify 0 - 999 days.
  • For REEV_TIME, in hhmmss format, you can specify a minimum value of 30 seconds (000030) and a maximum value of 23 hours, 59 minutes, and 59 seconds (235959).
For example, the following definitions create a sampling interval of 24 hours and 5 minutes:
"REEV_DAYS": "1",
"REEV_TIME": "000500"
 Formula tab, Sampling interval fields
AUTOSTART Run at startup.

Valid values: *YES, *NO

Specify *YES if you want monitoring to start as soon as the situation is saved. If a monitoring agent to which the situation is distributed goes offline, the situation will start automatically when the agent starts again.

Specify *NO if you want to start the situation manually.

 Formula tab, Run at startup option
DISTRIBUTION Managed systems where to run the situation.
Use the following format:
"DISTRIBUTION": ["node_1","node_2"]
where node_n is one or more nodes (managed systems), listed in JSON array format, where to run the situation.
For example:
"DISTRIBUTION": [
    "*MVS_DB2",
    "DB2plex:DB2plex:Plexview",
    "IC1D:RSD4:DB2"
    ]
When making updates to the DISTRIBUTION values, you must include in the request all the node values that are currently defined for the situation. You can obtain the defined values using the GET /situations endpoint. If you omit an entry, the node is removed from distribution. You can also add nodes to distribution.
Important: Including an empty array in your request removes all definitions.
 Distribution tab, Assigned field
ADVISE Expert advice. You can enter text that describes instructions for the user, or provide the URL of a page to display. Expert Advice tab, Text or Advice Location field
CMD Action to perform when the situation becomes true.
To run a system command, use the following format:
"CMD": "system_command"
where system_command is the command to issue at the system.
To issue a universal message, use the following format:
"CMD": "message:category;severity;universal_msg"
where:
  • message is a literal value
  • category is a one-word term of up to 16 characters
  • severity is a one-word term of up to 8 characters
  • universal_msg is the text (up to 245 characters) to display when the situation occurs.
On the Action tab:
  • For system commands: the System Command option under Action Selection, and the System Command field.
  • For universal messages: the Universal Message option under Action Selection, and the Category, Severity, and Message fields.
REFLEXACTION_OPTIONS Indicate the reflex action options to take when the situation becomes true.

The REFLEXACTION_OPTIONS object includes the following properties in JSON object format:

"REFLEXACTION_OPTIONS": {
    "EACH_ROW" : "Y|N",
    "EACH_INTERVAL" : "Y|N",
    "WHERE" : "TEMS|TEMA"
    }
EACH_ROW
If the condition is true for more than one monitored item, specify Y to take action on each item, or specify N to only take action on the first item. The default value is N.
EACH_INTERVAL
If the condition stays true over multiple intervals, specify Y to take action in each interval, or specify N to not take action twice in a row. The default value is N.
WHERE
When the action is executed, specify TEMS to perform the action at the Managing System (TEMS), or specify TEMA to perform the action at the Managed System (agent). The default value is TEMA.

When making updates to the REFLEXACTION_OPTIONS properties, if a property and its value are not specified, the default value is used.

Options on the Action tab:
If the condition is true for more than one monitored item:
  • Only take action on first item
  • Take action on each item
Where should the Action be executed:
  • Execute the Action at the Managed System (Agent)
  • Execute the Action at the Managing System (TEMS)
If the condition stays true over multiple intervals:
  • Don't take action twice in a row (wait until situation goes false then true again)
  • Take action in each interval
The following table describes the situation information properties that are defined in the SITINFO object:
Table 2. SITINFO properties
Property Description Location in TEP Situation Editor
TFWD Event Integration Facility (EIF) forwarding, which forwards situation events to one or more EIF receivers.

Specify Y to forward situation events to one or more EIF receivers. An EIF event is sent for each situation event.

Valid values: Y, N

 EIF tab, Forward Events to an EIF Receiver option
SEV The severity for forwarded situation events. EIF tab, EIF Severity field
TDST Event Integration Facility (EIF) destinations for the forwarded events. Each destination represents one or more EIF receivers.
Use the following format:
"TDST": ["destination_1","destination_2"]
where destination_n is one or more destinations, listed in JSON array format, to which forwarded events will be sent.
 EIF tab, Assigned EIF Receivers field
ATOM For multiple-row attribute groups, you can enable the situation to continue to test all rows in the data sampling and open events.

Only columns from tables that are specified in the main formula and are eligible for ATOMIZE are processed.

For example, the following definition indicates that only the columns from table REALTHDA that are eligible for ATOMIZE are processed: 
"ATOM": "REALTHDA.TDIDPLAN"
Tip: You can use the GET /system/tables?name=REALTHDA endpoint to identify columns that are eligible for ATOMIZE, as indicated by "ATOMIZE": true.
 On Formula tab, select Advanced settings. On Advanced Situation Options window, Display Item tab, Item field.
COUNT Consecutive true samples, which is the number of times the situation remains true before an event is opened.
Use the following format:
"COUNT": "number"
where number is an integer.
 On Formula tab, select Advanced settings. On Advanced Situation Options window, Situation Persistence tab, Consecutive true samples field.