Understanding the NMS Java Application Configuration Process

Oracle Utilities Network Management System Java applications are configured using standard product configuration data with overrides that are customer/project specific. This section describes the product configuration files and explains the process for creating and deploying custom overrides.

This section includes the following topics:

• Understanding NMS Java Application Configuration Files

• Understanding the Process for Building and Deploying Custom Configuration

• Testing the Java Client Configuration

Understanding NMS Java Application Configuration Files

While there is some graphical user interface (GUI) configuration information stored in the database (for example, certain menu options), most Java application GUI configuration is contained in XML and text files. The primary configuration file types are:

• *.xml: the primary Oracle Utilities Network Management System Java application XML configuration files. The *.xml files follow the JBot XML schema (jbot.xsd) and must be modified as a whole file to be valid. Most of the attributes in the XML file are either required or have a default value.

• *.inc: XML snippets that are referenced in the XML files.

• *.properties: standard Java configuration text files. Properties configuration follow a base-plus-delta hierarchy so you only need to include a project version of a properties file when you wish to modify a property and then only need to include the lines that are being modified.

Configuration File Location

NMS Java application configuration files are installed in the ${NMS_BASE}/dist/baseconfig/product/ directory. When creating a custom configuration, the application’s configuration files are copied to the ${NMS_CONFIG}/jconfig/ directory using the same directory structure as they exist in the product directory.

For example, the AMR interface configuration file (AMRInterface.properties) is located in the ${NMS_BASE}/dist/baseconfig/product/server/ directory. To customize the interface, copy the configuration file to ${NMS_CONFIG}/jconfig/server/ and edit the new file.

Understanding the Process for Building and Deploying Custom Configuration

Once configuration files are modified, the applications must be rebuilt and deployed to the Oracle WebLogic Application Server.

Note: the customizations to the Java application configuration are made and built after the initial installation of the Oracle Utilities Network Management System.

Create or Modify the Project build.properties File

When implementing custom configurations, the project parameters are added to the build.properties file. The file contains various properties that are required for the configuration build process.

The file is located in your ${NMS_CONFIG}/jconfig/directory. If it not in the directory, it needs to be created from a template.

1. Copy $NMS_BASE/templates/build.properties.template to $NMS_CONFIG/[project]/jconfig/.

2. Rename the template to build.properties.

3. Edit the file to customize it for your environment.

The file includes all of the variables that may be set and their usage. Some of the parameters depend on specific implementation options and may not apply to your project. For example, the config.multispeak_jms parameter is only needed for projects with the MultiSpeak Adapter.

Some of the general values in the build.properties file are:

project.name	The name of the project/customer. This is displayed in the Help About dialog of any Java GUI applications to identify the application as being configured for the project/customer.
project.tag	This is a version control tag or other identifier used to identify a particular build of the customer-specific configuration. This is also displayed on the Help About dialog of any Java GUI applications to identify a customer-specific configuration deployment.
publisher.ejb-user	This is the user that the corba publisher will run as. It should be part of the nms-service group. If not defined, defaults to nms1.
dir.localization	If the configuration is based off of a localized (non-English language) version, enter the directory of the localization configuration. Otherwise leave this commented out.
dir.config.deploy	This is the directory where runtime configuration jar files will be created. The default is a staging area ($NMS_HOME/java/deploy), but it is also possible to configure these runtime files to be deployed directly to the application server; if this is desired, uncomment the line and update the path as appropriate for your WebLogic deployment.
dir.working	This is the directory where the configuration files will be copied to.
dir.client_installed	This is the directory where the Oracle Utilities Network Management System Java applications will be installed on a PC.

Build Process for XML and Properties Files

After making changes to the java application configuration files and modifying the build.properties file for your environment, the runtime configuration jar files are created by running the following command:

$ nms-install-config --java

The command will create the cesejb.ear and nms-multispeak.ear (Oracle Utilities Network Management System MultiSpeak Adapter) files.

If the cesejb.ear file is to be deployed to a staging area, it must be copied to the appropriate directory for the Java application server (e.g., WebLogic).

