Department of
Sustainability and
Environment
VMAS Demonstration Website
Technical Design
Version 1.0
8th January 2008
Philip Huynh
Pitcher Partners
Level 19, 15 William Street
Melbourne. VIC 3000
Telephone: +613 8610 5664
Facsimile +613 8610 5999
Email philip.huynh@pitcher.com.au
Technical Design
Table of Contents
1.
Executive Summary ...................................................................................................................... 3
2.
Background and Context ............................................................................................................. 4
2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8
3.
Technology and Infrastructure .................................................................................................... 6
3.1
3.2
3.3
4.
Purpose ................................................................................................................................ 4
Intended Audience ............................................................................................................... 4
Objectives............................................................................................................................. 4
Design Goals ........................................................................................................................ 4
Assumptions and Constraints ............................................................................................... 4
Terms ................................................................................................................................... 5
References ........................................................................................................................... 5
Source code ......................................................................................................................... 5
Application Technologies...................................................................................................... 6
Hardware Requirements....................................................................................................... 6
Software Requirements ........................................................................................................ 6
Solution Architecture ................................................................................................................... 7
4.1 Physical Architecture ............................................................................................................ 7
4.2 Interfaces.............................................................................................................................. 8
4.2.1
Connection A (Browser to VMAS Demo) ........................................................................ 8
4.2.2
Connection B (VMAS Demo to VMAS) ........................................................................... 8
4.2.3
Connection C (VMAS Demo to IWS) .............................................................................. 8
4.2.4
Connection D (Browser to Google Maps) ....................................................................... 8
4.3 Project Structure................................................................................................................... 9
5.
Site Overview .............................................................................................................................. 10
5.1 Home / Login ...................................................................................................................... 10
5.2 Resources .......................................................................................................................... 10
5.3 VMAS Demonstration ......................................................................................................... 11
5.3.1
User Input ...................................................................................................................... 11
5.3.2
Result Summary ............................................................................................................ 13
5.3.3
Detailed Results ............................................................................................................ 14
6.
Website integration ..................................................................................................................... 16
6.1
6.2
6.3
7.
VMAS ................................................................................................................................. 16
Google Maps ...................................................................................................................... 21
IWS .................................................................................................................................... 22
Appendices.................................................................................................................................. 24
7.1 Tutorial – VMAS Parsed address lookup ............................................................................ 24
7.2 Site Configuration and Maintenance .................................................................................. 30
7.2.1
General configuration (web.config) ................................................................................ 30
7.2.2
Menu configuration (Web.sitemap) ................................................................................ 32
7.2.3
User configuration (App_Data\users.xml) ...................................................................... 33
7.2.4
Function configuration (App_Data\functions.xml) .......................................................... 34
7.2.5
Documentation configuration (App_Data\documentation.xml) ....................................... 36
Commercial in Confidence
Page 2
Technical Design
1. Executive Summary
The Spatial Information and Infrastructure (SII) group within the Department of Sustainability and
Environment (DSE) maintain and provide a service known as the Victorian Mapping and Address
Service (VMAS). VMAS is primarily designed for use by Victorian Government departments, and offers
customers a single web service interface with a series for addressing and spatial functions. The VMAS
environment is hosted and maintained by Geomatic Technologies, with the application development
and integration into websites intended to be performed by the end users of the service.
The VMAS demonstration website was designed to display the potential uses and capabilities of
VMAS. The website is used to market the service to other government departments, and the
associated code and documentation provides a framework for further development by end users.
Commercial in Confidence
Page 3
Technical Design
2. Background and Context
2.1 Purpose
The purpose of this document is to outline the technical design for the solution, including the
technology and infrastructure, system integration, and configuration options for maintenance and
support. The document also provides a basis for building other applications to consume the VMAS
web service.
2.2 Intended Audience
The intended audience of this document are third party developers who will be working within their own
applications to build similar functionality as the demonstration website.
2.3 Objectives
The VMAS demonstration website was designed with the following core objectives in mind:


Provide a flexible environment for demonstrating the use of VMAS;



Provide authentication to secure the site and provide to access live and test VMAS environments;
Demonstrate the integration of other DSE and third party web services, namely Image Web
Service (IWS) and Google Maps;
Provide information for prospective users of the VMAS service;
Provide a framework for the future development of other VMAS client applications;
2.4 Design Goals
The following design goals were taken into account:

Website to be developed based on industry best practices, including the use of recommended
naming conventions, cascading style sheets (css) for separation of layout and content, and W3C
standard-compliant HTML;



Code to be clear with sufficient comments and documentation;
Website must be easily maintained and configurable without requiring code changes;
Website to be lightweight and self-contained (eg. Use of XML files rather than supporting
databases) to keep the deployment process simple;
2.5 Assumptions and Constraints
The following assumptions and constraints have been made in regards to the design, support and
enhancements of the VMAS demonstration website:

All development, support, and issue resolution in regard to the functionality and operation of the
VMAS web service is the responsibility of SII and Geomatic Technologies;

VMAS Demonstration website to be compatible with Internet Explorer 6.0+ and Mozilla Firefox
2.0+;


