Model configuration requires a number of configuration parameters, scripts, and SQL files to be defined in order to fully set up an operational Oracle Utilities Network Management System. The following sections provide a checklist of the configuration settings that are required for a successful model build.

Each user of the Oracle Utilities Network Management System must have an .nmsrc file in the $NMS_HOME directory. Edit the .nmsrc file to set the following required environment variables:

Isis is the messaging backbone used by the Oracle Utilities Network Management System Operations Model, and it is required for every step of a model build. See the Isis Configuration chapter for information about setup and configuration.

To ensure isis is running, type:

Result: If isis is running, a "1" is returned, but (as is accepted *nix practice) the return value of nms-isis process itself is 0 (echo $?=0). If isis is not running, a "0" is returned but $?=1. This can be useful in common shell scripts used to monitor/manage the isis message bus.

Through the installation process the nmsrc file and the Oracle Wallet should be setup correctly so the ISQL script can be run by an administrative user to connect to an interactive session of the database.

ISQL can make a connection to the database. To verify that a connection is possible to the database, complete these steps:

The model builder is primarily concerned with the tables within the selected database and the directory structure located under ${OPERATIONS_MODELS} as shown below.

If the directory structure has not been set up, run the script nms‑mb‑setup to configure it. It requires the OPERATIONS_MODELS environment variable to be set to the user’s map data directory.

The [project]‑mb‑setup script creates and cleans the directory structure for customer specific model build setups.

The [project]‑mb‑preprocessor script is called during the initial setup process to set up any additional directories or database tables that may be required by the model preprocessor. It is only required if special setup is needed.

If the data directory already exists from an obsolete data model, nms‑mb‑setup -clean should be called to clean up all the residual files.

The operations model is designed around a class hierarchy. At the top of the hierarchy is the superclass, from which all other classes inherit attributes. The hierarchy may have multiple levels, each level having a parent/child relationship. The superclass is the only level that is always a parent and never a child.

Classes and inheritance are defined and configured in the [project]_classes.dat and [project]_inheritance.dat files, respectively, located in the [project]/data directory. These files are loaded when the nms‑setup command is run to set up the data model.

These files can be individually loaded using the ODLoad command. The syntax to load classes.dat in Classes table via ODLoad is:

The inheritance relationships file, inheritance.dat, can be loaded into the INHERITANCE table via ODLoad. The syntax is:

In addition to these base class and inheritance files, special files may be included for dynamic condition classes ([project]_cond_classes.dat, [project]_cond_inheritance.dat) and classes required for the power flow application ([project]_pf_classes.dat, [project]_pf_inheritance.dat). These additional files would be supplemental to the base files and should not duplicate any entries.

Oracle includes some required classes within the nms_core_classes.dat file. These classes are required in order for the Oracle Utilities Network Management System to work properly. Their inheritance is defined in nms_core_inheritance.dat and is also required. None of the information in these files should be changed, removed, or duplicated.

The Oracle Utilities Network Management System attribute table is populated using [project]_attributes.sql. The user attribute table is populated using the [project]_model_attributes.sql file.

Control Zones are discrete, hierarchical sections of a utility's distribution system. Control Zone configuration requires defining zones, assigning devices to zones and, optionally, creating zone sets (or groups) that assist in assigning crews to multiple zones and to filter crews.

If you plan to use the Oracle Utilities Network Management System control authority functionality, then all electrical devices should have an assigned Network Component Group (NCG). This is usually assigned in the source data or computed in the preprocessor.

Control Zones are initially defined in the [project]_control_zones.dat file, which is a text file that is read by nms‑control‑zones as part of the nms‑setup and, generally, by the [project]‑postbuild script following model builds. Product configuration uses a depth of five control zones, but you can configure zones to a maximum depth of 10 levels.

Control Zone Sets may be defined for crew assignments. Control Zone Sets are defined in the control_zone_set table.

To create Control Zone Sets, do the following:

For example, you want your zone set (SuperZone Set) to have two zones (Northern Region and Fuzzy). After checking the control_zones table, you determine that Northern Region has an ncg_id of 100000130 and Fuzzy has an ncg_id of 1.

Using a sql file to add the rows to the control_zone_set table, you add the following sql commands:

If you want to restrict the zone set visibility to certain users only, add records to the CONTROL_ZONE_ALIASES table for those users only. If no CONTROL_ZONE_ALIASES records are present for that zone set, the zone set will be available to all users. If you want to exclude access to zones in the zone set from certain users, add entries in the EXCLUDED_ZONE_SET for the set_name value used above. Similarly, add records to the DEFAULT_ZONE_SET table to give users automatic access to them.

Oracle Utilities Network Management System Viewer symbol information is stored in [project]_SYMBOLS.sym file for legacy soft symbols or in the $NMS_CONFIG/jconfig directory structure for Pixmap or Scalable Vector Graphics symbols. The [project]_ssm.sql file maps classes to the particular symbol. The symbology file build process has been standardized to build the run-time symbol file ($NMS_CONFIG/data/SYMBOLS/[project]_SYMBOLS.sym) from these symbol file sources in order of increasing preference:

The command, nms-make-symbols, will do the construction of the run-time symbology file and will make a backup of the resulting file if one existed prior to the execution of this script. Run nms-make-symbols before running nms-install-config to get your [project]_SYMBOLS.sym file up to date with the your latest configuration and NMS product release.