The build process copies and/or merges the xml and properties files from the product and project directories to $NMS_HOME/java/working and combines them in a jar file.

• When a project xml file exists, it takes precedence over the product version.

• Product and project properties files are combined into one generated file.

Example

You want to rename the Work Agenda tool in the Web Workspace Tools menu.

Workspace_en_US.properties Product Version:

...

# Tools - Options

MNU_TOOLS.text = Tools

MNU_WORK_AGENDA_1.text = Work Agenda 1...

MNU_WORK_AGENDA_1.tooltip = Start Work Agenda 1

MNU_WORK_AGENDA_2.text = Work Agenda 2...

MNU_WORK_AGENDA_2.tooltip = Start Work Agenda 2

MNU_VIEWER_1.text = Viewer 1...

MNU_VIEWER_1.tooltip = Start Viewer 1

...

1. Create a new Workspace_en_US.properties file in ${NMS_CONFIG}/jconfig/product/ops/workspace/properties.

2. Copy the lines that you want to edit from the product version of Workspace_en_US.properties and paste them into the new project file.

3. Edit the lines in the new file:

MNU_WORK_AGENDA_1.text = Work List One...

MNU_WORK_AGENDA_1.tooltip = Start Work List One

MNU_WORK_AGENDA_2.text = Work List Two...

MNU_WORK_AGENDA_2.tooltip = Start a second Work List

4. Save and close the project file.

5. When you run the build, a generated version of the file will be created that merges the changes into the product properties file:

Generated Version:

# Generated from projects\jconfig\ops\workspace\properties\Workspace_en_US.properties

# $Id: Workspace_en_US.properties,v 1.3 $

MNU_WORK_AGENDA_1.text = Work List One...

MNU_WORK_AGENDA_1.tooltip = Start Work List One

MNU_WORK_AGENDA_2.text = Work List Two...

MNU_WORK_AGENDA_2.tooltip = Start a second Work List

# Generated from product\jconfig\ops\workspace\properties\Workspace_en_US.properties

MNU_VIEWER_1.text = Viewer 1...

MNU_VIEWER_1.tooltip = Start Viewer 1

…

Project values that change a product value will override the product value; however, if a project duplicates, but does not change, the product configuration, then the line is removed from the project configuration in the generated file.

Deploying to WebLogic Application Server

To deploy the Oracle Utilities Network Management System application in your domain, follow these steps:

1. Access the WebLogic Server Administration Console by entering the following URL:

http://hostname:port/console

Here hostname represents the DNS name or IP address of the Administration Server, and port represents the number of the port on which the Administration Server is listening for requests (port 7001 by default).

2. If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.

3. In the left pane of the Administration Console, select Deployments.

4. If a previous release of Oracle Utilities Network Management System (cesejb) is in the table:

• Select the checkbox to the far left of the deployed cesejb application and click Stop and choose Force Stop Now to stop the application.

• Select the checkbox to the far left of the deployed cesejb application. Click the Delete button at the top or bottom of the Deployments table to delete the cesejb application, then click Yes to confirm your decision.

5. In the right pane, click Install.

6. In the Install Application Assistant, locate the cesejb.ear to install. This will be in the directory listed in your build.properties setting "dir.config.deploy".

7. Click Next.

8. Specify that you want to target the installation as an application.

9. Click Next.

10. Select the servers and/or cluster to which you want to deploy the application.

Note: If you have not created additional Managed Servers or clusters, you will not see this assistant page.

11. Click Next.

12. Click Next.

13. Review the configuration settings you have specified, and click Finish to complete the installation.

14. To activate these changes, in the Change Center of the Administration Console, click Activate Changes.

Validate Read Only Tables

If running under WebLogic, verify that the nms_readonly.sql accurately defines the tables that the client needs access to. The most likely reason that this list will need to be changed is if a viewer search was added that uses another table or view.

Note that the device attribute tables will always be included so they do not need to be explicitly listed in the readonly.sql file.

If the list needs to be changed from product, copy the nms_readonly.sql to a project specific file and put it in $NMS_CONFIG/sql.

