Bosch IoT Remote Manager

This document describes the ways to manage the hosts added to the RM backend.

Overview

In an RM system there are backend hosts, which play specific roles: control center, management servers and remote access servers.

From the control center it is possible to configure backend server hosts, that is, to define new hosts and modify the roles of already added ones. In addition, there are specific options available for configuration of management servers.

For more information about the basic principles of backend server host configuration, refer to Basic Concepts.

Calling the APIs for Backend Server Host Configuration

The backend server hosts in an RM system can be monitored through the Configurator Manager service (com.prosyst.mprm.admin.system.ConfiguratorManager) and be configured through the com.prosyst.mprm.admin.system.Configurator instance, retrievable from the Configurator Manager.

When using the Configurator Manager service for managing backend server host, you get information only about those hosts which are added persistently in the system.

When using the Configurator instance, it is assumed that you are going to make some changes and then apply them to the system by calling the apply method. Changes are accumulated in the Configurator so that you can apply them altogether, which saves system restart and reinitialization. Before applying you receive information about the hosts currently set in the Configurator, not about the hosts from the persistent configuration.

Both configuration utilities can be access from either a backend OSGi framework or a Remote Access to RM. For more information about the accessing the Configurator Manager and Configurator, refer to the System Configuration Management document.

Configuring Backend Server Hosts

Backend server hosts are configured through the Configurator for the specific system configuration. You can also use the Configurator Manager to retrieve persistent information about the hosts currently added in the system.

Backend server hosts are represented by the com.prosyst.mprm.admin.system.BackendServerHost interface. It allows you to view the state of the host as well as retrieve its identification and connection data.

Getting Backend Server Hosts in an RM System

The backend server hosts currently added to an RM system can be viewed with the method of the com.prosyst.mprm.admin.system.SystemObserver interface, implemented by the Configurator Manager and Configurator.
There are several approaches when getting information on RM backend hosts:

Approach	Method from SystemObserver
Getting the BackendServerHost representation for a host with specific host ID	`getBackendServerHost(String hostId)`
Getting all BackendServerHosts with the same role in an RM system	`getBackendServerHosts(String roleID)`
Getting the IDs of all hosts	`getBackendServerHostIds()`
Getting the BackendServerHosts for all backend server hosts	`getBackendServerHosts()`

Getting the Configuration of a Backend Host

By Using the Configurator Manager

