Client Guide

Client's Guide to ValEx Webservices

This guide describes in detail the process you need to take to order a valuation and recieve the completed valuation report using ValEx's web services.

Account Setup

See this article on account setup

Note: At the moment you will still have to use the normal ValEx interface if you want to see the in-progress status's of your jobs (i.e. accepted, assigned, inspected, delayed). However this will be implemented so you can receive updates through webservices soon

Starting Development

ValEx has a dedicated test environment located at http://vxtest.valex.com.au. You'll be given a username, and password; and WSDLs. The first is a simple test soap service, to check authentication works via an auth() method and provide rudimentary debugging via repeat(). The second is a fully functional end point for ordering valuations.

Problems?

Some clients using .NET have difficulty connecting to us, and may find this article useful.

Getting a job quote

We provide a simple, RESTful fee lookup service if you are interested in this kind of functionality.

Ordering a valuation through ValEx

  1. First, you need to get all the information regarding the valuation and construct an XML/LIXI packet containing the Valuation Request
  2. Once you've created the XML/LIXI packet you need to validate it against the XSD available at https://ws.valex.com.au/lixi/schema/1.5.1/ValuationTransaction.xsd to ensure that all the data is valid
  3. You then place the XML/Lixi Valuation Request into a soap envelope with the authentication headers(which contain your valex username and password).

    Make a soap request to our webservice at https://ws.valex.com.au/soap/lixi/1.3.1/service.php?n=client&wsdl

  4. We're deprecating the codes below. We now have an option you can pass in in the soap request to get soap faults back instead of codes. These should prove to be a lot more useful.
  5. In response to your soap request we can send you a soap response - read more about success and error messages.

Receiving Completed Valuation Reports and Status updates

  1. Once the valfirm has completed the valuation report, the job gets added to the "outbound queue".
  2. After the job reaches the top of the queue, a xml/lixi packet gets created for it.
  3. A connection is made to your webservice via soap using the location of your wsdl and the xml/lixi packet is passed as an argument. The username and password you provided us for your webservices is added to the AuthHeader in the soap pack.
  4. You send us a response code of 0 if it was successful or please send back a soap fault if there was any form of error.

Soap service methods

In general, we recommend providing the methods: statusUpdate(lixi_workflow_xml), cancel(lixi_valuation_xml), response(lixi_valuation_xml). statusUpdate() is where we send appointment, inspection, and other progress updates. cancel() and response() are how we return our full valuation data and invoice to your system.

Ordering With High Priority Urgency (RequestedPriority/@Indicator)

RequestedPriority/@Indicator has the following values:

  • High
  • Normal
  • Low

Set this attribute to "High" to set the urgency level to urgent within Valex. This will be displayed to the valuer. Please use sparingly.

Ordering an EVR (Electronic Valuer Review)

RP Data's EVR Reports may be ordered and managed within Valuation Exchange.

To order an EVR, select the service type as follows:

<FullRegistered ValSubType="ShortForm" ...>
<SubTypeNote>EVR</SubTypeNote>

Apart from the obvious fields that are included in standard valuation requests, some important fields include:

MessageBody/@Status

/ValuationTransaction/Message/MessageBody/@Status can have any of the follow values depending on the LIXI message type.

For workflow:

  • Accepted to accept a job
  • Assigned to accept a job and assign a valuer
  • Inspected when the property has been physically inspected
  • Delayed to delay a job (and record against SLA)
  • InProgress when a delay has ended or expired
  • Cancelled when a job has been cancelled

For valuation requests:

  • Initial for a standard request
  • Inquiring if the request is a quote request
  • AmendmentRequired if the report is being amended

For valuation responses:

  • ValuationCompleted

New Zealand

We currently have the following sites set up for NZ:

New Zealand Addresses

LIXI is an Australian standard; with concepts of 'state' and 'suburb' built in at a fundamental level.

In Australia, the geographical/political divisions are:

  • Country
  • State
  • Local Government Area
  • Suburb

with each entity contained within the borders of its next level up. Only Suburb, Postcode, State & Country are commonly used in addresses.

New Zealand is a more complicated entity, consisting of:

  • Country
  • Region/Regional Council
  • Territorial Authority
  • Suburb

with some combined concepts of "Unitary Authority" (both a region and a territorial authority).

Typically only Suburb, Postcode, Territorial Authority/Unitary Authority & Country are used in addresses.

To support this, ValEx renders the below structure:

