Are you RETS Ready?

OK, so I'm cannibalizing a post by the Center for RealtorĀ® Technology's Chris McKeever. See the original if interested. The rest of this post will be about installing the Open Source Variman RETS server (also available from CRT at: http://www.crt.realtors.org/projects/rets/variman/).

For nearly a year, DIS has been involved in enhancing and maintaining Variman on behalf of CRT. Variman 3.1 was recently released and supports the RETS 1.5, 1.7 and 1.7.2 specifications and passes compliance tests. Since the deadline for becoming RETS compliant is rapidly approaching (December 2009), I thought I'd take a moment to describe how to install Variman. Please note that DIS is also available to help install and maintain your Variman installation of so desired.

That said, let's get to work. Of course, the first thing needed is Variman itself. It may be downloaded free from here. There are a couple of versions of the installation:

  • Standalone version with an embedded Tomcat server;
  • A Web Application version that runs under a web server like Tomcat - this is intended to be used if Variman will run on your established web server;
  • A standalone Windows version that will install Variman as a Windows service.

Source code as well as sample data and metadata are also available from the link.

Variman is a Java application and therefore requires Java (1.5 and later) and a database. The current databases supported are the Open Source PostgreSQL and MySQL as well as Microsoft SQL Server. Once your prerequisites are installed, you can proceed to the task of installing Variman itself.

As part of my development and testing, I run Variman in both the standalone and web server flavors on a FreeBSD server where it is the target for the Certification Tests. I do my development and testing on an Apple Power Mac and a Windows XP box. In essence, I'm installing and running all versions. For the examples here, I'll only show the standalone and Tomcat installation from my FreeBSD server. First, let's do the standalone version.

The current version of Variman is 3.1.1 and I've downloaded the file variman-3.1.1.tar.gz and placed it into my target directory. From there, it is a simple matter to untar the file:

dis[mklein]:~: tar -zxf variman-3.1.1.tar.gz 
dis[mklein]:~: cd variman-3.1.1

There are a couple of files that need to be initialized: the rets-config.xml and rets-logging.properties files. There are sample default files included in the distribution which can be copied as a starting place. The rets-logging.properties file is probably fine as it is, but the rets-config.xml file will need to be updated with your specific details. For now, let's just copy the sample files into place:

dis[mklein]:~/variman-3.1.1: find . -name "*.dist"
./variman/WEB-INF/rets/rets-config.xml.dist
./variman/WEB-INF/rets/rets-logging.properties.dist
dis[mklein]:~/variman-3.1.1: cp variman/WEB-INF/rets/rets-logging.properties.dist variman/WEB-INF/rets/rets-logging.properties      
dis[mklein]:~/variman-3.1.1: 

Next you need to tell Variman the name and provide the credentials to your database. For this example, I'm going to create a brand new database called rets. Once that is done, we can either edit the rets-config.xml file by hand, or use the GUI. For expediency's sake, I'll manually edit the file.

There are five XML tags that must be updated:

  • <type>
  • <host>
  • <name>
  • <username>
  • <password>

type represents the database type you are using; host represents the host upon which your database server is running; name represents the name of the database; username and password are for a user with administrative privileges to the database.

Before:

<?xml version='1.0' ?>
<rets-config>
  <port>6103</port>
  <!--
  <address>127.0.0.1</address>
  -->

  <metadata-dir>WEB-INF/rex/metadata</metadata-dir>
  <!--
  <get-object-root>/tmp/pictures</get-object-root>
  <photo-pattern>%k-%i.jpg</photo-pattern>
  <object-set-pattern>%k.xml</object-set-pattern>
  <nonce-initial-timeout>1</nonce-initial-timeout>
  <nonce-success-timeout>1</nonce-success-timeout>
  <strict-parsing>true</strict-parsing>
  -->
  
  <database>
    <type>postgresql</type>
    <host>localhost</host>
    <name>rex_test</name>
    <username>dave</username>
    <password/>
    <max-active>100</max-active>
    <max-wait>120000</max-wait>
    <max-idle>10</max-idle>
    <max-ps-active>100</max-ps-active>
    <max-ps-wait>120000</max-ps-wait>
    <max-ps-idle>10</max-ps-idle>
  </database>
</rets-config>

After:

<?xml version='1.0' ?>
<rets-config>
  <port>6103</port>
  <!--
  <address>127.0.0.1</address>
  -->

  <metadata-dir>WEB-INF/rex/metadata</metadata-dir>
  <!--
  <get-object-root>/tmp/pictures</get-object-root>
  <photo-pattern>%k-%i.jpg</photo-pattern>
  <object-set-pattern>%k.xml</object-set-pattern>
  <nonce-initial-timeout>1</nonce-initial-timeout>
  <nonce-success-timeout>1</nonce-success-timeout>
  <strict-parsing>true</strict-parsing>
  -->
  
  <database>
    <type>postgresql</type>
    <host>dbserver.dis.com</host>
    <name>rets</name>
    <username>mklein</username>
    <password/>
    <max-active>100</max-active>
    <max-wait>120000</max-wait>
    <max-idle>10</max-idle>
    <max-ps-active>100</max-ps-active>
    <max-ps-wait>120000</max-ps-wait>
    <max-ps-idle>10</max-ps-idle>
  </database>
</rets-config>

Once you have done that, you may save the file and then invoke the administrative utility to create the tables required by Variman:

dis[mklein]:~/variman-3.1.1: java -jar variman-admin.jar create-schema

At this point, your database should show the administrative tables:

dis[mklein]:~/variman-3.1.1: psql rets
Welcome to psql 8.2.13, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help with psql commands
       \g or terminate with semicolon to execute query
       \q to quit

rets=# \d
                List of relations
 Schema |        Name        |   Type   | Owner  
--------+--------------------+----------+--------
 public | hibernate_sequence | sequence | mklein
 public | rets_accounting    | table    | mklein
 public | rets_group         | table    | mklein
 public | rets_user          | table    | mklein
 public | rets_user_groups   | table    | mklein
(6 rows)

rets=# \q
dis[mklein]:~/variman-3.1.1: 

For all intents and purposes, Variman is now installed, though it isn't really functional at this point because it lacks the metadata which describes your data. We'll cover that in the next post.

Now that we've installed the standalone server, installing the webapp version is pretty much the same, though there are some slight differences that will be described below. I've downloaded the file variman-webapp-3.1.1.tar.gz and placed it into my target directory. In this case, the target directory is under the web container's hierarchy. From there, it is a simple matter to untar that file as above:

dis[mklein]:/usr/local/apache-tomcat6.0/webapps: tar -zxf variman-webapp-3.1.1.tar.gz 
dis[mklein]:/usr/local/apache-tomcat6.0/webapps: cd variman-webapp-3.1.1/
dis[mklein]:/usr/local/apache-tomcat6.0/webapps/variman-webapp-3.1.1: 

From here, the initialization steps are the same as given above. However, when done with that, you need to move or soft link (on Unix) the variman directory so it is directly below the webapps directory. Further, anytime you want to run the administrative tool, you need to make sure that the variman directory is in the same location as the variman-admin.jar file (again, only if you do not use softlinks).

You can also check out the Variman Online Manual.