Creating situations

Edit online

This example describes how to use the PUT /situations endpoint to create situations.

When using this endpoint, you must provide the following information in the request body:
  • The situation name. Specify a unique name to create a new situation. For more information about the situation name, see Situation name.
  • The PDT property specifying the formula for the situation.

You can also specify other optional properties. For more information about the request body properties, see Request body for creating situations.

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

With the PUT /situations endpoint, you can also import multiple existing situations from one runtime environment into a different runtime environment. Thus, you can re-create multiple situations in a new runtime environment in a single request. For more information about importing situations, see Importing multiple situations.

Creating one situation per request

When using the PUT /situations endpoint to create a single situation, include in the request body the NAME and PDT properties.

The format of the path is as follows:
https://host:port/api/v1/situations
For example:
{
  "NAME": "Situation_1",
  "PDT": "*IF *VALUE Active_Server_Pages.Allocated_Memory *EQ 1",
  "DISTRIBUTION": [
    "string",
    "string"
  ]
}

You can also specify other optional properties. For more information about the request body properties, see Request body for creating situations.

Creating multiple situations in a request

When using the PUT /situations endpoint to create multiple situations, include in the request body the NAME property and the PDT property for each situation you want to create.

The format of the path is as follows:
https://host:port/api/v1/situations
In the request body, for each situation you want to create, specify the information as a separate object. For example:
[
   {
     "NAME" : "Situation_1", 
     "PDT": "*IF *VALUE Active_Server_Pages.Allocated_Memory *EQ 1"
   }, 
   {
     "NAME" : "Situation_2", 
     "PDT": "*IF *VALUE Active_Server_Pages.Allocated_Memory *EQ 1",
     "FULLNAME": "124 Situation name"
   }
]

You can also specify other optional properties. For more information about the request body properties, see Request body for creating situations.

Situation name

You must specify a unique name (the NAME property) in the request body to create a new situation.

The specified value is stored in the situation definition as follows:
NAME
If the value is 31 characters or less, does not start with a number, and contains only alphanumeric characters or the underscore character, the value is stored as the NAME attribute for the situation.
FULLNAME
If any of the following conditions exist, the specified value is stored as the FULLNAME attribute for the situation:
  • The specified value is longer than 31 characters
  • The specified value starts with a number
  • The specified value contains symbols other than alphanumeric or the underscore character (for example, whitespace characters, question mark, exclamation mark)
When the provided value for the situation name is stored as the FULLNAME attribute due to any of these conditions, then the value of the NAME attribute is generated automatically and returned in the response body.
Note: Both the NAME attribute value and the FULLNAME attribute value must be unique.

Request body for creating situations

The following example shows the format of the request body and includes all properties that can be specified. 
{
  "NAME": "string",
  "ADVISE": "string",
  "AUTOSTART": "string",
  "CMD": "string",
  "FULLNAME": "string",
  "PDT": "string"
  "REEV_DAYS": "string",
  "REEV_TIME": "string"
  "SITINFO": {    
    "COUNT": "string",
    "ATOM": "string",
    "TFWD": "string",
    "TDST": "string",
    "SEV": "string"
 },
  "TEXT": "string",
  "REFLEXACTION_OPTIONS": {
    "EACH_ROW" : "string",
    "EACH_INTERVAL" : "string",
    "WHERE" : "string"
 },
  "DISTRIBUTION": [
    "string"
  ]
}

In addition to the required properties, include only the properties that you want to define. For properties that are not specified, default values are used.

The following table describes the properties that can be used when creating a situation and also provides the relevant location in the Tivoli Enterprise Portal (TEP).
Note: Properties NAME and PDT are required.
Table 1. Situation elements eligible when creating a situation
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
FULLNAME The name value of the defined situation when the value does not meet the NAME criteria.

You can specify the FULLNAME attribute together with the NAME attribute.

 Formula tab, Name field
TEXT Situation description.

Valid values: character string, max length 64 bytes

Default value: none (empty field)

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

Valid values: character string, max length 1022 characters

Note: This parameter is required.

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"

    A correlated situation in TEMS REST services corresponds to the Correlated Situation type when creating a situation in TEP.

    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"

    An embedded situation in TEMS REST services corresponds to the Situation Comparison option when selecting conditions for a situation in the Tivoli Enterprise Portal .

    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 when creating a situation.

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

  "SITINFO": {
    "TFWD": "string",
    "SEV": "string",
    "TDST": "string",
    "ATOM": "string",
    "COUNT": "string"
  }

When specifying the SITINFO object in your request to create a situation, you must include all of these properties.

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. These character-string fields accept only integer values.
Valid values:
  • For REEV_DAYS, in ddd format, specify 0 - 999 days. The default value is 0.
  • 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). The default value is 001500.
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.

Specify *YES if you want monitoring to start as soon as the situation is created. 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.

Valid values: *YES, *NO

Default value: *YES

 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 defining the DISTRIBUTION values, you must include in the request all the node values to define for the situation.

Note:
  • When correlating situations, ensure that the DISTRIBUTION value is specified as *HUB, which is the only valid value.
    "DISTRIBUTION": [
            "*HUB"
        ]
  • When embedding situations, ensure that DISTRIBUTION is specified and the situations 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.

Default value: none (empty field)

 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.

Default value: none

 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 specifying the REFLEXACTION_OPTIONS object in your request to create a situation, 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

Default value: 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.

Importing multiple situations

With the PUT /situations endpoint, you can import multiple situations from one runtime environment into a different runtime environment by completing the following steps:

  1. In the runtime environment with the existing situations, use the GET /situations endpoint to retrieve the situations that you want to import into a different runtime environment.
  2. Copy the response.
  3. Switch to the runtime environment into which you want to import the situations and select the PUT /situations endpoint.
  4. Insert the data for the copied situations into request body, and submit the request.

In the response body, you will find the information for each processed situation.

Important: The original runtime environment might differ from the destination runtime environment into which you import the situations. So, for all the situations to be imported successfully, make sure you observe the following recommendations before submitting the PUT /situations request:
  • If the original runtime environment and the destination runtime environment include nodes (managed systems) with different names, the situations that are distributed to the nodes that do not exist in the destination runtime environment will not be created. This scenario also applies to correlated situations that have node names in the formula.

    To avoid this scenario, update the node names in DISTRIBUTION or in PDT (for correlated situations) accordingly.

  • If you have custom managed system groups in the original runtime environment and want to keep them in the destination runtime environment, you should either create them in the destination runtime environment or rename them accordingly.
  • If the situations that you want to import include correlated or embedded situations in them, mind the order of the situations in request body; so that the situations that are included in embedded or correlated situations are defined before the situations that include them.
    For example, the correlated situation with the name SituationThatMonitors includes SituationToMonitor1 and SituationToMonitor2. In request body, SituationToMonitor1 and SituationToMonitor2 should be placed before SituationThatMonitors, as shown in the following example:
    [
  {
     "NAME" : "SituationToMonitor1", 
     "PDT": "*IF *VALUE Active_Server_Pages.Allocated_Memory *EQ 1",
     "FULLNAME": "123 Situation name 1"
   }, 
   {
     "NAME" : "SituationToMonitor2", 
     "PDT": "*IF *VALUE Active_Server_Pages.Allocated_Memory *EQ 1",
     "FULLNAME": "124 Situation name 2"
   },
   {
     "NAME" : "SituationThatMonitors", 
     "PDT": "*IF *VALUE *HSITNAME *EQ SituationToMonitor1 *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",
     "FULLNAME": "124 Situation name 2"
   }
]