<Location PropertyIdentification="NZ-1554515">
  <Address>
    <StreetNo>1</StreetNo>
    <Street Type="Place">Test</Street>
    <!-- Suburb -->
    <City>Unsworth Heights</City>
    <!-- Territorial Authority -->
    <State Name="Other" OtherDescription="North Shore City" />
    <!-- Auckland Region is implied -->
    <Postcode>632</Postcode>
    <Country>NZ</Country>
  </Address>
</Location>

For Unitary Authorities, ValEx models a Territorial Authority linked to a Region, each having the same name.

There are Gisborne District, Nelson City, Tasman District, Marlborough District, and Auckland Council.

Chatham Islands Council is not modelled at this stage.

Regions are modelled along geographic features such as major drainage divides, and Territorial Authorities are based on populations. As such, a Territorial Authority can exist in more than one Region - Taupo District for instance exists in 4 regions.

Country

//Address/Country

Territorial Authority

//Address/State[@Name="Other"]/@OtherDescription

Suburb/Postcode

//Address/City
//Address/Postcode

Regions in New Zealand

See wikipedia for a full list.

Public holidays in New Zealand

At this stage, public holidays are not modelled for individual regions of new zealand - only national holidays are recorded.

Area specific public holidays are associated with provinces or other geographical constraints which are distinct from Suburb/Territorial Authority/Region.

Service Types / Products

As of January 2012, only Long Form reports and EVR are generally supported. This is because Short Form are based on the Australian Property Institute's PropertyPro format, which obviously is not suitable for New Zealand.

LIXI Queue Log

Within ValEx, we have a LIXI Queue Log. This can be useful for debugging LIXI issues.

To access the Queue Log, simply log into ValEx, open a job record, and click on the Queue Log icon in the upper right-hand corner.

This is an explanation of some of the less obvious information:

Queue This can be inbound from client to valex, outbound from valex to valfirm, inbound from valfirm to valex, or outbound from valex to client.
Method This can be soap-lixi, or email-pdf (usually you should only be concerned with soap-lixi).
Packet Type This can be a request, workflow, or response

You can download the following files:

  • Raw: The raw SOAP Request
  • Payload: The LIXI Message sent in the SOAP Request
  • Response: The raw SOAP Response

Extending the LIXI standards

One problem we have encountered a number of times is the requirement to go beyond the LIXI valuation standards.

This is because the LIXI standards really do represent the most common uses; but the ValEx platform and its partners are seeking to innovate - the two goals of innovation and standards often conflict.

Consequently for the 1.4.1 version of the ValEx XSD, we are introducing a minimal change to allow much greater extensibility.

We are introducing an <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="skip"/> node.

What this allows is for lixi partners to define information in a non-lixi namespace; without breaking schema validation.

For instance:

<ValuationTransaction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:foo="http://foo.com"
ProductionData="No">
            
            <-- Appearing after the RelatedPartySegment or AttachmentSegment -->
            <foo:Foo>Hello! I'm a custom string, but could be any valid custom XML structure</foo:Foo>
</ValuationTransaction>

We are strongly advocating this amongst the LIXI valuation and CAL standards group as a way to move forward with custom or proprietry requirements; whilst still remaining LIXI standard compatible.

You can preview and update to the 1.4.1 schema; which is not yet in use by the ValEx application.

Panel Lookup Web Service (Objective-C, iPhone Example)

A sample implementation of the Panel Lookup Web Service for the iPhone in Objective-C.

