Improving documentation
This commit is contained in:
parent
203bffbbf8
commit
1f42cd16db
80
README.md
80
README.md
@ -134,29 +134,75 @@ When `download-roster.js` fails (due to missing/expired session, download error,
|
||||
**Note:** s-nail must be installed for error emails to work. See Prerequisites above.
|
||||
|
||||
|
||||
## LLAW Google Civic Information API Query version 2
|
||||
## Perl Script (google-civic-api.pl)
|
||||
|
||||
The original script for processing LWVWV membership data. It queries the Google Civic Information API for legislative district information and converts roster CSV files to various formats.
|
||||
|
||||
### Description
|
||||
|
||||
Copyright (C) 2025 - by Jonathan Rosenbaum
|
||||
|
||||
This may be freely redistributed under the terms of the GNU General Public License
|
||||
|
||||
Usage: ./google-civic-api.pl google ./roster-file (queries Google Civic Api Delegate and Senate District for all LWVWV members)
|
||||
./google-civic-api.pl WV000 '*.csv' (show all information for members at large, but do not query Google)
|
||||
./google-civic-api.pl WV000 '*.csv' email (only show email addresses for members at large, but do not query Google)
|
||||
### Usage
|
||||
|
||||
1st argument can be one of these types:
|
||||
google (all members with senate/delegate district query) which prints out this csv data:
|
||||
'Name,Email,Phone,Address,Delegate District,Senate District,League ID,Join Date'
|
||||
ALL (all members without senate/delegate district query)
|
||||
League ID: WV000 (members at large) WV102 (Huntington) WV103 (Morgantown-Monogalia) WV112 (Jefferson)
|
||||
```bash
|
||||
./google-civic-api.pl google ./roster-file (queries Google Civic Api Delegate and Senate District for all LWVWV members)
|
||||
./google-civic-api.pl WV000 '*.csv' (show all information for members at large, but do not query Google)
|
||||
./google-civic-api.pl WV000 '*.csv' email (only show email addresses for members at large, but do not query Google)
|
||||
```
|
||||
|
||||
2nd argument must be the location of the LWVWV roster file, and prints out this csv information:
|
||||
Name,Email,Phone,Address,Join Date,
|
||||
### Arguments
|
||||
|
||||
3rd argument 'email' will only print out the email addresses, and only works with the ALL or League ID type argument
|
||||
1. **Query Type:**
|
||||
- `google` - All members with senate/delegate district query
|
||||
- `ALL` - All members without district query
|
||||
- `League ID` - Specific league (e.g., WV000, WV102, WV103, WV112)
|
||||
|
||||
You will want to send results to a file.
|
||||
Example: ./google-civic-api.pl google '*.csv' > 2023-districts
|
||||
2. **Roster file** - Path to CSV file
|
||||
|
||||
3. **Output format** (optional):
|
||||
- `email` - Output only email addresses
|
||||
- `email-csv` - Output CSV format: email,first_name,last_name
|
||||
|
||||
### Output Formats
|
||||
|
||||
**Full CSV (google type):**
|
||||
```
|
||||
Name,Email,Phone,Address,Delegate District,Senate District,League ID,Join Date
|
||||
```
|
||||
|
||||
**Email only:**
|
||||
```
|
||||
First Last <email@example.com>
|
||||
```
|
||||
|
||||
**Email CSV (for subscription):**
|
||||
```
|
||||
email@example.com,FirstName,LastName
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Query Google API for all members with district info
|
||||
./google-civic-api.pl google '*.csv' > 2023-districts.csv
|
||||
|
||||
# Get emails for state members only (WV000)
|
||||
./google-civic-api.pl WV000 '*.csv' email > state-emails.txt
|
||||
|
||||
# Generate subscription CSV for all members
|
||||
./google-civic-api.pl ALL '*.csv' email-csv > members.csv
|
||||
```
|
||||
|
||||
### Column Name Based Parsing
|
||||
|
||||
The script now uses column names from the CSV header rather than fixed positions, making it robust against column reordering. If required columns are missing, it will display an error showing which columns were expected and which are available.
|
||||
|
||||
|
||||
## Docker Automation
|
||||
|
||||
Copyright (C) 2025 - by Jonathan Rosenbaum
|
||||
|
||||
## Automation
|
||||
|
||||
@ -237,3 +283,9 @@ Low-level script that subscribes members to a **single** Mailman 3 list via the
|
||||
2. Converts output to CSV format: `email,first_name,last_name`
|
||||
3. Sends batch subscribe request to connector
|
||||
|
||||
|
||||
## Related Projects
|
||||
|
||||
- **[mailman-connector](https://git.bikeshopi.dev/bike/mailman-connector)** - REST API service for batch-subscribing members to Mailman 3 lists (used by automation)
|
||||
- **[automation/](automation/)** - Docker-based automation with Ofelia scheduler for hands-off operation. See [automation/README.md](automation/README.md) for Docker setup and configuration.
|
||||
|
||||
|
||||
@ -1,6 +1,8 @@
|
||||
# LWVWV Member Subscription Automation
|
||||
|
||||
Automated Docker container for subscribing LWVWV members to Mailman 3 mailing lists.
|
||||
Part of the [LWVWV project](../). This directory contains Docker-based automation for subscribing LWVWV members to Mailman 3 mailing lists via the [mailman-connector](https://git.bikeshopi.dev/bike/mailman-connector) API service.
|
||||
|
||||
For standalone script usage (without Docker), see the [main project README](../README.md).
|
||||
|
||||
## Overview
|
||||
|
||||
@ -26,11 +28,12 @@ This automation coordinates:
|
||||
└──────────┘ └──────────────┘ └──────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│mailman- │
|
||||
│connector │
|
||||
│(batch sub) │
|
||||
└──────────────┘
|
||||
┌──────────────────────────────────┐
|
||||
│ [mailman-connector](https://git. │
|
||||
│ bikeshopi.dev/bike/mailman- │
|
||||
│ connector) - REST API for batch │
|
||||
│ Mailman 3 subscriptions │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Files
|
||||
@ -68,7 +71,7 @@ $VARIABLE_NAME = "value";
|
||||
|----------|-------------|---------|
|
||||
| `$CONNECTOR_URL` | URL of mailman-connector | `https://mailman-connector.example.org` |
|
||||
| `$CONNECTOR_PASSWORD` | Secret password for connector API | `your_secret_password` |
|
||||
| `$MAILMAN_LIST_ID` | Target mailing list ID | `members.lists.example.org` |
|
||||
| `$MAILMAN_LIST_ID` | Target mailing list ID(s). Format: `list_id:league_id` or just `list_id`. For multiple lists, use comma-separated values. | `members.lists.lwvwv.org:WV000` or `list1:WV000, list2:WV103` |
|
||||
|
||||
#### Required for Portal Download
|
||||
| Variable | Description | Example |
|
||||
@ -121,6 +124,35 @@ $stateLeagueID = "WV000";
|
||||
$localLeagueIDs = "WV102|WV103|WV112";
|
||||
```
|
||||
|
||||
### Multi-List Configuration with League Filtering
|
||||
|
||||
When managing multiple local leagues, you can subscribe different member groups to different lists using the colon-separated format:
|
||||
|
||||
```perl
|
||||
# Format: list_id:league_id
|
||||
# State list gets WV000 members, Morgantown list gets WV103 members
|
||||
$MAILMAN_LIST_ID = "members.lists.lwvwv.org:WV000, morgantown.lists.lwvwv.org:WV103";
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
- **list_id**: The Mailman list identifier (e.g., `members.lists.lwvwv.org`)
|
||||
- **league_id**: The LWV League ID to filter members (e.g., `WV000`, `WV103`, or `ALL`)
|
||||
- If `:league_id` is omitted, defaults to `ALL` (all members)
|
||||
|
||||
**Examples:**
|
||||
```perl
|
||||
# Single list, all members
|
||||
$MAILMAN_LIST_ID = "members.lists.lwvwv.org";
|
||||
|
||||
# Single list, only state (WV000) members
|
||||
$MAILMAN_LIST_ID = "members.lists.lwvwv.org:WV000";
|
||||
|
||||
# Multiple lists with different league filters
|
||||
$MAILMAN_LIST_ID = "members.lists.lwvwv.org:WV000, morgantown.lists.lwvwv.org:WV103, huntington.lists.lwvwv.org:WV102";
|
||||
```
|
||||
|
||||
The script filters the roster by League ID before subscribing, so each list only receives its members.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Configure Environment
|
||||
@ -243,3 +275,9 @@ The container needs access to:
|
||||
- Sensitive data is never committed to git
|
||||
- Session file (`.session.json`) is also mounted read-only
|
||||
- All scripts use the single `../env` file - no duplicated configuration
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- **[Main Project README](../README.md)** - Standalone script usage, Google Civic API documentation, and general project information
|
||||
- **[mailman-connector](https://git.bikeshopi.dev/bike/mailman-connector)** - The REST API service used for batch Mailman 3 subscriptions
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user