7. Run archive configuration commands

Request

The request URL for running archive configuration commands has the following form:

/run-archive-configuration-commands

The request must use the POST method.

The request body must be a JSON object that has a single member. This member has the key commands and an array as its value. Each of the array elements must be a JSON object that represents an archive configuration command.

The format of the object depends on the respective command and is described in the section called “Archive Configuration Commands”. Commands may be processed in parallel, so a single request should never specify more than one command that affects the same channel as the result is not predictable.

Response

The response is a JSON object with the with the following members:

Field nameInternal data typeJSON data typeDescription
errorMessagestringstring error message indicating a global problem. Such a problem does not affect a specific channel, but the whole execution (e.g. problems while accessing the database). If such an error is present, no changes have been made to the server configuration. null if there is no global error.
resultsarray of objectarray of object result object for each command that was specified in the request. The results have the same order as the commands had in the request. May be null if errorMessage is set.

Each result object is a JSON object with the following structure:

Field nameInternal data typeJSON data typeDescription
commandobjectobject command to which this result belongs. This command object is equal to the one that has been specified in the request, but some members may differ slightly due to normalization.
errorMessagestringstring error message describing the reason for which the operation failed. null if the operation was successful or if no explanation for the error is available.
successbooleanboolean true if the command was executed successfully, false if the command failed.

If the user could not be authenticated or is not authorized to use the import function, HTTP error code 403 (forbidden) is returned and the response body is invalid. If there is an error for at least one command, HTTP error code 500 (internal server error) is returned and the success member of the corresponding command or commands is set to false. If there is a general problem while processing the request (e.g. the database is currently unavailable), HTTP error code 503 (service unavailable) is returned and the errorMessage is set in the response.

Archive Configuration Commands

There are seven different archive configuration commands:

  • add channel
  • add or update channel
  • move channel
  • refresh channel
  • remove channel
  • rename channel
  • update channel

Each command is described by a JSON object, but except for the common commandType member, each of the different commands has a slightly different structure.

Add channel

The add channel command adds a new channel to the archive configuration. The channel is only added if it does not exist yet. If there already is a channel with the same name, the operation fails. The object for the add channel command has the following structure:

Field nameInternal data typeJSON data typeDescription
channelNamestringstring name of the channel that shall be added.
commandTypeenumstring always the literal string add_channel.
controlSystemTypestringstring internal identifier for the control-system support that shall be used for the channel. This is the same identifier that is also used in configuration files.
decimationLevelsset of intarray of string decimation levels for the channel (identified by their decimation periods specified in seconds). The raw decimation level (with a decimation period of zero) is always added, even if it is not specified in the array. If the whole array is null, this is interpreted like an array containing zero as its only element.
decimationLevelToRetentionPeriodmap of int to intobject with string member values retention period for each decimation level (specified in seconds). Each member uses the decimation period of the respective decimation level as its key and the retention period as its value. A value of zero means that samples shall be retained indefinitely. Entries for a decimation level that is not also specified in decimationLevels are discarded (except for the raw decimation level which is always included implicitly). Negative retention periods are converted to zero. If a decimation level is specified in decimationLevels, but not in decimationLevelToRetentionPeriod, a retention period of zero is assumed. If the whole object is null, a retention period of zero is used for all decimation levels.
enabledbooleanboolean true if archiving shall be enabled for the channel, false if archiving shall be disabled.
optionsmap of string to stringobject with string member values control-system-specific configuration options. The member key is the option name and the member value is the option value. Specifying null has the same effect as specifying an empty object.
serverIdUUIDstring UUID of the server to which the channel shall be added.

Add or update channel

The add or update channel command is very similar to the add channel command. However, instead of failing when the specified channel already exists, it updates the channel configuration to match the specified configuration.

The control-system type of a channel cannot be changed, so the command fails if the channel exists, but its control-system type does not match the specified control-system type. The command also fails when the specified server ID does not match the server ID of the already existing channel. Channels can be moved from one server to another one, but the move channel command has to be used for this task.

The object for the add or update channel command has the same structure as the add channel command, only the value of the commandType member is different:

