Skip to content

docs(custom-events): seeds, field types, payload mode and event state (PDI-2712) - #193

Merged
karlrank merged 2 commits into
mainfrom
claude/pdi-2712-custom-event-preview-docs
Nov 20, 2026
Merged

karlrank merged 2 commits into
mainfrom
claude/pdi-2712-custom-event-preview-docs

Conversation

@karlrank

Copy link
Copy Markdown
Member

Summary

Docs part of PDI-2712. Badenova followed the custom events docs and still needed a call to find out why their preview failed and why it returned the whole contact. This updates docs/integrations/custom-events.md only:

  • A custom event and its seed belong to one organization. An ID copied from another organization or sandbox is not found (preview and trigger).
  • Field types must match the stored values (new subsection): a customer number stored as a number fails a string field and the event is rejected; convert with $string(...) or declare the stored type. Empty optional fields are left out; required ones fail.
  • Entity data or mapped fields only (new subsection): documents mapping.payload for the first time. extend (default, "Add to the entity data") carries the complete entities with every attribute; replace ("Only the mapped fields") sends only the mapped fields. A neutral :::info Good to know note says that this can include personal data, that it suits most integrations, and when to use replace.
  • Status, enabled and auto_trigger (new subsection under Lifecycle): what each answers, and why responses from the draft phase show draft / false / false; read the live state with GET /v1/events/{event_name}.
  • Preview responses: warnings on 200, and a table of 400s (Seed entity not found in this organization, Seed entity has the wrong schema, schema validation, projection) with the issues body. Trigger and validation sections point to the same issues shape.
  • Small accuracy fix: a field may reuse a node ID with replace.

Merge after

The preview warnings, the seed errors and the issues body ship with https://gitlab.com/e-pilot/product/events-automation/event-catalog-api/-/merge_requests/86. The builder behaviour mentioned in step 4 (search by ID, type and empty-field hints) ships with https://gitlab.com/e-pilot/product/360-portal/epilot360-event-catalog/-/merge_requests/37. Merge this once both are on prod.

Test plan

  • Docusaurus build in CI (onBrokenLinks: throw); the new anchors are same-page

Generated by Claude Code

Custom event authors could not work out from the docs why their preview
failed or what their event sent (PDI-2712):

- A custom event and its seed belong to one organization; an ID from
  another organization or sandbox is not found.
- Field types must match the stored values; how to convert, and how
  empty optional fields are left out.
- `mapping.payload`: `extend` carries the complete entities (including
  personal data), `replace` only the mapped fields, with a "good to
  know" note on when to use which.
- What `event_status`, `enabled` and `auto_trigger` mean, and why a
  draft-phase response shows draft/false/false.
- Preview `warnings` and the `issues` on every 400.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Q8ogdv74mD5Ggwi1RN2Rf
@karlrank
karlrank marked this pull request as ready for review November 20, 2026 11:15
@karlrank
karlrank merged commit d794fb7 into main Nov 20, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants