Patient Summary Best Practices

Patient Summary works best when ingestion, generation, and retrieval are designed for clinic-day use. This guide covers the production practices that keep summaries reliable for partner applications. In production, focus on these outcomes:

• FHIR data is in CKG before summary generation starts.
• Generation does not block clinician login or chart open.
• Polling is bounded and stops on terminal statuses.
• Failures are logged and visible to your team.
• Empty clinical states are clear in the UI.

​

Decide before you build

Before you wire Patient Summary into production, align on a few product decisions. Agree where clinicians see the summary, when generation runs, and how your UI handles missing appointments or missing history.

​

Authentication

Use the authentication model your partnership already follows for Suki Partner APIs.

• Keep partner_token and signing material on your backend only.
• Use sdp_suki_token for Patient Summary generation, status, and retrieval calls.
• Use the required SDP JWT bearer token for CKG Data Ingestion endpoints.
• Refresh tokens before expiry instead of waiting for unauthorized failures during clinic hours.
• Scope credentials by environment. Do not reuse staging secrets in production.

Refer to Partner authentication and Patient Summary authentication guides for more details.

​

Polling recommendations

Patient Summary has two polling surfaces:

• CKG ingestion status after upload.
• Summary job status after generation.

Recommended approach:

• Poll about every 5 seconds at first.
• Add backoff if a job is still running after the first minute.
• Set a maximum polling window so a stuck job cannot loop forever.
• Stop immediately on terminal statuses such as COMPLETED, FAILED, ABORTED, or ARCHIVED.
• For scheduled bulk generation, update each appointment as it completes instead of waiting for the entire schedule.

​

Retry strategies

Retry only when retrying is safe and useful.

​

Handling failures

Separate system failures from clinical empty states.

• No upcoming appointment is not an API failure. Show that an appointment is required to view the summary.
• No prior record found is a valid clinical state. Show About this visit and Problems, and state that no record was found under Summary and Previous visits.
• Ingestion failed and generation failed are system failures. Log them, alert on them, and provide a fallback such as manual chart review.

When a failure affects a clinician-facing screen, show a short recovery message and keep the rest of the patient profile usable.

​

Logging

Log enough to reconstruct one appointment path through the system. Capture at least:

• organization_id
• transaction_id for ingestion
• correlation_id when provided
• fhir_encounter_id
• fhir_practitioner_id
• patient_summary_id when returned
• HTTP status code and error response body
• Job status transitions and timestamps

These fields are also what support needs when an upload or generation issue requires investigation.

​

Monitoring

Monitor both technical health and clinic readiness. Useful signals:

• Ingestion success rate and time to complete
• Generation success rate and time per appointment
• Count of appointments still preparing at clinic open
• Rate of empty prior-history summaries
• Rate of “no upcoming appointment” views versus true generation failures
• Retry volume and repeated failures for the same encounter

Alert when morning ingestion or schedule generation falls behind the window your clinic operations expect.

​

Performance considerations

• Ingest once per morning for the day’s schedule where possible.
• Pre-generate summaries before peak login instead of generating only when a patient is opened.
• Skip generation when a summary already exists for the appointment.
• Retrieve pre-visit sections for dense schedule UIs, and full summaries for chart review.
• Cache completed summary payloads for the appointment lifetime when your product and privacy rules allow it.

​

Voice-first clinician UI

If your product supports voice commands, design Patient Summary so clinicians can open and navigate sections quickly during busy clinic flow.

• Keep section names stable.
• Keep empty states clear and easy to speak.
• Avoid hiding “no appointment” or “no prior record” messages behind nested menus.
• Make it easy to open, reread, and move between About this visit, Summary, Previous visits, and Problems.

​

Security considerations

• Keep all Patient Summary and CKG credentials server-side.
• Transmit clinical data only over HTTPS.
• Limit access to summary content to authorized clinical users for the relevant patient and encounter.
• Avoid writing full PHI-rich request and response bodies into unrestricted logs.
• Retain support identifiers without copying more clinical text than your security policy allows.
• Rotate credentials according to your organization policy.
• Validate that fhir_encounter_id and fhir_practitioner_id match the authenticated clinical context your application already trusts.

​

Next steps

Continue with the following guides:

• Patient Summary basic usage to implement the end-to-end API workflow.
• Patient Summary API quickstart to validate the flow on staging.
• Error messages to interpret Patient Summary API errors.