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:

Import Initial Properties & Connections into Configuration Application: Rather than manually entering each connection, you can use the REST API to import initial connections into the RTView Configuration Application. You can subsequently edit those connections using the RTView Configuration Application.
Property Editor REST API, Version 5.2#Automate Connection Updates: Rather than using the RTView Configuration Application to manage your connection properties, you can use the REST API to add, edit, and delete connections. This is useful when you have an automated system for provisioning and want to automatically add monitoring as part of the provisioning process. These connections will not be included in the RTView Configuration Application and will only be edited via the REST API.

Import Initial Properties & Connections into Configuration Application

Replace <PackageName> with the abbreviated name for the solution package you are configuring.

To Import Properties:

Install and start the Monitor.
Open a command prompt and navigate to the rtvapm/sampleapps/propeditor directory. Follow the instructions in the README.txt file to configure the node application to connect to the Monitor.

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 Property Editor REST API, Version 5.2#Encrypt Property Text for details.

Use the sample application to retrieve a list of solution packages in your data server as follows:

node main.js -action=getSPs

Use the sample application to get a list of available properties for your solution package as follows:

node main.js -action=getPropertyDescriptions -sp=<PackageName>

where <PackageName> is the abbreviated name for a solution package on the retrieved list.

Create a json file containing the connections and other properties you would like to add. Note that the file contents must be valid json. See Property Editor REST API, Version 5.2#Sample json for details about json properties.
Confirm that the RTView Configuration Application is NOT in use.
Use the sample application to add the properties as follows:

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 Property Editor REST API, Version 5.2#Adding, Editing, Deleting JsonPrimitive Properties for additional information.

Use the sample application to update or restart the data server. An update will apply connection properties. A restart is required to apply non-connection properties:

Node main.js -action=updatePropertiesOnServer

Or

Node main.js -action=restartServers

Now that the initial properties are imported, you can use the RTView Configuration Application to edit your configuration.

Automate Connection Updates

Replace <PackageName> with the abbreviated name for the solution package you are configuring.

To Auto-update Connections:

Install and start the Monitor.
In a text editor, open projects\rtview-server\rtvservers.dat and add -properties:autoconnections at the end of the dataserver line.
Open a command prompt and navigate to the rtvapm/sampleapps/propeditor directory. Follow the instructions in the README.txt file to configure the node application to connect to the Monitor.
By default, all properties (including passwords) are sent to the rtvadmin servlet and on to Data Server in plain text. You can optionally encrypt that text. See Property Editor REST API, Version 5.2#Encrypt Property Text for details.
Use the sample application to get a list of solution packages in your Data Server as follows:

node main.js -action=getSPs

Use the sample application to get the list of available properties for a solution package as follows:

node main.js -action=getPropertyDescriptions -sp=<PackageName>

where <PackageName> is the abbreviated name for a solution package on the retrieved list.

Create a json file containing the connections and other properties you would like to add. Note that the file contents must be valid json. See Property Editor REST API, Version 5.2#Design Notes for details about json properties.
Use the sample application to add the properties as follows:

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 Property Editor REST API, Version 5.2#Filenames for more information.

Use the sample application to update or restart the data server. An update will apply connection properties. A restart is required to apply non-connection properties:

Node main.js -action=updatePropertiesOnServer

Or

Node main.js -action=restartServers

Now that the initial connections have been added, you can delete or modify those connections as follows:

node main.js -action=editProperties -filename=autoconnections -propstoadd=jsonadd.json -propstoremove=jsondelete.json -merge=true

See Property Editor REST API, Version 5.2#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.

Encrypt Property Text

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:

In the sample node.js-based application (in the rtvapm\sampleapps\propeditor directory), set the cryptKey variable to the key you want to use for the AES encryption.

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.

In the data server's rtvservers.dat file, pass the value you used for cryptKey into the command line using the -propkey command line argument on the data server line.

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

Design Notes

This section contains additional options for the REST API.

Supported API Actions

The REST API supports several actions.

To get the list of actions, go to the sample application as described above and execute the following on the command line:

node main.js -action=getActions

To get the description of a single action:

node main.js -action=getActions -name=actionName

You can also execute any action that start with "get" in a browser as follows (where host, port, and rtvadmin are the values you specified in the sample application):

http://host:port/rtvadmin/api?action=getActions&name=actionName

Filenames

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.

Sample json

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.

Adding, Editing, Deleting JsonPrimitive Properties

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”

}

Adding and Editing JsonObject Properties

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.

Deleting JsonObject Properties

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 Property Editor REST API, Version 5.2#Sample json for details about generating properties for your solution package.

Example:

{

"solmon": {

"conn": [{

"__name": "conn2"

},

{

"__name": "conn3",

}

]

}

Updating vs. Restarting Data Servers

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.

High Availability

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.