Bulk Update by Minto Spatial Solutions

Bulk Update by Minto Spatial Solutions: User Guide

Updated: 2011/04/25 Copyright Information

Trademarks and Registered Trademarks

Smallworld is a registered trademark of General Electric Company

2 Table of Contents

1 Overview...... 4 1.1 Supported Versions...... 4 1.2 Document History...... 4 2 Bulk Update Tool...... 5 3 Administrator Notes...... 9 3.1 Changes to Image Build Process...... 9 3.2 Changes to Applications...... 9 3.3 Customizable Magik Code...... 9

3 1 Overview The Bulk Update by Minto Spatial Solutions (also referred to in this document as the Bulk Update tool) is a productivity tool that allows multiple attributes of multiple records to be updated in a single operation. It includes the following features:  Select records to be updated in a variety of ways: based on map selection, a trail, or the Smallworld scrapbook.  Review individual records before updating them: goto, highlight, and optionally remove any single record or set of records before they are processed.  Set new values for any or all physical attributes of the selected records, and perform the update with a single action. 1.1 Supported Versions This document describes the version of this software that is released as part of the MSS 420 package, and is compatible with the SWAF architecture of Smallworld Core Spatial Technology version 4.2.0. 1.2 Document History

Date Name Description 2007/02/19 Tim Minto  Created (from V4.0 version of document). 2008/05/31 Tim Minto  Updated to V4.1.1. 2011/04/25 Tim Minto  Updated to V4.2.0.

4 2 Bulk Update Tool Your system administrator will typically define an action on a pulldown menu in your application which activates the Bulk Update tool. Here is a screen shot of this menu:

This menu consists of the following components:  The Pulldown menu functions and Toolbar are at the top of the menu. All of these functions are described below.  The upper portion of the menu is the Table list. It displays all tables which are currently candidates for the bulk update process. Note that these candidates are selected using the various Add and Remove functions described below. o If a single table is selected, the Field list (described below) will be updated to display the attributes of the first record in the table, and the “Record” column in this list will indicate that the first record is being displayed. o In the example screen shot above, the Place of Interest table has been selected, and the Field list is displaying record number 1 out of 2 total candidates.

5 o The Display First/Previous/Next/Last functions (described below) can then be used to cycle through the candidate list if desired.  The lower portion of the menu is the Field list. When a selection is made in the Table list, this will display all physical fields of that table which may be updated. o Note that it is possible to select multiple entries in the Table list. In this case, the Field list will only display those fields which are shared by all selected tables. o A field is considered to be shared between two tables if it has the same name, and the same data type (such as string, integer, date, or enumerated list). For string fields, the length of the field must also be the same in order to be considered to be shared. o For example, if you have an attribute named “Date Installed” that exists on many tables such as Pipe, Valve and Fitting, you could select records from all of those tables at once, and then update the “Date Installed” with a single action.  The appearance of the Field list is very similar to the fields that are displayed on a standard object editor. For each field, the following columns of information are displayed: o Field name: the name of the field, along with a graphical indicator of whether it is an alphanumeric ( ), enumerated ( ), or catalog ( ) type of field. o Value: the current value of this field. o Updated: if the field has been updated, a delta ( ) symbol is displayed. o Mandatory: if the field is mandatory, an asterisk ( ) symbol is displayed.

The following Pulldown menu functions are available:

Function name Button Description

File Pulldown Clear Proposed If any proposed changes have been made in the Field list, Changes this will clear those proposed changes. Bulk Update If any proposed changes have been made in the Field list, this will update all candidate records in all tables selected in the Table list with those proposed values. Bulk Delete This will delete all candidate records in all tables selected in the Table list. Interrupt The following functions on this menu can take a long time to run if a large volume of data is selected: Add by Map Selection, Add by Trail, Add by Scrapbook, Remove by Map Selection, Copy to Scrapbook, Goto Selected Tables, Goto All, Highlight Selected Tables, and Highlight All.

When any of those functions is run, this function will become enabled, and performing this function will cause that long-running process to be interrupted. Close This closes the Bulk Update menu.

