...
The server configurations are stored in two locations in the system: in the central database that allows to manage and review the management of the values via the user interface; and in every server’s registry that allows the local services to read them. The current configuration values can be retrieved from both locations. The system was designed like this to minimize the actions performed by the recorder services: when multiple configuration values and/or multiple extension configurations should be changed, then all changes can be configured without influencing the services, and when everything is configured in the central database, then all recorded changes can be pushed to the server at the same time.
Basically, the values stored in the central database and the registry should not be different, but after a server installation or a manual registry change, there can be differences. Before configuring the server, the differences must be eliminated by using the configurationDifferences endpoint. When the central database value is chosen as the proper value, then one or more configuration tasks will be generated that indicate the required changes in the registry. When the server registry is chosen as the proper value, then the central database will be updated and no other action is required.
...
In the following sections, different use case examples demonstrate the usage of the server configuration-related endpoints.
Use case:
...
Step 1: change the configuration
Firstly, the current value can be retrieved by the server hostname (“verbamr01") and URL encoded registry path (“%5CVerba%5CEmail%20Settings%5CTLSKeyPass") with the next request:
...
There are differences between the central database and the local registry
When there are differences, then a few configuration API endpoints will respond with an HTTP 409 Conflict status and error code PREREQUISITE_NOT_MET.
Retrieve the list of the differences in a certain server.
Request:
| Code Block |
|---|
GET https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configuration?settingPath=%5CVerba%5CEmail%20Settings%5CTLSKeyPass&source=REGISTRY |
If the value should be encrypted like in this case, the new value should be encrypted with the following request:
Request:
| Code Block |
|---|
POST /verba/restapi/v1/encodePassword
new plain password |
Response:
| Code Block |
|---|
NEW ENCRYPTED PASSWORD |
This new value can be used to update the configuration in the local database.
| Code Block |
|---|
PUT https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configuration?settingPath=%5CVerba%5CEmail%20Settings%5CTLSKeyPass
NEW ENCRYPTED PASSWORD |
Step 2: resolve the difference between the central database and the local registry
Retrieve the list of the differences in the certain server.
Request:
| Code Block |
|---|
GET https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationDifferences |
Response:
| Code Block |
|---|
{ "differences": [ { "path": "\\Verba\\Email Settings\\TLSKeyPass", "valueRegistry": "old encrypted configurationDifferences |
Response:
| Code Block |
|---|
{
"differences": [
{
"path": "\\Verba\\Email Settings\\TLSKeyPass",
"valueRegistry": "old encrypted password",
"valueDb": "NEW ENCRYPTED PASSWORD",
"serverCustom": false
},
{
"path": "\\Verba\\Email Settings\\TLSCert",
"valueRegistry": "foo",
"valueDb": "",
"serverCustom": false
}
]
} |
Based on the retrieved information, the differences must be resolved by items with a decision about specifying which data source contains the correct values. For the resolution, a list has to be sent with the correct data sources.
...
| Code Block |
|---|
POST https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationDifferences
Content-Type: application/json
{
"resolutions": [
{
"path": "\\Verba\\Email Settings\\TLSKeyPass",
"correctSource": "DATABASE"
},
{
"path": "\\Verba\\Email Settings\\TLSCert",
"correctSource": "REGISTRY"
}
]
}Settings\\TLSCert",
"correctSource": "REGISTRY"
}
]
} |
Response:
| Code Block |
|---|
"differences": [] |
If there are no more differences in the configuration an empty list should be retrieved. In another case, the resolution must continue. During this step, when the central database value is chosen, then configuration tasks will be created for the server.
Use case: Individual server configuration modification
Step 1: Change the configuration
Firstly, the current value can be retrieved by the server hostname (“verbamr01") and URL encoded registry path (“%5CVerba%5CEmail%20Settings%5CTLSKeyPass") with the next request:
| Code Block |
|---|
GET https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configuration?settingPath=%5CVerba%5CEmail%20Settings%5CTLSKeyPass&source=REGISTRY |
If the value should be encrypted like in this case, the new value should be encrypted with the following request:
Request:
| Code Block |
|---|
POST /verba/restapi/v1/encodePassword
new plain password |
Response:
| Code Block |
|---|
"differences": [] |
If there are no more differences in the configuration an empty list should be retrieved. In another case, the resolution must continue. During this step configuration tasks have been created for the server.
...
NEW ENCRYPTED PASSWORD |
This new value can be used to update the configuration in the local database.
| Code Block |
|---|
PUT https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configuration?settingPath=%5CVerba%5CEmail%20Settings%5CTLSKeyPass
NEW ENCRYPTED PASSWORD |
Step 2: Applying the configuration changes on the server
...