5. Import channel configuration for a server

Request

The request URL for importing the channel configuration for a server has the following form:

/channels/by-server/<server ID>/import

The <server ID> has to be replaced by the UUID associated with the respective server. The request must use the POST method.

The request body must be a JSON object with the following members:

Field nameInternal data typeJSON data typeDescription
addChannelsbooleanboolean true if channels present in the configuration file, but missing on the server shall be added to the server. false if no new channels shall be added to the server. Default is false.
configurationFilearray of bytestring Base64 (RFC 4648) encoded contents of the configuration file that shall be imported.
removeChannelsbooleanboolean true if channels missing in the configuration file, but present on the server shall be removed from the server. false if no new channels shall be removed from the server. Default is false.
simulatebooleanboolean true if no modifications shall be made. This means that the response will have the same content as if all changes where applied successfully. This is useful in combination with the removeChannels option in order to see which channels would be removed. Default is false.
updateChannelsbooleanboolean true if channels present in the configuration file and also present on the server shall be updated to match the configuration specified in the file. false if no existing channels shall be changed. Default is false.

Response

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

Field nameInternal data typeJSON data typeDescription
addOrUpdateFailedmap of string to stringobject (with string attribute values) object with a member for each channels for which an add or update operation failed. The channel name is the member’s key and the corresponding error message is the member’s value. May be null if there is a global error or if the data is sent in response to a request that has the simulate flag set.
addOrUpdateSucceededset of stringarray of string list of channels for which an add or update operation was successful. In case of an update operation, this does not necessarily mean that the server configuration has been updated. It might also have already been identical to the configuration specified by the file. May be null if there is a global error.
errorMessagestringstring error message indicating a global problem. Such a problem does not affect a specific channel, but the import process in general (e.g. a syntax error in the configuration file). If such an error is present, no changes have been made to the server configuration. null if there is no global error.
removeFailedmap of string to stringobject (with string attribute values) object with a member for each channel for which a remove operation failed. The channel name is the member’s key and the corresponding error message is the member’s value. May be null if there is a global error or if the data is sent in response to a request that has the simulate flag set.
removeSucceededset of stringarray of string list of channels for which a remove operation was successful. May be null if there is a global error.

If there is a problem with the request parameters (e.g. a syntax eror in the configuration file), HTTP error code 400 (bad request) is returned. If there is a general problem with the request body, the response body is invalid. If there only is a problem with the contents of the configuration file, a valid JSON response with the errorMessage set is returned. 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 when applying the changes for at least one channel, HTTP error code 500 (internal server error) is returned and the channel is added to the addOrUpdateFailed or removeFailed maps. 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.

Example

Request:

POST /admin/api/1.0/channels/by-server/7cf8f393-cd00-46ae-9343-53e9cb5793fd/import

{
  "addChannels": true,
  "configurationFile": "PD94bWwgdmVy... (shortened for this example)",
  "removeChannels": true
}

Response:

{
  "addOrUpdateFailed": {
    "someChannel": "Channel \"someChannel\" cannot be added because a channel
↪with the same name already exists."
  },
  "addOrUpdateSucceed": [
    "newChannel"
  ],
  "errorMessage": null,
  "removeFailed": {},
  "removeSucceeded": [
    "someOtherChannel"
  ]
}