Skip to main content

Bots & OAuth Clients

Automation Bots​

What is a Bot?​

A bot is a server-side automation script that runs automatically when something happens in the FHIR data platform. You write the logic in TypeScript, deploy it via the Admin Portal, and attach it to a Subscription that triggers it when the relevant data changes.

Examples of what bots can do:

  • Send a notification to a patient when a new lab result arrives
  • Automatically calculate or populate derived data fields
  • Sync data between ChartChat and an external system
  • Run scheduled tasks (cron bots) on a timer

Bots run inside the ChartChat server — they are not exposed to patients or the public. Every bot has a name, optional description, and optionally an Access Policy that limits what data the bot can touch.

Viewing All Bots​

Go to Admin → Bots (/admin/bots). The table lists all bots in the project with their name, last updated date, and a link to each bot resource.

Creating a Bot​

  1. Go to Admin → Bots and click Create new bot (or navigate to /admin/bots/new)
  2. Fill in:
FieldRequiredDescription
NameYesA descriptive name for the bot (e.g., Lab Result Notifier)
DescriptionNoWhat this bot does
Access PolicyNoRestricts what FHIR resources this bot can read/write. Strongly recommended.
  1. Click Create Bot
  2. You will see a link to Go to new bot — click it to open the bot resource
  3. Go to the Editor tab to write and deploy the bot's TypeScript code

Editing Bot Code​

From the bot's resource page, click the Editor tab. This opens a TypeScript editor where you write the bot logic. Click Deploy to compile and upload the code to the server.

Once deployed, the bot will execute whenever its linked Subscription fires.

Assigning an Access Policy to a Bot​

A bot without an Access Policy runs with full project-admin access — it can read and write anything. This is dangerous if the bot has a bug. Always assign a narrowly scoped Access Policy that only covers the resource types the bot actually needs.

See Access Policies for how to create one.

Removing Bot Queue Jobs​

If a bot is misbehaving and flooding the job queue, a super admin can remove all its pending queued jobs from Super Admin → Remove Bot ID Jobs from Queue. This stops the bot from executing any more queued work without deleting the bot itself.

OAuth Clients​

What is an OAuth Client?​

An OAuth client is an application that is authorized to connect to ChartChat's FHIR API. Each client has a unique Client ID and Client Secret that it uses to authenticate API requests.

Who needs an OAuth client:

  • The Member Portal (already registered)
  • Any third-party application connecting via SMART on FHIR
  • Backend scripts or services that call the FHIR API programmatically
  • Testing tools that need API access

Viewing All Clients​

Go to Admin → OAuth Clients (/admin/clients).

Creating an OAuth Client​

  1. Go to Admin → OAuth Clients and click Create new client (bottom right, or navigate to /admin/clients/new)
  2. Fill in:
FieldRequiredDescription
NameYesA clear label for this client (e.g., Member Portal, EHR Sync Script)
DescriptionNoWhat this client is used for
Redirect URINoThe URL the server redirects to after OAuth login. Only needed for browser-based apps using authorization code flow. Leave blank for machine-to-machine clients.
Access PolicyNoLimits what this client can read/write via the API. Strongly recommended for any non-admin client.
  1. Click Create Client
  2. Click Go to new client to open the ClientApplication resource
  3. From the Details tab, copy the Client ID (the resource id field) and Client Secret — provide these to the application that needs them

Copy the client secret immediately. If you lose it, you must regenerate it by editing the resource — the old secret stops working right away.

Assigning an Access Policy to a Client​

Any client that is not a trusted internal admin tool should have an Access Policy assigned to it. This ensures that if the client's credentials are ever compromised, the attacker can only access the subset of data the policy allows.

See Access Policies for examples.

Secrets​

Secrets are encrypted key-value pairs stored at the project level, accessible to bots and server-side code. They are never exposed to the browser or to patients.

Common uses:

  • API keys for external notification services (SMS, email)
  • Credentials for third-party healthcare data providers
  • Encryption keys used in bot logic

Managing Secrets​

  1. Go to Admin → Secrets (/admin/secrets)
  2. Add, edit, or remove key-value pairs
  3. Click Save

Secrets are immediately available to all bots in the project after saving.

Never put secrets directly in bot code — always store them here and read them via the secrets API inside the bot.