01. De workflow
Om panden op te halen en te verwerken doorloopt de Media Partner de volgende 5 stappen:
- Haal de lijst op met actieve Contracten ('makelaarskantoren').
- Haal per actief Contract de lijst met pand summaries op (een beperkte set aan gegevens per actief pand).
- Controleer per pand aan de hand van de pand summary of het pand in de database van de Media Partner anders is dan het pand van de Connector.
- Indien het pand anders is (gewijzigd door de makelaar) haal dan alle pandgegevens op en verwerkt deze.
- Meld het resultaat van de verwerking aan de Connector d.m.v. een 'confirm' of een 'reject'.
In een sequence diagram ziet dit er als volgt uit:
Stap A + B: Het ophalen van actieve Contracten
Het ophalen van contracten gaat d.m.v. een HTTP GET actie. Naast het ophalen van Contract verzoeken (zie hier) en Contract beëindigingsverzoeken (zie hier) kan ook de lijst met actieve Contracten opgehaald worden. Dit zijn de Contracten waarvan de makelaar panden met de Media Partner wil delen. Alleen de pandgegevens van panden met een actief contract tussen de Media Partner en de makelaar mogen door de Media Partner gebruikt worden. Dit zijn ook de enige pandgegevens die de Connector aanlevert.
Een makelaar dient via de software voor een Media Partner een verzoek in voor een Contract. De status van het Contract (eerst INACTIVE) wordt nu PENDING ACTIVATION.De Media Partner bevestigd dit verzoek waarna het Contract actief wordt (status ACTIVE). Vervolgens kan de makelaar via de software een verzoek indienen voor beëindiging van het Contract (status PENDING DEACTIVATION). Dit verzoek wordt opgehaald door de Media Partner die de beëindiging bevestigd (status INACTIVE).
Een Media Partner ontvangt alleen actieve panden van de Connector als het Contract de status ACTIVE of PENDING DEACTIVATION heeft. In alle andere gevallen dient de Media Partner de pandgegevens die horen bij het betreffende Contract te verwijderen.
Als eerste haalt de Media Partner alle actieve Contracten op. Dit gaat met een HTTP GET request op alle MediaContracts met de status van het Contract 'active'. De URL van dit GET request ziet er voor versie 16.0 van de connector en token ABCDEFG als volgt uit:
https://api.wazzupsoftware.com/ActivateService.svc/16/0/ABCDEFG/mediacontract/?state=active
Hieronder een C# code voorbeeld:
private IList<MediaContractSnapshot> getMediaContractSnapshots(string constractState)
{
var url = string.Format(@"{0}ActivateService.svc/16/0/{1}/mediacontract/?state={2}",
m_connectorURL, m_token, constractState);
var result = XmlLib.GetObject<MediaContractSnapshotResult>(url);
if (!result.IsSuccess)
throw new Exception(result.ErrorMessage);
return result.ArrayOfMediaContractSnapshot;
}
Stap C + D Het ophalen van Real Estate Property Summaries
Per Contract kunnen de Real Estate Property Summaries opgehaald worden. De Summaries bevatten een beperkte set aan gegevens van de actieve panden; genoeg voor de Media Partner om te bepalen of de gegevens van de panden in zijn database nog overeenkomen met de gegevens zoals de makelaar ze als laatst heeft bijgewerkt.
Een belangrijk veld uit de Summaries is 'ModificationDateTimeUtc'; als dit veld anders is dan de vorige keer dat de pand gegevens door de Media Partner is opgehaald dan heeft de Media Partner niet de meest recente pand gegevens en zal hij deze dus opnieuw op moeten halen.
Hieronder aantal pand Summaries in een XML bestand:
Het ophalen van de Summaries gaat met een HTTP GET request. De URL van dit GET request ziet er voor versie 16.0 van de Connector, token ABCDEFG en Realtor ID 376 (uit het MediaContract uit stap A + B) als volgt uit:
https://api.wazzupsoftware.com/OutputService.svc/16/0/ABCDEFG/realestatesummary/?realtorid=376
Hieronder een C# code voorbeeld:
public IList<RealEstatePropertySummarySnapshot> GetRealEstatePropertySummaries(int realtorID)
{
modifiedSinceUTC = modifiedSinceUTC ?? new DateTime(1900, 1, 1).ToUniversalTime();
var url = string.Format(@"{0}OutputService.svc/16/0/{1}/realestatesummary/?realtorid={2}", m_connectorURL, m_token, realtorID"));
var result = XmlLib.GetObject<RealEstatePropertySummarySnapshotResult>(url);
if (!result.IsSuccess)
throw new Exception(result.ErrorMessage);
return result.ArrayOfRealEstatePropertySummarySnapshot;
}
Stap E + F Het ophalen van een Real Estate Property
Komt de Media Partner met behulp van de Summaries tot de conclusie dat de pandgegevens in de database van de Media Partner niet meer actueel zijn dan kan hij de actuele gegevens ophalen door middel van een HTTP GET request. De URL van dit GET request ziet er voor versie 16.0 van de Connector, token ABCDEFG en Realtor ID 376 (uit de Summary uit stap C + D) en Real Estate Property ID 1365 (uit de Summary uit stap C + D) als volgt uit:
https://api.wazzupsoftware.com/OutputService.svc/16/0/ABCDEFG/realestate/?realtorid=376&id=1365
Hieronder een C# code voorbeeld:
public RealEstateProperty GetRealEstateProperty(int realtorID, int realEstateProperyID)
{
var url = string.Format(@"{0}OutputService.svc/16/0/{1}/realestate/?realtorid={2}&id={3}",
m_connectorURL, m_token, realtorID, realEstateProperyID);
var result = XmlLib.GetObject<RealEstatePropertyResult>(url);
if (!result.IsSuccess)
throw new Exception(result.ErrorMessage);
return result.RealEstateProperty;
}
Stap G + H Het bevestigen van een succesvolle verwerking van een Real Estate Property
Wat er na het ophalen van een Real Estate Property gebeurt is per Media Partner verschillend. De één verwerkt de gegevens in haar database waarna deze op de portal verschijnt; de ander start met DTP werkzaamheden en maakt m.b.v. de gegevens een papieren brochure. Voor de ene Media Partner heeft de pandgegevens binnen enkele seconden verwerkt; de ander heeft enkele dagen nodig. Maar zodra de Media Partner zijn werk voor het pand heeft afgerond bevestigt de Media Partner dit aan de Connector. Deze Connector geeft dit bericht vervolgens weer door aan de makelaar via de software van de Content Provider (b.v. Kolibri). Ook kan er extra informatie toegevoegd worden bij deze bevestiging; namelijk een bericht en een url. In het bericht informeert de Media Partner de makelaar over het eindresultaat van de succesvolle verwerking en de optionele url verwijst naar een webpagina waar de makelaar het resultaat kan bewonderen. Een voorbeeld van een bericht kan zijn "De pandgegevens zijn succesvol verwerkt in onze database." en een url bijvoorbeeld "https://www.mediapartner.nl/woningaanbod/koop/arnhem/jansbuitensingel/7").
De ene Media Partner verwerkt continu de wijzigingen van het pand. Zo zal een Portal altijd de meest recente gegevens willen ontvangen en tonen op haar site. Telkens als deze Media Partner pandgegevens ontvangt bevestigd de Media Partner de succesvolle verwerking aan de Connector. En dit geldt dus niet alleen als het pand voor het eerst wordt aangeboden, maar ook telkens als er wijzigingen zijn doorgegeven en verwerkt door de Media Partner.
Een andere Media Partner verwerkt de gegevens van een pand slechts één keer. Zo zal een drukker de gegevens verwerken en de brochure drukken. Worden de pandgegevens daarna gewijzigd dan zal de drukker (meestal) niet opnieuw brochures gaan drukken. In het geval dat de Media Partner de gegevens slechts 1x verwerkt bevestigd de Media Partner dus ook slechts 1x de correcte verwerking van de pand gegevens.
Het bevestigen van een succesvolle verwerking van de pandgegevens gaat door middel van een HTTP POST actie. De URL van zo'n POST actie ziet er voor versie 16.0 van de Connector, token ABCDEFG en Realtor ID 376 (uit de Summary uit stap C + D) en Real Estate Property ID 1365 (uit de Summary uit stap C + D) als volgt uit:
Hieronder een C# code voorbeeld:
public void ConfirmRealEstatePropertyRetrieval(int realtorID, int realEstateProperyID, string mediaPartnerUrl, string message)
{
var url = string.Format(@"{0}OutputService.svc/16/0/{1}/realestate/?realtorid={2}&id={3}&action={4}&url={5}&message={6}",
m_connectorURL, m_token, realtorID, realEstateProperyID, "confirm", HttpUtility.UrlEncode(mediaPartnerUrl), HttpUtility.UrlEncode(message));
var result = HttpLib.PostMessage<DefaultResult>(url);
if (!result.IsSuccess)
throw new Exception(result.ErrorMessage ?? "Unknown error message.");
}
Stap I + J Het weigeren van de verwerking van een Real Estate Property
Helaas gaat niet altijd alles gelijk goed. Zo kan het zijn dat een pand niet aan de minimale eisen van de Media Partner voldoet. Heeft een pand bijvoorbeeld geen foto's maar is dit een vereiste van de Media Partner dan kan deze dit terugkoppelen aan de makelaar. Dit gaat via de Connector door een HTTP POST actie uit te voeren. Bij deze actie kan een reden worden opgegeven die wordt getoond via de software van de Content Provider aan de makelaar. De makelaar kan vervolgens de noodzakelijk acties ondernemen om ervoor te zorgen dat het pand wel geaccepteerd wordt. Bijvoorbeeld door foto's toe te voegen aan het betreffende pand. Wijzigt de makelaar het pand dan zal de Media Partner dit merken als hij de Summaries gaat verwerken. Het pand met foto's wordt opnieuw opgehaald en het pand kan alsnog succesvol verwerkt worden.
De URL van een POST actie waarmee het pand wordt geweigerd ziet er voor versie 16.0 van de Connector, token ABCDEFG en Realtor ID 376 (uit de Summary uit stap C + D) en Real Estate Property ID 1365 (uit de Summary uit stap C + D) als volgt uit:
Hieronder een C# code voorbeeld:
public void RejectRealEstatePropertyRetrieval(int realtorID, int realEstateProperyID, string message)
{
var url = string.Format(@"{0}OutputService.svc/16/0/{1}/realestate/?realtorid={2}&id={3}&action={4}&message={5}",
m_connectorURL, m_token, realtorID, realEstateProperyID, "reject", HttpUtility.UrlEncode(message));
var result = HttpLib.PostMessage<DefaultResult>(url);
if (!result.IsSuccess)
throw new Exception(result.ErrorMessage ?? "Unknown error message.");
}