This has been archived as another component exists which includes the functionality provided by this component. I believe it's in the best interest to work towards making a great single component, and I don't have the time to maintain this one. A merge request for the O365 component has been made with changes to support limiting required access, which will hopefully be merged in by the time you read this.
This custom component for Home Assistant provides read only sensors representing events within Microsoft Outlook Calendars.
The code is based on the Google Calendar integration along with Microsoft To Do for authenticating.
This is currently a work in progress
, and will possibly change to provide a better user experience or new functionality.
In order to use this component, you'll need to create an app that the component can authenticate on behalf of. This can be done by following the instructions below, which were adapted from Microsoft docs.
-
Open a browser and navigate to the Azure Active Directory admin center. Login using a personal account (aka: Microsoft Account) or Work or School Account.
-
Select
Azure Active Directory
in the left-hand navigation, then selectApp registrations
underManage
. -
Select
New registration
. On theRegister an application
page, set the values as follows.a. Set Name to
Home Assistant
b. Set Supported account types to
Accounts in any organizational directory and personal Microsoft accounts
.c. Under
Redirect URI
, set the first drop-down toWeb
and set the value to match your Home Assistant base url with the addition of/api/microsoft-outlook-calendar
. For examplehttps://hassio.local:8123/api/microsoft-outlook-calendar
.If your instance of home assistant isn't accessible in the web, then set this to
localhost
(e.g.http://localhost:8123/api/microsoft-outlook-calendar
) -
Choose
Register
. On theHome Assistant
page, copy the value of theApplication (client) ID
and save it in yoursecrets.yaml
with the keyoutlook_client_id
. -
Select
Authentication
underManage
. Locate theImplicit grant
section and enableID tokens
. ChooseSave
. -
Select
Certificates & secrets
underManage
. Select theNew client secret
button. Enter a value inDescription
and selectNever
as the option forExpires
and chooseAdd
. -
Copy the
client secret
value before you leave this page. Save it in yoursecrets.yaml
with the keyoutlook_client_secret
.
Add the src folder with the name outlook_calendar
into your config directory.
Add the following to your configuration.yaml
.
outlook_calendar:
client_id: !secret outlook_client_id
client_secret: !secret outlook_client_secret
track_new_calendar: false # This is optional, and is true by default.
Restart Home Assistant
, and once it comes online you should have a notification prompting you to authorise your account with the component.
If the redirect url you specified isn't public facing, there's a chance that you'll get a page not found
error. Just update localhost
to your Home Assistant
instance (e.g. http://hassio.local:8123/api/microsoft-outlook-calendar
) and refresh your browser. You should now be greeted with a page stating that the authentication was successful and a file .outlook_calendar.token
should now be present in the root of your Home Assistant
configuration directory.
When you first authenticate with the component, or call the outlook_calendar.scan_for_calendars
service, a file called outlook_calendars.yaml
will be generated in the root of your Home Assistant
configuration directory.
This will look something like.
- cal_id: ***
entities:
- device_id: main
ignore_availability: true
name: Main
track: true
- cal_id: ***
entities:
- device_id: family_calendar
ignore_availability: true
name: Family Calendar
track: false
- device_id: guests
ignore_availability: true
name: Guests
track: true
filter: contains(subject,'visit') or contains(subject,'staying')
cal_id - string/required
The unique id for this calendar. This is generated by Outlook and must not be changed.
device_id - string/required
The name that all your automations/scripts will use to reference this device.
name - string/required
What is the name of your sensor that you’ll see in the frontend.
track - boolean/required
Should we create a sensor (true) or ignore it (false).
The default value is equal to the track_new_calendar
configuration.
filter - string/optional
The criteria that must be present for events to match. This supports anything that is supported by the $filter query parameter.
offset - string/optional
A set of characters that precede a number in the event title for designating a pre-trigger state change on the sensor. This should be in the format of HH:MM or MM.
The default value is !!
ignore_availability - boolean/optional
If set to true, we'll ignore availability for the event. Otherwise we'll only include events that are marked as free.
The default value is true
.
max_results - integer/optional
The maximum number of entries to retrieve at any given time. The default value is 5.
From the example above, we would end up with the binary sensors calendar.main
and calendar.guests
which will toggle themselves on/off based on events on the same calendar that match the filter value set for each. As we don't have any filtering set for calendar.main
, it will not filter events out and always show the next event available.
- offset_reached: If set in the event title and parsed out will be on/off once the offset in the title in minutes is reached. So the title Very important meeting #Important !!-10 would trigger this attribute to be on 10 minutes before the event starts.
- all_day: true/false if this is an all day event. Will be false if there is no event found.
- message: The event title.
- description: Not set.
- location: The event Location.
- start_time: Start time of event.
- end_time: End time of event.