Expert Agent

Setting up an import from Expert Agent

When creating a property import from Expert Agent you'll be presented with the following fields:

Obtain data from - In 99.99% of cases this can be left as 'FTP'. The option to obtain data from a 'local directory' was added in the event that your server doesn't allow FTP and you have managed to get the feed onto the server via another method.

FTP details - The 'FTP host' will default to ftp.expertagent.co.uk and will likely remain unchanged.

The 'FTP username' and 'FTP password' will need to be obtained from Expert Agent.

FTP directory - This will likely remain empty unless told otherwise by Expert Agent.

Use FTP passive mode - Depending on your server configuration you may need to tick this. Our advice is to have it unticked by default. If you run an import and in the logs it says it has issues downloading the XML file, then try it with this ticked.

XML file name - Defaults to properties.xml and shouldn't need to be changed, though we have seen some feeds use properties2.xml . We're unsure on the difference here.

Only import updated properties - To ensure feeds run quicker and more efficiently you can tick this option to only import properties that have changed since the last time an import ran.

Developer hooks

Hook name: propertyhive_expertagent_departments_to_import

Hook type: Filter

Description: The property data received by Expert Agent has a department node. By default we'll only import properties have a department containing the words 'sales', 'lettings' or 'commercial'. Use this filter to exclude or include departments imported.

Example usage:

add_filter( 'propertyhive_expertagent_departments_to_import', 'customise_departments' );
function customise_departments( $departments )
{
    // $departments (array) - defaults to ['sales', 'lettings', 'commercial']

    $departments [] = 'character'; // ensure it's lowercase

    return $departments ;
}

add_action( "propertyhive_property_imported_expert_agent_xml", 'set_custom_department', 10, 2 );
function set_custom_department( $post_id, $property )
{
    if ( strtolower($property->department) == 'character' )
    {
        update_post_meta( $post_id, '_department', 'residential-sales' );
    }
}

Hook name: propertyhive_pre_import_properties_expertagent_xml

Hook type: Action

Description: Executed after the properties are parsed but before they are actually imported.

Example usage:

add_action( 'propertyhive_pre_import_properties_expertagent_xml', 'pre_import' );
function pre_import( $properties )
{
     // $properties (array) - Array of SimpleXML objects containing property data received from Expert Agent

    // do something here...
}

Hook name: propertyhive_expertagent_xml_properties_due_import

Hook type: Filter

Description: Executed after the properties are parsed but before actually being imported. Allows you to filter out any properties you don't want to import.

For example, maybe you want to only import properties belonging to a certain office.

Example usage:

add_filter( 'propertyhive_expertagent_xml_properties_due_import', 'filter_properties' );
function filter_properties( $properties )
{
    // $properties (array) - Array of SimpleXML objects containing property data received from Expert Agent

    $new_properties = array();
    
    foreach ($properties as $property)
    {
        if ( isset($property->branch) && (string)$property->branch == 'My Branch' )
        {
            $new_properties[] = $property;
        }
    }
    return $new_properties;
}

Hook name: propertyhive_expertagent_xml_address_fields_to_check

Hook type: Filter

Description: If you have locations setup under 'Property Hive > Settings > Custom Fields' we'll look at a number of address fields provided in the data from Expert Agent and, if a matching 'Location' is found, we'll set it accordingly.

Using this filter you can customise the address fields in the XML that we consider when looking for a matching location.

Example usage:

add_filter( 'propertyhive_expertagent_xml_address_fields_to_check', 'customise_address_fields' );
function customise_address_fields($address_fields)
{
    // $address_fields (array) - defaults to ['district', 'town', 'county']

    $address_fields[] = 'country'; // also look at country when mapping to location

    return $address_fields;
}

Hook name: propertyhive_property_imported_expert_agent_xml

Hook type: Action

Description: Executed after each individual property is imported.

Example usage:

add_action( 'propertyhive_property_imported_expert_agent_xml', 'property_imported', 10, 2 );
function property_imported( $post_id, $property )
{
    // $post_id (int) - the WordPress post ID of the imported property
    // $property (SimpleXML object) - The property received from Expert Agent

    // do something here...
}

Hook name: propertyhive_post_import_properties_expertagent_xml

Hook type: Action

Description: Executed after all properties have been imported.

Example usage:

add_action( 'propertyhive_post_import_properties_expertagent_xml', 'post_import' );
function post_import()
{
    // do something here...
}

Hook name: propertyhive_property_removed_expert_agent_xml

Hook type: Action

Description: Executed after a property has been removed from Property Hive due to it not being present in the feed.

Example usage:

add_action( 'propertyhive_property_removed_expert_agent_xml', 'property_removed' );
function property_removed( $post_id )
{
    // $post_id (int) - the WordPress post ID of the imported property

    // do something here...
}

Code Snippets

Importing new homes

If you want to set a custom field or flag in Property Hive for properties flagged as a 'New Home' in Expert Agent, a snippet like so will be needed:

add_action( 'propertyhive_property_imported_expert_agent_xml', 'set_new_home_field', 10, 2 );
function set_new_home_field($post_id, $property)
{
    if ( isset($property->newHome) && (string)$property->newHome == 'YES' )
    {
        update_post_meta( $post_id, '_new_home', 'yes' ); // Change custom field name accordingly
    }
}

The above assumes a custom field has been setup called 'New Home' and can be amended accordingly.

If you'd prefer to set a marketing flag or property type you would need to use the WP wp_set_post_terms() function like so:

add_action( 'propertyhive_property_imported_expert_agent_xml', 'set_new_marketing_flag', 10, 2 );
function set_new_marketing_flag($post_id, $property)
{
    if ( isset($property->newHome) && (string)$property->newHome == 'YES' )
    {
        // Change 90 accordingly to the ID of the marketing flag you wish to set
        wp_set_post_terms( $post_id, 90, 'marketing_flag' ); 
    }
}

Troubleshooting

My brochures aren't updating

When a brochure is updated in Expert Agent (e.g. to include an image or price change) they don't change the URL of the brochure included in the XML.

As a result, we have no way of knowing that the brochure has changed and that we need to download it again.

The solution to this is to store brochures as 'URLs' instead of 'Media Files' under 'Property Hive > Settings > General > Media'.

The FTP connection is failing

If the logs are stating that there is an issue with regards to FTP then please try the following:

1. Tick the 'Use FTP passive mode' setting referenced above.
2. Confirm with Expert Agent that the details are correct
3. Verify the details are correct by using a FTP client like FileZilla or a site like ftptest.net.
4. If they connect ok in step 3 but issues persist it's likely firewall related and is a question for your hosting company.