Editing situations

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

When using this endpoint, you must provide a request body that specifies the following information for each situation to update:

The name of the defined situation (the NAME property).
The date when the situation was last modified (the LSTDATE property). Specify this information as a timestamp value. 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.
The situation information to modify. The properties that can be updated are described in Request body for situation editing.

The format of the request slightly 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, include in the request body the NAME property, the LSTDATE property, and the situation information to modify.

The format of the path is as follows:

https://host:port/api/v1/situations

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

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

Always include in the request body the NAME and the LSTDATE properties. 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. The NAME value is 31 characters or less, does not start with a number, and contains only alphanumeric characters or the underscore character. Note: This parameter is required.	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. Note: This parameter is required.
`FULLNAME`	The `name` value of the defined situation when the value does not meet the NAME criteria. The name of the defined situation is stored as the FULLNAME attribute if it is longer than 31 characters, starts with a number, or contains symbols other than alphanumeric or the underscore character (for example, whitespace characters, question mark, exclamation mark).	Formula tab, Name field
`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, max length 1022 characters `PDT` examples for the supported situation types: Standard situation: `"PDT": "IF VALUE ALL_THREADS.Plan EQ K06PLAN AND VALUE ALL_THREADS.Plan EQ K07PLAN"` Correlated situation: `PDT": "IF VALUE HSITNAME EQ SituationToMonitor AND VALUE HNODE EQ PLEXA:SYSTEM1:MVSSYS AND VALUE HDELTASTAT EQ Y AND VALUE HSITNAME EQ SituationToMonitor2 AND VALUE HNODE EQ PLEXA:SYSTEM2:MVSSYS AND VALUE HDELTASTAT EQ Y"` Note: To be valid, `PDT` must contain at least two existing situations. The statement `HDELTASTAT EQ Y` means that the situation is 'true'. Thus, `Y` is the only valid `HDELTASTAT` value. Embedded situation: `"PDT": "IF SIT SituationToMonitor EQ TRUE AND VALUE TableA.ColumnE GT 90.0"` Note: To be valid, `PDT` must contain at least one existing situation and at least one other clause, which can be another existing situation or an attribute comparison. When including multiple situations, ensure the situations are from the same agent or All Managed Systems.	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", "TDB2:SYS1: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: For all situation types, including an empty array in your request removes all definitions. For correlated situations, the only valid `DISTRIBUTION` value is `HUB`. `"DISTRIBUTION": [ "*HUB" ]` For embedded situations, both the embedding situation and the embedded situation must have at least one matching `DISTRIBUTION` value, otherwise the request is invalid.	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.