Vacation Calendar plugin

Welcome to the Vacation Calendar plugin!

Introduction

The Vacation Calendar plugin allows you to get a comprehensive overview of your colleagues' vacations and out-of-office events. Clearly see when your vacations overlap or which team members will be present on specific occasions, making your life and teamwork easier and more efficient.

Our plugin is based on Microsoft-Calendar Plugin with modifications for focusing on multiple users' calendars. Full credit to them for their great plugin!

How it works

The plugin interacts with the Microsoft Graph API to fetch users' calendars and schedule items. Mark your events as Out of Office in either the Outlook client or the Teams client. By marking your events as "Out of Office," they will be correctly reflected in the Vacation Calendar plugin, providing an accurate overview of your availability.

Autentication

The Vacation Calendar plugin requires Microsoft authentication. If you have not set this up, please follow the upstream guide on Microsoft authentication: Backstage.io Microsoft Authentication Guide.

At present, the plugin supports only Microsoft authentication and does not integrate with other Backstage authentication methods. If you need the plugin to support a different authentication method, please create an issue so we can discuss your requirements.

Getting started

1. First, install the plugin into your app:

# From your Backstage root directory
yarn --cwd packages/app add @axis-backstage/plugin-vacation-calendar

2. Setup the API-factory.

// packages/app/src/apis.ts:
import {
  vacationCalendarApiRef,
  VacationCalendarApiClient,
} from '@axis-backstage/plugin-vacation-calendar';

createApiFactory({
    api: vacationCalendarApiRef,
    deps: {
      authApi: microsoftAuthApiRef,
      fetchApi: fetchApiRef,
    },
    factory: ({ authApi, fetchApi }) =>
      new VacationCalendarApiClient({ authApi, fetchApi }),
  }),

3. Modify your entity page to include the VacationCalendarPage component:

// In packages/app/src/components/catalog/EntityPage.tsx
import { VacationCalendarPage } from '@axis-backstage/plugin-vacation-calendar';

const groupPage = (
  <EntityLayout>
    <EntityLayout.Route path="/vacation-calendar" title="Out Of Office">
      <Grid md={6}>
        <VacationCalendarPage />
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

By doing this, all Backstage users who are part of that group will be displayed in the Out of Office tab on the group's entity page.

Integration with the Catalog

To fetch all colleagues with the same manager for a user entity, add the manager annotation to the entity's catalog-info.yaml file:

apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  # ...
  annotations:
    manager: value # The Backstage username of the mananger

If the manager annotation is set, you can display all users with the same manager for a user entity. To do this, add the VacationCalendarPage component to the entity page for users:

// In packages/app/src/components/catalog/EntityPage.tsx
import { VacationCalendarPage } from '@axis-backstage/plugin-vacation-calendar';

const userPage = (
  <EntityLayout>
    <EntityLayout.Route path="/vacation-calendar" title="Out Of Office">
      <Grid md={6}>
        <VacationCalendarPage />
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

New Frontend System

The plugin supports the new Backstage frontend system via the ./alpha entry point.

1. Install the plugin into your app:

# From your Backstage root directory
yarn --cwd packages/app add @axis-backstage/plugin-vacation-calendar

2. Add the plugin to your app:

// packages/app/src/App.tsx (or wherever you configure your frontend features)
import vacationCalendarPlugin from '@axis-backstage/plugin-vacation-calendar/alpha';

export const app = createApp({
  features: [
    // ...
    vacationCalendarPlugin,
  ],
});

The plugin will automatically add an "Out Of Office" tab to Group and User entity pages. No manual route or API setup is required — the plugin handles both the API factory and the entity content tab as extensions.

Overriding the entity filter

By default the tab is shown on Group and User entities. You can override this in your app-config.yaml:

app:
  extensions:
    - entity-content:vacation-calendar/entity:
        config:
          filter: 'kind: Component'

Development

The plugin has been added to the example app in this repository, meaning you'll be able to access it by running yarn start in the root directory, and then navigating to /vacation-calendar.

You can also serve the plugin in isolation by running yarn start in the plugin directory. This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. It is only meant for local development, and the setup for it can be found inside the /dev directory.

Screenshots