engine9 person_remote

person_remote records whether a warehouse person_id has a vendor or CRM identifier for a particular plugin. Use this skill when loading, exporting, or debugging plugin-scoped remote_person_id values. The table is written by the people pipeline; it is not a timeline table or a plugin-prefixed people table.

Quick reference

Concepts

Plugin scope is not stored directly on person_remote. It is derived by joining person_remote.source_input_id to an input.id and filtering on input.plugin_id.

File format

Unique: (source_input_id, remote_person_id, person_id).

Rule: Plugin scoping is not a column on person_remote; always derive it by joining input.

FROM person_remote
INNER JOIN input ON person_remote.source_input_id = input.id
  AND input.plugin_id = '<plugin uuid>'

That is exactly what @engine9/schemas/person_remote:segment_definition_clause:all compiles when given pluginId — the filter used by export universes (“remote people for plugin X”).

An empty export or segment for “plugin remotes ∩ transactions” almost always means there are no person_remote rows whose source_input_id belongs to that input.plugin_id, not that there are no transactions.

Workflow

When rows are written

person_remote is upserted inside the inbound people pipeline, after person_id is assigned:

… → person_remote:transforms:extractRemotePersonIds  # extract remote_person_id → identifiers
  → … appendInputId / appendPersonId …
  → person_remote:transforms:upsertPersonRemote # requires pluginId; needs remote_person_id + person_id + input_id
  → sql.tables.upsert

Built by buildInboundTransforms (@engine9/core/lib/peoplePipeline/getInboundTransforms.js). Upsert implementation: @engine9/schemas/person_remote/transforms/inbound/upsert_tables.js.

Triggers that write person_remote

What “without loading to the database” means here

idFiles does write warehouse identity/attribute tables (person, person_remote, person_email, …). It does not require:

• loadTimeline / loadTimelineTables
• A plugin people table such as tatango_kic_person

So: use idFiles (or loadPeople) to populate Tatango-scoped person_remote without a Tatango people-table load or a timeline load. Skip do_not_upsert / doNotUpsert (those run identity lookup only and skip all upserts, including person_remote).

Rules

For @engine9/schemas/person_remote:segment_definition_clause:all with pluginId = <Tatango uuid> (or the equivalent export SQL) to return rows after an id/load:

1. Rule: plugin_id / pluginId must be that plugin’s UUID, not remote_plugin_id or a plugin slug.
2. Rule: input_id / default_input_id must be an input.id whose input.plugin_id is the same plugin. person_remote.source_input_id is set from the row’s input_id through appendInputId and upsert. If the input belongs to another plugin, a search scoped to the intended plugin misses the rows.
3. File/stream rows with a non-empty remote_person_id. Without it, extract and upsert no-op for remotes (email/phone-only rows still create people, but no person_remote).
4. Prefer an email and/or phone on the same row so new remotes attach to existing donors instead of creating orphan people — identity still follows e9-person-id.
5. Rule: do_not_upsert must be false (the default), or identity lookup runs without writing person_remote.

idFiles sketch

await inputWorker.idFiles({
  filename: '/path/to/people.csv', // or file_array: [{ filename, input_id, ... }]
  input_id: '<uuid of an input owned by that plugin>',
  plugin_id: '<plugin uuid>',
  // optional: remote_input_id / remote_input_name / input_type when creating/healing input metadata
});

idFiles requires input_id (or default_input_id) on each file item. If plugin_id is omitted, it is loaded from that input row — so the input must already belong to the target plugin.

Equivalent without writing an ID parquet (people only):

await personWorker.loadPeople({
  filename: '/path/to/people.csv', // or stream: [{ remote_person_id, email, ... }]
  plugin_id: '<plugin uuid>',
  default_input_id: '<uuid of an input owned by that plugin>'
});

Extract / upsert details

• Extract (person_remote:transforms:extractRemotePersonIds): builds lookup key {pluginId}.{remote_person_id} lowercased, unless the inbound value already starts with a UUID + ..
• Upsert (person_remote:transforms:upsertPersonRemote): looks up existing remotes for this pluginId via person_remote ⨝ input; inserts with source_input_id = row.input_id, or updates the existing row for the same person+remote under that plugin.
• Rows lacking remote_person_id or person_id are skipped by upsert.

Outbound and exports

person_remote:transforms:appendRemotePersonId joins remotes for a plugin onto an export file (the inverse of inbound upsert). Search all only filters existence by plugin; append is for writing the vendor id column back out.

Troubleshooting

1. Confirm plugin UUID: account plugins (or SELECT id, name, path FROM plugin).
2. Count remotes for that plugin (join input) — not a bare COUNT(*) on person_remote.
3. Confirm candidate input rows: SELECT id, plugin_id, input_type, remote_input_name FROM input WHERE plugin_id = ?.
4. If plugin people tables exist but remotes do not, those people were never run through loadPeople/id with that plugin’s plugin_id + matching input_id.
5. If remotes exist under the wrong plugin’s inputs, fix the input ownership / re-id with the correct plugin_id + input_id pair — do not only change the export filter unless that matches product intent.

Related documentation

Code map