97 lines
5.2 KiB
Markdown
97 lines
5.2 KiB
Markdown
# Mail Forwarding Automation
|
|
|
|
This directory contains an Infrastructure-as-Code (IaC) deployment for Google Apps Script.
|
|
It automates the creation and synchronization of Google Workspace mail forwarding by reading from a Google Sheet (typically populated by Google Forms) and managing Workspace Groups.
|
|
|
|
## Prerequisites
|
|
To deploy this code to your Google Workspace, you need the following installed on your machine:
|
|
- [Node.js & npm](https://nodejs.org/)
|
|
- Google Clasp CLI: Run `npm install -g @google/clasp`
|
|
|
|
## Step 1: Authentication & Setup
|
|
Before you can deploy, you must authenticate your local machine with your Google Workspace Admin account and enable the Apps Script API.
|
|
|
|
1. **Enable the API:** Go to [https://script.google.com/home/usersettings](https://script.google.com/home/usersettings) and turn **ON** the "Google Apps Script API".
|
|
2. **Login:** In your terminal, run:
|
|
```bash
|
|
clasp login
|
|
```
|
|
This will open a browser window. Sign in with your Workspace Admin account (`@haumdaucher.de`) and grant the necessary permissions.
|
|
|
|
## Step 2: Configuration
|
|
You must configure the script to point to your specific Google Sheet.
|
|
Open `src/Code.js` and modify the `CONFIG` block at the top of the file:
|
|
|
|
```javascript
|
|
const CONFIG = {
|
|
// 1. The ID of the Google Sheet (found in the URL: https://docs.google.com/spreadsheets/d/<THIS_ID>/edit)
|
|
SPREADSHEET_ID: "YOUR_SHEET_ID_HERE",
|
|
|
|
// 2. The name of the tab at the bottom of the screen
|
|
SHEET_NAME: "Form Responses 1",
|
|
|
|
// 3. The column numbers containing the data (1 = A, 2 = B, 3 = C, etc.)
|
|
COL_FORWARD_ADDRESS: 6,
|
|
COL_FORWARD_TO_ADDRESS: 4,
|
|
|
|
// 4. Your admin email for receiving reports
|
|
ADMIN_EMAIL: "admin@haumdaucher.de",
|
|
|
|
// 5. Dry run mode. If true, script logs intended changes without modifying Workspace.
|
|
DRY_RUN: true,
|
|
|
|
// ... leave the GROUP_DESCRIPTION_TAG untouched!
|
|
};
|
|
```
|
|
|
|
## Step 3: Deployment
|
|
Once configured, you need to create an Apps Script project in your Google Account and push this code to it.
|
|
|
|
1. Navigate to this `mail_forwarding` directory in your terminal.
|
|
2. Initialize the project as a standalone script:
|
|
```bash
|
|
clasp create --type standalone --title "Haumdaucher Mail Forwarding" --rootDir ./src
|
|
```
|
|
*(This creates a hidden `.clasp.json` file linking this directory to the cloud project).*
|
|
3. Push the code:
|
|
```bash
|
|
clasp push
|
|
```
|
|
|
|
> **⚠️ Important:** `clasp push` only uploads the code. It does **not** install or update the background triggers. You must always re-run the `setup` function in the Apps Script IDE after a push to ensure the triggers are active and up to date.
|
|
|
|
## Step 4: Initialization
|
|
The code is now in the cloud, but the background triggers need to be activated and the Admin SDK authorized.
|
|
|
|
1. Open the project in your browser:
|
|
```bash
|
|
clasp open-script
|
|
```
|
|
2. **Ignore the large blue "Deploy" button.** You do *not* need to create a deployment. This script runs via background triggers, not as a web app.
|
|
3. In the toolbar directly above the code editor, look for a dropdown menu showing function names (it might currently say `syncForwardings`). Click the dropdown and select `setup`.
|
|
4. Click the **Run** button (the play icon) right next to the dropdown.
|
|
5. **Authorization Required:** Google will prompt you to review permissions. *(Note: This interactive browser consent screen is a strict Google Workspace security requirement for scripts accessing the Admin API, which is why this specific step cannot be automated via CLI).*
|
|
- Click "Review Permissions"
|
|
- Choose your Admin account.
|
|
- Click "Advanced" -> "Go to Haumdaucher Mail Forwarding (unsafe)"
|
|
- Click "Allow" to grant access to the Admin Directory API, Gmail API, and Google Sheets.
|
|
5. Once authorized, the `setup` function will finish executing. It installs the background `onChange` trigger.
|
|
|
|
## System Status: LIVE
|
|
The system is currently configured for active production (`DRY_RUN: false`). Any changes to the Google Sheet will result in real-time creation, modification, or deletion of Google Workspace Groups.
|
|
|
|
To revert to dry-run mode for testing:
|
|
1. Open `src/Code.js` and change `DRY_RUN: false` to `DRY_RUN: true`.
|
|
2. Run `clasp push`.
|
|
|
|
**You are done!** Whenever a new response is submitted to the configured Google Sheet via Forms, the script will automatically run in the background, reconcile the forwarding groups, and send you an email report.
|
|
|
|
## Troubleshooting & Analysis
|
|
If you find that the script is not triggering when a new form is submitted:
|
|
|
|
1. **Check Executions:** Run `clasp open-script` and click on the **Executions** tab (the list/bullet icon) in the left sidebar.
|
|
- **No entries?** The trigger never fired. You may need to run the `setup()` function again to ensure the triggers are installed.
|
|
- **Failed entries?** Click on the failed execution to see the exact error message and stack trace.
|
|
2. **Re-Run Setup:** If you have pushed new code or changed your Google Account permissions, always re-run the `setup` function in the Apps Script UI to refresh the background triggers and authorization.
|
|
3. **Trigger Source:** Ensure the Google Sheet you are using is the same one linked to your Google Form. The `onFormSubmit` trigger only fires on the specific sheet receiving the form responses.
|