Use constraints to set general rules for availability.
Formerly known as "filters"
In our previous availability endpoint POST /findtime, constraints were known as "filters". We've renamed them to "constraints", but they serve the same purpose.
Caution
Please be advised that we have a character limit of 64000 characters of JSON in requests; therefore, we advise that old constraints in the past that are no longer valid be removed when sending requests to the API.
The most typical use-case for constraints is setting opening hours and/or working hours. You can do this with two different kinds of constraints; blocking and allowing.
"Allowing" constraints implicitly blocks everything else, so for instance the constraint AllowDay, with the day set to monday, will block all the other days in the week.
This means that you do not need to explicitly block periods that are implicitly being blocked with an "allowing" constraint. So if you are using the allow_weekdays constraint, you don't need to also supply the block_weekends constraint.
You can combine constraints to fit your use-case. As mentioned the most common use case is setting opening hours. With opening hours Monday to Friday 9am to 5pm this would look like this:
Example-1: Allow Monday to Friday 9 to 5PM and block weekends
{
"availability_constraints": [
{"block_weekends": {} },
{"allow_hours": {"start": 9, "end": 17} }
]
}
Example-2: Allow Monday to Friday 9 to 5PM and block weekends and block lunch hours 12 to 1PM.
{
"availability_constraints": [
{"block_weekends": {} },
{"allow_hours": {"start": 9, "end": 17} },
{"block_hours": {"start": 12, "end": 13} }
]
}
You can set constraints for your resources (eg. individual working hours in their specific timezone) and your projects (eg. business opening hours). You can also add constraints on the fly when you perform your availability queries. All of these different constraints will be taken into account by Timekit when looking for availability.
Available constraints
- Day and time
- Hours
- Day
- Period
- Weekdays
- Weekends
- [Event Based Allowing/Blocking Period] (#event-based-allowingblocking-period)
Day and time
Example-3: Repeat One-Off Availability on Project Level and Resource Level:
Sometimes you may not have a regular weekly schedule. Rather, if you have an irregular schedule in this situation, you can set your working hours to be repeated on certain days only.
i.e. Allow slots to be available on Monday, Wed and Friday available from 10 to 5pm
{
"availability_constraints": [
{ "allow_day_and_time": {"day": "Monday", "start": 10, "end": 17 }},
{ "allow_day_and_time": {"day": "Wednesday", "start": 10, "end": 17 }},
{ "allow_day_and_time": {"day": "Friday", "start": 10, "end": 17 }}
]
}
Hours
Example-4: Block/Allow specific hours everyday
{
"availability_constraints": [
{"allow_hours": {"start": 9, "end": 17} },
{"block_hours": {"start": 12, "end": 13} }
]
}
Day
Example-4: Block/Allow specific days during week
{
"availability_constraints": [
{"allow_day": {"day": "Monday"} },
{"block_day": {"day": "Friday"} }
]
}
Period
Example-4: Allow or block a specific time period given two timestamps.
Ideal for blocking out a fixed time range like holidays (if it's not practical to block out the time using calendar events instead)
{
"availability_constraints": [
{"allow_period": {"start": "2018-06-01 09:00:00", "end": "2018-06-30 17:00:00"} }
]
}
Weekends
Example-5: Only allow or block weekends.
{
"availability_constraints": [
{"allow_weekends": {} }
]
}
{
"availability_constraints": [
{"block_weekends": {} }
]
}
Weekdays
Example-6: Only allow or block weekdays.
{
"availability_constraints": [
{"allow_weekdays": {} }
]
}
{
"availability_constraints": [
{"block_weekdays": {} }
]
}
Event Based Allowing/Blocking Period
Event type allow/blocking availability allows you to define period that you can allow and block. You can create multiple event based allow/blocking which would make your slots available or blocked between these defined events.
Example-7: Event Based Blocking Period
Block 10 AM to 11 AM every Monday and Wednesday from May 1,2022 to May 31, 2022.
Also, Block 12 PM to 1 PM every Thursday and Friday from June 1,2022 to June 30,2022
{
"availability_constraints": [
{
"block_event_period": {
"periods": [
{
"days": [
"Monday",
"Wednesday"
],
"start": "2022-05-01 10:00",
"end": "2022-05-31 11:00"
},
{
"days": [
"Thursday",
"Friday"
],
"start": "2022-06-01 12:00",
"end": "2022-06-30 13:00"
}
]
}
}
]
}
Example-8: Event Based Allow Period
Allow 8 AM to 5 PM every Mon, Wed, Fri from May 1, 2022 to May 31, 2022.
Also, allow 9 AM to 12 PM every Tue and Thurs from May 1, 2022 to May 31, 2022.
Also, allow 9 AM to 4 PM every Mon, Tue, Wed, Thurs, Fri from June 1, 2022 to June 30, 2022.
Also, allow 10 AM to 12 PM every Sat from May 1, 2022 to Never Ends.
{
"availability_constraints": [
{
"allow_event_period": {
"periods": [
{
"days": [
"Monday",
"Wednesday",
"Friday"
],
"start": "2022-05-01 10:00",
"end": "2022-06-01 11:00"
},
{
"days": [
"Tuesday",
"Thursday"
],
"start": "2022-05-01 09:00",
"end": "2022-06-01 12:00"
},
{
"days": [
"Saturday"
],
"start": "2022-05-01 09:00",
"end": "9999-12-31 12:00"
},
{
"days": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"start": "2022-06-01 09:00",
"end": "2022-07-01 16:00"
}
]
}
}
]
}
Example-9: Event Based Allow/Block Period
Flu shots are available from April 01, 2022 to May 01, 2022 every Thursday only however every Thursday during this period employee takes lunch break around 12-1pm
{
"availability_constraints": [
{
"block_event_period": {
"periods": [
{
"days": [
"Thursday"
],
"start": "2022-04-01 12:00",
"end": "2022-05-31 13:00"
}
]
}
},
{
"allow_event_period": {
"periods": [
{
"days": [
"Thursday"
],
"start": "2022-04-01 09:00",
"end": "2022-05-31 17:00"
}
]
}
}
]
}