Skip to content

Trio Job Sync Integration Guide

Introduction

This guide outlines the process for agencies to integrate with Trio VMS to maintain a synchronized list of availabe jobs. The integration uses both the Trio API for initial data retrieval and periodic syncs as well as Trio webhooks for real-time updates.

Authentication

Before accessing the Trio API, you need to set up authentication and obtain an API Key to use in the X-API-KEY header in each request.

Integration

sequenceDiagram
    participant A as Agency System
    participant T as Trio VMS API
    participant W as Trio
    actor C as Facility
    A->>+T: /api/v3/Job
    T->>-A: All Open Jobs
    C->>+W: Create Job 123
    W->>-A: Webhook POST Job 123
    C->>+W: Close Job 234
    W->>-A: Webhook POST Job 234
    loop Timed Refresh
        A->>+T: /api/v3/Job?modifiedDate
        T->>-A: Open Jobs Modified after
    end

Retrieve Initial Job List

To get the initial list of jobs, use the /api/v3/Job endpoint: 

GET https://api.triovms.com/ahsa/api/v3/Job
X-API-KEY: apiKeyValue
This endpoint returns a list of all open jobs available to your agency.

You can use the modifiedDate query parameter to limit the response to jobs that were modfied after a specific date. A simple date will be accepted and the time will default to midnight UTC. 

GET https://api.triovms.com/ahsa/api/v3/Job?modifiedDate=2024-09-01T00:00:00Z
X-API-KEY: apiKeyValue

IMPORTANT

Updates to the NumberOfCurrentOpenPositions does not trigger an update to a Job's ModifiedDateUtc or a Job Update webhook event. If this is a critical piece of data to keep updated in your system, use the api/v3/Job endpoint without a modifiedDate parameter.

Register Job Update Webhook

To receive real-time updates about job changes, register a webhook listener and an endpoint on your server to receive webhook payloads. See Webhook Registration for detailed instructions on registering webhooks within Trio.

Implement Webhook Endpoint

Create an endpoint on your server to receive webhook payloads:

  1. Set up a secure HTTPS endpoint (e.g., https://your-agency-domain.com/trio-webhooks/jobs)
  2. Implement request validation to ensure the webhook is from Trio.
  3. Process the incoming webhook payload and update your local job data accordingly.

Job Sync Implementation

To maintain a synchronized job list:

  1. Perform an initial fully sync using the API:
    • Retrieve all jobs using the /Job endpoint.
    • Store the jobs in your database.
    • Record the timestamp of this sync.
  2. Set up a periodic sync (e.g., daily) to catch any missed updates:
    • Use the /Job endpoint with the modifiedDate parameter set to your last sync timestamp.
    • Update your local database with any changed or new jobs.
    • Record the timestamp of this sync.
  3. Process incoming webhooks in real-time:
    • Use the Job Number as the unique identifier to determine if the job is new (not in your database) or update an existing Job.

IMPORTANT

The /api/v3/Job endpoint only returns Open or OnHold jobs. Your job ingestion process will need to account for jobs no longer returned from then endpoint as Closed.

Implementing webhooks will notify when a Job becomes Closed.

Best Practices

  1. Implement error handling and retries for API requests and webhook processing.
  2. Use a queueing system for webhook processing to handle high volumes of updates.
  3. Implement logging for all API interactions and webhook events for troubleshooting.
  4. Regularly check the /webhooks endpoint to ensure your webhooks are still active and properly configured.
  5. Implement a way to perform a full re-sync if you suspect your job data has become out of sync.

By following this guide, you should be able to implement a robust job sync integration with Trio VMS, keeping your agency's job listings up-to-date using both API and webhook mechanisms.