Jfb Action External Api

---
name: jfb-action-external-api
description: How to read submitted JetFormBuilder form data from a custom
  action, transform it (including %macro% replacement of admin-typed
  templates), call an external HTTP API, write the response back into
  the form context for downstream actions to use, and dispatch JFB
  events based on the API outcome. Use when building a custom action
  that integrates with a third-party service (LLM call, webhook, CRM,
  payment processor, geolocation lookup) and needs the action to
  behave as a node in a data-flow graph rather than a one-shot leaf.
  Triggers on mentions of "jet_fb_context", "update_request", "has_field",
  "get_value", "wp_remote_post" with form data, "macro replacement", or
  "API call from action".
author: Soczó Kristóf
contact: mailto:lonsdale201@hotmail.com
plugin: jetformbuilder
plugin-version-tested: "3.5.6"
api-stable-since: "3.0"
php-min: "7.4"
last-updated: "2026-04-28"
docs:
  - https://github.com/Crocoblock/developer-documentation/tree/main/03-jet-form-builder
  - https://developer.wordpress.org/reference/functions/wp_remote_post/
source-refs:
  - includes/context/context.php
---

# JetFormBuilder: action — read form data, call external API, write result back

Most custom JFB actions follow the same data-flow shape: pull values out of the submitted form, optionally interpolate admin-typed templates with `%field%` macros, hit an external HTTP API, transform the response, write it back into the form context so downstream actions can read it, and (optionally) dispatch a custom JFB event based on the outcome to fan out to conditional follow-up actions.

This skill covers that full lifecycle inside `do_action()`. It complements **`jfb-form-action`** (which covers the action class structure) and **`jfb-action-events`** (which covers event dispatch). This one is specifically about the **PHP-side data flow** — the API surface JFB exposes for read/write/macro/dispatch from inside an action.

## API stability note

The `jet_fb_context()` global (with `get_value`, `update_request`, `has_field`, `resolve_request`), `Tools::sanitize_text_field()`, and the `Tab_Handler_Manager::instance()->options( $tab_id )` accessor have been stable across JFB 3.x in source observed. The WordPress HTTP API (`wp_remote_post`, `wp_remote_retrieve_body`, `WP_Error` handling) is WP core. The `plugin-version-tested` value records last end-to-end verification.

## When to use this skill

- A custom action calls a third-party HTTP API as part of its work.
- An action needs to read multiple form fields and interpolate them into a request body or instructions string.
- The admin should be able to write templates like `"Verify %email% for order %order_id%"` and have JFB substitute the field values.
- The API response should be written back into the form context so other actions can use it (for example, a "ChatGPT Decision" action writing the answer into a hidden form field that a "Send Email" action then includes).
- The action should branch the action chain based on the API response (success/failure/decision).
- The diff/files contain `jet_fb_context()`, `update_request`, `wp_remote_post`, `wp_remote_retrieve_body`, `WP_Error`, or macro substitution patterns like `%[a-z_]+%`.

## Architecture in one paragraph

JFB exposes the live form submission as a singleton via `jet_fb_context()`. From inside `do_action( array $request, Action_Handler $handler )`, the `$request` parameter is an associative array of field IDs to current values, but the **same data is also available** through `jet_fb_context()->get_value( $field_id )` — and the context is the source of truth: subsequent actions read from it. To **write** a value back (so downstream actions see it), call `jet_fb_context()->update_request( $value, $field_id )`. Admin-typed templates with `%field%` placeholders are interpolated by a small replacer that calls `jet_fb_context()->has_field()` and `get_value()`. External API calls go through WordPress's HTTP API (`wp_remote_post` etc.) with proper timeout, header, and error handling — never `file_get_contents` or `curl_*` directly. API credentials come from the plugin's settings tab via `Tab_Handler_Manager::instance()->options( $tab_id )`. Outcome branching is done by dispatching a custom event through `jet_fb_events()->execute( EventClass::class, $form_id )` — this fans out the chain without the action knowing which followups exist.

## Step 1 — read the form data

There are two correct ways to read a field's submitted value, with different semantics:

```php
public function do_action( array $request, Action_Handler $handler ) {
    $email = $request['email_field_id'] ?? '';                 // direct from request
    $email = jet_fb_context()->get_value( 'email_field_id' );  // through context
}
```

