Build Sophisticated Sequential Scheduling Features With the Nylas Calendar API

[
  {
    "start_time": 1595430000,
    "end_time": 1595458800,
    "user_match": [
      {
        "user": "[email protected]",
        "match": 100
      },
      {
        "user": "[email protected]",
        "match": 50
      }
    ],
    "average_match": 75
  }
]

Summarize Account Availability

The last availability function will calculate the average availability for each email address across all of the time slots that are all users are available in. This information will be used in the situation where the script is unable to find time to sequentially schedule all meetings on the primary user’s calendar. It can be used to determine which email address has the most scheduling conflicts which would allow the user to individually schedule separate meetings when there are a lot of schedule conflicts.

# Accepts: A list returned by evaluated_timeslots()
def match_availability(evaluated_timeslots):
    user_availability = {}
    # For all of the time slots we evaluated earlier...
    for time_slot in evaluated_timeslots:
        for user_match in time_slot["user_match"]:
            if user_match["user"] not in user_availability.keys():
                user_availability[user_match["user"]] = []
            user_availability[user_match["user"]].append(user_match["match"])
    # Return a list of users and their average availability
    availability = []
    for user,matches in user_availability.items():
        availability.append({
            'user': user,
            'match': sum(matches) / len(matches)
            })
    return availability

This function will return a list of dictionaries that indicate the average availability for each email address.

[
  {
    "user": "[email protected]",
    "match": 65
  },
  {
    "user": "[email protected]",
    "match": 22
  }
]

# Accepts: A list of time slots that we'll attempt to sequentially schedule the meetings 
def plan_meetings(time_slots):
    if len(time_slots) > 0:
        # Choose the time slot with the highest average availability first
        # This ensures we start with the most likely possibility.
        highest_time_slot = {"average_match": 0}
        for time_slot in time_slots:
            if time_slot["average_match"] > highest_time_slot["average_match"]:
                highest_time_slot = time_slot
        # Sort the users by availability from least to most.
        # Starting with least available user makes it more likely to find time for everyone
        sorted_users = sorted(highest_time_slot["user_match"], key=lambda item: item["match"])

        # Generate a list of available time slots that are divided into equal lengths 
        available_time_slots = []
        for i in range(
                highest_time_slot["start_time"],
                highest_time_slot["end_time"] - meeting_length * 60,
                meeting_length * 60
                ):
            available_time_slots.append({'start_time': i, 'end_time': i + meeting_length * 60})

        planned_time_slots = []
        planned_users = []
        # For each email address in our sorted list...
        for user in sorted_users:
            # For each time slot the user is available
            for time_slot in available_time_slots:
                # Check the availability for the email address
                free_busy = nylas.free_busy(user["user"], time_slot["start_time"], time_slot["end_time"])[0]
                # Schedule the email address in the first available slot
                if len(free_busy["time_slots"]) == 0:
                    planned_time_slots.append({
                        'start_time': time_slot["start_time"],
                        'end_time': time_slot["end_time"],
                        'user': user["user"],
                        })
                    planned_users.append(user["user"])
                    # Make the slot unavailable after scheduling an event
                    available_time_slots.remove(time_slot)
                    break
            if user["user"] not in planned_users:
                print("could not find available time for {}".format(user["user"]))
                return []
        return planned_time_slots

    else:
        return []

This function returns a list of possible meeting times for each email address that creates a sequential schedule.

[
  {
    "start_time": 100000,
    "end_time": 400000,
    "user_schedule": [
      {
        "user": "[email protected]",
        "start_time": 100000,
        "end_time": 200000
      },
      {
        "user": "[email protected]",
        "start_time": 200000
        "end_time": 300000
      }
    ]
  },
  ...
]

Schedule the Meetings

# Accepts a list of time slots generated by plan_meetings()
def schedule_meetings(planned_time_slots):
    for planned_time_slot in planned_time_slots:
        event = nylas.events.create()
        calendars = nylas.calendars.all()
        for calendar in calendars:
            if calendar["name"] == user_email:
                event.calendar_id = calendar["id"]
        event.title = "1 on 1 with {}".format(user_email)
        event.description = "Let's catch up on our current progress"
        event.busy = True
        event.participants = [
                {'email': user_email},
                {'email': planned_time_slot["user"]},
                ]
        event.when = {
                "start_time": planned_time_slot["start_time"],
                "end_time": planned_time_slot["end_time"],
                }
        event.save()
    return True

if __name__ == "__main__":
    start_date,end_date = date_range.split(" - ")
    start =  datetime.datetime.strptime(start_date, "%m/%d/%Y")
    end =  datetime.datetime.strptime(end_date, "%m/%d/%Y")
    dates = [start + datetime.timedelta(days=x) for x in range(0, (end-start).days + 1)]

    time_slots = {}
    planned_time_slots = []
    for date in dates:
        # Find all times the primary user is available
        available_timeslots = find_available_timeslots(total_time, date, user_email)
        # Identify the time slots that the provided email addresses are also available
        evaluated_timeslots = eval_timeslots(available_timeslots, direct_reports)
        # Identify possible sequential schedules
        planned_time_slots.append(plan_meetings(evaluated_timeslots))
        # Calculate overall email address availability
        user_availability = match_availability(evaluated_timeslots)
    # Automatically schedule the meetings for the first available time slot.
    for planned_time_slot in planned_time_slots:
        if len(planned_time_slot > 0):
            schedule_meetings(planned_time_slot)
            break
        else:
          print("Unable to schedule meetings with all email addresses.")
          # Show availability info so the user can schedule meetings individually
          print(user_availability)

$ python3 sequential_schedule.py