WordPress Integration Overview
The Reports application integrates with the Aleteia WordPress network (WordPress.com VIP, 8 language editions) in both directions: WordPress calls the app through webhooks and JSON APIs, and the app reads from / writes to WordPress through the native WP-JSON REST API, XML-RPC, and custom wp-json endpoints.
Reads used to go through the WordPress.com public API (public-api.wordpress.com/rest/v1.1). That API now answers 403 on most editions — en is a private blog and es, pt, si, it, ar have REST access disabled — so every read was failing. Wordpress::RestAPI replaces it with the native /wp-json/wp/v2/ endpoints of each backend host, normalizing responses back to the v1.1 shape callers expect. Writes are unchanged and still go through XML-RPC.
The two APIs differ in more than the host: WP-JSON returns a bare array plus an X-WP-Total header instead of a {found, posts} envelope, spells the identifier and permalink id/link rather than ID/URL, wraps text fields in a {rendered:} object, reports dates in site local time with no offset, and serves each custom post type from its own route rather than through a type parameter. Callers use WP-JSON field names directly; the client only assembles what the API does not hand over ready to use — it unwraps the rendered envelope, rebuilds an unambiguous UTC date from date_gmt, and resolves featured_image from the bare id WP-JSON returns.
This page is the inventory of every integration feature. Use it as the entry point to the detailed documentation and as a checklist when the WordPress backend changes.
Sites and Configuration
The WordpressAPI class maintains the map of language editions (en, es, fr, it, pl, pt, ar, si) and their backend hosts, including staging equivalents used automatically outside production.
The ar and it editions are currently excluded from active synchronization (ACTIVE_SITES): media copy, author sync, and batch indexing skip them. The remaining six editions are fully active.
Credentials and shared secrets are provided via environment variables (WORDPRESS_USERNAME, WORDPRESS_PASSWORD, WP_PRE_SHARED_KEY) — see Environment Variables.
High-Level Architecture
Inbound: WordPress → Reports
| Feature | What it does | Trigger | Status |
|---|---|---|---|
| Post scrape webhook | On post publish/update, dispatches Facebook Open Graph re-scrape, Algolia indexing, and post attachment processing | Webhook on every post create/update | Active — entry point of the whole content pipeline |
| Media upload webhook | Notifies the app that an image was uploaded so it can be processed and copied | Webhook (JWT authenticated) on media upload | Active — part of Media Copy |
| Email campaigns API | WordPress manages SendGrid campaigns (create, update, delete, deliver, test) through JWT-authenticated calls to the app | Editor actions in WordPress | Active — see Email Campaigns |
| Slideshow copy API | WordPress editors request copying a slideshow from one edition to another | Editor action → async API request | Active — see Slideshow Copy API |
Outbound: Reports → WordPress
| Feature | Direction | Trigger | Status |
|---|---|---|---|
| Algolia search indexing | Read (posts, guest authors, categories) | Scrape webhook per article + batch reindex | Active — critical for site search |
| Media copy between editions | Read metadata + write attachments to other editions | Media webhook + background jobs (CopyWordpressPictureJob, SaveMasterPictureMetadataJob) | Active for the six active editions |
| Author synchronization | Read (WordPress users → local database) | Hourly cron (SyncWordpressAuthorsJob) | Active |
| Daily prayers (Magnificat) | Write (daily_prayer posts via XML-RPC) | Cron import every 6 hours + publish jobs | Partially active — gated by the magnificat feature flag, enabled for en and fr only. See Magnificat |
| Taxonomy management | Read + write (remap categories/tags, delete terms) | On-demand: admin UI actions and maintenance tasks | Active, manual use only |
| Article deindexing | Write (Yoast noindex/nofollow meta) | On-demand: CSV-driven job (DeindexPostsJob) | Active, occasional use |
| Editorial reports & exports | Read (posts, content, categories, co-authors, media library) | Monthly crons (Slovenian article export, picture reports), on-demand author payment reports, maintenance export tasks | Active |
Configuration-Only Usage
Some parts of the app do not call WordPress at all but rely on the locale→domain maps defined in WordpressAPI:
- Donation and subscription redirects build return URLs from the edition domains.
- Donations analytics resolves per-locale Google Analytics secondary tracker IDs.
If the WordPress client is ever replaced, these mappings must be preserved.
Detailed Documentation
- Media Copy Overview — image synchronization pipeline
- Slideshow Copy API — cross-edition slideshow duplication
- Maintenance Tasks — taxonomy management and data exports
- Magnificat Integration — daily prayers publishing
- Email Campaigns — WordPress-driven SendGrid campaigns
- Environment Variables — credentials and shared secrets