Configuring OMA Search Options

Overview

OMA search options can be project configured to search for objects in the NMS model. The OMA source code provided is set up to search the OPAL model and may need to be tweaked in order to work with a specific project model. In general, the predefined searches for Device ID, Customer information (name, phone, address, account ID, and meeter ID), Feeder Name, and Latitude and Longitude should work as is for most projects however the Substation search (dependent on use of class 10210/substation fences), Site ID search, and Street Intersection search will most likely need to be changed to match project models.

Configuration

The configuration of the OMS search is in three places:

• NMS Database mobile_search Views

• OMA src/js/resources/config/map.js self.searchDefinitions

• OMA src/js/viewModels/map.js and src/js/views/map.html

NMS Database mobile_search Views

Add views in the database to support OMA searches. By convention, OMA search view names should start with mobile_search_ (for example, mobile_search_device_view). Be sure to add them to the GET:/mobile/dataset/{table} API whitelist table (mobile_dataset_tables) and to the READ_ONLY_TABLES. OPAL defines these in the OPAL_schema_mobile_crew_setup.sql file, which is called by the OPAL‑mobile‑crew‑setup script. Projects should define there own versions of these files.

OMA search views should always contain these fields:

• DEV_CLS: object class number of search objects

• DEV_IDX: object index number of search objects

• <search field>: any field you use as a search value (for example, device id)

You can include the following optional fields:

• X_COORD and Y_COORD: if these are provided, the GET:mobile/dataset/{table} API may use these to identify the location to focus on (see the API description below).

• LATITUDE and LONGITUDE: if these are provided, the GET:mobile/dataset/{table} API may use these to identify the location to focus on (see the API description below).

• <more fields>: any other fields to provide context to the OMA user if multiple records match the users search criteria (such as location, feeder, city, and so on).

Example

The following example is from the OPAL_schema_mobile_crew_setup.sql file:

create or replace view mobile_search_device_view as

select a.alias "DEVICE_ID",

c.c_desc "DEV_TYPE",

a.h_cls "DEV_CLS",

a.h_idx "DEV_IDX",

(select coalesce((

select cz.name from network_components nc, control_zones cz

where a.h_cls = nc.h_cls and a.h_idx = nc.h_idx and nc.active = 'Y'

and cz.death is null and nc.ncg = cz.ncg_id

),'NONE') from dual) "FEEDER",

(select coalesce((

select cz2.name from network_components nc, control_zones cz, Control_Zone_Structures czs, control_zones cz2

where a.h_cls = nc.h_cls and a.h_idx = nc.h_idx and nc.active = 'Y'

and cz2.death is null and cz.death is null and czs.active = 'Y' and nc.ncg = cz.ncg_id

and cz.ncg_id = czs.child_ncg_id and cz2.ncg_id = czs.parent_ncg_id

),'NONE') from dual) "SUBSTATION",

(select coalesce((

select pc.x_coord from point_coordinates pc, partitions p

where a.h_cls = pc.h_cls and a.h_idx = pc.h_idx and pc.active = 'Y' and p.active = 'Y'

and pc.partition = p.h_idx and p.coord_system = 0 and pc.sequence = 1 and p.h_cls = 4001

),NULL) from dual) "X_COORD",

(select coalesce((

select pc.y_coord from point_coordinates pc, partitions p

where a.h_cls = pc.h_cls and a.h_idx = pc.h_idx and pc.active = 'Y' and p.active = 'Y'

and pc.partition = p.h_idx and p.coord_system = 0 and pc.sequence = 1 and p.h_cls = 4001

),NULL) from dual) "Y_COORD"

from alias_mapping a,

classes c

where a.active = 'Y'

and a.db_type = 'OPS'

and a.h_cls = c.c_numb

and upper(c.c_type) like 'ATT\_%' ESCAPE '\'

and upper(c.c_type) not like '%STREET%'

and upper(c.c_type) != 'ATT_SUPPORT_STRUCTURE'

;

grant SELECT, INSERT, UPDATE, DELETE ON mobile_search_device_view TO CES_RW;

GRANT select ON mobile_search_device_view TO CES_RO;

delete from mobile_dataset_tables where OBJECT_NAME = 'mobile_search_device_view';

insert into mobile_dataset_tables (OBJECT_NAME, ACCESS_LEVEL) values ('mobile_search_device_view', 'READ');

delete from READ_ONLY_TABLES where OBJECT_NAME = 'mobile_search_device_view';