Developers have familiarity with Microsoft .Net and Visual Studio 2005 IDE;
Whilst this document discusses the basics of the integration with other services (ie. Google Maps
and IWS), the primary focus is on VMAS integration.
Commercial in Confidence
Page 4
Technical Design
2.6 Terms
Term
Description
VMAS
Victorian Addressing and Mapping Service
DSE
Department of Sustainability and Environment
SII
Spatial Information and Infrastructure
MARS
Mapping, Address and Routing Service
IWS
Image Web Server
WMS
Web Map Service
WS-I
Web Services Interoperability
OGC
Open GIS Consortium
API
Application Programming Interface
IDE
Integrated development environment
2.7 References
The following reference documentation was used throughout for the technical design process, and
should be read in conjunction with this document:



Business Requirements for a VMAS demonstration page




DSE SII (10302) Test User v2.1

VMAS Demonstration Website source code
Victorian Mapping and Address Service: Overview
MARS Developer Guide
OGC Web Map Service Interface (OGC 01-068r3 v1.1.1)
Google Maps API (http://code.google.com/apis/maps/index.html)
Building ASP.NET 2.0 Web Sites Using Web Standards (http://msdn2.microsoft.com/enus/library/aa479043.aspx)
2.8 Source code
DSE will have ownership of the complete source for the VMAS demonstration website and associated
tutorials.
Commercial in Confidence
Page 5
Technical Design
3. Technology and Infrastructure
3.1 Application Technologies
The technologies used to develop and deploy this system are:

Microsoft .Net Framework version 2.0

Microsoft ASP.Net 2.0

Dynamic HTML (DHTML) / JavaScript

Microsoft Windows Server 2003 R2

Microsoft Internet Information Web Services (IIS) version 6.0
The languages used are:

Microsoft Visual Basic.Net

HTML & CSS

Javascript
The development environment is:

Visual Studio 2005
3.2 Hardware Requirements
The demonstration website has been deliberately kept lightweight. Although the hardware
requirements will depend upon factors such as the expected load, concurrent users, and frequency and
duration of visits, it is anticipated that a current model entry level server with the following specification
would be sufficient for this system:

3 GHz CPU


2 GB RAM
30 GB Hard Disk Drive
NB. The application itself (including documentation) requires less than 10MB of disk space.
3.3 Software Requirements
Microsoft Windows Server 2003 R2 Standard Edition is the operating system of choice as it is currently
a mature product which is fully supported by Microsoft, with constant availability of updates, patches
and vulnerability fixes.
The web server of choice is Microsoft’s Internet Information Server version 6.0, which is packaged
alongside the installation of Microsoft Windows Server 2003 R2 Standard Edition.
Microsoft’s .Net Framework 2.0 is also required on the server.
Commercial in Confidence
Page 6
Technical Design
4. Solution Architecture
4.1 Physical Architecture
The following diagram describes the physical architecture of the VMAS demonstrator website.
Client
HTTP
Internet
Firewall
HTTP
Firewall
VMAS
Demonstration
Server
Commercial in Confidence
Google Maps
Server
HTTP
Firewall
IWS
Server
Page 7
Technical Design
4.2 Interfaces
The following diagram describes the interfaces between the systems.
Connection A
Connection B
VMAS Demo
VMAS
Browser
Connection C
Connection D
Google Maps
4.2.1
IWS
Connection A (Browser to VMAS Demo)
This is the connection between the end user’s web browser and the web server hosting the
demonstration website. Transfer consists of standard HTTP requests to the server to render HTML to
the client.
4.2.2
Connection B (VMAS Demo to VMAS)
This is the connection between the demonstration web server and the web server hosting the (WS-I)
standard-compliant VMAS web service. The connection therefore exchanges XML messages over
HTTP using the SOAP protocol.
4.2.3
Connection C (VMAS Demo to IWS)
This is the connection between the demonstration web server and the IWS web server. IWS
implements WMS version 1.1.1 as specified by the Open GIS Consortium (OGC). The connection
consists of HTTP (GET) requests and responses containing the image stream.
4.2.4
Connection D (Browser to Google Maps)
This is the connection between the end user’s web browser and the Google Maps web server.
Requests are issued using javascript in conjunction with the Google Maps API to issue HTTP requests.
Commercial in Confidence
Page 8
Technical Design
4.3 Project Structure
The project structure for the demonstration website is arranged as follows:
VMASDemo
Contains main configuration file and web pages
App_Code
Contains business objects and library functions
App_Data
Contains additional configuration files
App_Web
References
documentation
Contains references to the VMAS web service
Contains VMAS documentation resources
images
Contains images used in the website
scripts
Contains javascript libraries
styles
Contains css stylesheets
xslt
Commercial in Confidence
Contains xsl transforms
Page 9
Technical Design
5. Site Overview
5.1 Home / Login
The homepage contains basic VMAS contact information and provides login functionality to the
demonstration website. Two users exists, TEST and LIVE, which connect to the test and live VMAS
web services respectively.
5.2 Resources
The resources page contains links to relevant VMAS information. Items can be set to appear in the list
depending on whether the user is authenticated or not.
Commercial in Confidence
Page 10
Technical Design
5.3 VMAS Demonstration
The VMAS demonstration page provides the core template for interacted with the VMAS web service.
5.3.1
User Input
This section allows the user provide input for a particular VMAS function. The function list
displays all the VMAS functions available to the current logged in user, and are grouped
according to the type of input fields they require. If the user is logged in as ‘LIVE’, then the
function list will correspond to the functions available to the live VMAS environment.
The demonstration website handles the following input types:
Commercial in Confidence
Page 11
Technical Design
Parsed Address
This allows address input by parsed (well-defined) fields.
Unparsed Address
This allows address input by a single field.
Lot Plan
This allows input by lot plan lookup.
Reverse Geocode
This allows input by geocode lookup.
Commercial in Confidence
Page 12
Technical Design
5.3.2
Result Summary
This section provides a summary of the VMAS function call. It indicates success or failure
and may provide additional information such as the number of address matches and
confidence levels.
Successful example
Failure example
Commercial in Confidence
Page 13
Technical Design
5.3.3
Detailed Results
There are three representations of the VMAS response to give users a quick visual
comparison and also to highlight some of the integration and extensibility possibilities.
VMAS
Direct response from the function call is displayed in the middle pane. Depending on the type
of function invoked, this may display a map image and/or related details such as geocode
reference and additional property features.
Google Maps
The Google Maps section displays imagery based on the geocode coordinates returned from
the VMAS function call.
IWS
The IWS section applies a conversion process to the geocode coordinates to retrieve the
imagery from IWS.
Commercial in Confidence
Page 14
Technical Design
Commercial in Confidence
Page 15
Technical Design
6. Website integration
6.1 VMAS
The VMAS web service is a WS-I 1.1 compliant web service, and is built using Geomatic Technologies’
MARS web service. For a comprehensive guide of the MARS API, please refer to the document
‘MARS Developers Guide (Version 1.0)’ by Geomatic Technologies.
The following section highlights some of the technical details to consume the VMAS web service as
used in the demonstration website.
Prerequisites
An account must be created by DSE for accessing the VMAS web service in TEST and LIVE
environments.
Request
Basics
The web method responsible for invoking the VMAS functions is called MARSRequest. This single
method has built-in flexibility to handle the various input types (eg. parsed address, unparsed address,
lot plan and geocode). Each request requires the functionID, version and authentication details as
input.
Providing these details will generate a request xml similar to the following:
<?xml version="1.0" encoding="utf-16"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<request xmlns="http://www.mars.geomatic.com.au/">
<pRequest functionID="200" version="1.1">
<Authentication userID="10302" password=""
tier1ID="TIER1IDHERE" tier2ID=" TIER2IDHERE "
tier3ID="" tier4ID="" />
</pRequest>
</request>
</soap:Body>
</soap:Envelope>
Commercial in Confidence
Page 16
Technical Design
In addition, depending on the selected function, additional information is required to be provided as part
of the MARSRequest.
Parsed Address request
If the function expects a parsed address as input then additional fields should be provided to the
Address element to refine the search. The table below shows the mapping for the parsed address
fields from the demonstration website to the MARS Address attributes.
Field
MARS Address attribute
Street Number
thoroughfareNumberFrom
eg. 15
Street Name
thoroughfareName
eg. William
Street Type
thoroughfareTrailingType
eg. St
Suburb
locality
eg. Melbourne
Postcode
Postcode
eg. 3000
State
state
eg. VIC
NB. The MARS API provides to full listing of Address fields.
The above example inputs would generate a request xml similar to the following:
<?xml version="1.0" encoding="utf-16"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<request xmlns="http://www.mars.geomatic.com.au/">
<pRequest functionID="200" version="1.1">
<Authentication userID="10302" password=""
tier1ID="TIER1HERE" tier2ID="TIER2HERE" tier3ID="" tier4ID="" />
<AddressLookup>
<Address thoroughfareNumberFrom="15" thoroughfareName="William"
thoroughfareTrailingType="St" locality="Melbourne"
postcode="3000" state="VIC" />
</AddressLookup>
</pRequest>
</request>
</soap:Body>
</soap:Envelope>
Commercial in Confidence
Page 17
Technical Design
Unparsed Address request
If the function expects an unparsed address as input then AddressLine field is required.
The request xml would be similar to:
<?xml version="1.0" encoding="utf-16"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<request xmlns="http://www.mars.geomatic.com.au/">
<pRequest functionID="1039" version="1.1">
<Authentication userID="10302" password=""
tier1ID="TIER1HERE" tier2ID="TIER2HERE" tier3ID="" tier4ID="" />
<AddressLookup>
<Address addressLine="15 William St Melbourne VIC 3000" />
</AddressLookup>
</pRequest>
</request>
</soap:Body>
</soap:Envelope>
Lot Plan request
If the function expects a Lot Plan as input then the LotPlan feature must be provided.
The request xml would look like:
<?xml version="1.0" encoding="utf-16"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<request xmlns="http://www.mars.geomatic.com.au/">
<pRequest functionID="1033" version="1.1">
<Authentication userID="10302" password=""
tier1ID="TIER1HERE" tier2ID="TIER2HERE" tier3ID="" tier4ID="" />
<FeatureLookup>
<Feature name="LotPlan" value="1\TP809868" />
</FeatureLookup>
</pRequest>
</request>
</soap:Body>
</soap:Envelope>
Geocode request
For a geocode lookup the LatLon feature must be provided.
The request xml would be similar to the following:
<?xml version="1.0" encoding="utf-16"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<request xmlns="http://www.mars.geomatic.com.au/">
<pRequest functionID="1023" version="1.1">
<Authentication userID="10302" password=""
tier1ID="TIER1HERE" tier2ID="TIER2HERE" tier3ID="" tier4ID="" />
<FeatureLookup>
<Feature name="LatLon" value="-37.8189709916667,144.959486691667" />
</FeatureLookup>
</pRequest>
Commercial in Confidence
Page 18
Technical Design
</request>
</soap:Body>
</soap:Envelope>
Response
The response from the VMAS web service call is in the form of a MARSResponse.
Error response
The response to an error scenario consists of an Error element with the following attributes:
Error attribute
Description
code
The error code
severity
Severity level (1 is most severe)
message
Message describing error
referenceID
Optional link identifying where the error occurred
A sample error response would look similar to:
<?xml version="1.0" encoding="utf-16"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<requestResponse xmlns="http://www.mars.geomatic.com.au/">
<requestResult>
<Error code="V003" severity="1"
message="Function_ID does not exist" referenceID="" />
</requestResult>
</requestResponse>
</soap:Body>
</soap:Envelope>
Commercial in Confidence
Page 19
Technical Design
Success response
The response to a successful web service call will vary depending on the function and may return
elements such as match metadata (eg. confidence and geocode levels), matching addresses, result
maps and address features (eg. Melway reference, SPI, Area, etc).
The example below shows the response to a successful parsed address lookup. Here it contains
information such as multiple address matches, geocode coordinates, image stream, and property
features. See the MARS developer’s guide for the full listings.
<?xml version="1.0" encoding="utf-16"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<requestResponse xmlns="http://www.mars.geomatic.com.au/">
<requestResult success="TRUE" numberOfResults="40">
<Result resultID="207964283" confidence="100" geocodeLevel="ADDRESS"
geocodeLevelCode="4">
<Address thoroughfareNumberFrom="15" thoroughfareNumberTo="33"
thoroughfareName="WILLIAM" thoroughfareTrailingType="STREET"
locality="MELBOURNE" postcode="3000" state="VIC" country="Australia"
addressLine="15-33 WILLIAM STREET, MELBOURNE VIC 3000">
<Pos>-37.8190203333333,144.959463558333</Pos>
</Address>
<Map scale="2000" title="15-33 WILLIAM STREET, MELBOURNE VIC 3000"
image="/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQE...">
<BoundingBox minX="144.955982705112" minY="-37.8216635325403"
maxX="144.962944411554" maxY="-37.8163771341263"
centreX="144.959463558333" centreY="-37.8190203333333" />
</Map>
<Feature name="MESHBLOCK" value="20112800000" />
</Result>
<Result resultID="209515493" confidence="100" geocodeLevel="ADDRESS"
geocodeLevelCode="4">
<Address thoroughfareNumberFrom="15" thoroughfareName="WILLIAM"
thoroughfareTrailingType="STREET" locality="MELBOURNE" postcode="3000"
state="VIC" country="Australia"
addressLine="15 WILLIAM STREET, MELBOURNE VIC 3000">
<Pos>-37.8190203333333,144.959463558333</Pos>
</Address>
<Feature name="MESHBLOCK" value="20112800000" />
</Result>
...
</requestResult>
</requestResponse>
</soap:Body>
</soap:Envelope>
Appendix 1 contains a step-by-step tutorial on how to build a page to invoke a VMAS function.
Commercial in Confidence
Page 20
Technical Design
6.2 Google Maps
The Google Maps section utilises the Google Maps API for retrieving imagery. For a comprehensive
guide of the API, please refer to http://code.google.com/apis/maps/ .
The following section highlights some of the technical details for integrating with Google Maps.
Prerequisites
A Maps API key is required for interacting with Google Maps. This key must be registered online
(http://code.google.com/apis/maps/signup.html) and is valid for a single directory on the web server.
ie. By registering the site http://www.host.com/VMASDemo, the key would be valid for all URLs in the
http://www.host.com/VMASDemo directory.
Setup
The web page requires a reference to the Google Maps API javascript library with the API key.
<script type="text/javascript"
src="http://www.google.com/jsapi?key=ABQIAAAAQ5sDqL0IS2QD04efvE010xR1hthCMa_X6LBzZD5_
9Sx6u9CNcxTH-Mcm9DG4wJC3unT3YIjqaNcZHA"></script>
A div container must also be created to hold the resulting image from Google Maps.
eg.
<div id="mapGoogle"></div>
Loading the map
A map can be requested by supplying the geocode coordinates. The code to invoke the map will be
similar to the following script block.
<script type="text/javascript">
google.load("maps", "2");
// Call this function when the page has been loaded
function initialize() {
// set up the coordinates to look up
var lat = 37.4419;
var lng = -122.1419;
var map = new google.maps.Map2(document.getElementById("mapGoogle"));
map.setCenter(new google.maps.LatLng(lat, lng), 13);
}
google.setOnLoadCallback(initialize);
</script>
Commercial in Confidence
Page 21
Technical Design
6.3 IWS
IWS is built upon the WMS specification as detailed in the document ‘Web Map Service
Implementation Specification (Version 1.1.1)’ by Open GIS.
The key points in retrieving imagery from IWS are as follows:
Prerequisites
An account must be created by DSE for accessing IWS.
Requests
Images are retrieved by issuing HTTP GET requests to the IWS endpoint/handler. Authentication
details must be submitted in the HTTP request header (see RenderIWSImage.aspx.vb for sample
code).
Refer to the WMS spec for a detailed explanation of the parameters. The following lists the parameters
used with the demonstration website:
Parameter
Description
REQUEST
Type of request to invoke
VERSION
Protocol version number. Must match with server.
FORMAT
Image format to return
SRS
Spatial Reference System. Describes the coordinate system
used for the bounding box.
LAYERS
Name to layer to use
WIDTH
Width of image in pixels
HEIGHT
Height of image in pixels
TRANSPARENT
Display of map background
BBOX
Bounding Box. Coordinates of image area
The complete request URL would look similar to the following:
http://images.land.vic.gov.au/ecwp/ecw_wms.dll?&REQUEST=GetMap&VERSION=1.1.1&FORMAT=i
mage/png&SRS=EPSG:102171&LAYERS=AERIAL_MELBOURNE_2005DEC11_AIR_VIS_35CM_VG94&WIDTH=40
0&HEIGHT=400&STYLES=&TRANSPARENT=TRUE&BBOX=2496331.03145792,2409010.71239332,2496531.
03145792,2409210.71239332
A conversion process is required to transform geocode coordinates to the bounding box values
(BoundingBox.vb contains the conversion code).
Commercial in Confidence
Page 22
Technical Design
Response
Generally, responses from IWS take two forms.
On error, it returns xml with the error message
eg.
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ServiceExceptionReport SYSTEM
"http://images.land.vic.gov.au/ecwplugins/lib/xml/exception_1_1_1.dtd">
<ServiceExceptionReport version="1.1.1">
<ServiceException code="47" >
An invalid parameter was used.
</ServiceException>
</ServiceExceptionReport>
On success, it returns the image stream in the format specified by the FORMAT querystring parameter
(RenderIWSImage.aspx.vb contains the code for handling both of these responses).
Commercial in Confidence
Page 23
Technical Design
7. Appendices
7.1 Tutorial – VMAS Parsed address lookup
The following tutorial shows a step-by-step guide for creating a new web page to consume the VMAS
web service. This tutorial assumes familiarity with Visual Basic.Net and Visual Studio 2005, however
the concepts may be quite similar for other programming languages and development environments.
Create project
1. In Visual Studio 2005, create a new Web Site project called VMASTutorial.
Create reference to web service
2. Right-click the project in Solution Explorer and select Add Web Reference...
3. In the URL field, enter the web service endpoint and click Go.
http://test.vmas.net.au/MARS/MARS.asmx?WSDL
Commercial in Confidence
Page 24
Technical Design
4. Once the web service has been located click Add Reference. This will automatically generate the
proxy objects to interact with the web service.
Create sample form
5. Right-click the project in Solution Explorer and select Add New Item...
6. Select the Web Form template and name the page ParsedAddressLookup.aspx. Click Add.
7. To setup the input fields, in Source view, copy the following between the HTML form tags
<table>
<tr>
<td>Street Number"</td>
<td><asp:TextBox ID="txtStreetNumber" runat="server"></asp:TextBox></td>
</tr>
<tr>
<td>Street Name</td>
<td><asp:TextBox ID="txtStreetName" runat="server"></asp:TextBox></td>
</tr>
<tr>
<td>Street Type</td>
<td><asp:TextBox ID="txtStreetType" runat="server"></asp:TextBox></td>
</tr>
<tr>
<td>Suburb</td>
<td><asp:TextBox ID="txtSuburb" runat="server"></asp:TextBox></td>
</tr>
<tr>
<td>Postcode</td>
<td><asp:TextBox ID="txtPostcode" runat="server"></asp:TextBox></td>
</tr>
<tr>
<td>State</td>
Commercial in Confidence
Page 25
Technical Design
<td><asp:TextBox ID="txtState" runat="server"></asp:TextBox></td>
</tr>
</table>
<asp:Button ID="btnSubmit" runat="server" Text="Submit" />
<hr />
Results: <br />
<asp:TextBox ID="txtResults" runat="server" TextMode="MultiLine" Height="200px"
Width="500px"></asp:TextBox>
8. Click on the Design tab to switch to design view. The form should look like below:
9. Double-click on the Submit button to automatically generate the event handler in
ParsedAddressLookup.aspx.vb.
10. Add the following namespaces to the very top of the file.
Imports au.net.vmas.test
Imports System.Net
11. Paste the following constants just above the btnSubmit_Click function and make sure you update
the VMAS credentials according to your account details.
' proxy server if required, otherwise leave empty
Private Const _proxy As String = ""
' Vmas Url
Commercial in Confidence
Page 26
Technical Design
Private Const _vmasUrl As String = "http://test.vmas.net.au/MARS/MARS.asmx"
' Vmas version to use
Private Const _vmasVersion As String = "1.1"
' Vmas function to invoke
Private Const _functionId As String = "205"
'Vmas account
Private Const
Private Const
Private Const
Private Const
Private Const
details
_vmasUserId As String = "10302"
_vmasTier1 As String = "TIER1HERE"
_vmasTier2 As String = "TIER2HERE"
_vmasTier3 As String = ""
_vmasTier4 As String = ""
12. Replace the btnSubmit_Click function with the following code:
Protected Sub btnSubmit_Click(ByVal sender As Object, ByVal e As System.EventArgs) _
Handles btnSubmit.Click
' create mars object
Dim vmas As New au.net.vmas.test.MARS
vmas.Url = _vmasUrl
' use proxy if required
If Not String.IsNullOrEmpty(_proxy) Then
vmas.Proxy = New WebProxy(_proxy, True)
End If
' initialise request
Dim vmasRequest As New au.net.vmas.test.MARSRequest()
vmasRequest.version = _vmasVersion
vmasRequest.functionID = _functionId
' initialise authentication credentials
Dim authentication As New au.net.vmas.test.MARSRequestAuthentication()
authentication.userID = _vmasUserId
authentication.tier1ID = _vmasTier1
authentication.tier2ID = _vmasTier2
authentication.tier3ID = _vmasTier3
authentication.tier4ID = _vmasTier4
vmasRequest.Authentication = authentication
' initialise address lookup
Dim addresses(0) As au.net.vmas.test.Address
addresses(0) = New au.net.vmas.test.Address()
addresses(0).thoroughfareNumberFrom = txtStreetNumber.Text.Trim()
addresses(0).thoroughfareName = txtStreetName.Text.Trim()
addresses(0).thoroughfareTrailingType = txtStreetType.Text.Trim()
addresses(0).locality = txtSuburb.Text.Trim()
addresses(0).postcode = txtPostcode.Text.Trim()
addresses(0).state = txtState.Text.Trim()
vmasRequest.AddressLookup = addresses
Dim vmasResponse As au.net.vmas.test.MARSResponse
Dim message As String
Try
' make vmas call
vmasResponse = vmas.request(vmasRequest)
' process the response
message = "Success: " & vmasResponse.success & vbCrLf & _
"No. results: " & vmasResponse.numberOfResults & vbCrLf & _
"---------------------------" & vbCrLf
If vmasResponse.Error IsNot Nothing AndAlso vmasResponse.Error.Length > 0 Then
message = message & "Error" & vbCrLf & _
Commercial in Confidence
Page 27
Technical Design
"
"
"
code: " & vmasResponse.Error(0).code & vbCrLf & _
message: " & vmasResponse.Error(0).message & vbCrLf & _
severity: " & vmasResponse.Error(0).severity & vbCrLf
Else
Dim resultItem As au.net.vmas.test.MARSResponseResult
Dim addressItem As au.net.vmas.test.Address
Dim featureItem As au.net.vmas.test.Feature
For Each resultItem In vmasResponse.Result
For Each addressItem In resultItem.Address
message = message & "Address: " & addressItem.addressLine & vbCrLf
If addressItem.Pos IsNot Nothing _
AndAlso addressItem.Pos.Length > 0 Then
message = message & "Geocode: " & addressItem.Pos(0) & vbCrLf
End If
Next
For Each featureItem In resultItem.Feature
message = message & "Feature: " & _
featureItem.name & " - " & featureItem.value & vbCrLf
Next
message = message & "---------------------------" & vbCrLf
Next
End If
txtResults.Text = message
Catch ex As Exception
txtResults.Text = "The following error occurred: " & vbCrLf & ex.Message
Finally
vmasResponse = Nothing
vmasRequest = Nothing
vmas = Nothing
End Try
End Sub
13. In Solution Explorer, right click on ParsedAddressLookup.aspx and select Set As Start Page
from the context menu.
14. Hit the green play button to load the page. If a Debugging Not Enabled prompt appears, click
OK to modify the Web.config file.
Commercial in Confidence
Page 28
Technical Design
15. Enter some search criteria and click Submit. The results of the web service call should be
displayed in the Results text box.
Commercial in Confidence
Page 29
Technical Design
7.2 Site Configuration and Maintenance
The VMAS demonstration website was designed to be easily configurable to cater for changes such as
functions, user settings and document links, without requiring code changes. This is achieved through
the use of xml configuration files. The following section outlines the options available for configuration
by a site administrator. To make a change, simply edit the appropriate xml file.
7.2.1
General configuration (web.config)
The web.config file contains general site configuration settings.
The authentication section maintains the user passwords to the website.
<authentication mode="Forms">
<forms name=".ASPXAUTH" loginUrl="Default.aspx" protection="All">
<credentials passwordFormat="Clear">
<user name="TEST" password="TESTPASSWORDHERE"/>
<user name="LIVE" password=" LIVEPASSWORDHERE "/>
</credentials>
</forms>
</authentication>
In addition, the appSettings section contains the following options:
Setting
Description
VmasWs.MARS
URL for VMAS web service endpoint
NoMatchesToDisplay
The number of matches to display in the result summary
section without scrolling
AddressLookupEnable
Enables/disables address (ajax) lookup functionality for
unparsed addresses
AddressLookupMaxResults
Maximum no of results to return from address (ajax) lookup
for unparsed address
GoogleKey
Google Maps API key. This key identifies the server issuing
requests Google maps requests.
GoogleMapVersion
Google Maps API version number to use
IWSUrl
URL for IWS requests
IWSRequest
IWS request type
IWSVersion
IWS version number
IWSFormat
IWS image format
IWSSRS
IWS Spatial Reference System
IWSLayers
IWS Layer to use
IWSUsername
IWS username
Commercial in Confidence
Page 30
Technical Design
Setting
Description
IWSPassword
IWS password
IWSProxy
Proxy (if required) to access IWS server
eg.
<configuration>
<appSettings>
<add key="VmasWs.MARS" value="http://www.vmas.net.au/MARS/MARS.asmx"/>
<!-- No of result matches to display in list -->
<add key="NoMatchesToDisplay" value="5"/>
<!-<add
<!-<add
Enable Address Lookup (ajax) functionality -->
key="AddressLookupEnable" value="true"/>
Number of results to return from address lookup -->
key="AddressLookupMaxResults" value="20"/>
<!-<add
<!-<add
Key for access google maps (server specific) -->
key="GoogleKey" value="ABQIAAAAQ5sDqL0IS2QD04efvE010xR1... "/>
Google Map version -->
key="GoogleMapVersion" value="2"/>
<!-<add
<add
<add
<add
<add
<add
<add
<add
<add
IWS Settings -->
key="IWSUrl" value="http://images.land.vic.gov.au/ecwp/ecw_wms.dll?"/>
key="IWSRequest" value="GetMap"/>
key="IWSVersion" value="1.1.1"/>
key="IWSFormat" value="image/png"/>
key="IWSSRS" value="EPSG:102171"/>
key="IWSLayers" value="AERIAL_MELBOURNE_2005DEC11_AIR_VIS_35CM_VG94"/>
key="IWSUsername" value="vmasdemo"/>
key="IWSPassword" value="IWSPASSWORDHERE"/>
key="IWSProxy" value=""/>
</appSettings>
...
</configuration>
Commercial in Confidence
Page 31
Technical Design
7.2.2
Menu configuration (Web.sitemap)
The website’s menu is controlled from the Web.sitemap file. Each menu item corresponds to a
siteMapNode element and has the following configurable options:
Setting
Description
url
Link to display on click
title
Menu title
description
Description of menu item (displays on mouse over)
roles
(optional) Provides ability to control visibility of menu item
based on roles.
Generally, the following options are available

* - always display

test – display for test user only

live – display for live user onlt

test,live – display for test and live users
eg.
<?xml version="1.0" encoding="utf-8" ?>
<siteMap xmlns="http://schemas.microsoft.com/AspNet/SiteMap-File-1.0" >
<siteMapNode url="" title="" description="" roles="*">
<siteMapNode url="Default.aspx" title="Home" description="" roles="*" />
<siteMapNode url="Main.aspx" title="VMAS Demonstration" description="" />
<siteMapNode url="http://gwweb.gw.com.au/AddressSearch/pages/search.jsp"
title="Example Input Form" description="" roles="live,test" />
<siteMapNode url="Links.aspx" title="Resources" description="" />
<siteMapNode url="Default.aspx?action=logout" title="Logout" description="" />
</siteMapNode>
</siteMap>
Commercial in Confidence
Page 32
Technical Design
7.2.3
User configuration (App_Data\users.xml)
The users.xml file contains user-specific settings for interacting with the test and live environments.
For each user, the following configuration options are available:
Setting
Description
vmasUrl
URL for VMAS web service endpoint (test or live)
vmasProxy
Proxy (if required) to access VMAS server
vmasVersion
Version of VMAS service to use
vmasUserId
VMAS user credentials
vmasTier1
VMAS user credentials
vmasTier2
VMAS user credentials
vmasTier3
VMAS user credentials
vmasTier4
VMAS user credentials
eg.
<?xml version="1.0" encoding="utf-8" ?>
<users>
<user id="test">
<vmasUrl>http://test.vmas.net.au/MARS/MARS.asmx</vmasUrl>
<vmasProxy></vmasProxy>
<vmasVersion>1.1</vmasVersion>
<vmasUserId>10302</vmasUserId>
<vmasTier1>TIER1HERE</vmasTier1>
<vmasTier2> TIER2HERE </vmasTier2>
<vmasTier3></vmasTier3>
<vmasTier4></vmasTier4>
</user>
<user id="live">
<vmasUrl>http://www.vmas.net.au/MARS/MARS.asmx</vmasUrl>
<vmasProxy></vmasProxy>
<vmasVersion>1.1</vmasVersion>
<vmasUserId>10302</vmasUserId>
<vmasTier1>TIER1HERE</vmasTier1>
<vmasTier2> TIER2HERE </vmasTier2>
<vmasTier3></vmasTier3>
<vmasTier4></vmasTier4>
</user>
</users>
Commercial in Confidence
Page 33
Technical Design
7.2.4
Function configuration (App_Data\functions.xml)
The functions.xml file contains the list of available functions group by function type and environment
(test or live). This file directly controls the function dropdown list and input parameters.
For each environment, the following settings are available:
Setting
Description
id
Indicates environment (test or live)
reverseGeoCodeLookupId
Function Id to use for reverse geocode lookup (available via
context menu on google map)
addressLookupId
Function Id to use for address (ajax) lookup for unparsed
address input
eg.
<?xml version="1.0" encoding="utf-8" ?>
<functions>
<group id="test" reverseGeoCodeLookupId="1035" addressLookupId="1057">
...
</group>
<group id="live" reverseGeoCodeLookupId="301" addressLookupId="707">
...
</group>
</functions>
In addition the following function types are available within each group, with each type determining the
input fields to display:
Setting
Description
ParsedAddressVerification
Takes parsed address inputs
GetMapSnapAddress
Takes parsed address inputs
UnParsedAddressVerification
Takes unparsed address input
UnParsedGetMapSnap
Takes unparsed address input
GetMapSnapLotPlan
Takes lot plan inputs
ReverseGeocode
Takes geocode coordinate inputs
Commercial in Confidence
Page 34
Technical Design
eg.
<?xml version="1.0" encoding="utf-8" ?>
<functions>
<group id="test" reverseGeoCodeLookupId="1035" addressLookupId="1057">
<functionType id="ParsedAddressVerification" name="Parsed Address Verification">
...
</functionType>
<functionType id="GetMapSnapAddress" name="Get Map Snap Address">
...
</functionType>
<functionType id="UnParsedAddressVerification" name="Unparsed Address Verification">
...
</functionType>
<functionType id="UnParsedGetMapSnap" name="Unparsed Get Map Snap">
...
</functionType>
<functionType id="GetMapSnapLotPlan" name="Get Map Snap Lot Plan">
...
</functionType>
<functionType id="ReverseGeocode" name="Reverse Geocode">
...
</functionType>
</group>
...
</functions>
Within each functionType element are the associated functions:
Setting
Description
id
Function Id corresponding to the VMAS function
name
The name of the VMAS function
eg,
<?xml version="1.0" encoding="utf-8" ?>
<functions>
<group id="test" reverseGeoCodeLookupId="1035" addressLookupId="1057">
<functionType id="ParsedAddressVerification" name="Parsed Address Verification">
<function id="100" name="100 - Verify Property Address" />
<function id="101" name="101 - Find Postcode" />
<function id="102" name="102 - Find Melway Ref" />
<function id="103" name="103 - Find LGA" />
<function id="106" name="106 - Find Planning Info" />
<function id="107" name="107 - Find VicMap PFI" />
<function id="108" name="108 - Find Dol Region" />
<function id="109" name="109 - Find DVC Region" />
<function id="110" name="110 - Find Plan/Lot Number" />
<function id="111" name="111 - Find Property Details" />
<function id="650" name="650 - VICMAP Address verification" />
<function id="1018" name="1018 - DSE_DEMO" />
<function id="1019" name="1019 - TEST" />
<function id="1030" name="1030 - GNAF Address Verification" />
<function id="1032" name="1032 - Postal DPID" />
<function id="1041" name="1041 - Get ROM Map" />
<function id="1043" name="1043 - POSTMAN Test" />
</functionType>
...
</group>
...
</functions>
Commercial in Confidence
Page 35
Technical Design
7.2.5
Documentation configuration (App_Data\documentation.xml)
The documentation.xml file contains the links to documentation to be displayed on the Resources
page. The documentation items may be grouped into categories, with each item having the following
options:
Setting
Description
title
The title of the document
link
The relative path to the document file
description
The description of the document
display
A flag to indicate whether to display the documentation
depending on whether the user is authenticated.
The following options are available:

ALL – display to authentication and unauthenticated
users

AUTH – display to authenticated users only

UNAUTH - display to unauthenticated users only
eg.
<?xml version="1.0" encoding="utf-8" ?>
<documentation>
<category name="Documentation">
<item title="VMAS Overview"
link="Documentation/VMAS Overview oct_2007.pdf"
description="System Overview And Trial Access Definition &amp; Request Form"
display="UNAUTH"/>
<item title="VMAS Overview (technical)"
link="Documentation/VMAS Overview _Tech_ oct_2007.pdf"
description="System Overview n (with technical architecture)"
display="AUTH"/>
<item title="MARS Developers Guide"
link="Documentation/MARSDevelopersGuide1.0.pdf"
description="MARS Developer's Guide 1.0"
display="AUTH"/>
</category>
...
</documentation>
.
Commercial in Confidence
Page 36