EventPerson Mapping - Advanced
This article covers the advanced EventPerson field-map options that go beyond the starter mapping: making category roles mutually exclusive, migrating identifiers, and the fields the basic article only mentions in passing (items, program membership, and cancellation).
New to EventPerson ingests? Start with the basic mapping and the mapping overview. This article assumes you already know how a field map reads keyMatch from your payload and writes to a type.
How it works
An EventPerson ingest creates or updates a person within a single event. A field map is a list of rules; each rule reads a value from your payload (keyMatch) and writes it to a Jomablue field (type). keyMatch is a path, so a value can sit anywhere in the payload, including inside nested objects (contact.details.email). A person is identified by organisation_uid: a match updates the existing person, otherwise a new one is created. Anything the mapping does not reference is ignored, so an over-complete mapping never causes harm.
The mapping
The complete mapping combines every technique in this article. Each section below explains one part of it.
Matching on more than one unique identifier
The organisation_uid rule can list several payload paths separated by |, oldest first:
The endpoint reads whichever of those paths are present in the payload. This is useful when you change the identifier your system sends: a person first created under legacy_id is still matched when you start sending contact_id, so they are updated in place rather than duplicated. The right-most path is treated as the current identifier.
Assigning categories
Categories group People by role or type (Delegate, Sponsor, Speaker, and so on). There are two ways to assign them, and a mapping should use one style only.
By value. Use value rules when your payload carries a role as text (for example "category": "Speaker"). Each rule fires when the payload value equals its valueMatch, and assigns the matching mapToId:
If the path in keyMatch holds an array rather than a single string, the rule fires when valueMatch is one of the array's values. That lets a payload send several roles at once (for example "roles": ["Speaker", "VIP"]) and have each matching rule assign its category.
By ID. Use the wildcard form when your payload already carries Jomablue category IDs as an array:
This reads the array at categories and assigns each entry as a category ID. Only integer IDs are accepted; anything else in the array is ignored. Category IDs are specific to each instance, not each event: a given ID identifies the same category across every event in your instance.
The numbers used here are placeholders. Look up the real category IDs from your instance, and set valueMatch to the strings your system actually sends.
If an ingest assigns no category, the event's default category is applied.
Replacing categories (mutually exclusive roles)
By default categories are additive: assigning one leaves any the person already has. To make roles mutually exclusive, so a person ends up in exactly one, add replaceExistingIds to each value rule listing the other IDs in the set:
When a rule assigns its category, the IDs in its replaceExistingIds are removed from the person. A rule never lists its own mapToId. Any category the person holds that is not in the list is left untouched.
With the set above, sending "category": "Speaker" assigns category 3 and removes 1, 2, 4, and 5. Send "category": "Sponsor" next time and the person moves from Speaker to Sponsor. This is the technique to reach for when each person maps to a single role and re-sends should overwrite the previous one.
Assigning a single item
The item type assigns a fixed item (a gala dinner ticket, a workshop place, a piece of merchandise) when a payload value is present:
The item with mapToId is assigned when the value at keyMatch is present and truthy. Add valueMatch to require a specific value:
Here the item is assigned only when ticket_type equals gala. Unlike categories, assigning an item does not remove other items, and mapToId is required.
Program and campaign membership
The program_member type links a person to a membership in one of your programs or campaigns. It reads a nested object (or an array of them) and needs the program's UID and the membership's UID at minimum:
- keyMatch points at the membership object. Use a wildcard (memberships.*) when the payload carries an array of memberships; the remaining paths are then read from each element.
- programUidKeyMatch and programMemberUidKeyMatch are required. A membership is only created when both resolve to a value.
- programNameKeyMatch, programMemberStatusKeyMatch, and programMemberArchivedKeyMatch are optional.
For a single membership, point keyMatch at the object ("keyMatch": "membership") and drop the wildcard.
Cancellation status
The cancelled type sets a person's registration status from a value in your payload:
When the value at keyMatch equals valueMatch, the person is marked cancelled. Any other non-empty value marks them registered. If the field is absent, the status is left unchanged. valueMatch is required, and defines which incoming value means cancelled.
Custom fields: named and wildcard
The wildcard form maps every key inside an object to a custom field, reusing the payload's own keys:
To map a single, specifically named field, use a fixed keyMatch and mapToKey:
You can combine both: a wildcard rule for the bulk of the object plus named rules for values that live elsewhere in the payload. Custom field keys should be snake_case.
Mobile numbers and country
Mobile numbers are stored in international E164 format (for example +61402222111). The mobileCountry option controls how local formats are handled:
- With mobileCountry: the number is parsed using that country's rules and converted to E164, so local formats are accepted. 0402 222 111 with country AU becomes +61402222111. mobileCountry points at the payload path holding the country. Accepted values are ISO 3166 alpha-2 (AU) or alpha-3 (AUS) codes, or country names.
- Without mobileCountry: the number must already be in E164 format (starting with +). Anything else is discarded.
If you only ever receive local numbers from one country, point mobileCountry at any payload field that reliably carries that country code.
Worked example
Payload:
Resulting person:
Field | Value |
|---|---|
organisation_uid | CRM-10432 (read from contact_id; matched if it exists, else created) |
name | Jordan Avery |
job_title / company | Head of Partnerships, Northwind Labs |
mobile | +61402222111 (converted from local AU format) |
status | registered (not cancelled, so active) |
category | Speaker (ID 3); IDs 1, 2, 4, 5 removed if present |
item | gala dinner ticket (ID 12) |
program membership | Ambassadors (PROG-2026), member M-88 |
custom fields | dietary_requirements = Vegetarian, tshirt_size = L |
Send the same identifier again with different values and the person is updated in place. Send "category": "Sponsor" next time and the person moves from Speaker to Sponsor.
Validation
Before a payload is mapped, it can be checked against validation rules. Each rule targets a payload key (dot notation, including wildcards for arrays) and applies one or more checks separated by |. A payload that fails is rejected before any person is created or updated.
- required rejects a payload where the field is missing or empty (the identifier and the names needed to create a person).
- nullable is only checked when present.
- in:... limits a value to a fixed list, catching typos before they map to nothing.
- required_with:... requires a field only when a related field is present, so the membership identifiers are only enforced when memberships is sent.
Match these keys to your own payload paths, and update the lists to your own values.