Field nameInternal data typeJSON data typeDescription
channelNamestringstring name of the channel that shall be added or updated.
commandTypeenumstring always the literal string add_or_update_channel.
controlSystemTypestringstring internal identifier for the control-system support that shall be used for the channel. This is the same identifier that is also used in configuration files.
decimationLevelsset of intarray of string decimation levels for the channel (identified by their decimation periods specified in seconds). The raw decimation level (with a decimation period of zero) is always added, even if it is not specified in the array. If the whole array is null, this is interpreted like an array containing zero as its only element.
decimationLevelToRetentionPeriodmap of int to intobject with string member values retention period for each decimation level (specified in seconds). Each member uses the decimation period of the respective decimation level as its key and the retention period as its value. A value of zero means that samples shall be retained indefinitely. Entries for a decimation level that is not also specified in decimationLevels are discarded (except for the raw decimation level which is always included implicitly). Negative retention periods are converted to zero. If a decimation level is specified in decimationLevels, but not in decimationLevelToRetentionPeriod, a retention period of zero is assumed. If the whole object is null, a retention period of zero is used for all decimation levels.
enabledbooleanboolean true if archiving shall be enabled for the channel, false if archiving shall be disabled.
optionsmap of string to stringobject with string member values control-system-specific configuration options. The member key is the option name and the member value is the option value. Specifying null has the same effect as specifying an empty object.
serverIdUUIDstring UUID of the server to which the channel shall be added if it does not exist yet or to which it must belong if it already exists.

Move channel

The move channel command moves a channel from one server to a another one. If the specified channel does not exist, the command fails. It also fails if the specified expectedOldServerId does not match the server ID of the channel’s current server. The object for the move channel command has the following structure:

Field nameInternal data typeJSON data typeDescription
channelNamestringstring name of the channel that shall be moved.
commandTypeenumstring always the literal string move_channel.
expectedOldServerIdUUIDstring expected UUID of the server which currently owns the channel. If null, the channel is moved regardless of the server it currently belongs to.
newServerIdUUIDstring UUID of the server to which the channel shall be moved.

Refresh channel

The refresh channel command causes a server to temporarily stop archiving for that channel, reload its configuration, and resume archiving with the freshly loaded configuration. This command succeeds, even if the channel does not exist or actually exists on a different server. However, the actual refresh action only happens on the specified server. The object for the refresh channel command has the following structure:

Field nameInternal data typeJSON data typeDescription
channelNamestringstring name of the channel that shall be refreshed.
commandTypeenumstring always the literal string refresh_channel.
serverIdUUIDstring UUID of the server on which the refresh action should run. This does not have to be, but typically should be the UUID of the server that owns the channel.

Remove channel

The remove channel command deletes a channel (and all its data). If the specified channel does not exist, the command fails. It also fails if the specified expectedServerId does not match the server ID of the channel’s current server. The object for the remove channel command has the following structure:

Field nameInternal data typeJSON data typeDescription
channelNamestringstring name of the channel that shall be deleted.
commandTypeenumstring always the literal string remove_channel.
expectedServerIdUUIDstring expected UUID of the server which currently owns the channel. If null, the channel is deleted regardless of the server it currently belongs to.

Rename channel

The rename channel command changes the name of a channel. If the specified channel does not exist or the specified newChannelName is already in use, the command fails. It also fails if the specified expectedServerId does not match the server ID of the channel’s current server. The object for the rename channel command has the following structure:

Field nameInternal data typeJSON data typeDescription
commandTypeenumstring always the literal string rename_channel.
expectedServerIdUUIDstring expected UUID of the server which currently owns the channel. If null, the channel is renamed regardless of the server it currently belongs to.
newChannelNamestringstring new name for the channel.
oldChannelNamestringstring old name of the channel.

Update channel

The update channel command updates the configuration of an existing channel. If the specified channel does not exist, the operation fails. It also fails if the expectedControlSystemType does not match the actual control-system type of the channel or the expectedServerId does not match the ID of the server that owns the channel.

The set of decimation levels that shall be added and removed can be described in an explicit or in a differential fashion. For an explicit description, use the decimationLevels member. For a differential description, use the addDecimationLevels and removeDecimationLevels members. Only one of the two ways to describe the change can be used at the same time. Setting both decimationLevels and either or both of addDecimationLevels and removeDecimationLevels results in an error.

If decimation levels are listed in decimationLevels or addDecimationLevels, but do not have a corresponding entry in decimationLevelToRetentionPeriod, a retention period of zero is assumed for these decimation levels, even if they already exist with a different retention period.

Like the decimation levels, the control-system-specific configuration options can also be described in an explicit or in a differential fashion. For an explicit description, use the options member. For a differential description, use the addOptions and removeOptions members. Only one of the two ways to describe the change can be used at the same time. Setting both options and either or both of addOptions and removeOptions results in an error.

The object for the update channel command has the following structure:

