ring-scheduler-3cx/README.md

# 3CX Ring Group Scheduler

AWS Lambda that automatically updates the after-hours and holiday forwarding destinations on a 3CX ring group daily at 8am ET.

## How it works

- Two EventBridge rules fire daily (one for EST, one for EDT) to handle DST
- Lambda checks if it's actually 8am Eastern — skips if not
- Reads the weekly schedule from `config/schedule.yaml`
- Authenticates to 3CX V20 XAPI via OAuth2
- Updates the ring group's "office closed" and "holiday" routing

## Schedule config

Edit `config/schedule.yaml` to change the weekly schedule or add exception dates:

```yaml
ring_group_number: "800"

weekly_schedule:
  Monday: "114"
  Tuesday: "115"
  Wednesday: "114"
  Thursday: "115"
  Friday: "116"
  Saturday: "100"
  Sunday: "100"

exceptions:
  "2026-12-25": "100"
```

## Setup

### 1. Create 3CX API client

In 3CX Admin Console > Integrations > API, create a new client with XAPI access enabled.

### 2. Store credentials in SSM

```bash
aws ssm put-parameter --name /3cx-scheduler/domain --value "yourcompany.3cx.us" --type SecureString
aws ssm put-parameter --name /3cx-scheduler/client_id --value "your-client-id" --type SecureString
aws ssm put-parameter --name /3cx-scheduler/client_secret --value "your-secret" --type SecureString
```

### 3. Deploy

```bash
sam build
sam deploy --stack-name ring-scheduler-3cx --resolve-s3 --capabilities CAPABILITY_IAM --parameter-overrides Timezone=America/New_York
```

## Manual invocation

```bash
# Run using today's schedule
aws lambda invoke --function-name 3cx-ring-group-scheduler \
  --payload '{"force": true}' \
  --cli-binary-format raw-in-base64-out output.json

# Override to a specific extension
aws lambda invoke --function-name 3cx-ring-group-scheduler \
  --payload '{"force": true, "override_extension": "100"}' \
  --cli-binary-format raw-in-base64-out output.json
```