Build Problem-Based Charting Using Web SDK

What you will build

20 min | Intermediate

A Web SDK ambient encounter with problem-based charting enabled
One Assessment and Plan section marked as the Problem-Based Note (PBN)
EMR diagnoses seeded into the first session of the encounter
A note submit handler that reads sectioned note content

Using an AI coding tool?Copy the following prompt to add the Suki developer documentation as a skill and MCP server to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, llms.txt, and skill.md), refer to AI-optimized documentation.

Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the MCP server for documentation search.

Open in Cursor

In this use-case tutorial, you build a React Web SDK ambient page for problem-based charting. You wrap with SukiProvider, authenticate with SukiAuthManager, call init, then mount SukiAssistant with ambientOptions: exactly one LOINC section with isPBNSection: true, EMR diagnoses for the first session, and onNoteSubmit to receive the note. By the end of this tutorial, documentation follows problems, merges visit discussion with diagnoses you already know, and your app receives sectioned note content on submit.

Prerequisites

Before you begin, make sure you have:

Completed Partner onboarding and received your partnerId and partnerToken.
A React 18+ app that can host the Web SDK UI.
Host URLs on the Suki allowlist and a partner JWT that meets Web SDK prerequisites.
Web SDK v2.1.2+ for the diagnoses block (EMR merge).
LOINC section codes from Note sections. This tutorial uses Assessment and Plan (51847-2) as the PBN.

If you are new to Web SDK ambient, complete Build a Web SDK ambient session first, then return here to add PBC.

Only one section can have isPBNSection: true. If more than one section is marked as PBN, the ambient session fails to start. Seed diagnoses only on the first session in an encounter. Later re-ambient cannot seed diagnoses.

Architecture

Project setup

Use a React 18+ app that meets Web SDK prerequisites (see Prerequisites). Use Web SDK v2.1.2+ for diagnoses seeding.
Install the required dependencies:

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

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

Configure your credentials:
- Keep partnerId and partnerToken ready for SukiAuthManager.
- Confirm host URLs meet Web SDK prerequisites.
- Have LOINC section codes ready. This tutorial uses Assessment and Plan (51847-2) as the PBN.

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.

Wrap Your App with SukiProvider

In Web SDK v3, wrap your tree with SukiProvider. Run init in a child component, not on the provider.

import { SukiProvider } from "@suki-sdk/react";

function App() {
return (
<SukiProvider>
  <PbcAmbientPage />
</SukiProvider>
);
}

Create SukiAuthManager and Call Init

Create one SukiAuthManager with useMemo, then call init from useSuki() when the SDK is not initialized yet.

