Editing history collection configurations

This example shows how to edit history collection configurations.

To edit one or more history collection configurations, use the PATCH /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 following information for each history collection configuration to update:

(Required) The name of the existing history collection configuration (the NAME property).
(Required) The timestamp when the history collection configuration was last modified (the LSTDATE property).
The history collection configuration information to modify.

For details about the properties, see Properties for editing history collection configurations.

You can update one or multiple history collection configurations in a single request. For each history collection configuration that is to be updated in the request, you provide a separate object in the request body. For more information, see the next section.

Examples of request body for editing history collection configurations

In each request to update a history collection configuration, you must provide a request body. You must specify the details for each requested history collection configuration to update as a separate object.

For each history collection configuration to update, include the NAME property, the LSTDATE property, and the history collection configuration information to modify.

The following examples show variations of the request body.

Updating one history collection configuration in the request

Include in the request body the history collection configuration information to modify. Identifying properties NAME and LSTDATE are required.

Specify any of the other properties that you want to update. The following example shows the properties to update the collection interval:

{
   "NAME" : "uadvisor_name", 
   "LSTDATE" : "01293012930293",
   "REEV_DAYS": "1", 
   "REEV_TIME": "000000"
}

Updating multiple history collection configurations in the request

Include in the request body the information to modify for the history collection configurations, with details for each history collection configuration specified as a separate object. Identifying properties NAME and LSTDATE are required for each history collection configuration. Specify any of the other properties that you want to update.

The following example shows the properties to update the collection interval for two history collection configurations in a single request:

[
  {
     "NAME" : "uadvisor_name_1", 
     "LSTDATE" : "01293012930293",
     "REEV_DAYS": "1",
     "REEV_TIME": "000000"
  }, 
  { 
     "NAME" : "uadvisor_name_2", 
     "LSTDATE" : "01293012930293", 
     "REEV_DAYS": "1", 
     "REEV_TIME": "000000"
  }
]

Updating all properties for a history collection configuration

The following example shows the format of the request body for a history collection configuration editing request that includes all supported properties. Always include in the request body the NAME and the LSTDATE properties. For the remainder of the properties, you can include only those properties that you want to update.

{
  "NAME": "string",
  "LSTDATE": "string",
  "COLLECTION_STORE": "string",
  "FILTER": "string",
  "REEV_DAYS": "string",
  "REEV_TIME": "string",
  "TEXT": "string",
  "FULLNAME": "string",
  "WAREHOUSE_TRIGGER": integer,
  "DISTRIBUTION": [
    "string"
  ]
}

The properties are described in the next section.

Properties for editing history collection configurations

The following table describes the supported properties for editing history collection configurations.

Table 1. Request body properties for history collection configuration editing
Property	Description
`NAME`	(Required) The name of the defined history collection configuration. You cannot modify this value. The name is in the format `UADVISOR_xxxxx`. Commonly, K`pp` and `tablename` appear in the name.
`LSTDATE`	(Required) The timestamp when the history collection configuration was last modified. This value is updated automatically with each edit request; you cannot manually modify this value. Because this value changes each time the history collection configuration is edited, you must update the value with each `PATCH /data/historycollections` request. Note: This timestamp value is used as a locking mechanism to prevent multiple requests from updating the history collection configuration 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 /data/historycollections` endpoint; the lstdate parameter is returned as part of the response.
`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.
`FULLNAME`	The full name of the defined history collection configuration.
`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 making updates to the `DISTRIBUTION` values, you must include in the request all the node values that are currently defined for the history collection configuration. You can obtain the defined values using the `GET /data/historycollections` 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.