Build a Form Filling Session with EHR Handoff

Use-case tutorial: Open a Form filling SDK session in React and map structured_data to your EHR with correlation_id

What you will build

20 min | Intermediate

• A Form filling session opened with template IDs.
• A stable correlation_id for your EHR mapping.
• Mapping structured_data into one EHR payload after submit.

Using an AI coding tool?

Copy the prompt below to point your agent at the Form filling skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Form filling skill and connect the documentation MCP.

CopiedCopy promptOpen in Cursor

In this tutorial, you open Form filling from React, pass template IDs and a stable correlation_id, then map structured_data from the submit result for EHR handoff.

By the end of this tutorial, submit returns filled form values and your mapping builds one EHR payload per filled template.

Prerequisites

Before you begin, make sure you have:

• Completed Partner onboarding.
• Valid Form filling template_id values from Suki support. Refer to Form filling templates.
• A React 18+ app that meets Form filling SDK prerequisites.

EHR field names differ by partner system. The mapping in this tutorial is illustrative. Adapt fields to your chart schema.

Architecture

Project setup

1. Complete Partner onboarding and obtain valid Form filling template_id values (see Prerequisites).
2. Install the required dependencies:.

# pnpm
pnpm add @suki-sdk/form-filling @suki-sdk/form-filling-react @suki-sdk/core

# npm
npm install @suki-sdk/form-filling @suki-sdk/form-filling-react @suki-sdk/core

3. Configure your credentials:.

   • Keep credentials ready for the Form filling client configuration used in later steps.
   • Have valid template_id values from Suki for your partner account.

4. Give the Form filling container height. React mounts the UI in .suki-form-filling. Without height, the iframe looks blank:.

.suki-form-filling {
  width: 100%;
  height: min(80vh, 720px);
  min-height: 400px;
}

Tutorial steps

Work through each step in order. Read the explanation, review the code example, then continue to the next step. The full code example is available in the accordion below.

1. Create FormFillingClient Once

   Build SukiAuthManager and FormFillingClient in useMemo. Set autoRegister: false unless your integration uses provider auto-registration (default is true).

   Check: One FormFillingClient is created in useMemo for the encounter screen.

   import { useMemo } from "react";
   import { SukiAuthManager } from "@suki-sdk/core";
   import { FormFillingClient } from "@suki-sdk/form-filling-react";
   
   function useEncounterFormClient() {
   return useMemo(() => {
   const authManager = new SukiAuthManager({
     partnerId: "YOUR_PARTNER_ID",
     partnerToken: "YOUR_PARTNER_TOKEN",
     environment: "staging",
     loginOnInitialize: true,
     autoRegister: false,
     providerId: "YOUR_PROVIDER_ID", // Replace with your provider ID
     providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
   });
   return new FormFillingClient({ authManager });
   }, []);
   }
   
2. Open Form Filling with Template IDs and correlation_id

   Wrap with FormFillingProvider. Pass template IDs from Suki support and your encounter id as correlation_id so results map back to the chart. Style .suki-form-filling with height before the UI mounts.

   Check: Form filling opens with template IDs, a stable correlation_id, and .suki-form-filling has explicit height.

   If it fails: Give .suki-form-filling an explicit height before the UI mounts. Zero height is the most common cause of a blank iframe. Use template_id values from Suki for your partner account.

   import { useState } from "react";
   import { FormFillingProvider, FormFilling } from "@suki-sdk/form-filling-react";
   
   // Required: .suki-form-filling needs explicit height or the iframe looks blank.
   // .suki-form-filling { width: 100%; height: min(80vh, 720px); min-height: 400px; }
   
   function EncounterFormPanel({ client, encounterId, onSubmit }) {
   const [open, setOpen] = useState(false);
   
   return (
   <FormFillingProvider client={client}>
     <button type="button" onClick={() => setOpen(true)} disabled={open}>
       Start
     </button>
     {open && (
       <FormFilling
         forms={[{ form_template_id: "YOUR_TEMPLATE_ID" }]} // Example placeholder: replace with your template ID
         correlation_id={encounterId}
         onSubmit={onSubmit}
         onCancel={() => setOpen(false)}
       />
     )}
   </FormFillingProvider>
   );
   }
   
3. Map structured_data for EHR Handoff

   In onSubmit, map structured_data.generated_values by form_template_id. Use correlation_id as your encounter key and ambient_session_id for idempotent saves. For production persistence, also handle your partner webhook.

   Check: onSubmit maps structured_data.generated_values by form_template_id, using correlation_id and ambient_session_id.

   If it fails: Pass a stable correlation_id when you open the session, then reuse that same value when you map submitted data back into the EHR.

   function mapResultToEhr(result) {
   return result.structured_data.generated_values.map((instance) => ({
   encounterId: result.correlation_id ?? "",
   sessionId: result.ambient_session_id,
   templateId: instance.form_template_id,
   fields: instance.data,
   }));
   }
   
   async function handleSubmit(result, setOpen) {
   const missing = result.structured_data.non_generated_values.map(
   (v) => v.form_template_id,
   );
   if (missing.length > 0) {
   console.warn("No output for templates:", missing);
   }
   
   const payloads = mapResultToEhr(result);
   for (const payload of payloads) {
   await fetch("/api/ehr/forms", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(payload),
   });
   }
   setOpen(false);
   }
   

