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.

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

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

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.

There are seven different archive configuration commands:

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:

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:

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:

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:

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:

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:

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:

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
    }
  ]
}