Autogrator is a .NET application that automatically uploads emails from Microsoft Outlook to Microsoft SharePoint.
The process which the application undertakes to achieve its objective can be divided broadly into the following steps: login to (classic) Outlook; process emails when they are received and optionally, restrict certain senders; export emails to a desired format (by default, PDFs); create—and check for the existence of—folders for the emails to be stored in and finally; upload the emails to SharePoint. Autogrator provides customisability at every stage of this process and uses Serilog to log the actions it performs.
The name 'Autogrator' is a truncated, denominalised portmanteau of 'automatic' and 'integration'. Autogrator is currently being hosted on Microsoft Azure VM(s) as you are reading this.
The setup process is rather lengthy due to the tighly-coupled nature of Microsoft's applications, services and Windows itself.
Containerisation of this application via Docker or other software is obviously infeasible due to the basic requirement
of having Microsoft Outlook installed and authenticated.
Therefore, the first pre-requisite of running Autogrator is that you have
a Windows VM to use.
- .NET 9.0
- A Windows VM if you plan to use Autogrator automatically (you do not need one for its setup, however)
- A user with sufficient administrative priviledges in Microsoft Entra admin center to grant appropriate application permissions for your registered application
- (Optional)
msbuild
if you want to build Autogrator manually
-
Create a new app registration at https://entra.microsoft.com. You do not need to include a Redirect URI
-
Once you have created your application, note its Client ID (which is also known as its Application ID) and its Tenant ID (also known as its Directory ID). You will need these values later to store in your
.env
file -
Create a new 'Client Secret' for your app registration by navigating to the 'Certificates & secrets' menu, and note the value as you will need it later
-
Navigate to your application's 'API Permissions' and add the application permission
Sites.ReadWrite.All
. Be wary that you will need sufficient administrative priviledges to grant this permission.
- Clone this repository using the command
git clone "https://github.com/Nicclassy/Autogrator"
-
Install Microsoft Office 365 and login to Outlook
-
Copy
.env.example
, rename it to.env
and fill out the missing values. The next two steps provide context with regard toAG_EMAIL_CONTENT_PATH
andAG_ALLOWED_SENDERS_*
but are optional. For the values pertaining to SharePoint (e.g. site paths/drive names), see Obtaining SharePoint Information. You can perform this step by using the following commands in PowerShell:
Copy-Item .env.example .env
# Alternatively, you can do: copy .env.example .env
# if you are using Command Prompt
your_favourite_editor .env
-
(Optional) For the variable
AG_EMAIL_CONTENT_PATH
, provide a file path—whose contents will be read byFile.ReadAllText
. If you would like to use the automated notification emails feature for more detailed diagnostics, you can use the following holes in the text of the file (as the file contents are just a message template):{LineNumber}
- The line number on which the exception is thrown{FileName}
- The name of the file from which the exception was thrown{Method}
- The name of the method from which the exception was thrown{ExceptionType}
- The type of exception which was thrown{TimeStamp}
- The timestamp of the thrown exception, which is determined immediately
An example file can be shown below:
This is an automatically generated email sent from Autogrator. Autogrator crashed at {TimeStamp} on line {LineNumber} in file {FileName} in method {Method} with an exception of type {ExceptionType}. Please see the attached log file for more details.
-
(Optional) For restricting/allowing email senders based on predefined rules, you can provide your own implementation of
IAllowedSenders
for use withAutogrator.Builder
. The corresponding environment variables are prefixed withAG_ALLOWED_SENDERS
. The file is downloaded from the SharePoint you specify. If you do not provide an implementation ofIAllowedSenders
thenAllEmailSendersAllowed
will be used (which allows all email addresses that are valid under RFC 5322). You can use your on implementation ofIAllowedSenders
withAutogrator.Builder
like this:
using Autogrator;
Autogrator autogrator = new Autogrator.Builder()
.WithAllowedSenders(new YourAllowedSenders())
.Build();
There are three ways to run Autogrator:
a. Use Autogrator in your code. Configure the instance of Autogrator
using Autogrator.Builder
and AutogratorOptions
. For example:
using Autogrator;
Autogrator autogrator = new Autogrator.Builder()
.WithAllowedSenders(new ExcelAllowedSenders())
.WithEmailFileNameFormatter(mailItem => $"{mailItem.SenderName} {mailItem.CreationTime}")
.WithOptions(new AutogratorOptions {
OverwriteDownloads = true,
SendExceptionNotificationEmails = true
})
.Build();
autogrator.Run();
b. Use Visual Studio Code to run Autogrator. This merely requires you to click the 'Start Without Debugging' button.
c. Start Autogrator using start.cmd
or start.ps1
.
In the fictional SharePoint URL
https://autogrator.sharepoint.com/sites/Autogrator/Documentation
the hostname is autogrator.sharepoint.com
,
the site path is /sites/Autogrator
and the drive name is Documentation
. Experiment with
Microsoft Graph Explorer
if you are unfamiliar with how the Microsoft Graph API works and would like to better understand how to use it.