Add custom fields to a plugin pull

A plugin's people or transaction pull brings in standard fields plus any vendor custom fields named in a plugin setting. Adding fields means appending names to that setting, never replacing it. Use this skill when someone asks to add one or more custom fields to a people, transaction, gift, or donation pull for an account. The work is MCP-only and starts with a check that the setting exists; when it does not, stop.

Quick reference

Rule: The setting name and section come from MCP plugin settings. The table above is the convention, not a substitute for checking.

Concepts

Engine9 plugin settings live in the warehouse setting table, one set per plugin row. Submodule settings carry section: "<Submodule>" in the catalog. A *_custom_fields setting is an array of vendor field identifiers that the pull requests in addition to standard fields.

Older plugins accept a custom_fields option on the load method itself, set in each dataflow job. That is the legacy mechanism. This skill does not edit method options.

Modern pulls write to input-store files, not database tables. Some accounts also keep plugin-prefixed warehouse tables (<table_prefix>person, <table_prefix>transaction) that need a matching column before new fields show up there.

Workflow

- [ ] A. Account and plugin found (MCP only)
- [ ] B. <submodule>_custom_fields setting exists — otherwise HARD STOP
- [ ] C. listCustomFields run on the right submodule
- [ ] D. Requested fields matched to exact identifiers
- [ ] E. Setting updated: existing values kept, new values deduped and appended
- [ ] F. Asked whether existing tables need varchar(255) columns
- [ ] G. Offered a backdating load

A. Find the account and plugin

1. Log in and search the account per e9-mcp. A count: 0 miss is a stop.
2. Call account plugins. Note each candidate's path, id (plugin uuid), table_prefix, and metadata.submodules.
3. When several instances of the vendor plugin exist, or it is unclear which job is the pull, list recent flow runs with task action: "list", a search on the vendor name, and include_task_runs. The running job's plugin path and submodule (for example ...RENxtBot.People with method loadPeople) identify the pull.

Rule: Discover the plugin from MCP only. Do not read local account configs or plugin source.

B. Confirm the setting exists (hard stop gate)

Call plugin settings for the account, filtered by path or plugin_id when known. Look for a setting named <submodule>_custom_fields with section equal to the submodule.

Rule: If the setting is not in the catalog, stop. Report what was checked and end the workflow. There is no point listing fields that cannot be saved.

Each of these is a hard stop:

Rule: Do not work around a missing setting. Do not edit custom_fields on dataflow jobs, run addCustomField, or change the load flow unless the user explicitly asks for that legacy path.

C. List custom fields

Schedule the submodule's listCustomFields with task (path = <plugin path>:<Submodule>, method: "listCustomFields", and plugin_id when more than one instance exists). Poll with action: "listTasks" and read the result with action: "output".

Rule: Run it on the submodule that matches the setting. People custom fields and gift custom fields are separate catalogs in most CRMs.

D. Match the requested fields

Match the user's names, which are often vendor UI labels, to the identifiers returned by listCustomFields. Use the identifier form that the setting's current values use.

Rule: When a requested name matches zero or several fields, show the candidates and ask. Do not guess.

E. Append to the setting

1. Read the current value from the settings response. It may be an array or a comma-separated string.
2. Build the new list: every existing value in its original order, then each new identifier not already present (case-insensitive compare).
3. Show before and after, then call setSetting with the full array.

{
  "command": "setSetting",
  "account_id": "<account_id>",
  "plugin_id": "<plugin uuid>",
  "name": "people_custom_fields",
  "value": ["existing_field_a", "existing_field_b", "new_field_c", "new_field_d"]
}

Rule: Append only. Do not remove or reorder existing custom fields without explicit guidance from the user.

4. Call settings again and confirm the stored value.

F. Existing tables (ask first)

Ask whether the new fields must also land in existing warehouse tables. Modern pulls keep data in files, so the answer is often no.

When yes, find candidates with sql tables using the plugin table_prefix (^<table_prefix>person, ^<table_prefix>transaction). Ignore _archive_* tables. Check describe for columns that already exist, then add only the missing ones:

ALTER TABLE <table_prefix>person ADD COLUMN <field> varchar(255)

Rule: New columns are varchar(255) unless the user specifies a type.

Rule: DDL needs the admin role. Show the exact statements and get confirmation before running them.

G. Backdate (optional)

The setting only affects future pulls. To fill history, offer to schedule the submodule's load method with a bounded window. Check its options first with task describe (start / end, interval, table). Use load with a bounded start / end / interval (for example start: "now", end: "2010-01-01", interval: "3M") rather than start: "none".

Rule: Prefer the submodule's load method over a timeWalk method. Use timeWalk only when task describe shows the submodule has no load method, and tell the user why.

{
  "account_id": "<account_id>",
  "path": "<plugin path>:Gifts",
  "method": "load",
  "plugin_id": "<plugin uuid>",
  "options": { "start": "now", "end": "2020-01-01", "interval": "3M" }
}

Rule: Offer the backdate; do not schedule it without confirmation. A wide pull can be large and hit vendor rate limits.

Rule: Cap the backfill end at 2010-01-01 unless the user explicitly asks to go further. Do not walk to the account's earliest transaction, 1900-01-01, or start: "none" without that explicit request. Frakture load also rejects more than 500 intervals — stay under that limit (for example, 3M from now to 2010 is fine; 3M to 1900 is not).

Rule: When splitting is required to stay under 500 intervals, still respect the 2010 cap unless the user waived it.

Troubleshooting

Related documentation

• MCP tools
• Plugin install and settings
• Declaring plugin settings