Components

customgenericdatafetch

An input field that triggers a backend API lookup through the Irembo gateway and maps the response into downstream form fields. Also covers customdirectdatafetch for calls to arbitrary URLs.

An input field that fires an API lookup — either through the Irembo gateway (customgenericdatafetch) or directly to any URL (customdirectdatafetch) — and maps the response into other form fields via the populates array.

Read Form Rules before using this component — keys, labels, required fields, expressions, visibility, and validation all follow shared conventions.

Choosing the right variant

ScenarioUse
Lookup goes through the Irembo API gateway using a configured endpointCodecustomgenericdatafetch
Lookup calls a target URL directly with a configurable HTTP method and path/query paramscustomdirectdatafetch
User must click a standalone button to trigger the lookup (no input field)genericbuttonfetch

When NOT to use

Instead of this, use…For…
customidinputNID / Foreigner ID / Child ID / NIN with built-in NIDA verification
customtininputCompany TIN with built-in RDB/RRA verification

customgenericdatafetch

Type string: customgenericdatafetch

Trigger types

triggerTypeWhen the fetch fires
INPUT_LENGTHWhen the typed value reaches genericInputLength characters
TRIGGER_BUTTONWhen the irembogov-button-trigger-wrapper sets props.runAction = true
FIELD_LISTENERWhen another field (identified by payloadKey or payloadKeyMappings[].sourceField) changes value
ON_SUCCESSAfter another customgenericdatafetch emits a success event

Props

PropTypeRequired?Description
labelstringrequiredVisible label. Must be unique across the form.
requiredbooleanrequiredAlways false. The expression controls the runtime value.
defaultRequiredbooleanrequiredtrue for required fields, false for optional ones.
urlstringrequiredGateway endpoint path. Almost always "/integration/v1/fetch/sync".
endpointCodestringrequiredIntegration endpoint code sent in the gateway request payload.
triggerTypestringrequiredOne of "INPUT_LENGTH", "TRIGGER_BUTTON", "FIELD_LISTENER", "ON_SUCCESS".
useBaseUrlbooleanrequiredAlways true — prepends the API gateway base URL.
populatesarrayrequired{ valueKey, targetKey } pairs mapping response paths to form field keys.
payloadKeystringconditionalForm field key whose value is sent as the request payload (single-key mode).
useMultiplePayloadKeysbooleanoptionalWhen true, use payloadKeyMappings instead of payloadKey.
payloadKeyMappingsarrayconditionalArray of { key, sourceField, isStatic } or { key, staticValue, isStatic: true } entries when useMultiplePayloadKeys is true.
genericInputLengthnumberconditionalMinimum character count to trigger the fetch when triggerType is "INPUT_LENGTH".
debounceTimenumberoptionalMilliseconds to wait after the last input change before firing. Defaults to 500.
errorMappingobjectoptionalError handling configuration: { detectionType, useApiMessage, defaultErrorCode, errorMessagePath }.
showGlobalErrorbooleanoptionalWhen true, displays fetch errors in the form's global error area.
hideFromPreviewbooleanoptionalWhen true, excludes this field from the submission preview panel.
populateRelativeToRootFormbooleanoptionalWhen false, populates target keys are resolved within the current repeater scope. Defaults to true (global).
disableFirstFetchOnRFAbooleanoptionalSkips the initial fetch when the form is in Request For Amendment state.
numericOnlybooleanoptionalRestricts input to digits only.
successMessagestringoptionalMessage displayed on successful fetch.
placeholderstringoptionalInput placeholder text.
hideFieldbooleanoptionalHides the field and excludes its value. Toggle via expressions["props.hideField"].

Validation messages

KeyWhen it fires
requiredField is empty on submit
invalidGenericInputFetch failed or returned no result
invalidIdFetch returned an error response
invalidInputInput format did not meet requirements

Examples

Auto-fetch on input length

{
  "key": "EMPLOYER_LOOKUP",
  "type": "customgenericdatafetch",
  "props": {
    "label": "Employer ID",
    "required": false,
    "defaultRequired": true,
    "url": "/integration/v1/fetch/sync",
    "endpointCode": "EMPLOYER_LOOKUP",
    "useBaseUrl": true,
    "triggerType": "INPUT_LENGTH",
    "genericInputLength": 9,
    "payloadKey": "EMPLOYER_ID",
    "populates": [
      { "valueKey": "data.companyName", "targetKey": "COMPANY_NAME" },
      { "valueKey": "data.address", "targetKey": "ADDRESS" }
    ]
  },
  "expressions": {
    "props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
  },
  "validation": {
    "messages": {
      "required": "Employer ID is required",
      "invalidGenericInput": "Employer not found"
    }
  }
}

Fetch triggered by another field (FIELD_LISTENER)

