This is the recommended approach when integrating updatedge API data with your own system. Querying and combining live updatedge availability data with your own business logic is the most effective way to implement the API in your business.
Overview
The diagram below shows an typical recommended implementation scenario.
Steps
- A worker shares their availability (makes changes to their timeline).
- When you query for availability, your system calls the updatedge api with a set of date time ranges and worker ids.
- You combine the availability scores and periods of availability with your own internal event data to produce your rankings.
Implementation Points
Worker Events
A typical function within an CRM system is display a user's events on a calendar. You can achieve this by retrieving worker events using the GetEvents endpoints and overlaying the data on your own calendar controls.
Availability
When you query for availability you will typically supply a number of date/time periods along with a set of worker ids to wish to retrieve availability for. You can also get periods of unavailability and "I'm Available Now" events from the API. Taking both of these result sets, you can merge them together to produce your result.
Potential Pitfalls
Discrepancies
Inevitably, the data you have in your internal system may not always match what the worker has stored in their own timeline. For example, they may have received an assignment confirmation but as yet not inserted it into their timeline. In this scenario, the booking is most likely already in your own system so you can filter out workers based on definitive assignments.
Where you allow your consultants to continue to modify worker calendars on your own system, you will need to think carefully about which events take priorities over others. For example, if you mark a worker out internally as unavailable for a morning due to phone call you had recently, you would need to compare the date/time that unavailability was created with the LastSharedOn property against each worker when you query updatedge for their availability to determine which event "wins".
Disconnected Workers
Once you have connected an internal record to an updatedge user, they may choose at some point to remove you from their contacts. If this happens, you will receive 401 messages when you query their data or as part of the errors collection on availability queries.
When this happens, you may want to contact those workers directly to ensure they haven't removed you in error and to encourage them to reconnect.
Empty Timelines
It is important to consider the LastSharedOn property when querying for availability. A worker may appear to be completely available across the time period you are querying for and thus return no unavailable events but they may also not have updated their timeline recently.
You can nudge users to do so using the API but you only have a limited number per day per worker. Bear this in mind when ranking your results. If a user regularly falls behind updating, you may wish to apply your own adjustments to where they are listed within your rankings.