Edit Pulldown Add by Map Selection This adds all records that are selected in your current map view to the list of candidates in the Table list. Add by Trail This adds all records that are partially or completely inside the trail of the current map view.

Note that this function will only consider any geometry that is selectable in the current map view.

6 Function name Button Description

Add by Scrapbook This adds all records that currently in the Smallworld scrapbook. Remove by Map This removes all records that are selected in your current Selection map view. Remove Current Record If you have selected a single table in the Table list, this removes the record in that table that is currently being displayed in the Field list. Remove Selected If you have selected one or more tables in the Table list, Tables this removes all of those records. Remove All This removes all records from the list of candidates, allowing you to start over by building a new set of candidates using the various Add functions described above. Remove By Attribute… If you have selected a single table in the Table list and a single attribute in the Field list, this function will activate a dialog that allows a specific set of records to be removed from the list of candidates.

For example, suppose you select a large number of Valves to be updated by using the Add by Trail function. However, you are only interested in ones that have a Status value of Proposed or Existing – any with a Status value of Abandoned should be excluded. In this case, you could select the Valve table and the Status attribute from the Table list and Field list respectively, then perform this function to remove all records where the Status value is Abandoned. Edit Current Record… If you have selected a single table in the Table list, this displays the current records for that table in a standard object editor. This provides full update access to that record (including join fields and geometry fields that are not handled by the Bulk Update tool). Copy To Scrapbook This copies the candidate records for all tables selected in the Table list to the Smallworld Scrapbook.

View Pulldown Goto Current Record If you have selected a single table in the Table list, this zooms the current map view to display the record in that table that is currently being displayed in the Field list. Goto Selected Tables If you have selected one or more tables in the Table list, this zooms the current map view to display all of those records. Goto All This zooms the current map view to display all candidate records. Highlight Current Record If you have selected a single table in the Table list, this highlights the record in that table that is currently being displayed in the Field list. Highlight Selected If you have selected one or more tables in the Table list, Tables this highlights all of those records. Highlight All This highlights all candidate records.

7 Function name Button Description

Display First If you have selected a single table in the Table list, this updates the Field list to display the first candidate record in the selected table. Display Previous This updates the Field list to display the previous candidate record in the selected table. Display Next This updates the Field list to display the next candidate record in the selected table. Display Last This updates the Field list to display the last candidate record in the selected table.

Options Pulldown Suppress Warnings? If this option is enabled, then any warning conditions that are raised while performing the update are directed to the log file, instead of displaying the warning in a dialog. This is useful if you consider warning messages to be a normal result, and wish to avoid having to click through a large number of warning dialogs while performing the update.

The default value for this option is false. Require Commit Before If this option is enabled, then you must commit (or rollback) Running? any changes that you have in progress before performing the update.

The Bulk Update tool does attempt to perform all updates within a single transaction, which means that you can use the Smallworld Undo function to undo an unwanted change. However, due to limits in the size of a single transaction that can be processed by a Smallworld database, performing a moderately large number of updates will exceed that size limit, resulting in a transaction that cannot be undone using the Undo function. Therefore, it is recommended that you ensure that any work-in-progress that you may have is committed before performing a bulk update, so that you can still use the Smallworld Rollback function to undo an unwanted change.

The default value for this option is true. Append To Text Joins? If this option is enabled, then any proposed value that is set for a text join type of field will be appended to the current value of that attribute for all records. This overrides the standard behavior of updating attribute values. This option is useful for adding a piece of text to the comments field for a set of objects – for example, to indicate that a set of valves was surveyed on a given date.

The default value for this option is false.

Usage note: whenever you select a different table in the Table list, or whenever you display a new record using the Display First/Previous/Next/Last functions, this will cause any proposed values to be cleared out – the same effect as performing the Clear Proposed Changes function. Therefore, the recommended usage of this tool is to first select and review the records of interest using the various functions on the Edit and View pulldown menus. Once the desired set of

8 candidate records has been selected, you may then set the new proposed field values in the Field list, and perform the update using the Bulk Update function.

