¶ Your brief
The “Programme” dropdown on the form needs value/label pairs for active programmes only, and a flag for free ones. KEZA returns a big catalogue. Instead of asking the service team to parse it, we reshape the answer in the endpoint. New idea: the response pass and response.transform.
¶ Two passes over one mapping
The engine evaluates the whole mapping twice.
¶ Step · Pass 1 · request
Input = the caller’s payload. Output used: method, path, query, headers, body, auth.
¶ Step · Pass 2 · response
Input = the partner’s answer, plus originalPayload (the request payload) when the answer is an object. Output used: the response key only.
¶ Step · Why it works
Paths that do not exist in a pass are simply empty. So request keys read payload fields and the response block reads partner fields.
¶ How your teacher does it · Endpoints → New Endpoint
| Field | Value | |
|---|---|---|
| **Endpoint adapter *** | FMAPPING (fetch) |
locked after save |
| **Endpoint code *** | VICTOR_KEZA_PROGRAM_OPTIONS_FETCH |
locked after save |
| **Endpoint url *** | http://mock-service-engine.apps:8000/victor/keza/v1/programs |
|
| **Endpoint type *** | FETCH (set by the adapter) |
|
| **Endpoint name *** | Victor KEZA Programme Options |
|
| **Partner *** | KEZA |
locked after save |
| Active | ON |
|
| **Endpoint description *** | Victor course: dropdown options from the KEZA catalogue (response transform). |
**Endpoint Mapping ***
{
"method": "GET",
"auth": {
"type": "TOKEN",
"parameters": { "token": "keza-api-key-victor-2026" },
"tokenConfig": { "headerName": "X-API-Key", "tokenPrefix": "" }
},
"response": {
"transform": {
"options": programs[active = true].{
"value": code,
"label": title & " (" & durationWeeks & " weeks)",
"free": fee.amount = 0
}
}
}
}
- Same TOKEN auth and same mock as Lesson 3.1: only the response changes.
- transform replaces the partner answer with whatever this expression builds.
programs[active = true]filters;.{ … }builds one object per programme.- String building:
title & " (" & durationWeeks & " weeks)". - A comparison gives a boolean.
Secrets · training literal. Hard-coded only because KEZA is a training mock. In a real integration use the environment variable instead: keza-api-key-victor-2026 → "${KEZA_API_KEY}" (the whole quoted string, nothing before or after; see Lesson 3.4).
Response transform in the portal editor
- response.transform: the shape the caller receives.
- A JSONata filter keeps only active programmes.
- A comparison produces a boolean.
- Update saves; the save-time check runs here.
¶ Predict first
KEZA has three programmes: DATA_ANALYTICS (active, free, 12 weeks), WEB_BASICS (active, paid, 8 weeks) and one inactive programme. Before you open the result, write down what options will contain.
¶ Transformed options · fetch/sync · VICTOR_KEZA_PROGRAM_OPTIONS_FETCH
HTTP 200 0.82 s captured on staging · 26 Sep 2026
1 · Request (curl)
curl -s -X POST "https://integration-gateway.staging.iremboinc.com/integration/v1/fetch/sync" \
-H "Authorization: Bearer $TOKEN" \
-H "portal: integration-management-portal" \
-H "Content-Type: application/json" \
-d '{
"endpointCode": "VICTOR_KEZA_PROGRAM_OPTIONS_FETCH",
"callerId": "victor-course",
"requester": "victor-course",
"payload": {}
}' | jq
2 · Real response
{
"status": true,
"responseCode": "integration_870000",
"responseMessage": "integration_870000",
"data": {
"id": "7af87cfe-92d5-482d-946f-d0a99434b9bd",
"endpointCode": "VICTOR_KEZA_PROGRAM_OPTIONS_FETCH",
"callerId": "victor-course",
"response": "{\"options\":[{\"value\":\"DATA_ANALYTICS\",\"label\":\"Data Analytics Foundations (12 weeks)\",\"free\":true},{\"value\":\"WEB_BASICS\",\"label\":\"Web Development Basics (8 weeks)\",\"free\":false}]}",
"adapterCode": "FMAPPING"
},
"timestamp": "2026-09-26T09:48:16.952964896",
"traceId": "6ab778c001ba75012d1ab36881249933"
}
3 · Decoded data.response
{
"options": [
{
"value": "DATA_ANALYTICS",
"label": "Data Analytics Foundations (12 weeks)",
"free": true
},
{
"value": "WEB_BASICS",
"label": "Web Development Basics (8 weeks)",
"free": false
}
]
}
4 · What to notice
- Two options, not three: the inactive programme was filtered out.
- The compact one-line JSON shows the answer was built by the engine, not copied from KEZA.
- The raw catalogue from Lesson 3.1 is not returned any more: transform replaces it.
Gotcha · When originalPayload disappears
If the partner returns a JSON array at the root (not an object), the response pass gets the array alone:
originalPayloadis not available. Refer to array items with$, for example$[active = true].
¶ Check yourself
Which expression in response.transform returns the applicant’s National ID that was sent in the request?
- A. nationalId
- B. originalPayload.nationalId
- C. payload.nationalId
- D. $$.request.payload.nationalId
Show the answer
B. In the response pass the root is the partner answer; the request payload is available as originalPayload.
Your turn · predict, then change
Change your copy of the transform to return only free programmes and add
"weeks": durationWeeks. Predict the output, then call it.
← 3.4 Choose and troubleshoot authentication · 4.2 Reject business failures: eligibility decision →