Session Mapping
A Session ingest creates or updates a session in an event from a JSON payload — usually a webhook from your agenda or scheduling system. Sessions support a lot of optional fields, but you only need a handful to get going. This article starts with the smallest useful mapping, then shows the extras you can add later.
How it works
A field map is a list of rules. Each rule reads a value from your payload (keyMatch) and writes it to a Jomablue session field (type). Point each keyMatch at wherever the value lives in your own payload, using dot notation (e.g. session.startTime).
Sessions are matched by resource_id first, then by organisation_uid. If neither matches an existing session, a new one is created. New sessions must have a name. Anything in the payload that no rule references is ignored.
Start simple
This is a complete, working mapping — an identifier, a name, when and where the session runs, how many people it holds, and whether it's live:
The core fields
resource_id — the session's internal ID, and the primary way sessions are matched. Accepts a plain integer or a formatted string like app_name/session/123 (the trailing number is used).
organisation_uid — your own identifier for the session. Used for matching when there's no resource_id, and stored on the session either way.
name — the session title. Required to create a new session.
description — the session description. HTML is supported.
start_time / finish_time — when the session runs. Accepts MySQL datetime (2026-04-01 09:00:00, treated as UTC) or ISO 8601 (2026-04-01T09:00:00Z, 2026-04-01T19:00:00+10:00). Offsets are converted to UTC.
location_resource_id — the location's internal ID (plain integer or app_name/location/123). The location must already exist. (If your payload carries a location UID or name instead of an ID, see “Locations by UID” below.)
capacity — the maximum number of attendees. A non-negative integer; numeric strings are accepted.
active — whether the session is visible in the community. Accepts true, 1, "yes", "true", "1" (case-insensitive); anything else is false. New sessions default to active if you don't map this.
Worked example
Payload:
Result: session 482 (matched by resource_id, else created) titled "Building on the Platform API", running 1 Apr 2026 from 23:00 to 00:30 UTC (converted from +10:00), in location 17, capacity 120, visible in the community. Send the same resource_id again with new values and the session is updated in place.
Adding more fields
Everything below is optional — add only what you need. The full mapping with every field is in session.json. Each row is a { "type": ..., "keyMatch": ... } rule, same as above.
Scheduling & setup
type | What it sets |
|---|---|
program_uid | Identifier for the program the session belongs to (stored, not used for matching). |
code | Short session code, max 16 characters. |
skill_level | Recommended skill level. |
sort_order | Display order. |
entry_buffer | Minutes before start that check-in opens. |
Access & visibility (booleans accept true/1/"yes" etc.)
type | What it sets |
|---|---|
restricted | Whether the session is restricted. |
restricted_allow_override | Whether the restriction can be overridden (only when restricted). |
visible_in_api | Visible in the Public Agenda API (only when that API is enabled). |
allow_survey | Whether the session allows surveys. |
Categorisation
type | What it sets |
|---|---|
categories | Category IDs — a pipe-separated string (`"1 |
traits | Trait IDs, same format as categories. |
Check-in messaging & feed card
type | What it sets |
|---|---|
email_content_id / sms_content_id | Email / SMS template sent on check-in. |
card_link_label / card_link_type / card_link_url | Feed card link shown on check-in (card_link_type is external or internal). |
card_content | Feed card HTML content. |
card_allow_rating / card_allow_comment | Whether the card allows star / text ratings. |
card_rating_message | The rating prompt message. |
Related content
type | What it sets |
|---|---|
related_content_buffer | Minutes after the session that related content can be requested. |
related_email_content_id / related_sms_content_id | Email / SMS template sent on related-content request. |
related_card_content_id | Card shown on related-content request. |
Community / app display
type | What it sets |
|---|---|
eventapp_promo_text | Promotion text for the session. |
eventapp_promo_logo | Promotional image. |
eventapp_background | Background config — a JSON object of CSS background properties (invalid values are ignored). |
Locations by UID
If your source sends a location UID and name rather than an internal ID, use location_organisation_uid instead of location_resource_id. It creates the location on the fly if it doesn't exist, and needs two paths:
If both location rules are configured, location_resource_id wins.
Validation
You can validate the payload before it's mapped. Each rule targets a payload key and applies one or more checks separated by |; a payload that fails is rejected before anything is created.
- required_without — at least one identifier is needed. resource_id is required only when organisation_uid is absent, and vice versa.
- required — name must be present to create a session.
- nullable — checked only when present: code is capped at 16 characters, and the times must be valid dates.
Match these keys to your own payload paths.