You can get the persistent configuration of the local or the connected backend host by calling the getHostConfig method of com.prosyst.mprm.admin.system.SystemState. SystemState can be obtained from the Configurator Manager (see System Configuration Management Programmer's Guide for details on observing the system).

The getHostConfig method returns a dictionary containing some of the following host properties:

Property	Wrapper Field	Description
mprm.host.id	`BackendServerHost.HOST_ID`	Contains the host ID, unique in the scope of the RM system.
mprm.host.address	`BackendServerHost.ADDRESS`	Contains the host address.
mprm.host.port	`BackendServerHost.PORT`	Indicates the host port allocated for the RM Connection Framework.
mprm.host.network	`BackendServerHost.HOST_NETWORK`	Contains the home network of the backend server host.
system.id	`SystemConfigurable.SYSTEM_ID (accessible only from within a backend host framework)`	Indicates the unique ID of the RM system.
system.version	`SystemConfigurable.SYSTEM_VERSION (accessible only from within a backend host framework)`	Contains the version of the RM System package.
mprm.cc	`Roles.CC`	Indicates if the host is the system control center. Can be true or false.
cc.host	`SystemConfigurable.CC_HOST (accessible only from within a backend host framework)`	Contains the control center host address.
cc.port	`SystemConfigurable.CC_PORT (accessible only from within a backend host framework)`	Contains the control center port used by the RM Connection Framework.
mprm.ras	`Roles.RAS`	Indicates if the host is a remote access server. Can be true or false.
mprm.ms	`Roles.MS`	Indicates if the host is/participates in a management server. Can be true or false.
mprm.ms.id	`ManagementServer.ID`	Contains the management server ID associated with the host. Available only if mprm.ms is true.
mprm.ms.context	`ManagementServer.CONTEXT`	Contains the device context of the management server associated with the host. Available only if mprm.ms is true.

By Using a Service on the Backend

On the backend OSGi framework, applications can use another convenient way to get the persistent configuration of the local host - by using the com.prosyst.backend.system.SystemConfigInfo service. It provides method for getting the essential attributes of the host's configuration. Note that this service is not available remotely to RAC-based applications.

Adding a New Backend Server Host

To add a new backend server host, it must be preliminary started.

Then, you take the following steps:

1. Define the identification properties of the host in a java.util.Dictionary implementation. These properties include:

Backend Host Property	Java Type	Description
`BackendServerHost.ADDRESS`		The network address of the host - this can be an IP address or a DNS name.
`BackendServerHost.PORT`		The host port for communication with the RM system. This is usually the port used by the RM Connection Framework.
`BackendServerHost.USER`	`String`	The name of the user, which has rights for administration of the host. By default, this is the system user.
`BackendServerHost.PASSWORD`		The password for the user specified with the above property. For the system user, the default password is system.
`BackendServerHost.HOST_NETWORK`		The parent network of the host. By default, it is added to the default network. For information about RM networks, refer to Network Configuration.

2. Call addBackendServerHost method of Configurator so that the host becomes a system entry. As a result, this method returns the BackendServerHost object for the host.

3. Define host roles with the setBackendServerHostRoles method. This method takes as arguments the backend server host ID, which can be taken from the BackendServerHost instance, and the roles that the host will have in the system, whose representation are provided in the com.prosyst.mprm.admin.system.Roles class.

You cannot add a new backend host without a role.

The example in the following listing adds a new backend server host to the system under the "My Host" ID and sets it as remote access server.

Adding a new backend server host to an RM system:

import com.prosyst.mprm.admin.system.BackendServerHost;
import com.prosyst.mprm.admin.system.Configurator;
import com.prosyst.mprm.admin.system.Roles;
import java.util.*;
       . . .
  BackendServerHost bckSHost = null;  static final String HOST_ADDRESS = "bckhost";
       . . .
    Hashtable hostProps = new Hashtable();
    hostProps.put(BackendServerHost.ADDRESS, HOST_ADDRESS);
    hostProps.put(BackendServerHost.HOST_ID, "My Host");
    hostProps.put(BackendServerHost.PORT, "11449");
    bckSHost = configurator.addBackendServerHost(hostProps);
    configurator.setBackendServerHostRoles(bckSHost.getId(), new String[] {Roles.RAS});
       . . . 

Setting Host Roles

Host roles are modified with the setBackendServerHostRoles method of the system Configurator, which requires a dictionary with the new host roles including the ones that the host already has. For role definition you can use the fields of the Roles class.

Getting/Setting Host Connection URLs

Getting connection URLs. The URLs for contacting a specific backend host can be retrieved with the following BackendServerHost methods:

BackendServerHost Method	Description
`getURLs()`	Returns all connection URLs of the backend host. Currently, these can be URLs for socket and SSL connection.
`getURL(String schema)`	Returns the host connection URL related to the specified scheme. The scheme parameter should include only the scheme name, that is, "socket" or "ssl".
`getURL()`	Returns the preferred host connection URL. Currently, this is the URL for socket connection.

The following listing retrieves the connection URLs of all host in the system. For each host it gets all host's connection URLs, the SSL connection URL and the preferred URL.

Retrieving host connection URLs:

import com.prosyst.mprm.admin.system.ConfiguratorManager;
import com.prosyst.mprm.admin.system.BackendServerHost;
        
       . . . ConfiguratorManager configMgr;
// Getting the Configurator Manager service
       . . .
   BackendServerHost[] hosts = configMgr.getBackendServerHosts();
   for(int i=0; i< hosts.length; i++){
     String[] hostURLs = hosts[i].getURLs();
     for(int j=0; j < hostURLs.length; j++) {
       System.out.println("HOST " + hosts[i].getId() + "URL: " + hostURLs[j]);
     }
     System.out.println("HOST Preferred URL: " + hosts[i].getURL());        
     System.out.println("HOST URL for specific schema: " + hosts[i].getURL("ssl"));
       . . . 

Setting connection URLs. You can change the connection URLs of a host with the updateBackendServerHostURLs method of Configurator.

Another way to set a connection URL is by invoking the Configurator's setBackendServerNetworkURLs method for the "default" network (Network.DEFAULT_NETWORK).

The following listing sets socket and ssl connection URLs to all backend hosts in the system.

Setting host connection URLs:

import com.prosyst.mprm.admin.system.Configurator;
import com.prosyst.mprm.admin.system.BackendServerHost;
             . . .
  Configurator configurator;
  // Getting the Configurator for the current system
              . . .
  BackendServerHost[] hosts = configurator.getBackendServerHosts();
    for(int i=0; i< hosts.length; i++){
      String[] hostURLs = {"socket://" + hosts[i].getHostAddress() + ":" + hosts[i].getPort(),
                           "ssl://" + hosts[i].getHostAddress() + ":11443"};
      BackendServerHost host = configurator.updateBackendServerHostURLs(hosts[i].getId(),
                                                                    hostURLs);
    }
             . . .

Removing a Backend Server Host

A backend server host can be removed from the host configuration of the RM system with the removeBackendServerHost method of Configurator.

Configuring Management Servers

Management servers are managed through the Configurator entity, which includes adding/removing management servers, specifying constituent backend server hosts and modifying device contexts.

Managing the Device ManagementTree

The tree of managed devices is represented by the com.prosyst.mprm.admin.system.TreeBrowser interface, which is implemented by Configurator. It offers methods for tree navigation and creation/removal of nodes.

The nodes in the device management tree stand for specific device groups, represented as com.prosyst.mprm.admin.system.GatewayGroup instances. A device group has a name and a path, equal to its name appended to the path of the parent node. The root node path is null.

The following listing creates two nodes in the device management tree - "Node 1" and "Node 2". Then it searches for "Node 2" in the device management tree and on success assigns the object value to another object which will be used further in this document examples.

Managing the device management tree:

import com.prosyst.mprm.admin.system.Configurator;
import com.prosyst.mprm.admin.system.GatewayGroup;
       . . .
  GatewayGroup msCtx = null;  String GW_GROUP1 = "Node 1";
  String GW_GROUP2 = "Node 2";
       . . .
    GatewayGroup group1 = configurator.createNode(null, GW_GROUP1);
    GatewayGroup group2 = configurator.createNode(null, GW_GROUP2);
       . . .
    GatewayGroup[] grs = configurator.getSubGroups(null);
    for (int i=0; i < grs.length; i++) {
      System.out.println("Group = " + grs[i].getName() + "\t " + grs[i].getPath());
      if((grs[i].getName()).equals(GW_GROUP2)){
        msCtx = grs[i];
      }
    } 

Defining a Management Server

When adding a management server to an RM system, you first introduce it. It is not necessary to specify its host (or hosts if clustered) in this stage - this can be done afterwards (see "Assigning a Server Backend Host" below).

A management server definition is done with the addManagementServer method of Configurator, which requires the following arguments:

Management Server Attribute	Description
`ManagementServer.ID`	The ID of the management server. This can be any unique management server ID within the context of an RM system.
`ManagementServer.CONTEXT`	The context of devices, which the management server will be responsible for. Namely, this is the path to the node in the device management tree, the devices in whose sub nodes the management server will manage. You can modify the device tree as described in "Managing the Device Management Tree" above.

The following listing defines a new management server with an ID "My MS" and a context "Node 2" which was previously retrieved in the above listing "Managing the device management tree".

Defining a Management Server in an RM system:

import com.prosyst.mprm.admin.system.ManagementServer;
import com.prosyst.mprm.admin.system.Configurator;
import java.util.*
       . . .
    Hashtable msProps = new Hashtable();
    msProps.put(ManagementServer.ID, "My MS");
    msProps.put(ManagementServer.CONTEXT, msCtx.getPath());
    ManagementServer mServer = configurator.addManagementServer(msProps);
       . . .

Assigning a Backend Server Host

To be able to make a backend server host(s) a management server, you must have first added it to the system either using the console or in program way as previously described.

The host is set as management server with the setBackendServerHostRoles method by including the management server ID in the roles set of the host.

The following listing makes the backend server host from the above listing "Adding a new backend server host to an RM system" play the function of the the management server from the previous listing "Defining a Management Server in an RM system".

Specifying the backend server host of the management server:

import com.prosyst.mprm.admin.system.Configurator;
import com.prosyst.mprm.admin.system.BackendServerHost;
import com.prosyst.mprm.admin.system.ManagementServer;
import com.prosyst.mprm.admin.system.Roles;
. . .
   configurator.setBackendServerHostRoles(bckSHost.getId(),
                                       new String[] {Roles.RAS, mServer.getId()});
. . .

Modifying Management Server Context

If you want to change the device context of a management server, you should use the updateManagementServerContext method of Configurator with the tree path of the new context.

Removing Management Servers

To remove a specific management server, you should use the removeManagementServer method of Configurator. It is also possible to clear all management server in the system with the removeManagementServers method.

References

Backend Server Host Configuration - Conceptual Guide.
Configurator Manager Service API Documentation.
Configurator API Documentation.
SystemObserver API Documentation.
TreeBrowser API Documentation.