The sms‑start script is used to start up Oracle Utilities Network Management System services. It normally reads the system.dat file to determine which services to start up and what arguments to give them. Before a model is built, this configuration must not be used, because it contains startup commands for the Dynamic Data Service (DDService), the Managed Topology Service (MTService), and the Job Management Service (JMService), none of which will execute until a model has been at least partially built. The model build process expects to find another configuration file, system.dat.model_build, in the same directory that has a more limited set of services. In addition, the system.dat.init file starts up the database services (DBService and ODService) that are used for initial setup.

The Automated Setup script (nms‑setup) and related *.sql and script files will reference a [project]_licensed_products.dat file to properly configure the model to support the products you have licensed. This file is a text file and contains a list of the licensed Oracle Utilities Network Management System options. There is a template version of this file in $NMS_BASE/templates/licensed_products.dat.template. The template should be copied to your $NMS_CONFIG/sql directory and renamed to a [project]_licensed_products.dat file. Then you should edit the file to uncomment the options you have licensed and are implementing. This edited template file should then be installed using the nms-install-config installation script prior to running the nms‑setup command.

The following table describes the product codes used in the template file; refer to the template file for the most current set of product codes and descriptions.

Oracle has an automated process that sets up the database schema and directory structure. Any scripts, SQL files, or data files that are properly set up, named and installed will automatically get picked up and used by this process. The automated setup process will use various SQL files mentioned in this section to build the initial data model.

The nms‑setup script must be run on the model build host machine, which is the machine on which MBService is running. This process loads scripts, SQL, and data files that are properly configured and installed. The script makes liberal use of ISQL, which submits all SQL files to the database to be run. The syntax is:

The following table describes the nms‑setup command line options.

 

nsm‑setup automatically sends its output to a log file in $NMS_LOG_DIR. The standard naming convention is:

The log file named is amended when any combination of the -clean, -offline, or -showme parameters are used:

When output is sent to a log file, a single line will be sent to the console indicating the name of the log file. The first line of the log file shows the arguments that were passed to nsm‑setup.

The nms-post-setup script must be run after the nms‑setup unless nms‑setup was run with the ‑clean, ‑offline, or ‑post option (in which case nms-setup will have automatically run nms‑post‑setup). This process loads scripts, SQL, and data files which will adversely affect the active NMS environment in dual-environment configuration. Running nms-post-setup will make the current environment the active environment.

 

nms-post-setup sends its output to a log file in $NMS_LOG_DIR named setup_post.[date].[time].log.

The NMS_CONFIG_ORDER variable indicates configurations to use. The setup process looks only for the files containing the values specified in this variable. The syntax is:

The first argument is the name of the customer or project. The last argument is the name of the default base configuration. There may be multiple configurations specified between the first and last arguments. When the system boots it processes the arguments from right to left, so it first loads the base configuration. Then it moves on to the previous argument and loads the associated configuration files if they exist. The process continues until each argument is processed.

The setup process runs a large set of shell and SQL scripts that set up all aspects of the NMS model. The right-most value of the NMS_CONFIG_ORDER environment variable identifies a base, or predefined configuration. By default, the setup process sets up the model in the predefined configuration. However, the setup script contains numerous "hooks" that when encountered, install project-specific configuration that overrides the base configuration.

For example, if project XYZ defines a base model stdbase, then the NMS_CONFIG_ORDER environment variable is set to "xyz stdbase". The stdbase configuration is used by default, with project-specific files overriding stdbase files when encountered. The stdbase configuration may contain a script (stdbase‑mb‑preprocessor) that sets up the data model for the stdbase version of the preprocessor. Project XYZ uses a different preprocessor with a different setup. The NMS setup process has a hook for a [project]‑mb‑preprocessor file, so any file of this form with the project prefix as specified by NMS_CONFIG_ORDER (in this case, xyz‑mb‑preprocessor) is called in place of the stdbase version. The exact details are dependent upon the nature of the "hook" involved. Some hooks are set up to call both the project script and the base script, while others will only call one or the other.

At the very end of the nms-setup process is a hook to add project specific additional setup processes using the optional [project]‑supplement script. Typical processes added in this script include:

In order for Oracle Utilities Network Management System Trouble Management to run, customer information must be linked into the model. This information is assumed to be in the database, whether explicitly loaded or whether linked in as a synonym. Oracle requires that the table that contains the customer information be joined to the SUPPLY_NODES table in the CES_CUSTOMERS table

The CES_CUSTOMERS table is populated with details about customers, their meters, and their locations. It includes information from the following tables:

 

To update the Oracle Utilities Network Management System customer model, project-specific customer import processes will drop and rebuild mirror versions of these tables, named:

 

On initial population, populate both the CU_* and CU_*_CIS tables and gather database statistics for them. This will ensure that the staging tables and the core tables are initially in sync and will perform well. They will then run nms‑update‑customers, which will perform change detection between the CU_*_CIS tables and their Oracle Utilities Network Management System counterparts, perform incremental updates to them, and re-create the CES_CUSTOMERS table.

From the CES_CUSTOMERS table, a smaller (summary) table must be extracted that is called CUSTOMER_SUM.

The CUSTOMER_SUM table is a smaller extraction of the CES_CUSTOMERS information in which the customer information is summarized. JMService uses this for faster calculations. Depending on the definition of CUSTOMER_SUM table, a fresh extraction may be required after each model build.