Integrations¶

Auto-generated from knowledge base TOML files by docs_gen.py. Do not edit manually; run dazzle docs generate to regenerate.

Integrations connect DAZZLE apps to external systems via declarative API bindings with triggers, field mappings, and error handling. Foreign models define the shape of external data for type-safe rendering without owning the source records.

Integration¶

External service integration declaration. Defines API connections, actions, data sync points, and declarative field mappings for external systems.

v0.30.0 adds declarative mapping blocks: base_url, auth, mapping with triggers, HTTP requests, request/response field mappings, and error handling strategies.

A map_request target is a dotted path. An all-digit segment is a list index: otherGains.0.assetType renders {"otherGains": [{"assetType": ...}]}, and a later .1 extends that list. map_response accepts the same target string and stores it as one entity field name.

transport: app renders the request and calls pipeline.serve.app_init.integration_transport instead of opening a socket. The hook receives the method, interpolated path, declared base_url, static mapping headers, and JSON body, and returns the status and body. The application adds per-request headers and chooses the host. on_error: retry calls the hook again. A missing hook is an error.

Syntax¶

integration <name> ["<Title>"]:
  [transport: app]
  [base_url: "<url>"]
  [auth: <api_key|oauth2|bearer|basic> from env("<KEY>")[, env("<KEY2>")]]

  [mapping <mapping_name> on <EntityName>:]
    [trigger: on_create [when <expr>]]
    [trigger: on_update [when <expr>]]
    [trigger: on_transition <from> -> <to>]
    [trigger: manual "<Label>"]
    request: <GET|POST|PUT|DELETE|PATCH> "<url_template>"
    [headers:]
      "<Header-Name>": "<value>"
    [map_request:]
      <field[.index][.path]> <- <source.path>
    [map_response:]
      <field[.path]> <- <source.path>
    [on_error: <ignore|log_warning|revert_transition|retry>]
    [on_error: set <field> = "<value>", <action>]

Example¶

integration companies_house:
  base_url: "https://api.company-information.service.gov.uk"
  auth: api_key from env("COMPANIES_HOUSE_API_KEY")

  mapping fetch_company on Company:
    trigger: on_create when company_number != null
    trigger: manual "Look up company"
    request: GET "/company/{self.company_number}"
    map_response:
      company_name <- response.company_name
      company_type <- response.type
      incorporation_date <- response.date_of_creation
    on_error: set company_status = "lookup_failed", log_warning

integration stripe_payments:
  base_url: "https://api.stripe.com/v1"
  auth: api_key from env("STRIPE_SECRET_KEY")

  mapping create_payment on Invoice:
    trigger: on_transition reviewed -> submitted
    request: POST "/payment_intents"
    headers:
      "Accept": "application/json"
    map_request:
      amount <- self.amount_pence
      currency <- self.currency
    map_response:
      stripe_payment_id <- response.id
    on_error: revert_transition

Related: Domain Service, Foreign Model, Entity

Foreign Model¶

Declaration of data structures from external systems (APIs, services) that Dazzle surfaces can display but doesn't own. Foreign models define the shape of external data for type-safe rendering.

Syntax¶

foreign_model <ModelName> "<Title>":
  <field_name>: <type>
  ...

Related: Integration, Domain Service