9 3 Administrator Notes 3.1 Changes to Image Build Process The source code for this product should be placed in a directory that is accessible during your image build process. This code is available in the subdirectory named “mss” of the product zip file. Simply copy this code to a directory of your choice. This directory will be considered to be the “product directory” for the MSS product, and this will be referred to as the directory in various steps below.

Ensure that the latest TSB patches are installed before proceeding with an image build. Notably, the this product relies on changes introduced in TSB 104. If you do not have these TSB patches installed, contact the Smallworld help-desk for assistance.

As part of your image build process, ensure that following steps are performed:  The MSS product must be added. This can be done using the following code (where is the directory that contains the product.def file): o smallworld_product.add_product()  The module named mss_bulk_update must be loaded. This can be done by either making it a prerequisite of any module that you currently load in your application, or by explicitly loading the module using the following code: o sw_module_manager.load_module(:mss_bulk_update) 3.2 Changes to Applications For any application that will use this product, the following changes should be made to the config.xml and gui.xml files for that application:

Changes to config.xml:  Add the following plugin, which provides access to the Bulk Update menu:

Changes to gui.xml:  To provide access to the Bulk Update menu, add the following action to the appropriate pulldown menu in your application:

3.3 Customizable Magik Code This section describes all subclassable and/or redefinable methods which you may customize to suit your particular data model and environment. dd_record_mixin.mss_bu_excluded_partition_names  This shared constant is a collection of partition names for which records cannot be bulk- updated.  It provides a coarse level of control over what features can be updated – for example, if you have any data partitions which are “short transaction” type of partitions, it is likely not appropriate to permit bulk-updating of those records, as there is no way to undo or rollback the results if a bulk update is made in error. dd_record_mixin.mss_bu_visible_fields(_optional an_ace, vis_tag)  This method determines the list of visible fields to use for displaying an object in the Bulk Update menu.

10  The backstop behavior provides the same set and ordering of visible fields that would normally be seen in an object editor for AN_ACE (an ACE) and VIS_TAG (a field visibility tag, which defaults to “default”). o Key fields are excluded, as they cannot be bulk-updated. o Geometry fields and non-text join fields are also excluded.  The VIS_TAG can be changed in the Bulk Update menu itself by setting the mss_bulk_update_plugin.field_visibility_tag_name property. This tag has the same usage as for the object_editor_field_lister.field_visibility_tag_name – if you have customized that property for object editors in your application, it may be appropriate to also customize it for the Bulk Update menu to ensure a consistent appearance of available fields. dd_record_mixin.mss_bu_eligible?()  Return two boolean values: o The first indicates if self can be considered for bulk update processing. o The second indicates if self's child records should be traversed to also be considered for bulk update processing.  Should be subclassed to remove tables that are not candidates for being bulk-updated, or to avoid automatically following joins which may result in unwanted records (i.e. an entire circuit or CP system).  See the dd_record_mixin.mss_bu_child_records() method below for a discussion of what constitutes a “child” record. dd_record_mixin.mss_bu_child_records()  Locate all child records which should be considered for bulk update processing.  Return a rope where each value is a two item vector: o The child record. o A boolean indicating if the child should also be traversed to return its child records also. This will always be true as a result of this method, but subclasses may change this.  The purpose of this is to provide a mechanism for being able to graphically select a set of records, and then be able to consider related non-graphic records for the bulk update process. A good example is being able to select a set of transformer locations, and automatically consider the related transformer units for bulk-updating (even though those transformer units do not have their own geometry to select).  Default processing is to consider all non-super type joins as a “child” record. This means that sibling-type records in an M:N join will be pulled into the set of candidates. If this is not desirable for any specific record class in your data model, you may subclass this method; if it is not desirable in general for your data model, you may redefine this method. mss_bulk_update_plugin.figure_records_for_deletion(recs)  This method is used by the Bulk Delete function to determine an ordered collection of records to be deleted, given the set of records RECS specified by the user.  The default behavior is to simply return RECS, indicating that the order of deletion is not important and that no records need to be added to or removed from the set.