- (IBAction)lookupButtonPushed:(id)sender {
	// Setup Request
	NSString *urlString = [NSString stringWithFormat:@"https://ws.valex.com.au/rest/fee-lookup/"];
	NSMutableURLRequest *request = [[[NSMutableURLRequest alloc] init] autorelease];
	[request setURL:[NSURL URLWithString:urlString]];
	[request setHTTPMethod:@"POST"];
	
	// Setup POST variables
	NSDictionary *postVars = [NSDictionary dictionaryWithObjectsAndKeys:
							  @"myUsername", @"username",
							  @"mySecret", @"password",
							  @"10", @"serv_id",
							  [postcodeTextField text], @"postcode",
							  [suburbTextField text], @"suburb_name",
							  [emvTextField text], @"estimate",
							  nil];
	int postVarCount = 0;
	NSMutableData *postBody = [NSMutableData data];
	for (id postVarKey in postVars) {
		NSString *postVar = [[postVars objectForKey:postVarKey] stringByAddingPercentEscapesUsingEncoding:NSASCIIStringEncoding];
		if (postVarCount) {
			[postBody appendData:[@"&" dataUsingEncoding:NSUTF8StringEncoding]];
		}
		[postBody appendData:[postVarKey dataUsingEncoding:NSUTF8StringEncoding]];
		[postBody appendData:[@"=" dataUsingEncoding:NSUTF8StringEncoding]];
		[postBody appendData:[postVar dataUsingEncoding:NSUTF8StringEncoding]];
		NSLog(@"Post variable: %@=%@", postVarKey, postVar);
		postVarCount++;
	}
	[request setHTTPBody:postBody];
	
	// Get the HTTP response
	NSHTTPURLResponse* urlResponse = nil;  
	NSError *error = [[NSError alloc] init];  
	NSData *responseData = [NSURLConnection sendSynchronousRequest:request returningResponse:&urlResponse error:&error];  
	NSLog(@"Response Code: %d", [urlResponse statusCode]);
	if ([urlResponse statusCode] >= 200 && [urlResponse statusCode] < 300) {
		
		NSString *result = [[NSString alloc] initWithData:responseData encoding:NSUTF8StringEncoding];
		NSLog(@"Response: %@", result);
		
		// Process the XML contents of the response
		valfirms = [[NSMutableArray alloc] init];
		NSXMLParser *parser = [[NSXMLParser alloc] initWithData:responseData];
		[parser setDelegate:self];
		[parser parse];
		
		// Display to the user
		NSString *message = [[NSString alloc] init];
		int valfirmCount = 0;
		for (id valfirm in valfirms) {
			if (valfirmCount) {
				message = [message stringByAppendingString:@"\n\n"];
			}
			message = [message stringByAppendingString:valfirm];
			valfirmCount++;
		}
		UIAlertView *alert = [[UIAlertView alloc] init];
		[alert setTitle:@"Valuation Firms"];
		[alert setMessage:message];
		[alert addButtonWithTitle:@"Close"];
		
		[alert show];
		[alert release];
	}
}

- (void)parser:(NSXMLParser *)parser didStartElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qualifiedName attributes:(NSDictionary *)attributeDict {
	NSLog(@"Found element: %@", elementName);
	if ([elementName isEqualToString:@"valfirm"]) {
		NSString *valfirmName = [attributeDict objectForKey:@"name"];
		if (valfirmName) {
			[valfirms addObject:valfirmName];
		}
	}
}

Response Codes and Soap Faults

Valuation Exchange initially designed our soap connectivity to make use of a number of response codes.

Time has shown us that this is simply a bad idea - the codes are uninformative, and it makes it harder to understand issues at both ends of a connection.

As a result, we'll be deprecating the use of response codes as of July 1st 2010.

Indicating success

Returning a '0' is still the preferred indication of a successful webservices call; and is the easiest for us to parse.

Raising Errors

We strongly encourage integration partners to simply raise a SoapFault (php, .NET, Java) with the appropriate error strings.

This allows both parties to see informative error or even backtrace information; and more quickly resolve problems.

Handling Errors

ValEx raises SoapFaults when an error is encountered. The only exception is when parsing responses - our queuing system processes the majority of business logic asynchronously. In these instances, we'll incidate a success on the original soap operation, but generate a failure email later.

We'll be looking to further improve this behaviour at a later date, with tools like our compliance web service.

The types of error messages you will see are covered in our article on common errors.

Response codes

This style of interaction is deprecated

Code Description
0 Transaction successful

You recieved the valuation request successfully with no errors

2 Access denied
When sending the valuation request, a combination of the username and password was incorrect.
3 Permission denied

Although the username and password was correct, the username that had authenticated did not have permission to submit a valuation.

4 Invalid XML
The XML that was delivered was invalid, i.e. it was not well-formed.
5 Valuation message did not validate against schema
When you validated the incoming message against the XSD, the validation failed.
6 System Unavailable
Your system is not avaliable and can't accept valuation requests at this time.

 

Sample response

A successful response.

Improved Timezone Rendering

Just a quick note to let our users know - we've started rendering the correct timezone information for jobs in our LIXI correspondence.

We'll be incrementally rolling this out to all of our valuation partners in the near future.

Before we rendered:
<Time>08:00:00</Time>

Now we will render
<Time>08:00:00+10:30</Time> (or <Time>08:00:00+09:30</Time> when DST changes occur).

This should have little affect on implementors. According to ISO 8601,

If no time zone information is given with a time representation, the time is assumed to be in local time. While it may be safe to assume local time when communicating in the same time zone, it is ambiguous when used in communicating across different time zones. It is usually preferable to indicate a time zone (zone designator) using the standard's notation.

Syndicate content