Admin: Episode Editor + Calendar Events

[jerodsanto]

One recurring task that we'd love to automate is the sending and updating of calendar events to participants in episode recordings.

All of the required data elements to achieve this are in the system. Namely:

1. Episode Guests and their email addresses
2. Episode Hosts and their email addresses
3. Episode recording time

Here's an example form of a recent Go Time episode (other fields snipped):

This enhancement would integrate our episode editor with a calendaring platform (probably Google Calendar, as we use Google Apps, but open to better fitting alternatives) to automatically manage an attached calendar event with all participants for all episodes with a recording time set.

The integration will be uni-directional (only sending data to the calendaring platform, not syncing changes back), but will have to cover the following events/changes:

• Recording time is first set on an episode (create calendar event)
• Host/Guest is added or removed from an episode (update calendar event)
• Recording time is modified on an episode (update calendar event)
• Recording time is removed from an episode (cancel calendar event)

The following data points will be set on the calendar event:

(pseudocode)

1. event name: "Recording '#{podcast.name}'"
2. event start: episode.recorded_at
3. event duration: 90 minutes
4. event location: "Skype"
5. event notes: "Setup guide: https://changelog.com/guest/#{podcast.slug}"

[joebew42]

Hi @jerodsanto , since I started to tackle this issue, it could be useful to assign it to me? :rocket:

[joebew42]

Hi @jerodsanto ,

I have a question about the Calendar Events. What we have to do if we receive some failure message while creating the Calendar Event? We may have to consider to block the creation of an episode, or we can move on? So, it means that the calendar event update could go wrong, but it does not block any operation on the episode? What do you suggest?

Thank you! :)

[adamstac]

Good thinking. This certainly happens @joebew42.

My gut says don't block the creation of episodes.

[joebew42]

Hi there, I have another question here: does the fields duration and location of a calendar event may have fixed values or they can be modified? At the moment I am using 90 as default value for the duration field, and Skype as default value for the location field.

Thank you so much :+1: :rocket:

[adamstac]

They might in the future, but @jerodsanto may have more clarity on these details. Here's what I know...

Right now, a 60 minute recording time estimates 90 minutes all in. Not all productions will be 60 minutes. But, we are not capturing the recording durations of podcasts at this time.

Right now, we conduct our calls via Skype. This may change in the near future as some podcasts may record via other options such as Zencastr.

I'm not sure if this was helpful.

[joebew42]

Hi there, another question about the Google Calendar API. As mentioned in the description of this feature, it seems that the first external service that we may have to consider will be the Google Calendar API.

I tried to go in depth and read something about how to use them, and I discovered that everytime we create a Calendar Event by using the Google Calendar Events API an eventId is created, and that eventId should be used later for all other operations like DELETE, PUT or GET. Where do you think could be a good place to store this information? We may have to think to add a calendarEventId as a new field of Episode, or what?

[adamstac]

We'll have to defer to @jerodsanto on this one. He'll be back around on Monday.

[jerodsanto]

Good questions, @joebew42. Let me answer the best I can:

1. We shouldn't block the creation of the episode, but we may want to add an indicator/label in the admin UI for any draft episodes that have a future recorded_at set, but no attached calendar event.
2. Hardcoded values of 90 (minutes) and Skype for the duration and location fields is perfectly fine for now. We will re-assess if/when things change down the road.
3. Agree, let's store the eventId as a string field on Episode schema. Let's call it calendar_id

I'm back in action this week, so holler if you have more questions and I will respond promptly. Thanks!

[joebew42]

1. [...], but no attached calendar event.

In this case we may check if the field calendar_id* is not empty, right? As additional info, could be ufesul to add the URL to the calendar event?

In the meantime if you can add a sort of mock-up about how the Admin UI should looks like could be awesome :+1:

*BTW, we already have a field 'calendar_id` in the Google Calendar API and it represents the Calendar in which we are going to create the event. Don't you think that using the same name with different meanings could bring to some confusion? Take a look at the API documentation

[jerodsanto]

Yes, if the episode has a future recorded_at and no calendar_id then we have a problem and want an indicator.

I'd love to link to the calendar event in the admin as well, but don't want to store any additional data if possible. I think we can recreate the URL with this format: https://www.google.com/calendar/event?eid=[episode.calendar_id] (tested this grabbing event id from edit URL, but not sure if API will give same event id)

Here's a mockup from /admin/podcasts/podcast

The first one is <a href=""><i class="calendar icon"></i></a> and the second one is using <i class="red exclamation icon"></i>

[joebew42]

Hi @jerodsanto ,

Since we may have a conflict with the name calendar_id cause it is used either from the Google Calendar ID and from the Episode, but with different meanings, what do you think if we call the column with the calendar event id with calendar_event_id?

[jerodsanto]

calendar_event_id works for me 👌

[joebew42]

Hi @jerodsanto ,

I would like to know if for the field recorded_at field of the Episode we are using a TimeZone or is it expressed in UTC? What is the default TimeZone?

I'd love to link to the calendar event in the admin as well, but don't want to store any additional data if possible. I think we can recreate the URL with this format: https://www.google.com/calendar/event?eid=[episode.calendar_id] (tested this grabbing event id from edit URL, but not sure if API will give same event id)

Yes! We can build it, starting from its event_id :rocket:

[jerodsanto]

*_at fields are stored in Postgres as timestamp without time zone and are the UTC time. Sometimes we will represent them in the UI as local time, but that is done client-side where we have the local time without having to store a time zone for each user.

[joebew42]

Hi @jerodsanto ,

Since we are integrating our application with an external service (the Google Calendar). I would like to know where do you think could be a good place to put the documentation that explain how to configure the application to use the Google Services API. There are different steps to accomplish in order to configure the Google Services API:

• Create a Google Service Account
• Obtain the google service account credentials
• Export the environment variable GOOGLE_APPLICATION_CREDENTIALS
• Share a Google Calendar with the Google Service Account
• How to run integration test with mix test --only external

You think it could be useful to create a seprate .md file where we document all these steps?

For the last step I preferred to separate the execution of the GoogleCalendarService from all the test suite, just because it is an integration test. So I tagged it as :external and excluded by default.

Thanks :rocket:

[jerodsanto]

Yeah I think that's a good idea. How about docs/integrations.md

[joebew42]

Hi @jerodsanto ,

I am working on the update of an episode and I would like to know how to deal with a particular case:

Let suppose we want to update an episode that has a calendar event already associated, and we set the recorded_at field to nil. What do do? I imagine that in this case we have to remove the calendar event (from Google Calendar) and then set the calendar_event_id field to nil. Right? What do you think?

Thanks!

[jerodsanto]

Yes, I agree. This would imply that the recording was canceled for some reason and we have to reschedule. 👍

[gerhard]

I am convinced that our views on this have changed since this was opened.

In the interest of Kaizen 7 (ships September 14), closing this now. If we still think that it's relevant, it's OK to re-open.

改善