Field nameInternal data typeJSON data typeDescription
addDecimationLevelsset of intarray of string decimation levels (identified by their decimation periods specified in seconds) that shall be added for the channel. If the whole array is null and decimationLevels is also null, no decimation levels are added.
addOptionsmap of string to stringobject with string member values control-system-specific configuration options that shall be added to the channel configuration. The member key is the option name and the member value is the option value. If one of the specified options already exists, its value is updated with the specified value. If this member is null and options is also null, no control-system-specific options are added for the channel.
channelNamestringstring name of the channel that shall be updated.
commandTypeenumstring always the literal string update_channel.
decimationLevelsset of intarray of string decimation levels for the channel (identified by their decimation periods specified in seconds). The raw decimation level (with a decimation period of zero) is always added, even if it is not specified in the array. If the whole array is null and addDecimationLevels and removeDecimationLevels are also null, no decimation levels are added or removed. If the array is not null all existing decimation levels (except for the special raw decimation level) that are not also specified in the array are removed.
decimationLevelToRetentionPeriodmap of int to intobject with string member values retention period for each decimation level (specified in seconds). Each member uses the decimation period of the respective decimation level as its key and the retention period as its value. A value of zero means that samples shall be retained indefinitely. Entries for a decimation level that are not also specified in decimationLevels or addDecimationLevels and that do not already exist, are discarded (except for the raw decimation level which is always included implicitly). Negative retention periods are converted to zero. If a decimation level is specified in decimationLevels or addDecimationLevels, but not in decimationLevelToRetentionPeriod, a retention period of zero is assumed. If the whole object is null, a retention period of zero is used for all decimation levels that are newly added and the retention periods of all other decimation levels are not changed.
enabledbooleanboolean true if archiving shall be enabled for the channel, false if archiving shall be disabled. If null, the enabled flag is not changed.
expectedControlSystemTypestringstring internal identifier for the control-system support that is expected to be used for the channel. If null, the channel is updated regardless of its control-system type.
expectedServerIdUUIDstring UUID of the server to which the channel must belong. If null, the channel is updated regardless of the server to which it belongs.
optionsmap of string to stringobject with string member values control-system-specific configuration options. The member key is the option name and the member value is the option value. If this member is not null, all options are replaced by the specified options, removing options that existed before, but were not specified. If this member is null and both addOptions and removeOptions are also null, the control-system specific options for the channel are not changed.
removeDecimationLevelsset of intarray of string decimation levels (identified by their decimation periods specified in seconds) that shall be removed from the channel. If the whole array is null and decimationLevels is also null, no decimation levels are removed. The special decimation level for raw samples is never removed, even if zero is an element of this array.
removeOptionsset of stringarray of string control-system-specific configuration options (identified by their names) that shall be removed from the channel configuration. If one of the specified options does not exist, it simply is not removed. If this member is null and options is also null, no control-system-specific options are removed from the channel configuration.

Example

Request:

POST /admin/api/1.0/run-archive-configuration-commands

{
  "commands": [
    {
      "channelName": "someExistingChannel",
      "commandType": "add_channel",
      "controlSystemType": "channel_access",
      "decimationLevels": ["0", "30", "300"],
      "decimationLevelToRetentionPeriod": {
        "0": "864000"
      },
      "enabled": true,
      "serverId": "7cf8f393-cd00-46ae-9343-53e9cb5793fd"
    },
    {
      "channelName": "someNewChannel",
      "commandType": "add_channel",
      "controlSystemType": "channel_access",
      "decimationLevelToRetentionPeriod": {
        "0": "31536000"
      },
      "enabled": true,
      "options": {
        "someControlSystemOption": "someValue"
      },
      "serverId": "7cf8f393-cd00-46ae-9343-53e9cb5793fd"
    },
    {
      "addDecimationLevels": ["30"],
      "channelName": "someOtherChannel",
      "commandType": "update_channel",
      "decimationLevelToRetentionPeriod": {
        "0": "864000",
        "30": "31536000"
      }
    }
  ]
}

Response:

{
  "results": [
    {
      "command": {
        "channelName": "someExistingChannel",
        "commandType": "add_channel",
        "controlSystemType": "channel_access",
        "decimationLevels": ["0", "30", "300"],
        "decimationLevelToRetentionPeriod": {
          "0": "864000",
          "30": "0",
          "300": "0"
        },
        "enabled": true,
        "serverId": "7cf8f393-cd00-46ae-9343-53e9cb5793fd"
      },
      "errorMessage": "Channel \"someExistingChannel\" cannot be added because a
↪channel with the same name already exists.",
      "success": false
    },
    {
      "command": {
        "channelName": "someNewChannel",
        "commandType": "add_channel",
        "controlSystemType": "channel_access",
        "decimationLevels": ["0"],
        "decimationLevelToRetentionPeriod": {
          "0": "31536000"
        },
        "enabled": true,
        "options": {
          "someControlSystemOption": "someValue"
        },
        "serverId": "7cf8f393-cd00-46ae-9343-53e9cb5793fd"
      },
      "success": true
    },
    {
      "command": {
        "addDecimationLevels": ["30"],
        "channelName": "someOtherChannel",
        "commandType": "update_channel",
        "decimationLevelToRetentionPeriod": {
          "0": "864000",
          "30": "31536000"
        }
      },
      "success": true
    }
  ]
}