Automatische Abwesenheitsnotizen für unseren Urlaub per Microbot und Microsoft Office
Wer arbeitet, macht natürlich auch mal Urlaub. Bevor sich ein Kollege oder eine Kollegin in den wohlverdienten Urlaub verabschiedet, arbeiten wir bereits mit einer automatisierten Urlaubsübergabe, die uns unterstützt, unsere Themen für den Urlaub zu übergeben. Das betrifft beispielsweise die Vertretung in unseren Kundenprojekten, aber auch offene To-Do’s, die noch erledigt werden müssen. Damit eine während des Urlaubs eingehende E-Mail nicht ins Leere läuft, haben wir ebenfalls eine Abwesenheitsnotiz. Allerdings kann bei aller Vorfreude dieses nette Feature schnell vergessen werden. Damit hier keine Probleme entstehen, haben wir uns entschieden, dieses Thema an unsere Microbots abzugeben.
Die Voraussetzungen für eine automatisierte Abwesenheitsnotiz sind gegeben. Die Verwaltung von unseren Mitarbeiter:innen und Urlauben erfolgt in MOCO und bei unseren E-Mails setzen wir auf Microsoft Office. Beide Anbieter stellen eine gut dokumentierte API zur Verfügung, sodass diese Herausforderung ohne große Hindernisse gelöst werden kann. Das grobe technische Konzept sieht daher wie folgt aus:
Abfrage an MOCO, welche:r Mitarbeiter:in demnächst im Urlaub ist
Abfrage an Microsoft Office um gewünschte: Mitarbeiter:in zu ermitteln
Abwesenheitsnotiz für den Urlaubszeitraum der/des jeweiligen Mitarbeiter:in setzen
Slack-Benachrichtigung, als Bestätigung, dass die Abwesenheitsnotiz gesetzt ist
Bei vorherigen Automatisierungen haben wir bereits sehr gute Erfahrungen mit der MOCO API gemacht. Entsprechend schnell war die Abfrage, welche:r Mitarbeiter:in demnächst im Urlaub ist, schnell erledigt.
Microsoft Office nutzen wir viel über die Weboberfläche. Hier war etwas mehr Recherchearbeit nötig
Microsoft Office steuern mittels Microsoft Graph
Um Informationen in Microsoft Office ändern zu können, werden aus Sicherheitsgründen natürlich entsprechende Berechtigungen benötigt. Das funktioniert bei Microsoft über eine eigene Anwendung in Azure Active Directory (Azure AD). Wenn eine Anwendung in einem Azure AD-Mandanten registriert ist, können zugewiesene Benutzer - in unserem Fall unser Microbot - sicher darauf zugreifen.
(Source: https://learn.microsoft.com/de-de/azure/active-directory/manage-apps/what-is-application-management)
Die Anwendung ist mit wenigen Klicks erstellt. Lediglich ein Name und der unterstützte Accounttyp müssen gesetzt werden: in unserem Fall also "Single Tenant", da die Anwendung intern in unserer Organisation ist.
Im nächsten Schritt musste unter dem Reiter "Certificates & secrets" ein Client Secret, also eine Art Account, für die Anwendung angelegt werden. Der Client Secret besteht aus einer ID und einem Value, dem Passwort. Die Berechtigungen lassen sich unter dem Reiter "API permissions" entsprechend vergeben. Hier sind wir auf knifflige Berechtigungen gestoßen, da das ganze System sehr fein granular funktioniert. Generell gibt es zwei Typen von Berechtigungen: Delegated und Application. In unserem Fall war der Typ Application erforderlich und mit User.ReadWrite.All können alle Userprofile (wozu auch die Maileinstellungen gehören) gelesen und beschrieben werden. Die Client-ID wird als letzte Information noch benötigt, man findet sie unter "Overview".
Die Vorarbeit ist nun geleistet und wir können uns unserem MicroBot widmen. Damit der Bot die Nutzer abfragen und später die automatische Abwesenheitsnotiz setzen kann, benötigt er zuerst einen Security-Token. Diesen bekam er mit folgendem POST-Request:
const TOKEN_ENDPOINT = https://login.microsoftonline.com/${MICROSOFT_TOKEN}/oauth2/v2.0/token;
const postData = {
client_id: MICROSOFT_CLIENT_ID,
client_secret: MICROSOFT_CLIENT_SECRET,
scope: "https://graph.microsoft.com/.default",
grant_type: "client_credentials",
};
export function getAzureAccessToken(): Promise<AzureAccessType> {
return axios
.post(TOKEN_ENDPOINT, qs.stringify(postData), {
headers: { "Content-Type": application/x-www-form-urlencoded },
})
.then((response) => {
return response.data;
})
.catch((error) => {
console.log(error);
});
}Der MICROSOFT_TOKEN ist die ID, welche wir unter dem Reiter "Certificates & secrets" bekamen. MICROSOFT_CLIENT_SECRET ist das dazugehörige Passwort und MICROSOFT_CLIENT_ID ist die Client-ID der Anwendung. Mit dem Azure Access Token waren wir nun in der Lage, die Benutzer abzufragen.
export async function getUsers(): Promise<MicrosoftUsersType> {
const azureAccessToken = await getAzureAccessToken();
return axios
.get(`https://graph.microsoft.com/v1.0/users/`, {
headers: { Authorization: Bearer ${azureAccessToken.access_token} },
})
.then((response) => {
return response.data;
})
.catch((error) => {
console.log(error);
});
}Nachdem alle Mitarbeiter:innen von MOCO abgefragt wurden, die demnächst in den Urlaub gehen, mussten diese nur noch mit den Benutzeraccounts von Microsoft abgeglichen werden. Anschließend konnten wir für jede:n Mitarbeiter:in nun den Zeitraum seines/ihres Urlaubs mit einer passenden Abwesenheitsnotiz setzen.
export async function changeMailRespondForUser(microsoftUserId, message, startDate, endDate) {
const azureAccessToken = await getAzureAccessToken();
const mailData = {
"@odata.context": https://graph.microsoft.com/v1.0/$metadata#users('${microsoftUserId}')/mailboxSettings,
automaticRepliesSetting: {
status: "scheduled",
externalAudience: "all",
internalReplyMessage: message,
scheduledStartDateTime: {
dateTime: dayjs(startDate).utc().format(),
timeZone: "UTC",
},
scheduledEndDateTime: {
dateTime: dayjs(endDate).add(1, "day").utc().format(),
timeZone: "UTC",
},
},
};
return axios
.patch(`https://graph.microsoft.com/v1.0/users/${microsoftUserId}/mailboxSettings`, mailData, {
headers: { Authorization: Bearer ${azureAccessToken.access_token} },
})
.then((response) => {
return response.data;
})
.catch((error) => {
console.log(error);
});
}Zum Schluss wird der/die entsprechende Mitarbeiter:in in Slack kurz benachrichtigt, dass die Abwesenheitsnotiz gesetzt wurde. So startet der Urlaub angenehm!
Links: MOCO APP, MOCO APP API, Microsoft Office 360, Microsoft Office 360 API, Blogartikel von Jan Vidar Elven
