FluentCRM: register a rest_selector option list

For developers building a custom FluentCRM trigger, action, or benchmark that needs a multi-select / single-select field whose options come from your plugin (target courses, target products, target post types, target whatever). The settings-field side declares 'type' => 'rest_selector', 'option_key' => 'my_things'; the server side registers add_filter('fluentcrm_ajax_options_my_things', $callback, 10, 3). This is a small focused contract — under 100 lines of code per integration — but it has one subtle "include pre-selected IDs" trap.

API stability note

The fluentcrm_ajax_options_* filter family has been in place since FluentCRM 2.5.9. The 3-argument signature ($options, $search, $includedIds) and the [{id, title}, ...] return shape have not changed.

In FluentCRM 3.1.8, OptionsController::index() guards the comma-separated fields dispatcher with reflection: only public, non-static, zero-required-argument methods declared on OptionsController itself are invoked. Custom dynamic pickers still go through getAjaxOptions() and the fluentcrm_ajax_options_{option_key} fallback filter.

Misconception this skill corrects

"I'll filter the options by $search only — the picker handles the rest."

Wrong — the picker does NOT separately fetch labels for already-saved IDs. When the admin opens an existing trigger / action whose course_ids is [42, 99], the editor calls the same getAjaxOptions REST endpoint with $includedIds = [42, 99] and an empty $search. If your filter callback only honours $search, IDs 42 and 99 get a search query of '' against your filter — which most callbacks treat as "return everything matching empty string" (so the labels are present), but if you've added a posts_per_page cap the saved IDs may not appear in the result, and the editor renders the field as bare numbers.

The correct pattern: when $includedIds is non-empty, bypass $search and load those specific IDs unconditionally, then merge with the search-driven results. The canonical approach is to use post__in for CPT lookups so already-saved values always come back regardless of search range: