Creating history collection configurations

This example shows how to create history collection configurations.

To create one or more history collection configurations, use the PUT /data/historycollections endpoint.

The format of the path is as follows:

https://host:port/api/v1/data/historycollections

Each request requires a request body. Within the request body, specify the details for the history collection configuration.

You can create one or multiple history collection configurations in a single request. For each history collection configuration to be created in the request, you provide a separate object in the request body. For more information, see Examples of request body for creating history collection configurations.

For each history collection configuration that is created, the request generates the name (property NAME) in the format UADVISOR_xxxxx, where xxxxx lists the application name, a random number to ensure uniqueness, and the table name.

Examples of request body for creating history collection configurations

In each request to create a history collection configuration, you must provide a request body that specifies the details of the data collection. You must specify the definitions for each requested history collection configuration as a separate object.

The format of the request body when requesting only one history collection configuration to be created is shown in the following example. This example shows the minimum fields that are required.

{
  "APPLICATION": "KM5",
  "TABLE": "ASCPUUTIL",
  "FULLNAME": "History collection z/OS",
}

The format of the request body when requesting multiple history collection configurations to be created in a single request is shown in the following example. In this example, one of the history collection configurations copies content to the warehouse whereas the other does not.

[
   {
     "APPLICATION": "KM5",
     "TABLE": "ASCPUUTIL",
     "FILTER": "(JOBNAME='ITE4DS')",
     "REEV_DAYS": "0",
     "REEV_TIME": "003000",
     "FULLNAME": "History collection z/OS jobname",
     "WAREHOUSE_TRIGGER": 0,
   }
{
     "APPLICATION": "KM5",
     "TABLE": "LPCLUST",
     "REEV_DAYS": "0",
     "REEV_TIME": "003000",
     "FULLNAME": "History collection z/OS warehouse",
     "WAREHOUSE_TRIGGER": 2,
   }
]

For a description of each of the properties in the request body, see the next section.

Properties for creating history collection configurations

You can use the following properties when creating history collection configurations:

{
  "APPLICATION": "string",
  "TABLE": "string",
  "COLLECTION_STORE": "TEMA",
  "FILTER": "string",
  "REEV_DAYS": "string",
  "REEV_TIME": "string",
  "TEXT": "string",
  "FULLNAME": "string",
  "WAREHOUSE_TRIGGER": integer,
  "DISTRIBUTION": [
    "string"
  ]
}

The following table describes these properties.

Table 1. Request-body properties when creating history collection configurations
Property	Description
`APPLICATION`	(Required) Target product.
`TABLE`	(Required) Target table.
`FULLNAME`	(Required) The full name of the defined history collection configuration.
`COLLECTION_STORE`	Where the history data is collected. Specify `TEMA` to collect data at the Managed System (agent). Note: Specifying that the history data be collected at the Managing System (TEMS) is not supported.
`FILTER`	Filter criteria for preventing the collection of unwanted data. For example, the following definition filters collection by a specified job name: `"FILTER": "(JOBNAME='jobname')"`
`REEV_DAYS` `REEV_TIME`	Collection interval. You can change it to as seldom as once in 999 days or as often as one minute. These character-string fields accept only integer values. 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 one minute (000100) 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"`
`TEXT`	Description for the collection.
`WAREHOUSE_TRIGGER`	Determines whether the collected data is copied to the data warehouse and how often. This integer value specifies the number of collection intervals (which are set by the `REEV_DAYS` and `REEV_TIME` values) to elapse before exporting the collected data to the warehouse. Specify 0 to disable exporting the collected data to the warehouse.
`DISTRIBUTION`	Managed systems where to collect data. 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 collect data. 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 history collection configuration.