**Use `$request[...]`** when reading values that won't be changed by previous actions in the chain (most common case — submitted-as-is data).

**Use `jet_fb_context()->get_value( $field_id )`** when:
- A previous action might have called `update_request()` to mutate a value (e.g. a translation action overwriting a field with a translated copy).
- You want to write back later — for symmetry, read through the same API.
- You want to fall through `has_field()` cleanly when the field doesn't exist on the form.

`get_value()` returns the current context value (post any updates). `$request` is the snapshot passed to your `do_action`. They diverge only when intermediate actions mutate; if you control the chain, both work. If in doubt, **prefer the context API** — it's the source of truth.

## Step 2 — sanitize and validate

Form data has been validated by JFB's field rules but **NOT sanitized for your specific output target**. Your action is responsible for sanitization that fits how the data leaves your code.

```php
$email = sanitize_email( (string) $email );
if ( ! is_email( $email ) ) {
    throw new Action_Exception(
        __( 'Provided email is not valid.', 'myplugin' )
    );
}

// For text passed to an external API (no HTML expected):
$instructions = sanitize_textarea_field( $this->settings['instructions'] ?? '' );

// For values that act as identifiers (no whitespace, no special chars):
$external_id = Tools::sanitize_text_field( $request['external_id'] ?? '' );

// For numeric IDs:
$user_id = absint( $request['user_id'] ?? 0 );
```

`Tools::sanitize_text_field()` is JFB's wrapper that trims plus does the standard `sanitize_text_field` work. Use it for action settings that the user typed in the editor.

## Step 3 — macro replacement (`%field_id%` in admin templates)

A common pattern: the admin types a template like `"Hi %first_name%, your order %order_id% is ready"` in an action setting, and you substitute the form's actual field values at runtime. The replacer reads `jet_fb_context()` so it stays in sync with any mutations from upstream actions.

```php
private function replace_macros( string $template ): string {
    if ( false === strpos( $template, '%' ) ) {
        return $template;
    }

    return preg_replace_callback(
        '/%(?P<name>[a-zA-Z0-9\-_]+)%/',
        static function ( $match ) {
            $field = $match['name'];

            if ( ! jet_fb_context()->has_field( $field ) ) {
                return $match[0]; // leave the placeholder as-is
            }

            $value = jet_fb_context()->get_value( $field );

            if ( is_array( $value ) || is_object( $value ) ) {
                $value = wp_json_encode( $value );
            }

            return (string) $value;
        },
        $template
    );
}
```

Notes:

- **Regex matches `[a-zA-Z0-9\-_]+`** for the macro name — adjust if your field IDs allow other characters, but JFB field IDs are normally constrained to this set.
- **Skip the early-out (`strpos`) at your peril** — without it, every empty-template render runs a regex pass.
- **Unknown macro is left literal**, not stripped. The admin should see `%not_a_field%` in the output if they typo'd, not silently nothing.
- **Array / object values get JSON-encoded** because they have to become a string. If your context expects something else (CSV, comma-joined), customize the inner branch.
- **The macro replacer is `static`** — it has no instance state. Make it a private method or a free function.

JFB ships its own macro / preset / dynamic-value subsystems for richer cases (date formatters, computed values, related-post lookups). If your needs grow past simple field substitution, look into `jet_fb_dynamic_value()` or the macros module instead of expanding this regex.

## Step 4 — call the external API (WP HTTP API)

Always use `wp_remote_*` — never `file_get_contents`, `curl_init`, `fopen` for HTTP. WordPress's HTTP API handles transport selection, proxy config, SSL verify, and timeout consistently across hosts.