insert into READ_ONLY_TABLES (OBJECT_NAME) values ('mobile_search_device_view');

COMMIT WORK;

OMA src/js/resources/config/map.js self.searchDefinitions

The format for the search definitions is:

self.searchDefinitions = [

{

searchType: "Device ID",

field1Label: "Device ID:", field1Type: "String",

field2Label: "", field2Type: "",

searchTable: "mobile_search_device_view", searchColumn: "device_id", needs_location: 'Yes',

note:"Use % for multi-character wild card.<br>Use _ for single-character wild card.",

multiSelectAtts: [

{fieldName: "device_id", fieldLabel: "Device ID"},

{fieldName: "feeder", fieldLabel: "Feeder"},

{fieldName: "substation", fieldLabel: "Substation"},

{fieldName: "dev_type", fieldLabel: "Device Type"}

multiSelectTitle: "Device ID Search Results",

showAttsOnOneResult: false,

offlineDataFile: 'offlineDeviceIdSearch.json'

...

]

All fields are required (unless a default value is noted):

• searchType: name used on the top of the search panels and on the search type pull-down on the search panel.

• field1Label: label to use for search filed one on the search dialog panel.

• field1Type: use to validate the field entry, can be on of these values: String, Number, Phone, or COORD.

• field2Label and field2Type: used in search dialog if field2Label is not "".

• searchTable: the mobile_search database table or view to use for the search

• searchColumn: column name to use in the search table. If using two fields on the search panel, the two field values will be combined with a " & " (%20%26%20) between them.

• needs_location: Yes or No. If yes, the RESTful API will get a lat-long=true, which will cause the API to attempt to put _LATITUDE, _LONGITUDE, and LOCATION attributes on the result set.

• note: any special instructions you would like included on the search panel (for example, wild card instructions, format details, and so forth).

• multiSelectAtts: A list of fields to display to the user if they need to select a specific search result. The objects in the list will have two components:

• fieldName: name of the result seat field.

• fieldLabel: Label to use for the field.

These will be displayed in order in a tabular form in a multiple result set panel for the user to select from.

• multiSetlectTitle: Label to put on the top of the multiple result set panel.

• showAttsOnOneResult: True or False. If true, the search results will always be shown to the user, even if only one record is returned for the search. If false, a single record result set will automatically focus the map without presenting the result set to the user.

• focusPriority: {GEO|INT|SUM} - Default is GEO. GEO will focus on the geographic location if the object has a geographic representation, otherwise it will next focus on an internal location if it has one, finally we will focus on the summary location. INT will focus on the internal location if the object has an internal representation, otherwise it will focus on the geographic location. SUM will always focus on the summary location if non-zero, otherwise it will try to focus on the internal location.

• intFocus: {COORD-N|PARTITION} - Default is COORD-6. intFocus will specify the type of focus to do if the target map is an internal map. COORD-N will center the map on the search object coordinate and do N zooms. PARTITION will leave the map to view the entire partition.

• offlineDataFile: "filename" - If not specified, default is offline search is not configured for this search definition. If specified, OMA will download the specified file from the NMS Server $OPERATIONS_MODELS/offline_search directory from the offlineSearchFiles.zip file. File must be in JSON format and match the data structure of the RestFUL service response. OPAL has an example script to build the offline search JSON files (OPAL-build-mobile-offline-search-files).

You can include as many search definitions in the array as needed.

There is one special search definition (Latitude and Longitude) in the OPAL/OMA configuration that does not make any service calls and directly focuses the map:

{

searchType: "Latitude and Longitude",

field1Label: "Latitude,Longitude:", field1Type: "Coord",

field2Label: "", field2Type: "",

searchTable: "", searchColumn: "",needs_location: 'No',

note:"Please enter both Latitude,Longitude<br>separated by space or comma.",

multiSelectAtts: [],

multiSelectTitle: "",

showAttsOnOneResult: false

}

OMA src/js/viewModels/map.js and src/js/views/map.html

map.js and map.html may need changes based on special search actions you may want to perform.

The search function (map.js:self.doSearchClick) provides special actions based on the search type (self.mapSearchType). An example is the Latitude and Longitude search where we don't need to query the NMS system and it can be done while offline; whereas the other searches all require online access to the NMS server.

The map.html file contains the search dialog box definitions (MapSearchPopup and MapSearchSelectPopup). Based on special processing you might need for search options, these can be changed. An example of this is the Latitude and Longitude search where the wild card options are hidden since it is not relevant to this type of search.