---
title: Session Mapping
slug: docs/session-mapping
createdAt: 2026-07-07T06:32:56.345Z
---

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:

:::BlockQuote
\[
&#x20; \{ "type": "resource\_id", "keyMatch": "resource\_id" },
&#x20; \{ "type": "organisation\_uid", "keyMatch": "organisation\_uid" },
&#x20; \{ "type": "name", "keyMatch": "name" },
&#x20; \{ "type": "description", "keyMatch": "description" },
&#x20; \{ "type": "start\_time", "keyMatch": "start\_time" },
&#x20; \{ "type": "finish\_time", "keyMatch": "finish\_time" },
&#x20; \{ "type": "location\_resource\_id", "keyMatch": "location\_resource\_id" },
&#x20; \{ "type": "capacity", "keyMatch": "capacity" },
&#x20; \{ "type": "active", "keyMatch": "active" }
]
:::

### 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:**

:::BlockQuote
\{
&#x20; "resource\_id": "agenda/session/482",
&#x20; "organisation\_uid": "SESSION-482",
&#x20; "name": "Building on the Platform API",
&#x20; "description": "\<p>A hands-on walkthrough for developers.\</p>",
&#x20; "start\_time": "2026-04-01T09:00:00+10:00",
&#x20; "finish\_time": "2026-04-01T10:30:00+10:00",
&#x20; "location\_resource\_id": 17,
&#x20; "capacity": 120,
&#x20; "active": true
}
:::

**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:

:::BlockQuote
\{
&#x20; "type": "location\_organisation\_uid",
&#x20; "keyMatch": "location.externalId",
&#x20; "locationNameKeyMatch": "location.name"
}
:::

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.

:::BlockQuote
\{
&#x20; "resource\_id": "required\_without\:organisation\_uid",
&#x20; "organisation\_uid": "required\_without\:resource\_id|string",
&#x20; "name": "required|string",
&#x20; "code": "nullable|string|max:16",
&#x20; "start\_time": "nullable|date",
&#x20; "finish\_time": "nullable|date"
}
:::

- **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.