```php
private function call_external_api( array $payload ): array {
    $settings = $this->get_api_settings();
    $api_key  = trim( (string) ( $settings['api_key'] ?? '' ) );

    if ( '' === $api_key ) {
        throw new Action_Exception(
            __( 'API key is missing. Configure it in the plugin settings.', 'myplugin' )
        );
    }

    $response = wp_remote_post(
        'https://api.example.com/v1/endpoint',
        array(
            'headers' => array(
                'Authorization' => 'Bearer ' . $api_key,
                'Content-Type'  => 'application/json',
                'Accept'        => 'application/json',
            ),
            'body'    => wp_json_encode( $payload ),
            'timeout' => 30,
        )
    );

    if ( $response instanceof \WP_Error ) {
        throw new Action_Exception(
            sprintf(
                /* translators: %s: HTTP error message */
                __( 'API request failed: %s', 'myplugin' ),
                $response->get_error_message()
            )
        );
    }

    $code = (int) wp_remote_retrieve_response_code( $response );
    $body = (string) wp_remote_retrieve_body( $response );

    if ( $code < 200 || $code >= 300 ) {
        throw new Action_Exception(
            sprintf(
                /* translators: 1: HTTP status code, 2: response body excerpt */
                __( 'API returned %1$d: %2$s', 'myplugin' ),
                $code,
                wp_strip_all_tags( substr( $body, 0, 200 ) )
            )
        );
    }

    $decoded = json_decode( $body, true );
    if ( ! is_array( $decoded ) ) {
        throw new Action_Exception(
            __( 'API returned a non-JSON response.', 'myplugin' )
        );
    }

    return $decoded;
}
```

Critical points:

- **`timeout`** — set explicitly. WP default is 5 seconds which is too short for many APIs. 30 seconds is reasonable for most LLM/CRM calls; raise only if you know the upstream is slower.
- **`headers`** — always include `Content-Type` for POST bodies, and `Accept` for clarity. `Authorization` for any auth scheme.
- **`body`** — `wp_json_encode`, never plain `json_encode` (the WP wrapper handles charsets and edge cases).
- **`WP_Error` handling** — `wp_remote_*` returns either an array on success OR a `WP_Error` on transport failure. Always check.
- **HTTP status code** — `wp_remote_retrieve_response_code` is the canonical way to read it. Convert to int, check the 2xx range. A 200-OK with malformed body still throws below.
- **Body excerpt in error message** — `substr( $body, 0, 200 )` + `wp_strip_all_tags` keeps user-visible errors short and HTML-safe. Don't dump the full body — APIs sometimes return huge HTML error pages.
- **Throw `Action_Exception`, not `Exception`** — JFB only translates `Action_Exception` to user-facing messages.

For **SSRF protection** when the URL is admin-configurable (e.g. webhook URLs the user types in), additionally validate the URL host against an allowlist or use the `reject_unsafe_urls` request arg. See `wp-security-deep` for the full SSRF discussion.

## Step 5 — write the result back into form context

When your action produces data that downstream actions should see (e.g. ChatGPT writes its answer into a hidden field, a translation action replaces a value with its translated form), use `update_request`:

```php
$answer = $api_response['choices'][0]['message']['content'] ?? '';
$answer = sanitize_textarea_field( $answer );

jet_fb_context()->update_request( $answer, $target_field_id );
```

Key semantics:

