ews-calendar

name	ews-calendar
description	Extract calendar events from Microsoft Exchange via EWS API

Purpose

Fetch calendar events from Microsoft Exchange Web Services (EWS) and return them as structured JSON.

When to Use

• User asks about their calendar events ("What's on my calendar today?")
• Need to retrieve meetings for today, tomorrow, or a specific date
• Extracting meeting details: subject, time, location, organizer, body text, links

Security Model

Credentials are stored in OS keyring, NOT in config files:

• macOS: Keychain Access (encrypted, OS-managed)
• Linux: libsecret / gnome-keyring (encrypted, OS-managed)

Only EWS_URL and EWS_USER are stored in OpenClaw config (non-secret). The password is retrieved securely at runtime.

Setup

1. Install keyring tools (Linux only)

# Debian/Ubuntu
sudo apt install libsecret-tools gnome-keyring

# Fedora
sudo dnf install libsecret gnome-keyring

# Arch
sudo pacman -S libsecret gnome-keyring

macOS has Keychain built-in.

2. Store credentials in keyring

{baseDir}/ews-calendar-setup.sh --user "DOMAIN\\username"

You will be prompted for your password. This stores it securely in the OS keyring.

3. Configure OpenClaw

Add to ~/.openclaw/openclaw.json:

{
  skills: {
    entries: {
      "ews-calendar": {
        enabled: true,
        env: {
          EWS_URL: "https://outlook.company.com/EWS/Exchange.asmx",
          EWS_USER: "DOMAIN\\username"
        }
      }
    }
  }
}

Replace with your actual Exchange URL and username.

Usage

The skill runs {baseDir}/ews-calendar-secure.sh which:

1. Retrieves EWS_PASS from OS keyring
2. Calls the main script with all credentials in environment
3. Returns JSON output

Command Syntax

{baseDir}/ews-calendar-secure.sh --date <DATE> [--output <FILE>] [--verbose]

Parameters

• --date (required): Date filter
  • YYYY-MM-DD — specific date (e.g., 2026-03-03)
  • today — today's date
  • tomorrow — tomorrow's date
• --output <FILE>: Write JSON to file instead of stdout
• --verbose: Enable debug logging
• --debug-xml <FILE>: Save raw XML response for debugging

Output Format

Returns JSON array of calendar events:

[
  {
    "subject": "Team Standup",
    "start": "2026-03-03T10:00:00Z",
    "end": "2026-03-03T10:30:00Z",
    "location": "Conference Room A",
    "organizer": "[e-mail]",
    "body": "Weekly sync meeting to discuss sprint progress...",
    "links": ["https://zoom.us/j/12345", "https://confluence.example.com/doc"]
  }
]

Returns empty array [] if no events found.

Example Invocations

Get today's events:

{baseDir}/ews-calendar-secure.sh --date today

Get tomorrow's events to file:

{baseDir}/ews-calendar-secure.sh --date tomorrow --output /tmp/tomorrow.json

Get specific date with debug:

{baseDir}/ews-calendar-secure.sh --date 2026-03-03 --verbose --debug-xml /tmp/debug.xml

Troubleshooting

Password not found in keyring

[ERROR] Password not found in keyring for user: DOMAIN\username
[HINT] Run: ./ews-calendar-setup.sh to store credentials

Solution: Run the setup script to store your password:

{baseDir}/ews-calendar-setup.sh --user "DOMAIN\\username"

Linux: secret-tool not found

[ERROR] 'secret-tool' not found. Install: apt install libsecret-tools

Solution: Install libsecret tools:

sudo apt install libsecret-tools gnome-keyring

Linux: Keyring locked

On Linux, the keyring may be locked after login.

Solution: Unlock your keyring (usually happens automatically on desktop login). For headless servers, you may need to set up a keyring daemon.

HTTP request failed

[ERROR] HTTP request failed with status: 401

Possible causes:

• Incorrect username or password
• Password changed — re-run setup script
• Account locked or expired

SOAP Fault

[ERROR] SOAP Fault detected
Fault code: a:ErrorInvalidRequest
Fault string: The request is invalid.

Possible causes:

• Invalid EWS URL (check EWS_URL in config)
• Date format issue (use YYYY-MM-DD)
• Exchange server configuration issue

Credential Management

Update password (after password change)

{baseDir}/ews-calendar-setup.sh --user "DOMAIN\\username"

The script will overwrite the existing entry.

Remove credentials

{baseDir}/ews-calendar-setup.sh --user "DOMAIN\\username" --delete

Or manually:

macOS:

security delete-generic-password -a "DOMAIN\\username" -s "ews-calendar"

Linux:

secret-tool clear service "ews-calendar" user "DOMAIN\\username"

View stored credentials (macOS only)

security find-generic-password -a "DOMAIN\\username" -s "ews-calendar" -w

Files in This Skill

{baseDir}/
├── SKILL.md                 # This file
├── ews-calendar.sh          # Main script (reads from env or .env)
├── ews-calendar-secure.sh   # Wrapper that gets password from keyring
├── ews-calendar-setup.sh    # Store credentials in keyring
├── templates/
│   ├── find-items.xml       # SOAP template for finding calendar items
│   └── get-item.xml         # SOAP template for getting item details
└── .env.example             # Example config for standalone usage

Alternative: Standalone Usage (without keyring)

For development or testing, you can run ews-calendar.sh directly with a .env file:

1. Copy .env.example to .env
2. Fill in your credentials
3. Run: ./ews-calendar.sh --date today

Warning: This stores password in plaintext. Use keyring for production.