¶ In this lesson you will
- Add an INTEGRATION action, sync or async
- Wire the PUSH transition an async push needs
- Save response values with INTEGRATION_UPDATE
- Know what happens when a push fails
- Pay — IremboPay fires PAY (applicant)
- Breaking INTEGRATION — async: true, endpoint picked in the builder (engine → partner)
- PAID — state saved, application waits (engine)
- Callback — partner (or IM) posts to /v1/integration-notification (partner)
- PUSH — the callback fires PUSH (or the event it names) (engine)
- APPROVED — Subscription Renewed (applicant notified)
↻ No transition on PUSH from PAID = the callback has nowhere to go and the application stays in PAID.
¶ The INTEGRATION action
Add it on the transition where the data is ready: usually PAY (paid applications) or APPROVE (after the officer). Its args are just endpointCode and async. In the Workflow Builder the Endpoint field is a search over active PUSH endpoints, each shown as "name · adapter"; picking one saves its code. The new builder sets async to true by default; the legacy editor defaulted to false. Check it.
The engine sends the whole application payload: application fields and the payment transaction, every form value as a detail key (nested values become dotted keys such as address.street), certificate names, feedbacks, and the results of the transition's event configs. The integration manager's mapping picks what the partner needs.
¶ Push recipes
Sync (async: false)
{
"startState": "PAYMENT_PENDING",
"event": "PAY",
"endStateOne": {
"stateCode": "APPROVED",
"stateName": "Subscription Renewed",
"breakingAction": {
"actionType": "INTEGRATION",
"args": { "endpointCode": "COURSE_CANALBOX_RENEWAL_PUSH", "async": false }
},
"nonBreakingActions": [ { "actionType": "NOTIFICATION", "args": { "...": "..." } } ]
}
}
- Breaking: if CanalBox says no, the PAY event fails and is retried; the application stays in PAYMENT_PENDING
- Sync: the answer's
applicationDetailsare saved, then the application moves to APPROVED
What CanalBox gets back
Request the engine builds from the application (mapping by the integration manager):
{
"routerNumber": "CBXK0001", <- routerNumber (or phoneRouter)
"transactionNumber": "C2610...", <- applicationNumber
"prepaidPeriod": 3, <- subscriptionDuration
"amount": 60000, <- totalPrice
"renewType": "SAME_OFFER" <- renewPreviousPackage (YES / NO)
}
Saved on the application (applicationDetails):
{
"canalBoxTransactionId": "CBX-TX-89376539",
"subscriptionEndDate": "2027-01-01"
}
- The mapping reads these exact keys: name your form fields the same way
Async + PUSH transition
[
{
"startState": "PAYMENT_PENDING",
"event": "PAY",
"endStateOne": {
"stateCode": "PAID",
"stateName": "Paid",
"breakingAction": {
"actionType": "INTEGRATION",
"args": { "endpointCode": "PARTNER_RENEWAL_PUSH", "async": true }
}
}
},
{
"startState": "PAID",
"event": "PUSH",
"endStateOne": { "stateCode": "APPROVED", "stateName": "Subscription Renewed" }
}
]
- The engine adds a callback URL to the request
- The callback fires PUSH: this transition is mandatory
The callback
POST <application engine>/v1/integration-notification
{
"callerId": "<from the push>",
"applicationNumber": "C2609...",
"endpointCode": "PARTNER_RENEWAL_PUSH",
"status": "SUCCESS",
"applicationDetails": { "subscriptionExpiry": "2026-12-31" },
"event": null
}
eventempty means PUSH; it can name another event- status and errorCode are not checked: an error callback still moves the workflow
- Any
applicationDetailsare saved on the application
INTEGRATION_UPDATE
{
"actionType": "INTEGRATION_UPDATE",
"args": {
"endpointCode": "PARTNER_STATUS_CHECK",
"parametersToRetain": {
"expiryDate": "subscriptionExpiry",
"package.name": "packageName"
}
}
}
- Response values to save: each key is a JSONata expression over the response message, each value the application-detail key to write. Always a sync call. A key that fails is only logged
What a failed push does
| How it is placed | If the partner fails | Where you see it |
|---|---|---|
| Breaking, sync | The transition fails: the application stays in its start state and the user sees an error (INTEGRATION_ACTION_ERROR or the partner's code) |
Kibana: "=> Breaking action:", then the request's traceId |
| Breaking on a system event (PAY) | The event fails and is retried by the engine, then recorded by PROCESSING_FAILURE_TRACKER | Kibana: PROCESSING_FAILURE_TRACKER + application number |
| Breaking, async | The request fails at once like sync; if it is accepted, the application waits for the callback | Integration Management Portal · Requests (callback status) |
| Non-breaking | The transition is already saved; the push runs from a queue. Do not count on a retry: treat a failed non-breaking push as lost and check it | Kibana: "Non-breaking action to be added in the queue" |
¶ Certificates that come from the partner
Two ways. Through the integration answer: if the response or the callback carries pairs of CERTIFICATE_FILE-fileName-1 and CERTIFICATE_FILE-file-1 (a data URI such as data:application/pdf;base64,...) in its application details, the engine stores the file as the certificate. No extra action; every file needs both keys. With REGISTER_EXTERNAL_CERTIFICATE: a breaking action on an APPROVE_WITH_FORM transition, where the partner's officer uploads the file in the third-party form. Its args name the certificate, the attachment key and the expiration. Errors: EXTERNAL_CERTIFICATE_FILE_NOT_FOUND, EXTERNAL_CERTIFICATE_NAME_REQUIRED.
¶ The Endpoint mapping panel
For mapped (PMAPPING) endpoints, the action panel shows the endpoint's mapping read-only, with Evaluate mapping to run it on a sample payload. It warns when the mapping reads a value your form does not provide: rename your field or ask the integration manager to change the mapping ("Update it in Integration Management").
Assignment 3 uses a sync push
The production CanalBox integration is async: CanalBox calls IremboGov back and the callback moves the application from PAID to APPROVED. A training mock cannot call back, so on staging the course uses
COURSE_CANALBOX_RENEWAL_PUSHwith async: false on PAY → APPROVED. Learn the async recipe here; you will build callbacks in Course 2 (Integration Manager Certification).
Gotcha · three push traps
- Async without a PUSH transition: the application waits forever. The builder warns and can add the transition; keep it.
- Journey mapping is not integration: the Journey Services Mapping screen chains services together. Endpoints live in the Integration engine.
- URL_CALL is not an integration: it calls nothing. Use INTEGRATION (lesson B7).
Kibana: follow a push (application engine logs)
| When | KQL (paste in Discover) | What you get |
|---|---|---|
| The push left | message:"Async Integration Request:" and message:"<APP_NO>" |
The request and its callback URL |
| A sync call | message:"Sync Integration Request:" and message:"<APP_NO>" |
The request; copy its traceId, then search traceId:"6abd1baceb7eeb2030e42443c2391c10" and message:"Sync Integration Response:" (with your own traceId) for the answer |
| A breaking failure | message:"=> Breaking action:" and message:"<APP_NO>" |
Which action failed, and why |
| A stuck system event | message:"PROCESSING_FAILURE_TRACKER" and message:"<APP_NO>" |
Failed PAY with an INTEGRATION action |
| INTEGRATION_UPDATE | message:"INTEGRATION_UPDATE_ACTION" |
Including JSONata keys that failed to evaluate |
Integration Management Portal · Requests: the integration manager's view of every call
- Search by endpoint code or application number
- Request status and Callback status filters
- The application number links the call to your application
- Response details: the partner's answer
Tip · debug a push together
You own the workflow; the integration manager owns the endpoint. When a push fails, send them the application number and the Kibana line. They open the call in Requests, see the exact request and answer, and can resubmit it once the cause is fixed.
¶ Check yourself: match the pairs
Show the matches
| Item | Matches |
|---|---|
| INTEGRATION, async: true | Needs a PUSH transition from the waiting state |
| INTEGRATION, async: false | Waits for the answer and saves its applicationDetails |
| INTEGRATION_UPDATE | Keeps chosen response values under your detail keys |
| REGISTER_EXTERNAL_CERTIFICATE | Stores a certificate uploaded on APPROVE_WITH_FORM |
← C2 · Fetch on the form · C3b · Reading an async workflow →