- **`update_request( $value, $field_id )`** — argument order is `(value, field_id)`, NOT `(field_id, value)`. Easy to flip.
- **Writing to a non-existent field is silent** — the value is stored and `has_field` will return true after, but nothing visible in the form. To verify before writing, call `has_field` first.
- **Subsequent actions read the new value** via both `$request[ $field_id ]` (their `do_action`'s `$request` is re-resolved from context) AND `jet_fb_context()->get_value( $field_id )`. Both are in sync after `update_request`.
- **Save Record action** snapshots the request at submission end — values you write here will be in the saved submission.

If your action ALSO wants to pass non-field metadata to specific downstream actions (e.g. an internal API transaction ID, a calculated score), use `$handler->add_context_once( $this->get_id(), [...] )` instead. That's keyed by action type, not exposed as a form field, and accessible via `$handler->get_context( $action_type, $key )` in later actions.

## Step 6 — dispatch outcome events

Once you have the API result and have written it back, branch the chain by dispatching a custom event. Each branch can have its own followups (different actions wired to different events).

```php
use MyPlugin\Events\ApiSuccessEvent;
use MyPlugin\Events\ApiFailureEvent;

if ( $api_response['ok'] ?? false ) {
    jet_fb_events()->execute( ApiSuccessEvent::class, $handler->get_form_id() );
} else {
    jet_fb_events()->execute( ApiFailureEvent::class, $handler->get_form_id() );
}
```

Important caveats from observed production usage:

- **Save the action handler's position** before dispatching, restore after — the dispatch reuses the action handler and shifts its iteration cursor, which can confuse the surrounding chain:

```php
$previous_position = $handler->get_position();

try {
    jet_fb_events()->execute( $event_class, $handler->get_form_id() );
} finally {
    if ( $previous_position ) {
        $handler->set_current_action( $previous_position );
    } else {
        $handler->set_current_action( $this->_id );
    }
}
```

- **Pass the form ID** as the second argument. Some event executors need it.
- **Events must be registered** server-side via `'jet-form-builder/event-types'` filter (see `jfb-action-events`).
- **Listeners must opt-in** to the event in the editor — this is the standard `provideEvents` flow OR the action item decorator pattern (see `jfb-action-item-decorator`).

## Step 7 — credentials: read from settings tab, not constants

API keys and similar secrets should live in the plugin's settings tab (admin-managed, stored in `wp_options`). Don't hardcode, don't ship `wp-config.php` constants for plugin features — those are for the site owner.

```php
private function get_api_settings(): array {
    $defaults = array(
        'api_key' => '',
        'model'   => 'gpt-4',
        'enable_log' => false,
    );

    return array_merge(
        $defaults,
        Tab_Handler_Manager::instance()->options( 'myplugin-api-tab', array() )
    );
}
```

`Tab_Handler_Manager::instance()->options( $tab_id, $defaults )` reads the JFB settings tab's stored options — see `jfb-settings-tab` for how to register the tab itself. This pattern keeps the action code agnostic to where the credentials live, and makes it trivial for site admins to rotate keys.

## Step 8 — debug logging (gated)

Production actions called from form submissions can flood logs if you log indiscriminately. Gate logs behind a settings flag:

```php
private function should_log(): bool {
    static $enabled = null;
    if ( null !== $enabled ) {
        return $enabled;
    }
    $options = Tab_Handler_Manager::instance()->options( 'myplugin-api-tab', array() );
    $enabled = ! empty( $options['enable_log'] );
    return $enabled;
}

private function log( string $message ): void {
    if ( ! $this->should_log() ) {
        return;
    }
    error_log( '[MyPlugin] ' . $message );
}
```

The `static $enabled` cache avoids re-reading options on every log call within one request.

**What to log:**
- Request payload (sanitized — strip `Authorization` headers, redact secrets)
- API response status code and a short excerpt of the body
- Final outcome / decision

**What NOT to log:**
- API keys, tokens, full headers
- PII unless the user has opted in
- Full response bodies for high-volume endpoints

See `wp-security-secrets` for the full secrets-in-logs discussion.

## End-to-end example: complete `do_action()`

```php
/**
 * @throws Action_Exception
 */
public function do_action( array $request, Action_Handler $handler ) {
    // 1. Read settings (template + target field).
    $instructions = sanitize_textarea_field( $this->settings['instructions'] ?? '' );
    $target_field = Tools::sanitize_text_field( $this->settings['fields_map']['answer'] ?? '' );

    if ( '' === $target_field ) {
        throw new Action_Exception(
            __( 'Target field is required.', 'myplugin' )
        );
    }

    // 2. Macro-replace admin templates.
    $prompt = $this->replace_macros( $instructions );

    // 3. Call the API.
    $response = $this->call_external_api( array(
        'prompt' => $prompt,
        'model'  => $this->get_api_settings()['model'],
    ) );

    // 4. Sanitize + write the result back into form context.
    $answer = sanitize_textarea_field( $response['answer'] ?? '' );
    jet_fb_context()->update_request( $answer, $target_field );

    // 5. Dispatch outcome event.
    $previous_position = $handler->get_position();
    try {
        $event_class = ( $response['decision'] ?? false )
            ? \MyPlugin\Events\DecisionTrueEvent::class
            : \MyPlugin\Events\DecisionFalseEvent::class;

        jet_fb_events()->execute( $event_class, $handler->get_form_id() );
    } finally {
        if ( $previous_position ) {
            $handler->set_current_action( $previous_position );
        } else {
            $handler->set_current_action( $this->_id );
        }
    }
}
```

This shape — settings → macro → API → context write → event dispatch — covers the vast majority of integration actions. Most of the implementation effort is steering the API specifics; the JFB-side glue is constant.

## Critical rules

- **`jet_fb_context()` is the source of truth, not `$request`** — both work for reading, but if upstream actions might mutate, prefer `get_value`. For writes, ALWAYS use `update_request` (NOT direct array mutation).
- **`update_request( $value, $field_id )` argument order is value-first.** Easy to mix up.
- **Sanitize at the boundary** — even though JFB validates form fields, your action sends data to a different system with different rules. `sanitize_text_field`, `sanitize_email`, `absint`, `wp_kses_post` for HTML, `Tools::sanitize_text_field` for action settings.
- **Use `wp_remote_*` for HTTP, never `curl` / `file_get_contents` / `fopen` with URLs.** WP's HTTP API is the only correct path on multi-host environments.
- **Always set explicit `timeout`** — the default 5s breaks LLM and slow-CRM use cases.
- **Throw `Action_Exception` for failure**, never raw `Exception`. JFB only displays `Action_Exception` messages to the user.
- **Save and restore handler position around `jet_fb_events()->execute()`** — the dispatch shifts the iteration cursor.
- **API keys come from the settings tab via `Tab_Handler_Manager`** — never hardcode, never `wp-config.php` constants for plugin-feature credentials.
- **Gate `error_log` behind a settings flag** — production logs flood otherwise.
- **Strip secrets before logging** — `Authorization` headers, API keys, full bodies of auth-related endpoints.
- **Validate URL host for SSRF** when the URL is user-configurable — see `wp-security-deep`.
- **Macros come from `%field_id%`** — JFB field ID format. Don't invent your own delimiter; admins expect this convention.

## Common pitfalls (failure modes inferred from the API contract)

- **`update_request` writes nothing visible**: target field doesn't exist on the form. Verify with `has_field` first, OR document that the field is required.
- **Macro replacer eats `%`-signs in non-template text**: the regex matches greedily over `%foo%`. If your text legitimately contains percent characters, escape them in the admin help text (`100%%`) or use a different delimiter.
- **API call hangs the form submission for 30 seconds**: timeout is set, but the user is still waiting. Consider deferring slow calls to a background task (Action Scheduler) and dispatching events on completion. Out of scope here, but worth knowing.
- **Action throws on non-2xx, but the user only sees "Submit failed"**: `Action_Exception` was caught somewhere upstream OR a generic `\Exception` was thrown instead. Always use `Action_Exception` with a clear, translatable message.
- **`jet_fb_context()->get_value` returns null for a known field**: the form was submitted before that field was rendered (conditional block hid it). Use `??` to fall through to a default; do not throw.
- **Downstream actions don't see the updated value**: `update_request` was called with arguments swapped (`field_id` first, `value` second). Re-check argument order.
- **Event dispatched but no listener runs**: events not registered, OR listeners haven't opted-in via `provideEvents` / decorator. See `jfb-action-events`.
- **API key visible in error log**: logging the full request body without redaction. Add a redactor before the log call.

## Cross-references

- Run **`jfb-form-action`** first — this skill assumes a working action class with `action_attributes`, `action_data`, etc.
- Run **`jfb-action-events`** to register the events your action dispatches.
- Run **`jfb-action-item-decorator`** if you also want the visual TRUE/FALSE/Always toggle on every action (the canonical UI for action-event branching).
- Run **`jfb-settings-tab`** to register the settings tab where API credentials live.
- Run **`wp-security-deep`** for SSRF protection when API URLs are user-configurable.
- Run **`wp-security-secrets`** before release — credentials must come from the settings tab, never hardcoded.
- Run **`wp-i18n-audit`** to verify all error messages are translatable.

## What this skill does NOT cover

- Background / async API calls (Action Scheduler integration is a separate topic).
- Streaming API responses (Server-Sent Events, WebSocket) — out of scope.
- Multi-step API flows (OAuth, refresh tokens) — describe the storage of the refresh token, then this skill applies for each call.
- Idempotency keys / retries — depends on upstream API; not JFB-specific.
- File uploads from the form to an external API — possible but with different sanitization (`wp_check_filetype`, `wp_handle_upload` first).
- Rate limiting from your side — depends on the API; consider transients with TTL.

## References

- `chatgpt-for-jetformbuilder` plugin: production reference. See `includes/Actions/ChatgptDecisionAction.php` for the full pattern (`do_action`, `replace_macros`, `call_chatgpt`, `should_log`, settings tab integration).
- WP HTTP API: https://developer.wordpress.org/reference/functions/wp_remote_post/
- `jet_fb_context()` source: `wp-content/plugins/jetformbuilder/includes/context/context.php`