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:
Field name | Internal data type | JSON data type | Description |
---|---|---|---|
errorMessage | string | string |
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.
|
results | array of object | array 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 name | Internal data type | JSON data type | Description |
---|---|---|---|
command | object | object | 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. |
errorMessage | string | string |
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.
|
success | boolean | boolean |
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.
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.
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 name | Internal data type | JSON data type | Description |
---|---|---|---|
channelName | string | string | name of the channel that shall be added. |
commandType | enum | string |
always the literal string add_channel .
|
controlSystemType | string | string | 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. |
decimationLevels | set of int | array 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.
|
decimationLevelToRetentionPeriod | map of int to int | object 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.
|
enabled | boolean | boolean |
true if archiving shall be enabled for the
channel, false if archiving shall be
disabled.
|
options | map of string to string | object 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.
|
serverId | UUID | string | UUID of the server to which the channel shall be added. |
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 name | Internal data type | JSON data type | Description |
---|---|---|---|
channelName | string | string | name of the channel that shall be added or updated. |
commandType | enum | string |
always the literal string
add_or_update_channel .
|
controlSystemType | string | string | 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. |
decimationLevels | set of int | array 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.
|
decimationLevelToRetentionPeriod | map of int to int | object 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.
|
enabled | boolean | boolean |
true if archiving shall be enabled for the
channel, false if archiving shall be
disabled.
|
options | map of string to string | object 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.
|
serverId | UUID | string | 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. |
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 name | Internal data type | JSON data type | Description |
---|---|---|---|
channelName | string | string | name of the channel that shall be moved. |
commandType | enum | string |
always the literal string move_channel .
|
expectedOldServerId | UUID | string |
expected UUID of the server which currently owns the channel.
If null , the channel is moved regardless of
the server it currently belongs to.
|
newServerId | UUID | string | UUID of the server to which the channel shall be moved. |
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 name | Internal data type | JSON data type | Description |
---|---|---|---|
channelName | string | string | name of the channel that shall be refreshed. |
commandType | enum | string |
always the literal string refresh_channel .
|
serverId | UUID | string | 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. |
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 name | Internal data type | JSON data type | Description |
---|---|---|---|
channelName | string | string | name of the channel that shall be deleted. |
commandType | enum | string |
always the literal string remove_channel .
|
expectedServerId | UUID | string |
expected UUID of the server which currently owns the channel.
If null , the channel is deleted regardless
of the server it currently belongs to.
|
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 name | Internal data type | JSON data type | Description |
---|---|---|---|
commandType | enum | string |
always the literal string rename_channel .
|
expectedServerId | UUID | string |
expected UUID of the server which currently owns the channel.
If null , the channel is renamed regardless
of the server it currently belongs to.
|
newChannelName | string | string | new name for the channel. |
oldChannelName | string | string | old name of the 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 name | Internal data type | JSON data type | Description |
---|---|---|---|
addDecimationLevels | set of int | array 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.
|
addOptions | map of string to string | object 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.
|
channelName | string | string | name of the channel that shall be updated. |
commandType | enum | string |
always the literal string
update_channel .
|
decimationLevels | set of int | array 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.
|
decimationLevelToRetentionPeriod | map of int to int | object 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.
|
enabled | boolean | boolean |
true if archiving shall be enabled for the
channel, false if archiving shall be
disabled.
If null , the enabled flag is not changed.
|
expectedControlSystemType | string | string |
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.
|
expectedServerId | UUID | string |
UUID of the server to which the channel must belong.
If null , the channel is updated regardless
of the server to which it belongs.
|
options | map of string to string | object 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.
|
removeDecimationLevels | set of int | array 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.
|
removeOptions | set of string | array 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.
|
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 } ] }