{
  "key": "OWNER_DETAILS_FETCH",
  "type": "customgenericdatafetch",
  "props": {
    "label": "Owner Details",
    "required": false,
    "defaultRequired": false,
    "url": "/integration/v1/fetch/sync",
    "endpointCode": "FETCH_OWNER_DETAILS",
    "useBaseUrl": true,
    "triggerType": "FIELD_LISTENER",
    "debounceTime": 500,
    "useMultiplePayloadKeys": true,
    "payloadKeyMappings": [
      { "key": "documentNumber", "sourceField": "DOCUMENT_NUMBER", "isStatic": false }
    ],
    "populates": [
      { "valueKey": "data.ownerName", "targetKey": "OWNER_NAME" },
      { "valueKey": "data.ownerAddress", "targetKey": "OWNER_ADDRESS" }
    ],
    "hideField": true,
    "hideFromPreview": true,
    "showGlobalError": true
  },
  "expressions": {
    "props.hideField": "!model?.DOCUMENT_NUMBER",
    "props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
  },
  "validation": {
    "messages": {
      "invalidGenericInput": "Owner details could not be retrieved"
    }
  }
}

Common mistakes

  • Omitting endpointCode — the component throws at runtime.
  • Setting useMultiplePayloadKeys: true without payloadKeyMappings — the fetch fires with an empty payload.
  • Using payloadKey when useMultiplePayloadKeys: true — only payloadKeyMappings is read in multi-key mode.
  • FIELD_LISTENER pointing to a non-existent field — the listener finds no control to watch; the fetch never fires.
  • TRIGGER_BUTTON without props.runAction: false and props.runningAction: false — the fetch may fire unexpectedly on load.
  • Wrong populates.valueKey path — the gateway wraps the payload; use "data.fieldName" unless the endpoint returns the value at root.

customdirectdatafetch

Type string: customdirectdatafetch

All props from customgenericdatafetch apply. Use this when the fetch must call a URL directly instead of the Irembo API gateway.

Additional props

PropTypeRequired?Description
httpMethodstringrequired (for direct mode)HTTP verb: "GET", "POST", "PUT", "PATCH", "DELETE". Activates direct mode; bypasses the gateway.
pathParamsarrayoptionalReplaces path variables in url. Each entry: { "key": "varName", "value": "staticValue" } or { "key": "varName", "sourceField": "formFieldKey" }. Matches :varName or {varName} in the URL.
queryParamsarrayoptionalAppends query string parameters. Same shape as pathParams.
bodyMappingsarrayoptionalBuilds the POST/PUT/PATCH request body from static values or form fields.

Example

{
  "key": "VEHICLE_INFO",
  "type": "customdirectdatafetch",
  "props": {
    "label": "Vehicle Registration Number",
    "required": false,
    "defaultRequired": true,
    "url": "/registry/v1/vehicles/{plateNumber}",
    "httpMethod": "GET",
    "useBaseUrl": true,
    "triggerType": "INPUT_LENGTH",
    "genericInputLength": 7,
    "pathParams": [{ "key": "plateNumber", "sourceField": "VEHICLE_INFO" }],
    "populates": [
      { "valueKey": "make", "targetKey": "VEHICLE_MAKE" },
      { "valueKey": "model", "targetKey": "VEHICLE_MODEL" }
    ]
  },
  "expressions": {
    "props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
  },
  "validation": {
    "messages": {
      "required": "Vehicle registration number is required",
      "invalidGenericInput": "Vehicle registration not found"
    }
  }
}

Additional common mistakes

  • Omitting httpMethod — the component falls back to gateway mode and requires endpointCode; without either it throws.
  • Forgetting path variable placeholders in url — use :key or {key} in the URL; plain URLs receive no substitution.
  • pathParams[].sourceField pointing to a key that returns null — the resolved URL contains the string "null", causing a 404.

Checklist

  • key is UPPER_SNAKE_CASE and unique across the entire form
  • props.label is present, unique, and correctly cased
  • Field is nested at the correct depth: sections > formly-group > block > customgenericdatafetch
  • required: false (never true)
  • defaultRequired is set
  • expressions["props.required"] is present
  • url is set and useBaseUrl: true
  • endpointCode is set (gateway mode) or httpMethod is set (direct mode)
  • triggerType is one of the four valid values
  • populates entries use correct valueKey paths from the endpoint response
  • validation.messages includes at minimum invalidGenericInput

customcascadingdropdowns

A multi-level cascading dropdown for hierarchical selection. Each level filters the options available in the next level based on the parent selection.

genericbuttonfetch

A standalone button that calls the Irembo integration engine on click and populates downstream form fields from the response. No input field — the button is the entire widget.

On this page

Choosing the right variantWhen NOT to usecustomgenericdatafetchTrigger typesPropsValidation messagesExamplesAuto-fetch on input lengthFetch triggered by another field (FIELD_LISTENER)Common mistakescustomdirectdatafetchAdditional propsExampleAdditional common mistakesChecklist