The Monitor REST API allows you to add, edit, and delete properties on a running data server, which means that you can update connection properties without restarting the data server.
A sample node.js-based application is available in the rtvapm/sampleapps/propeditor directory that you can use to edit properties via the same rtvadmin servlet that is used by the RTView Configuration Application. This sample application also serves as an example of how to post to the rtvadmin servlet from your own application. See the README.txt file in the same directory for instructions about how to setup and run the sample application.
Two use cases are supported:
Also see Design Notes for details about Supported API Actions, Filenames, Sample json, Adding, Editing, Deleting JsonPrimitive Properties, Adding and Editing JsonObject Properties, Deleting JsonObject Properties, Updating vs. Restarting Data Servers, and High Availability.
Replace <PackageName> with the abbreviated name for the solution package you are configuring.
To Import Properties:
By default, all properties (including passwords) are sent to the rtvadmin servlet and on to the Data Server in plain text. You can optionally encrypt that text. See Encrypt Property Text for details.
node main.js -action=getSPs
node main.js -action=getPropertyDescriptions -sp=<PackageName>
where <PackageName> is the abbreviated name for a solution package on the retrieved list.
node main.js -action=editProperties -filename=project -propstoadd=jsonfile.json
Note that the file name must be project in this use case. Otherwise, the properties will not be applied. See Adding, Editing, Deleting JsonPrimitive Properties for additional information.
Node main.js -action=updatePropertiesOnServer
Or
Node main.js -action=restartServers
Replace <PackageName> with the abbreviated name for the solution package you are configuring.
To Auto-update Connections:
node main.js -action=getSPs
node main.js -action=getPropertyDescriptions -sp=<PackageName>
where <PackageName> is the abbreviated name for a solution package on the retrieved list.
node main.js -action=editProperties -filename=autoconnections -propstoadd=jsonadd.json
Note that the file name must match the -properties command line argument that you entered in rtvservers.dat. See Filenames for more information.
Node main.js -action=updatePropertiesOnServer
Or
Node main.js -action=restartServers
node main.js -action=editProperties -filename=autoconnections -propstoadd=jsonadd.json -propstoremove=jsondelete.json -merge=true
See Design Notes for more information.
Note: In this scenario, it is possible that the automated property updates are occurring at the same time that someone else is editing other properties in the RTView Configuration Application. Since all properties files are re-read when you execute the updatePropertiesOnServer post, the properties saved by the RTView Configuration Application are re-read as well. The RTView Configuration Application might say that you need to restart servers when it is not necessary.
By default, properties (including passwords) are sent in plain text from the client application to the servlet. To use AES encryption on the text, do the following:
The application might clip or pad this key as needed in order to generate a 16 element byte array that can be used by AES encryption.
You can either enter the key in plain text or you can scramble it using the encode_string command line utility.
For example, you could pass in -propkey:propertyKeyValue, or you could scramble the key as follows on the command line:
encode_string propertyKeyValue
which returns this value:
01343013550134901335013330134801335013500134601331013490134901353013450134801334
You can then use that value on the command line instead:
-propkey:01343013550134901335013330134801335013500134601331013490134901353013450134801334
This section contains additional options for the REST API.
The REST API supports several actions.
node main.js -action=getActions
node main.js -action=getActions -name=actionName
http://host:port/rtvadmin/api?action=getActions&name=actionName
When using the REST API to import initial properties into the RTView Configuration Application, the filename must be project. This is because the RTView Configuration Application reads and writes the project properties files and all RTView projects automatically read them. When using the REST API to automatically update properties that are not included in the RTView Configuration Application, the filename must match the -properties argument in the rtvservers.dat file and must NOT be project.
You can optionally use the RTView Configuration Application to generate sample json to get you started. Properties saved from the RTView Configuration Application are in projects\rtview-server\project.properties.json.
All primitive json values must be enclosed in quotes, even boolean and number values. The top level solution package element must be included.
The following example uses solmon (Solace) properties to illustrate. See the generating sample json properties for details about generating properties for your solution package.
Example:
{
“solmon”: {
“expiretime”:”10000”
}
}
Solution package connections are arrays of JsonObjects. The property descriptions indicate which fields in the json object are required and which are indexes. When adding a new connection (or other JsonObject), you must include all of the required and index fields or the property will not be saved. The top level solution package element must be included.
The following example uses solmon (Solace) properties to illustrate.
Example:
{
"solmon": {
"conn":
[{
"iscloudvmr": "true",
"__name": "conn2",
"url": "http://host2:8080/SEMP",
"version": "7.4VMR",
"vpnnamelist": "vpn1;vpn2"
},
{
"iscloudvmr": "true",
"__name": "conn3",
"url": "http://host3:8080/SEMP"
}
]
}
}
When adding connections to an existing file, you can either merge the new connections into the existing connection list or you can replace the whole list with the connections. This is controlled by the merge parameter. When merge is true, the indexes are used to control whether a new connection is added or an existing connection is modified.
Solution package connections are arrays of JsonObjects. The property descriptions indicate which fields in the json object are indexes. When deleting a connection (or other JsonObject), only the index fields are required. The top level solution package element must be included.
The following example uses solmon (Solace) properties to illustrate. See Sample json for details about generating properties for your solution package.
Example:
{
"solmon": {
"conn": [{
"__name": "conn2"
},
{
"__name": "conn3",
}
]
}
}
All connection properties support updates. Once you have added, edited, or deleted connections using the REST API, you can apply those changes with the updatePropertiesOnServer action. Restart is not required. Note that when connections are removed from your configuration, they are not immediately removed from the monitor. They stay in the caches (and display) but do not receive further updates. They will expire and be removed based on the settings in the DATA STORAGE tab of the RTView Configuration Application. All non-connections properties are applied on restart, so they must be applied with the restartServers action. Restarting your servers will also cause any deleted connections to be immediately removed from the caches and displays.
To edit properties for HA-configured servers, first follow the instructions in Configuring High Availability for DataServer Deliverables to configure the server for High Availability.