Alternate Deployment of Client-Only Changes

If it is desirable to deploy client‑only configuration changes without restarting the managed server each time, the following process can be used:

On the managed server, under startup parameters add this parameter:

-Dnms.config_override_dir=/override_dir

Replace override_dir with the path to a directory that can contain an updated nms_config.jar file. Ideally when multiple servers for a single instance of nms a shared directory should be used so that each server is updated with one operation.

Then if it is desired to update the existing configuration for a running do the following:

1. Run nms-install-config --java

2. Copy $NMS_HOME/java/working/cesejb.ear/lib/nms_config.jar to the override_dir defined above.

Then, the next time a client is started, it will use the overridden file.

Note: If this feature is used, it should be done as a process where any update to cesejb.ear deletes the obsolete nms_configuration. Otherwise, the managed server will log warnings that there is file older than the one in the cesejb.ear file. In this case, the version that is in the cesejb.ear file will be used.

Most things that are in the $NMS_CONFIG/jconfig can be modified this way, with the exception of items in the $NMS_CONFIG/jconfig/server directory. Also, most items in the Global_en_US.properties and CentricityTool.properties files cannot be modified, unless they only affect the client (such as window positions).

Color Configuration

Color schemes are defined in ColorSchemes.properties. You can define overrides for light and dark themes for colors, which are defined in UIManager.properties and themesource.properties. You can add schemes by creating entries in ColorSchemes.properties. All RGB colors are supported.

An example of a color that can be modified in the ColorSchemes.properties file would be the study mode border color. This provides a thicker border color (green by default) around windows and dialogs that support study mode and real-time mode:

dark.StudyModeBorder.color=#25AA3FCC

light.StudyModeBorder.color=#1E8931CC

Note that the hex values above include an alpha value so it is semi-transparent and the border does not obscure the items underneath it

Testing the Java Client Configuration

This section details how to test Java client configuration without deploying the changes to an app server. Changes can be made locally on a client Microsoft Windows machine and immediately tested.

1. Use the Configuration Assistant to create the client application installer and install the application you will be testing (for example, Web Workspace). See the Oracle Utilities Network Management System Installation Guide for complete instructions on creating the installer and installing the client applications.

Notes:

• The directions below assume that the client is installed to C:\OracleNMS and the project name is [your_project_name]. The location and the project name can be changed as appropriate.

• Installer Log Files: The installers create log files that may be used in troubleshooting installation issues. The log files are saved to:

C:\Users\[user]\AppData\Local\Temp\OracleNMS [Windows 7]

The log files have the following naming convention: [applicationname].log (for example, WebWorkspace.log).

2. On the NMS server machine, do the following:

$ cd $NMS_CONFIG

$ zip -r $HOME/nms_config.zip jconfig

$ cd $NMS_HOME

$ zip -r $HOME/java.zip java

3. Next, transfer them to the client machine.

• Unzip nms_config.zip to C:\OracleNMS\[your_project_name]

• Unzip java.zip to C:\OracleNMS\

4. Install Apache Ant version 1.8.2. Be sure to put the ant bin directory on the system path. For example, if Apache Ant is installed to C:\apache-ant-1.8.2, add C:\apache-ant-1.8.2\bin to the system path.

5. Create two environment variables (using the Microsoft Windows Control Panel):

• Name: NMS_CONFIG; Value: C:\OracleNMS\[your_project_name]

• Name: NMS_HOME; Value: C:\OracleNMS

You can then modify the configuration in C:\OracleNMS\<your_project_name>\jconfig

6. To test the changes do:

cd C:\OracleNMS\[your_project_name]\jconfig

ant clean config

ant config

Notes:

• ant clean config will regenerate all of the configuration; you will need to do that when updating to a new release.

• ant config can be used within a session to only update the files that have changed.

7. Finally, run the application as normal. The system will use the local configuration instead of the configuration on the server.

8. When satisfied with the configuration, transfer the files in C:\OracleNMS\[your_project_name] to the NMS server under $NMS_CONFIG.