¶ In this lesson you will
- Tell a fetch from a push
- Name who builds an endpoint and who uses it
- Know what you configure as a service manager, and what you ask for
¶ Why a service needs integrations
Government services rarely live in one system. An integrated service does two things a simple one cannot. It verifies and auto-fills: the applicant types a national ID or a router serial and the form fills the names from the owner's system. It notifies: when an application is paid or approved, the partner's system receives it straight away, and can answer back.
Two directions, one idea: a named call to a partner
| Fetch (pull) | Push | |
|---|---|---|
| Direction | IremboGov asks a partner for data | IremboGov sends an application to a partner |
| Where you configure it | A form field (Form step) | A workflow action on a transition (Workflow step) |
| When it runs | While the applicant fills the form | When the transition fires (APPLY, PAY, APPROVE...) |
| What you enter | The endpoint code (free text) or an Integration picker | The endpoint, picked from a list of active PUSH endpoints |
| Result | Fields filled, or data in formState.FETCHED_DATA |
Values saved as application details, maybe a callback that moves the workflow |
| Examples | NID lookup, TIN lookup, list of a partner's packages | Register the renewal at CanalBox, send an approved permit to a registry |
¶ Endpoint, adapter, mapping: the words you will hear
An endpoint is one registered connection to a partner, identified by a short code such as NIDAGETIDINFO. It is the only thing you type or pick. The adapter is the kind of connection behind it (a plain forward, a mapped call, a push). The mapping is the recipe that turns IremboGov's data into the partner's request and the partner's answer back into IremboGov's shape. Endpoints, adapters, mappings and mocks are built by the integration manager in the Integration Management Portal.
Integration Management Portal · API Endpoints (integration manager view)
- Code: what you enter in the form or pick in the workflow
- Type: FETCH endpoints serve forms, PUSH endpoints serve workflow actions
- Active: inactive endpoints are not offered in the workflow picker
- Only the integration manager creates or edits endpoints
Who does what
| Who | Does | Where |
|---|---|---|
| Integration manager | Registers the endpoint, its adapter, mapping, authentication and mocks; watches the Requests log | Integration Management Portal (IM guide) |
| Service manager (you) | Adds fetch fields to the form, INTEGRATION actions to the workflow, tests end to end | Service Manager Portal |
| QA reviewer | Tests the service with the integrations on the test environment | Service Manager Portal, portals |
| Partner | Exposes the API, and for async pushes calls IremboGov back | Their own system |
Gotcha · endpoints exist per environment
An endpoint created on UAT does not exist on staging or production. Before you test, check with the integration manager that every code your service uses exists and is active on that environment. The SRD often says "to be confirmed": get the final codes before you configure.
Scope of this course
In this course you use endpoints that already exist: you type or pick their code, send the right form values and read the answer. Building an integration (registering the endpoint, writing the mapping, authentication, mocks, callbacks) is covered in Course 2: Integration Manager Certification. For Assignment 3 the CanalBox endpoints and mocks are ready on staging; lesson C4 lists them.
Tip · ask for the code, not the URL
You never enter a partner URL or credentials in a service. If the SRD gives you a URL, raise a request for an endpoint with the integration manager and use the code they give you.
¶ Check yourself
The SRD says: "when the applicant types the router serial, show the owner's name". What do you configure?
- A. A fetch field in the form with the endpoint code, populating the Names field
- B. An INTEGRATION action on APPLY
- C. A URL_CALL action with the partner URL
- D. A price scenario
Show the answer
A. Data read while the applicant fills the form is a fetch, configured on a form field.
← B10 · Assignment 2: build a medium service · C2 · Fetch on the form →