Newton Outlook Add-in Configuration

This document describes how to configure the Newton Outlook Add-in with environment variables instead of hardcoded values.

Overview

The configuration has been modernized to use:

✅ Environment variables for all configuration
✅ Docker containerization for the taskpane
✅ Template-based manifest generation
✅ Runtime configuration injection

Configuration Files

1. Environment Variables (`.env`)

The main .env file now includes Outlook add-in configuration:

# Outlook Add-in Configuration
TASKPANE_HOST=localhost
TASKPANE_PORT=4400
TASKPANE_PROTOCOL=https
API_HOST=localhost
API_PORT=3000
API_PROTOCOL=http

# Azure AD for Outlook Add-in
AZURE_OUTLOOK_ADDIN_CLIENT_ID=19f7820f-271b-4ed3-94f8-fdbe71422a3e
AZURE_OUTLOOK_ADDIN_SCOPE=api://newton.ardorisai.de/39070cfa-e221-42cc-88fa-826f788a2b53/access_as_user

# Manifest Configuration
ADDIN_GUID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
ADDIN_VERSION=1.0.0.0
PROVIDER_NAME=ardoris GmbH
SUPPORT_URL=https://www.ardoris.de
APP_DOMAIN=www.ardoris.de

2. TypeScript Environment Service

Location: apps/outlook-addin/src/taskpane/environment/environment.ts

Provides strongly-typed configuration with runtime environment variable support:

import { loadEnvironmentConfig } from '../environment/environment';

const config = loadEnvironmentConfig();
console.log(config.api.baseUrl); // http://localhost:3000/api/v1
console.log(config.azure.clientId); // 19f7820f-271b-4ed3-94f8-fdbe71422a3e

Docker Setup

1. Dockerfile

Location: apps/outlook-addin/Dockerfile

Features:

Multi-stage build (Node.js + nginx)
Self-signed SSL certificates for HTTPS (required by Office)
Runtime environment variable injection
Health checks

2. Build and Run

# Build the taskpane container
docker build -t newton-outlook-taskpane -f apps/outlook-addin/Dockerfile .

# Run with environment variables
docker run -d \
  --name newton-taskpane \
  -p 4400:4400 \
  -e TASKPANE_HOST=localhost \
  -e API_HOST=localhost \
  -e API_PORT=3000 \
  newton-outlook-taskpane

3. Docker Compose

Location: docker-compose.outlook.yml

# Start all services
docker-compose -f docker-compose.outlook.yml up -d

# Start only taskpane
docker-compose -f docker-compose.outlook.yml up outlook-taskpane

Manifest Generation

1. Template-based Manifest

Template: apps/addin-manifest/manifest.template.xml Output: apps/addin-manifest/manifest.xml

The manifest is now generated from a template using environment variables.

2. Generation Scripts

Linux/Mac:

chmod +x scripts/generate-manifest.sh
./scripts/generate-manifest.sh

Windows:

scripts\generate-manifest.bat

3. Generated URLs

The manifest will contain environment-specific URLs:

Taskpane: https://localhost:4400/taskpane.html
Icons: https://localhost:4400/assets/icon-*.png
Resource ID: api://localhost:4400/19f7820f-271b-4ed3-94f8-fdbe71422a3e

Development Workflow

1. Local Development

# 1. Configure environment
cp .env.outlook.example .env.outlook
# Edit .env.outlook with your settings

# 2. Generate manifest
./scripts/generate-manifest.sh

# 3. Build and start taskpane
docker-compose -f docker-compose.outlook.yml up outlook-taskpane

# 4. Start your API server
pnpm nx serve api

# 5. Sideload manifest.xml in Outlook

2. Production Deployment

# 1. Set production environment variables
export TASKPANE_HOST=newton-addin.ardoris.de
export TASKPANE_PROTOCOL=https
export API_HOST=api.newton.ardoris.de
export API_PROTOCOL=https

# 2. Generate production manifest
./scripts/generate-manifest.sh

# 3. Build and deploy container
docker build -t newton-outlook-taskpane:prod -f apps/outlook-addin/Dockerfile .
docker run -d -p 443:4400 \
  -e TASKPANE_HOST=newton-addin.ardoris.de \
  -e API_HOST=api.newton.ardoris.de \
  newton-outlook-taskpane:prod

Configuration Reference

Environment Variables

Variable	Description	Default	Example
`TASKPANE_HOST`	Taskpane server hostname	`localhost`	`newton-addin.ardoris.de`
`TASKPANE_PORT`	Taskpane server port	`4400`	`443`
`TASKPANE_PROTOCOL`	Taskpane server protocol	`https`	`https`
`API_HOST`	API server hostname	`localhost`	`api.newton.ardoris.de`
`API_PORT`	API server port	`3000`	`443`
`API_PROTOCOL`	API server protocol	`http`	`https`
`AZURE_OUTLOOK_ADDIN_CLIENT_ID`	Azure AD client ID for add-in	-	`19f7820f-271b-4ed3-94f8-fdbe71422a3e`
`AZURE_TENANT_ID`	Azure AD tenant ID	-	`d313f676-90ff-4c91-a3b0-0507183e0b00`
`AZURE_OUTLOOK_ADDIN_SCOPE`	Azure AD scope for API access	-	`api://newton.ardorisai.de/.../access_as_user`
`ADDIN_GUID`	Office Add-in unique ID	-	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`
`ADDIN_VERSION`	Office Add-in version	`1.0.0.0`	`1.2.3.0`

Runtime Configuration

The taskpane receives configuration via window.__NEWTON_CONFIG__ object:

// Available in browser at runtime
window.__NEWTON_CONFIG__ = {
  TASKPANE_HOST: 'localhost',
  TASKPANE_PORT: '4400',
  API_HOST: 'localhost',
  API_PORT: '3000',
  AZURE_OUTLOOK_ADDIN_CLIENT_ID: '19f7820f-271b-4ed3-94f8-fdbe71422a3e',
  // ... other variables
};

Security Considerations

HTTPS Required: Office Add-ins require HTTPS in production
Self-signed Certificates: The Docker container generates self-signed certificates for development
Production Certificates: Use proper SSL certificates in production
Environment Variables: Keep sensitive values (client secrets) secure
CORS Configuration: Ensure API allows requests from taskpane domain

Troubleshooting

Common Issues

"Add-in not loading": Check HTTPS certificate and CORS settings
"Authentication failed": Verify Azure AD client ID and tenant ID
"API calls failing": Check API_HOST and API_PORT configuration
"Manifest validation errors": Regenerate manifest after changing environment variables

Debug Commands

# Check container logs
docker logs newton-taskpane

# Inspect generated configuration
docker exec newton-taskpane cat /usr/share/nginx/html/config.js

# Test HTTPS endpoint
curl -k https://localhost:4400/taskpane.html

# Validate manifest
# Upload manifest.xml to Office Add-in validation tool

Migration from Hardcoded Values

The following hardcoded values have been moved to environment variables:

Old Hardcoded Value	New Environment Variable
`https://localhost:4400`	`${TASKPANE_PROTOCOL}://${TASKPANE_HOST}:${TASKPANE_PORT}`
`http://localhost:3000/api/v1`	`${API_PROTOCOL}://${API_HOST}:${API_PORT}/api/v1`
`19f7820f-271b-4ed3-94f8-fdbe71422a3e`	`${AZURE_OUTLOOK_ADDIN_CLIENT_ID}`
`a1b2c3d4-e5f6-7890-abcd-ef1234567890`	`${ADDIN_GUID}`

All configuration is now externalized and can be modified without code changes! 🎉