System Overview

Introduction

Welcome to Propexo! This guide is designed to help you integrate your application with the Propexo API for the first time. We will walk you through the steps necessary to set up initial synchronization, manage ongoing syncs, and understand how to use webhooks and API requests effectively.

Webhooks

Webhooks are an important part of the Propexo integration process, providing real-time notifications for new and changed incoming data. Instead of polling the Propexo API, we recommend subscribing/configuring your server to listen for the events that you care about. Using webhooks will lower the amount of data transferred between our systems, and because we send webhooks within seconds of detecting a data sync during the sync process, your system will be able to react as quickly as possible to data updates.

Understanding Webhook Payloads

Webhooks should be relied on to deliver notifications with a minimal set of data. For instance, the residents model on the API includes an embedded array called leases_meta_data, which is only available via the API and not included in the webhooks payload for the same model.

When subscribing to the DATA_UPDATE event, the payload includes only the data that has changed as part of the event, not the full payload for the model. For example, if subscribed to the DATA_UPDATE event for the residents model and a resident’s first name changes, the payload will look like this:

1{
2  "data": {
3    "event": "DATA_UPDATE",
4    "object": "residents",
5    "record_id": "cly301zs1000109jv26hx7hii",
6    "diff": {
7      "new": { "first_name": "Mary" },
8      "previous": { "first_name": "Sarah" }
9    }
10  }
11}

As shown, the diff object only includes the changed data. There is no reference to the last_name or any other part of the residents model.

Synchronization Process

Each new integration (typically one per each of your customers) you set up will go through an initial synchronization process, followed by ongoing synchronizations to keep data up-to-date. Here’s how to handle both types of syncs effectively.

Initial Synchronization

The initial synchronization process is crucial for initializing the data exchange between your application and Propexo. This ensures that all necessary data is correctly fetched and stored in the Propexo Data Cache.

The primary difference between the initial sync and ongoing syncs (described below) is that the initial sync will not send DATA_NEW or DATA_UPDATE webhooks. This is because the initial sync is a bulk operation that can generate a large volume of data, which would be impractical to send via webhooks.

First-Time Sync Diagram

Propexo Initial Sync Diagram

Steps to Set Up Initial Synchronization

  1. Create/Enable Integration:

    • Use the Propexo API or Dashboard UI to create and enable a new integration. This step sets up the initial connection between the PMS and Propexo.
    • Follow the Propexo API documentation to create an integration.

  2. Initiate Sync:

    • Once the integration is enabled, Propexo will initiate the synchronization process.
    • Propexo fetches data from the PMS/ERP system and stores it in our data cache.

  3. Data Processing:

    • The Propexo ETL (Extract, Transform, Load) processes the fetched data and transforms it into our unified data format for storage in the data cache.

  4. Completion Notification:

    • After the data is processed and stored, Propexo sends a FIRST_SYNC_COMPLETE webhook to your application. This notification indicates that the sync has completed for the first time and your application can start using the data.

    Example webhook payload:

    1{
    2  "trigger": "FIRST_SYNC_COMPLETE",
    3  "data": {
    4    "event": "FIRST_SYNC_COMPLETE",
    5    "integration_id": "cly301lrc000009jvbp6vaz7i",
    6    "vendor": "PROPERTYWARE",
    7    "successful_job_count": 5,
    8    "failed_job_count": 0,
    9    "is_sync_finished": true
    10  }
    11}

Ongoing Synchronizations

After the initial synchronization, ongoing syncs ensure that your data remains up-to-date. These syncs detect and update new or modified data, allowing your application to stay current with minimal effort.

Ongoing Syncs Diagram

Propexo Ongoing Syncs Diagram

Steps to Manage Ongoing Synchronizations

  1. Scheduled Sync:

    • Propexo initiates regular syncs on a predefined schedule to update the data cache with any new or modified data from the PM system.

  2. Data Processing:

    • The ETL process handles the fetched data, transforming and storing it in the Propexo data cache.

  3. Data Check:

    • Propexo checks for new or updated data.
    • If new data is found, a DATA_NEW webhook notification is sent to your application for each new record.
    • If existing data has been updated, a DATA_UPDATE webhook notification is sent for each record, assuming you are subscribed to data updates for the associated model.

  4. Completion Notification:

    • After the sync process, a SYNC_COMPLETE webhook notification is sent to your application, indicating that the data is current and the synchronization cycle is complete.

  1. Subscribe to Webhooks:

    • Subscribe to and test FIRST_SYNC_COMPLETE, DATA_NEW, and DATA_UPDATE events.

  2. Create Your First Integration:

    • Ensure you have access to all the necessary data models. You can review PMS access per data model in the Propexo Dashboard UI. If access is insufficient, work with your customer to enable additional access and re-run data access checks in the Propexo Dashboard.

    Propexo Data Access Check

  3. Enable the Integration:

    • When ready, enable the integration to begin the first sync.

  4. Receive FIRST_SYNC_COMPLETE Event:

    • After a few minutes, you will receive the FIRST_SYNC_COMPLETE event. There are several variables that can affect sync speed. The most common variables are (adjustable) concurrency configurations in Propexo, and the size of your customer. Larger customers tend to have more data which translates into lengthier sync times.

  5. Make API Requests:

    • Make requests to the API for your enabled data models (e.g., properties, residents, leases).

  6. Handle Subsequent Syncs:

    • For ongoing syncs, you will receive DATA_NEW, DATA_UPDATE, and SYNC_COMPLETE (if subscribed) events. Note that these events are disabled for the first sync due to the volume of new data.

  7. Plan for Partial Payloads:

    • If using DATA_UPDATE webhooks, carefully plan for handling partial payloads, as described earlier.

Conclusion

By following this guide, you can effectively integrate your application with the Propexo API, ensuring data consistency and reliability. Utilize webhooks and the API efficiently to maintain up-to-date data with minimal effort. If you have any questions or need further assistance, please contact our support team.