How to specify requests to the TEMS REST services

Get started with the TEMS REST services.

Callers interact with the Tivoli Enterprise Monitoring Server (TEMS) REST services by using HTTP REST calls. Possible callers are command-line based (such as curl), web browser applications, front-end applications, or programmatic callers created using the OpenAPI Generator. The base path for the TEMS REST services is as follows: 
https://host:port/api/version
Where port is the well-known HTTP or HTTPS port for Tivoli® Management Services on z/OS®, as defined at your site.
Version v1 of TEMS REST services provides the following types of endpoints:
  • GET endpoints that allow read-only access to the OMEGAMON data. You can access the following types of information using available endpoints:
    • Collection data: real-time data, and near-term history from the persistent data store
      Note: TEMS REST services does not support retrieving data from the Tivoli Data Warehouse.
    • History collection configurations, which define what historical data is collected
    • Managed system data: applications, groups, nodes, tables, self-describing agent records, and Take Action command definitions. Paths for managed system data endpoints include /system in the address.
    • Situation definitions and statuses
  • POST endpoints that allow you to perform an activity. You can perform the following activities using available endpoints:
    • Start and stop a situation
    • Execute a Take Action
  • PATCH endpoint that allows you to edit a situation
All available request paths and responses can be found in the OpenAPI document.

TEMS REST services terminology

An understanding of the following terms and how they relate to OMEGAMON and the monitoring server will help expedite your getting starting with the TEMS REST services.
application
The application is the agent product code.
affinity
The agent affinity is a Tivoli Monitoring internal identifier that associates workspaces, queries, and other items, with the agent. It must be unique in the Tivoli Monitoring installation.
group
A defined set of resources (nodes) that is used to control the scope of data collection.
node
A unique token used for agent identification, which is used in data collection to identify one agent monitoring one system or subsystem.
table
A data structure consisting of rows and columns that is used by the monitoring server and monitoring agents to store collection data.

Using time values for requests

You can use time values when making requests for collection data or situation statuses:
Collection data

When requesting collection data using the GET /data endpoint, two types of collection data are available: real-time data, and near-term history from the persistent data store. To request near-term historical data, you must specify time values as part of the GET /data request. If you do not specify time values, the request returns real-time data.

For the GET /data endpoint, the time values are specified using the parameters timeFrom and timeTill. When requesting historical data, a start and end time must be provided for the request. If you specify the timeFrom parameter alone, then the timeTill parameter defaults to the current time. If you specify a value for the timeTill parameter, then you must also specify a value for the timeFrom parameter.

Situation status history

When requesting situation status history using the GET /situations/status/history endpoint, you must specify a start time from when to retrieve situation status history using the timeFrom parameter. You can also specify an end time using the timeTill parameter.

The format for the time values consists of 16 digits as follows: YYYMMDDHHMMSS000

Where:
  • YYY is the number of years since the year 1900.
  • MMDDHHMMSS is months, days, hours, minutes, and seconds, respectively.
  • The last three digits are zeros.
For example, 2023 July 17, 06:34:37 would be represented as follows: 1230717063437000
You can use the GET /timenow endpoint to retrieve the TEMS local time. The response returns the time value in the required format for use in the timeFrom and timeTill parameters.
Request:
https://host:port/api/v1/timenow
Response:
{
  "timenow": "1230717063437000"
}