import { useEffect, useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { useSuki } from "@suki-sdk/react";

function PbcAmbientPage() {
const authManager = useMemo(
() =>
  new SukiAuthManager({
    partnerId: "YOUR_PARTNER_ID",
    partnerToken: "YOUR_PARTNER_TOKEN",
    providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
    providerOrgId: "YOUR_ORG_ID",
    environment: "staging", // Example — staging | production
    loginOnInitialize: true,
  }),
[],
);

const { init, isInitialized } = useSuki();

useEffect(() => {
if (!isInitialized) {
  init({ authManager });
}
}, [init, isInitialized, authManager]);

if (!isInitialized) {
return <p>Initializing Suki Web SDK...</p>;
}

// Continue with encounter + ambientOptions in the next steps
return null;
}

Mark Assessment and Plan as the PBN

Build ambientOptions.sections with LOINC codes. Set isPBNSection: true on Assessment and Plan (51847-2) only. Use supported codes from Note sections.

const ambientOptions = {
sections: [
{
  loinc: "51847-2", // Assessment and Plan
  isPBNSection: true, // Exactly one PBN section
},
{
  loinc: "10164-2", // History of Present Illness
},
{
  loinc: "10187-3", // Review of Systems
},
],
};

Seed Existing Patient Diagnoses

Add diagnoses under ambientOptions for the first session in the encounter. Use ICD-10 only, exactly one code per diagnosis, and at least one of code or description. A seeded diagnosis appears in the note only if discussed during the visit. Refer to Existing patient diagnoses.

const ambientOptions = {
sections: [
{ loinc: "51847-2", isPBNSection: true },
{ loinc: "10164-2" },
{ loinc: "10187-3" },
],
diagnoses: {
values: [
  {
    codes: [
      {
        code: "I10", // Example ICD10 — replace with your EMR diagnosis code
        description: "Essential hypertension", // Example only
        type: "ICD10",
      },
    ],
    diagnosisNote: "Hypertension", // Example only
  },
],
},
};

Mount SukiAssistant and Handle Note Submit

Pass encounter (patient identifier required; gender MALE | FEMALE | UNKNOWN), ambientOptions, and onNoteSubmit. Keep identifiers at most 36 characters. Note submit returns the same shape whether or not you seed diagnoses (noteId, encounterId, contents).

import { useEffect, useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { useSuki, SukiAssistant } from "@suki-sdk/react";

function PbcAmbientPage() {
const authManager = useMemo(
() =>
  new SukiAuthManager({
    partnerId: "YOUR_PARTNER_ID",
    partnerToken: "YOUR_PARTNER_TOKEN",
    providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
    providerOrgId: "YOUR_ORG_ID",
    environment: "staging", // Example — staging | production
    loginOnInitialize: true,
  }),
[],
);

const { init, isInitialized } = useSuki();

const encounter = useMemo(
() => ({
  identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab", // Example only — replace with your encounter ID
  patient: {
    identifier: "905c2521-25eb-4324-9978-724636df3436", // Example only — replace with your patient ID
    name: {
      use: "official", // Example patient demographics — replace with real data
      family: "Doe",
      given: ["John"],
      suffix: [], // Required by Patient.name even when empty
    },
    birthDate: "1990-01-01", // Example only — YYYY-MM-DD
    gender: "MALE", // Example — must be "MALE" | "FEMALE" | "UNKNOWN"
  },
}),
[],
);

const ambientOptions = useMemo(
() => ({
  sections: [
    { loinc: "51847-2", isPBNSection: true },
    { loinc: "10164-2" },
    { loinc: "10187-3" },
  ],
  diagnoses: {
    values: [
      {
        codes: [
          {
            code: "I10", // Example ICD10 — replace with your EMR diagnosis code
            description: "Essential hypertension", // Example only
            type: "ICD10",
          },
        ],
        diagnosisNote: "Hypertension", // Example only
      },
    ],
  },
}),
[],
);

useEffect(() => {
if (!isInitialized) {
  init({ authManager });
}
}, [init, isInitialized, authManager]);

const handleNoteSubmit = (data) => {
console.log("Note submitted:", data.noteId);
data.contents.forEach((section) => {
  console.log(`${section.title}: ${section.content}`);
});
};

if (!isInitialized) {
return <p>Initializing Suki Web SDK...</p>;
}

return (
<SukiAssistant
  encounter={encounter}
  ambientOptions={ambientOptions}
  onNoteSubmit={handleNoteSubmit}
/>
);
}

Full code example

React

// Use-case tutorial: Problem-Based Charting with Web SDK Ambient (React)
// Copy this file into a React app, replace YOUR_* placeholders, then render <App />.
// Flow: SukiProvider → auth → init → ambientOptions (one PBN + diagnoses) → SukiAssistant + onNoteSubmit

import { useEffect, useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { SukiProvider, useSuki, SukiAssistant } from "@suki-sdk/react";

// 1) Wrap once at the root. Call init() in a child under SukiProvider.
function App() {
  return (
    <SukiProvider>
      <PbcAmbientPage />
    </SukiProvider>
  );
}

function PbcAmbientPage() {
  // 2) One long-lived auth manager. Recreating it every render breaks login state.
  const authManager = useMemo(
    () =>
      new SukiAuthManager({
        partnerId: "YOUR_PARTNER_ID", // Required: from partner onboarding
        partnerToken: "YOUR_PARTNER_TOKEN", // Required: keep off public clients in production
        providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
        providerOrgId: "YOUR_ORG_ID", // Required — replace with your org ID
        environment: "staging", // Example — use "production" only when ready
        loginOnInitialize: true,
      }),
    [],
  );

  const { init, isInitialized } = useSuki();

  // 3) Encounter + patient. Identifiers at most 36 characters.
  const encounter = useMemo(
    () => ({
      identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab", // Example only — replace with your encounter ID (max 36 chars)
      patient: {
        identifier: "905c2521-25eb-4324-9978-724636df3436", // Example only — replace with your patient ID (max 36 chars)
        name: {
          use: "official", // Example name fields — replace with real patient name data
          family: "Doe",
          given: ["John"],
          suffix: [], // Required by Patient.name even when empty
        },
        birthDate: "1990-01-01", // Example only — YYYY-MM-DD
        gender: "MALE", // Example — must be "MALE" | "FEMALE" | "UNKNOWN"
      },
    }),
    [],
  );

  // 4) PBC: exactly one isPBNSection: true. Seed diagnoses on the first session only.
  //    Assessment and Plan LOINC is 51847-2 (not 51848-0 Assessment alone).
  const ambientOptions = useMemo(
    () => ({
      sections: [
        { loinc: "51847-2", isPBNSection: true }, // Assessment and Plan (PBN)
        { loinc: "10164-2" }, // History of Present Illness
        { loinc: "10187-3" }, // Review of Systems
      ],
      diagnoses: {
        values: [
          {
            codes: [
              {
                code: "I10", // Example ICD10 — replace with your EMR diagnosis code
                description: "Essential hypertension", // Example only
                type: "ICD10", // Input codes must be ICD10
              },
            ],
            diagnosisNote: "Hypertension", // Example only — optional note
          },
        ],
      },
    }),
    [],
  );

  // 5) Initialize the SDK once when the provider tree is ready.
  useEffect(() => {
    if (!isInitialized) {
      init({ authManager });
    }
  }, [init, isInitialized, authManager]);

  // 6) Receive sectioned note content when the clinician submits.
  const handleNoteSubmit = (data) => {
    console.log("Note submitted:", data.noteId, data.encounterId);
    data.contents.forEach((section) => {
      console.log(`${section.title}: ${section.content}`);
    });
  };

  if (!isInitialized) {
    return <p>Initializing Suki Web SDK...</p>;
  }

  // 7) Mount Ambient with PBN options and the submit handler.
  return (
    <SukiAssistant
      encounter={encounter}
      ambientOptions={ambientOptions}
      onNoteSubmit={handleNoteSubmit}
    />
  );
}

export default App;

Troubleshooting

Session Fails to Start

Only one section may have isPBNSection: true.

Diagnoses Missing Later

Seed diagnoses only on the first session in an encounter.

Wrong Assessment and Plan Code

Use LOINC 51847-2 for Assessment and Plan (not 51848-0).

Summary

In this tutorial, you:

Mounted Web SDK ambient with one PBN section.
Seeded EMR diagnoses on the first session in an encounter.
Handled note submit to receive sectioned note content.

Use problem-based charting for deeper guidance.

Get Started

Concepts & Feature Guides

Tutorials

Resources

FAQs & Support

Build Problem-Based Charting Using Web SDK

Prerequisites

Architecture

Project setup

Tutorial steps

Full code example

Troubleshooting

Summary

Other tutorials

Build a Web SDK Ambient Session

Build a Webhook Notification Receiver

​Prerequisites

​Architecture

​Project setup

​Tutorial steps

​Full code example

​Troubleshooting

​Summary

​Other tutorials

​Build a Web SDK Ambient Session

​Build a Webhook Notification Receiver

Prerequisites

Architecture

Project setup

Tutorial steps

Full code example

Troubleshooting

Summary

Other tutorials

Build a Web SDK Ambient Session

Build a Webhook Notification Receiver