Full code example

React

// Form filling SDK + EHR handoff tutorial (React)
// Copy this file into a React app, replace YOUR_* placeholders, then render <App />.
// Flow: FormFillingClient → FormFillingProvider → FormFilling → map structured_data → your EHR API
// Do not rely on browser onSubmit alone in production. Also register a partner webhook.

import { useMemo, useState } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import {
  FormFillingClient,
  FormFillingProvider,
  FormFilling,
  useFormFilling,
} from "@suki-sdk/form-filling-react";

// Optional: sibling status under the same provider.
// Prefer isSessionActive; the provider may keep the last error until the next form-filling:error.
function FormFillingStatus() {
  const { isSessionActive, error } = useFormFilling();
  if (isSessionActive) {
    return <p>Form session active: speak to fill fields.</p>;
  }
  if (error) {
    return (
      <p role="alert">
        Form filling error ({error.code}): {error.message}
      </p>
    );
  }
  return null;
}

// Map each filled template to an EHR-shaped payload. Adapt `fields` to your chart schema.
function mapResultToEhr(result) {
  return result.structured_data.generated_values.map((instance) => ({
    encounterId: result.correlation_id ?? "", // Your encounter key from correlation_id
    sessionId: result.ambient_session_id, // Use for idempotent saves
    templateId: instance.form_template_id,
    fields: instance.data,
  }));
}

function EncounterFormFilling({ encounterId }) {
  // 1) Build auth + client once for the encounter page.
  const client = useMemo(() => {
    const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID", // Required: from partner onboarding
      partnerToken: "YOUR_PARTNER_TOKEN", // Required
      environment: "staging",
      loginOnInitialize: true,
      autoRegister: false, // Optional (default true); when true, providerName and providerOrgId are often required
      providerId: "YOUR_PROVIDER_ID", // Replace with your provider ID
      providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
    });
    return new FormFillingClient({ authManager });
  }, []);

  const [open, setOpen] = useState(false);

  // 2) Persist mapped results. Reuse this handler for onSubmit and onBackgroundSubmit.
  async function handleSubmit(result) {
    const missing = result.structured_data.non_generated_values.map(
      (v) => v.form_template_id,
    );
    if (missing.length > 0) {
      console.warn("No output for templates:", missing);
    }

    const payloads = mapResultToEhr(result);
    for (const payload of payloads) {
      // Replace with your EHR / charting API
      // Example EHR endpoint only — replace with your charting / EHR API
      await fetch("/api/ehr/forms", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(payload),
      });
    }
    setOpen(false);
  }

  return (
    <FormFillingProvider client={client}>
      <h1>Encounter {encounterId}</h1>
      <FormFillingStatus />
      <button type="button" onClick={() => setOpen(true)} disabled={open}>
        Start Form filling
      </button>
      {/* 3) Mount Form filling only while the session should be open.
          Style .suki-form-filling with height first or the iframe looks blank. */}
      {open && (
        <FormFilling
          forms={[{ form_template_id: "YOUR_TEMPLATE_ID_A" }, { form_template_id: "YOUR_TEMPLATE_ID_B" }]} // Example placeholders: replace with template IDs from Suki
          correlation_id={encounterId} // Ties results back to this encounter
          onSubmit={handleSubmit} // Required: receives FormFillingResult
          onCancel={() => setOpen(false)}
          onBackgroundSubmit={handleSubmit} // Late results after the clinician reopens or leaves
        />
      )}
    </FormFillingProvider>
  );
}

// 4) Demo root with a sample encounter id so this file is paste-ready.
function App() {
  // Example encounter id only — replace with your real encounter / chart key
  return <EncounterFormFilling encounterId="encounter-123" />;
}

export default App;

Troubleshooting

Blank Form Filling UI

Give .suki-form-filling explicit height before the UI mounts. Zero height is the most common cause of a blank iframe. See Form filling React integration.

Empty or Wrong Templates

Use template_id values from Suki for your partner account.

Cannot Correlate Results

Pass a stable correlation_id when you open the session and reuse it in your mapping.

Production Saves

Prefer your partner webhook in production; this tutorial maps from onSubmit for the session flow.

Summary

In this tutorial, you:

• Opened Form filling with template IDs and a stable correlation_id.
• Received FormFillingResult on submit.
• Mapped structured_data into EHR handoff payloads.

Other tutorials

Continue with another end-to-end tutorial.