Using a script to control import of network data

Using a script to more closely control the import of network data from GIS files or previously loaded GIS layers is an advanced function and should be used only by expert users with some experience of programming with a scripting language.

Import scripts can be written using VBScript. It may help to look up VBScript Tutorial or VBScript Reference on the Internet for full details of what you can do in VBScript. Please remember that VBScript is not the same as Visual Basic, Visual Basic.NET, VBScript.NET, or Visual Basic For Applications.

 You can use all the normal functionality available in VBScript to manipulate the data prior to import.

Script overview

The script contains a number of public subroutines that take the form:

OnBegin<tablename>

OnEnd<tablename>

OnBeginRecord<tablename>

OnEndRecord<tablename>

They are called as follows:

• OnBegin<tablename> - before importing the table
• OnEnd<tablename> - after importing the table
• OnBeginRecord<tablename> - before each record is processed. Specifically, this is called AFTER the data is read but before any processing is done. Processing in this case means the normal assignment of the import data to the InfoWorks WS Pro fields based on the field mapping set up on the Open Data Import Centre.
• OnEndRecord<tablename> - after the normal assignment of the import data to the InfoWorks WS Pro fields BUT before the data is written to the master database.

The script is executed using the Active Scripting Host. InfoWorks WS Pro looks through the list of subroutines for any of the public subroutines described above. In addition to these public subroutines, you can:

• define global variables used by the code
• define other subroutines called by the public subroutines listed above. Additional subroutines should be declared as Private.

Table names

The table names are the names that appear in the Table to Import Data Into list on the Open Data Import Centre, but with any spaces in the name removed. For example

• Node
• Conduit
• FixedHead
• TransferNode
• Reservoir

The method called after importing each record for the TransferNode table would be OnEndRecordTransferNode.

Using the public subroutines

• OnBegin<tablename> - the primary purpose of OnBegin is to initialise values in script global variables that are used later in the record. Potentially you can also decide, based on certain criteria, to abandon the import.
• OnEnd<tablename>
• OnBeginRecord<tablename> and OnEndRecord<tablename> - it makes little difference whether you do things in OnBeginRecord or OnEndRecord, except that:
• If you know you are going to abandon a record, you may as well do it in OnBeginRecord. This will speed up the import process.
• If you set a field using the script that is also set by the normal field mapping, you must do this in OnEndRecord. Otherwise the field will be overwritten by the normal assignment.

InfoWorks WS Pro Properties and methods

There are a number of methods and properties defined by InfoWorks WS Pro that can be called by the script.

When writing the script, the properties and methods described below must be preceded by Importer. (for example Importer.MsgBox("Hello"))

Properties

• boolean Abandonedand boolean TableAbandoned - Abandoned and TableAbandoned essentially have the same meaning. If you set them to True it stops further processing of the table. If you set either of these in OnBegin, then the table is not processed. If you set either of them in OnBeginRecord, then the record is not processed and no further records in the table are processed. If you set either of them in OnEndRecord, then the record IS processed but no further records in the table are processed. These are set to False before processing each import table.
• boolean WriteRecord - if set to false this record is not written to the database, but the overall import of the table continues. WriteRecord only serves any useful purpose in OnBeginRecord and OnEndRecord. If set to false in OnBeginRecord no further processing for that record is done and OnEndRecord is not called. If set to false in OnEndRecord the record is not written to the database. This is set to True on the beginning of each record.
• boolean DeleteRecord - used to delete objects. If set to true, this is interpreted as a request for deletion, as the object may not exist in InfoWorks WS Pro. When updating based on Asset ID, the asset ID of objects in the external data source and the InfoWorks WS Pro table are compared, otherwise the object ID is used. The value of the DeleteRecord property overrides the value of the WriteRecord property.

Methods

• void MsgBox(BSTR text) - MsgBox displays the string in a message box. Do not use this if you have lots of records. You can't stop the script before processing is completed.
• void OutputMessage(BSTR text, VARIANT messageType) - OutputMessage logs the message to the output window where errors or warnings also appear.
• text (required) - The text to log to the output window.
• messageType (optional) - valid parameters are:
• "E" - An error message, which prefixes text with 'Error:' and increments the number of processing errors
• "W" - A warning message, which prefixes text with 'Warning:' and increments the number of warning errors
• "I" - An informational message, which prefixes text with 'Info:'
• VARIANT Field(BSTR fieldName) - gets the field value from the external source database, GIS layer or CSV file. The fieldName variable is the external source field name. No unit conversion is carried out.

Assignment methods

• Field(BSTR fieldName) = VARIANT newValue - sets the value in InfoWorks WS Pro. In this case fieldName is the InfoWorks WS Pro field name. Values are always treated as being in InfoWorks WS Pro native units.