Availability

Determining user availability is one the core strengths of the updatedge platform.

When workers are actively adding events to their timelines and sharing with the system, you can ask the service to calculate availability for you in a number of ways by supplying one or more time periods (intervals) and worker user ids. The platform will calculate the overall percentage of availability across the intervals you specify and supply each users' result along with the periods of availability and occupancy within those intervals.

An example of availability can be seen on the updatedge portal. On the homepage, a hirer or agency can see the availability user's who have added them as a contact. Against each user's name is a serious of days and their availability.

In the same way, you can use the API to request availability either by retrieving periods of availability across multiple days or by receiving an overall availability percentage for each user and set of periods you specify.

#Repeated Daily Availability

One of the most popular requests is to get the periods of availability the worker has over a repeated period. The GetAvailabilityDaily endpoint lets you specify a period of up to 24 hours and then repeat that over a number of days (up to 31) to see this.

When calculating availability in this way, the platform will apply your specified interval and repeat pattern to worker events, combine any overlapping events and then slice them to fit the interval requested. You will then be given back a list of unavailable periods within the interval you specified and a seperate set of "I'm Available Now" events which have not been sliced to fit. This is so that you have a complete picture of when the user is requesting work across the interval you specify, regardless of your specified start and end points.

#Example

A worker has the following events in their timeline:

#Example Request

POST /availability/getPerDailyInterval?start=2019-09-16T15:00:00Z&end=2019-09-16T20:00:00Z&daysToRepeat=5&api-version=1.0
[
    "xxxx-xxxx-xxxx-xxxx"
]
Copy

#Example Response

{
    "data": [
        {
            "workerId": "xxxx-xxxx-xxxx-xxxx",
            "unavailableIntervals": [
                {
                    "start": "2019-09-16T15:00:00+01:00",
                    "end": "2019-09-16T17:00:00+01:00",
                    "intervalMinutes": 120
                },
                {
                    "start": "2019-09-17T15:00:00+01:00",
                    "end": "2019-09-17T17:00:00+01:00",
                    "intervalMinutes": 120
                },
                {
                    "start": "2019-09-18T15:00:00+01:00",
                    "end": "2019-09-18T17:00:00+01:00",
                    "intervalMinutes": 120
                },
            ],
            "availableNowIntervals": []
        }
        ...
    ],
    "errors": []
}
Copy

IMPORTANT

Please consult unauthorised resource access within the errors section of the documentation with regards to messages that are returned in the errors property.

#Hints and Tips

When integrator start working with updatedge data, they often have their own internal system in operation which has also traditionally captured worker availability. When augmenting this internal data with updatedge data there are a few things to be aware of.

#Ordering and Ranking

When working with two data set (internal and updatedge together), the LastShared attribute of each user becomes important. The relevancy of internal and updatedge data needs to be compared to ascertain which instance is the more recent. You can do this by examining the LastShared attribute of availability responses and comparing it with your own internal user's last modified date. You can then make a decision as to which set of data should be considered the more accurate when sorting.

#Discrepancies between data sources

You may come across instances where your internal data conflicts or differs from the data returned by updatedge. For example you may have an existing entry internally against a user's calendar which is not present on their updatedge timeline (i.e. they may not have entered the event manually). With offers sent from your internal systems via the api, the user will usually accept in-app which will allow both systems to be reconciled.

If however, the user has manually entered an event in their timeline which you have no record of or they have received an assignment from another agency or hirer you will have a discrepancy which you will need to apply your own business logic to.

It is recommended that when you start applying updatedge data to your users, you prevent modification of their calendar on your internal system with the exception of events that your system has created itself to avoid confusion.