An Irembo service rarely works alone. To process a KEZA training application, the form must read data that lives at KEZA (is this person eligible?) and later send the approved application to KEZA (enroll this person). The Integration Management Engine (IME) is the single broker for all of this. You do not write code per partner: you configure an endpoint in the portal, and the engine does the calling, authenticating, logging and error handling.
Irembo service (form + workflow (the caller)) → Integration engine (finds the endpoint by endpointCode, runs its mapping, authenticates) → Partner API (e.g. KEZA) or Mock (a fake KEZA you build in the portal)
fetch = read data from the partner. Used on a form (prefill or validate a field), so the endpoint uses the FMAPPING adapter.
push = send application data to the partner. Used in a workflow step (after submission or approval), so the endpoint uses the PMAPPING adapter.
sync = the caller waits for the answer. (async = queued, answered later by callback.)
Every call is saved as a Request you can inspect in the portal.
| Card | Answer |
|---|---|
| Fetch When do I use it? |
When the form must read partner data: prefill fields, check eligibility, validate a number. An endpoint used on a form always uses the FMAPPING (fetch) adapter. Called on /integration/v1/fetch/sync. |
| Push When do I use it? |
When a workflow step must send data: an approved enrollment, a document, a payment notice. An endpoint used in a workflow always uses the PMAPPING (push) adapter. Called on /integration/v1/push/sync and needs an applicationNumber. |
| Endpoint What is it? |
One configured partner operation: a unique code, the partner URL, an adapter (FMAPPING if a form uses it, PMAPPING if a workflow uses it) and a JSONata mapping that says how to build the request (and optionally how to read the response). |
| Mapping What does it do? |
A JSONata expression, evaluated against the caller’s payload, that returns the HTTP recipe: method, path, query, headers, body and auth. A response section can transform or validate what the partner sends back. |
Your tech notes · Two adapters, one rule
This course uses only the two adapters Service Builders need: FMAPPING and PMAPPING. Choose by where the endpoint is used: on a form → FMAPPING, in a workflow → PMAPPING. The direction (fetch = read, push = send) is what you then write in the mapping and the URL you call (
/fetch/syncor/push/sync). The adapter is locked after saving, so decide before you create the endpoint.
Follow a single fetch call from the Irembo service to KEZA and back.
POST to /fetch/sync with endpointCode, callerId, requester and payload (the form data). Push also needs applicationNumber.
It looks up the endpoint by code. Unknown code → 404 ENDPOINT_NOT_FOUND_EXCEPTION. A Request row is created with status CREATED.
The mapping runs against the payload and produces method, path, query, headers, body and auth.
If the mapping has an auth block, the engine gets or reuses a token and adds the header.
The engine calls the endpoint URL (the real partner or your mock).
The same mapping runs again with the partner’s answer as input: optional transform, validation and cache.
Success → status SUCCESS and a success envelope. Failure → FAILURE and an error envelope. Either way the full trace is visible under Requests. One exception: a sync push rejected by the mapping itself stays CREATED (Lesson 6.1).
Request envelope
{
"endpointCode": "VICTOR_KEZA_ELIGIBILITY_FETCH",
"callerId": "victor-course",
"requester": "victor-course",
"payload": {
"nationalId": "1199880012345678",
"programCode": "DATA_ANALYTICS"
}
}
Success envelope
{
"status": true,
"responseCode": "integration_870000",
"responseMessage": "integration_870000",
"data": {
"id": "2e438be6-0c78-478f-871f-abd9e735d2d7",
"endpointCode": "VICTOR_KEZA_ELIGIBILITY_FETCH",
"callerId": "victor-course",
"response": "{\n \"found\": true,\n \"learner\": {\n \"nationalId\": \"1199880012345678\",\n \"firstName\": \"Aline\",\n \"lastName\": \"Mukamana\",\n \"district\": \"Gasabo\"\n },\n \"eligibility\": {\n \"status\": \"ELIGIBLE\",\n \"programCode\": \"DATA_ANALYTICS\",\n \"reasonCode\": null,\n \"evaluatedAt\": \"2026-09-26T08:00:00Z\"\n }\n}",
"adapterCode": "FMAPPING"
},
"timestamp": "2026-09-26T09:59:40.977889843",
"traceId": "6ab77b6c9f1234521f86de28934960bd"
}
integration_870000 = fetch success. (Push success is PUSH_SYNC.)Error envelope
{
"httpStatus": 404,
"exception": "NotFoundException",
"responseCode": "ENDPOINT_NOT_FOUND_EXCEPTION",
"responseMessage": "ENDPOINT_NOT_FOUND_EXCEPTION",
"fieldErrors": []
}
Gotcha · data.response is a string
The partner’s JSON comes back inside a string (
"response": "{\n \"found\": true ..."). Callers must parse it a second time. With jq:jq '.data.response | fromjson'. Push answers do the same indata.message.
A KEZA training form must show the applicant’s eligibility before they can submit. What do you configure?
C. Reading partner data while the form is filled is a fetch, and anything used on a form is FMAPPING. PMAPPING belongs to workflow steps; a mock only stands in for the partner while you build.
| Item | Matches |
|---|---|
| endpointCode | Selects which endpoint runs |
| payload | The form data the mapping reads |
| data.response | The partner answer, as a string |
| applicationNumber | Required on every push call |
Your turn · classify three needs
For each need, write FMAPPING or PMAPPING and one line of why: (1) show a learner’s KEZA profile while the applicant fills the form; (2) send the approved enrollment to KEZA when the officer approves; (3) check a national ID before the applicant can submit.
Done when: your evidence pack has three answers. Check: form → FMAPPING (1 and 3), workflow step → PMAPPING (2).
← Welcome: become a certified Integration Manager · 1.2 Tour of the Integration Management Portal →