Administrator guide

NewInstance EHR (product code ehr) is the platform's cloud EHR for behavioral health and human services agencies. This guide is for whoever administers it: enabling the product, roles, general settings, the configuration screens under Settings, the form builder, reminders, client import, work queues, the Audit page, and webhooks.

Billing is in the billing guide, which covers payers, fee schedules, sliding scales, authorizations, the clearinghouse destination and the whole revenue cycle. Orders, inpatient and the portal are not built, and interoperability is only the FHIR capability statement (api.md section 11). Everything else described in this guide is live unless it says it is not built. The day to day clinical work, finding a client, writing and signing a note, the schedule, is in the clinician guide.

1. Enabling NewInstance EHR for an organizationlink

EHR is enabled for an organization the same way as any other platform product: the organization needs access to the ehr product, either through a billing subscription or direct access from a platform super admin.

Module entitlements are seeded ahead of the features themselves. Live today are the configuration, audit, and webhook and event capabilities described in this guide, client records, scheduling, clinical documentation, and billing with its two reports (billing guide, section 16). The orders, inpatient and portal modules are not built, interop serves only the FHIR capability statement (api.md section 11), AI is only the settings in section 3, and reporting has no reports beyond billing's.

Once access is granted, EHR appears in the organization's product list, and the EHR entry appears in the left navigation for every member holding ehr.client.view (section 2). The EHR home page shows the work queues with anything on them, that member's own schedule for today, counts of programs, locations and staff, and shortcuts to Work queues, Settings, Audit and Webhooks. The shortcuts a member cannot use are not shown.

2. Roles and accesslink

Ten role templates are seeded (defaultOrganizationPermissionGroupTemplates.json, keys product.ehr.<role>). Assign them to organization members from the organization's member and role screens, the same way as any other product role.

Caseload scoping applies to every role that does not hold ehr.client.all: a Clinician, Intern, Prescriber, or Nurse sees only clients on their caseload or in a program they are assigned to. EHR Admin, Clinical Supervisor, Front Desk, Biller, Quality Assurance, and Auditor can see every client in the organization. Staff without ehr.client.all who need to open a record outside their scope use break-the-glass (see section 15).

Which permission reaches the configuration a clinician needslink

ehr.config.view is held by one role template only, product.ehr.admin. Phase 2 therefore moved the configuration reads that clinical work depends on off that permission and onto the permission that describes who needs them. Without this change nine of the ten role templates could not book, could not create a client, and could not open a note.

ehr.config.view still reaches all of the above, and it is still the only permission that reaches the tenant settings as a whole, through ehrTenantSettings, the programs, the staff directory, the workflow definitions, and the SMS integration. Two of the narrow reads below, Documentation settings and Schedule settings, serve parts of the tenant settings.

Five narrow reads exist so a clinical screen never has to fall back on an administrative one:

• Assignable programs answers which programs a person may be enrolled in or assigned to, to anyone holding an EHR permission, and carries the level of care and whether the program is still active. Whether a program is a Part 2 program is served only to a holder of ehr.client.manage. Ask for the retired ones by name when you are showing history.
• Assignable staff answers which staff members are active, by name, to anyone holding an EHR permission.
• Co-signers answers who may co-sign one specific document. It resolves the staff whose organization role holds one of the role keys that document's form demands, and it never offers the author, because a person cannot co-sign their own note.
• Documentation settings answers the late entry window, whether a signature needs a PIN and the co-signature rules, to anyone who may read a document and to a holder of ehr.config.view.
• Schedule settings answers the clinic's time zone and the late cancellation notice in hours, to anyone holding ehr.schedule.view.

Reaching the EHR at alllink

The EHR entry in the organization's left navigation, and the EHR home it opens, need ehr.client.view (View clients), which each of the ten role templates above carries; an owner of the organization sees the entry and opens the home without it. A member without it is not shown the entry, and opening the EHR home by its address shows Access denied. A page inside the EHR area with a guard of its own applies that one instead, such as Settings, which needs ehr.config.view, and Billing, which opens as billing guide section 17 says; a page with none, such as Work queues, needs ehr.client.view as the home does. Each panel inside then applies its own permission. Add a member to the EHR product from the organization's product members screen, and give them one of the role templates above.

Who can give the most sensitive permissionslink

Seven permissions are held back for an owner or an administrator of the organization to give: ehr.client.all (Access all clients), ehr.part2.access (Access Part 2 records), ehr.breakglass.use (Break the glass), ehr.client.export (Export client data), ehr.reports.export (Export data), ehr.billing.refund (Ask for a refund) and ehr.billing.refund.approve (Approve a refund). Only an owner or an administrator can give one, whether by putting it in a permission group, by giving a member a permission group that carries it, by inviting someone with one, or by giving a member an EHR role that carries it. Making someone an owner or an administrator is held back in the same way. Anyone else who tries is refused, whoever the change is for, themselves included, in words naming what it would have given, for example: "Only an owner or an administrator of this organization can give Break the glass. Ask one of them to make this change."

A permission group's permissions, and the permission groups given to a member or named on an invitation, may name one twice: the repeat is not refused, and it is kept once.

3. General settingslink

Open Settings, then the General tab (?tab=general). Settings are grouped into cards.

The cards' controls and Save changes are offered only to a holder of ehr.config.manage (Manage configuration), the permission the server saves the settings with. Anyone else reads the cards with their controls turned off and no Save, under the line "Changing these settings needs the permission to manage the EHR configuration. You can read them and nothing here asks you to change one." The Programs, Locations, Service Codes, Appointment Types, Custom Fields, Forms and Workflows tabs (sections 4, 5 and 7 to 10) do the same: their New buttons, edit controls and row actions are offered only to a holder of ehr.config.manage, a form opened by anyone else shows nothing to change and no Save or Clone, and the same line says why.

Tenantlink

The Billing provider card below it carries what every claim names as its billing provider (billing guide, section 18), and says so: "Every claim this organisation sends names it as the billing provider: the display name above, with the NPI, tax ID and billing address here, and the taxonomy code where one is recorded. Sending a claim is refused while the name, NPI, tax ID or billing address is missing."

Emptying the NPI, the taxonomy code or billing address line 2 and saving clears it, and the card reads it back empty. A claim sent while the NPI is cleared is refused in the words a missing NPI always gave (billing guide, section 18): "A payer pays the organisation named on the claim, and this organisation has not recorded its ten digit NPI. An administrator records it once under the EHR organisation settings, and every claim then carries it. Nothing on the charge needs changing." A claim sent while the taxonomy code or line 2 is cleared is written without it. The tax ID is not cleared this way: left blank, it keeps the value on file.

An information banner below the Billing provider card shows the current encryption key version (Tenant data is encrypted with key version 1 at launch). All tenant data, including the tax ID, is encrypted per organization; the key version increments only when a key is rotated, and no screen, operation or script rotates one, so key rotation is not built.

42 CFR Part 2link

Documentationlink

Break the glasslink

Reviewer roles for break-the-glass notifications default to EHR Admin and Clinical Supervisor (product.ehr.admin, product.ehr.supervisor). This screen does not offer editing the reviewer role list; it can only be changed by updating tenant settings through the API, as breakGlass.reviewerRoleKeys.

Retentionlink

A legal hold flag exists in the data model to suspend purges, but retention purging is not built: nothing purges a record, so the two settings above and the flag are stored and read by nothing, and this screen does not offer the legal hold flag.

AI featureslink

Both settings, and a provider's BAA status, are stored. A platform super admin marks a provider's BAA status from the AI providers page. The AI capabilities these settings govern, such as ambient drafting, compliance checks and summaries, are not built, so nothing reads either setting, and no refusal to send PHI to a provider without a signed BAA is built.

Schedulinglink

No card on this tab shows these. They are kept under scheduling in the tenant settings and can only be changed by updating tenant settings through the API. A clinic that has changed none of them works under these defaults:

4. Programs and Part 2 markinglink

Open Settings, then the Programs tab. A program represents a level of care (an outpatient clinic, an IOP track, a residential unit, and so on).

Marking a program as Part 2 protects everything organized under it. Every child record created under a Part 2 program is flagged Part 2 on creation, and a client enrolled in a Part 2 program inherits the Part 2 flag, the records they already had included (clinician guide, section 3). Recording a disclosure (section 15) is how the organization tracks who Part 2 content was released to and why. Claims and statements leave through one disclosure check, which records each disclosure and sends a Part 2 client's claim only under a consent that permits it (billing guide, section 5), and an event naming a Part 2 client is held back from webhooks (section 15). The portal, FHIR resources and AI features, the other outbound paths, are not built.

5. Locations and roomslink

Open Settings, then the Locations tab.

6. Staff profiles and signature PINslink

Open Settings, then the Staff tab.

My staff profilelink

A member needs a staff profile before they can sign documentation or appear in staff lists. A profile, your own included, is made and changed only by someone holding ehr.staff.manage (Manage staff profiles), EHR Admin among the seeded roles. The card shows display name, credentials, NPI, programs, and Prescriber, PIN, and Active status badges, with two actions, Edit profile shown only to someone holding ehr.staff.manage and Set signature PIN shown to everyone:

• Edit profile: display name, credentials (comma separated, for example LCSW, PMHNP), NPI, taxonomy code, DEA number (write-only; unlike Tax ID and license numbers, there is no masked preview or any other confirmation shown after saving), licenses (state, number, expiration date, repeatable), supervisor, programs, Prescriber switch, Active switch.
• Set signature PIN: see below.

Anyone else reads under the card's title "Credentials used when you sign documentation. An administrator maintains this profile; your signature PIN stays yours to set.", and, while they have no profile, "An administrator creates staff profiles. Ask them to add yours, then set your signature PIN here."

Each license shows its expiration date in its Expires box: the date entered on this screen, or, for one recorded with a time of day, the day that time falls on in the clinic's time zone. A save that changes the licenses is not made while the clinic's time zone cannot be read, and the screen says so instead, for example "The clinic time zone could not be loaded, so nothing with a date on it can be saved. Reload the page, and tell an administrator if it keeps happening."

Staff directorylink

A table of every staff profile in the organization: name, credentials, NPI, Prescriber badge, PIN status, programs, and Active status. An admin with ehr.staff.manage can edit any profile and reset any staff member's PIN from this table. A PIN reset naming a staff profile this organization does not have is refused with "Staff profile not found", and nothing is written, not even to the audit log. A profile is made only for a current member of the organization, active or inactive, and made active only for one: anything else is refused with "This person is not a member of this organization, so nothing can be assigned to them. Choose a current member.", and nothing is written. The profile of someone who has left the organization, made inactive when they left, can still be edited while it stays inactive.

Signature PINslink

1. From the profile card, select Set signature PIN.
2. If a PIN is already set, enter the current PIN.
3. Enter and confirm a new PIN, 4 to 8 digits.
4. Save. The PIN is hashed (scrypt) and never stored or shown in clear text.

Signing and changing your own PIN both check the current PIN through the same lock: five failed attempts lock it for fifteen minutes for that staff member, whether the failures happened while signing or while trying to set a new PIN. During the lock, only an admin can clear it, immediately, with Reset PIN in the Staff directory; the staff member then sets a new PIN before they can sign or change it again themselves.

7. Service codes and unit ruleslink

Open Settings, then the Service Codes tab.

A service code must be unique by its code and its full set of modifiers; the same code can exist multiple times with different modifier combinations, and modifier order does not matter (HQ, GT and GT, HQ collide as the same code).

Search the list by code or name. Service codes feed programs (which codes a program can bill), appointment types (the default code for a scheduling template), and charge capture, which prices the code a visit names and bills it on a claim (billing guide, sections 2 and 5).

8. Appointment typeslink

Open Settings, then the Appointment Types tab. These are the scheduling templates appointments are booked from: the type comes first on a new appointment and sets its length, its colour and whether it can run by video (clinician guide, section 10).

9. Custom fieldslink

Open Settings, then the Custom Fields tab. Custom fields add extra data capture to client records: the client form asks for every field defined for Client, and the client keeps the answers. A field can also be defined for an Episode of care, an Encounter or a Program enrollment, but capturing custom fields on those records is not built, so nothing asks for those fields or keeps their answers. Fields are grouped by the record they are defined for.

Deleting a custom field definition does not delete data already stored in that field on existing records.

10. Form and workflow definitionslink

Open Settings, then the Forms tab or the Workflows tab. Both use the same versioned, config-as-data lifecycle, but with different available actions. A definition's key cannot be changed after creation once you try to edit it; clone it into a new key instead.

Formslink

Each form has a key, a name, a category (Intake, Assessment, Screener, Treatment Plan, Progress Note, Consent, Discharge, Shift Note, Incident, or Custom), a JSON schema (sections and fields), and optional signature, scoring, print, billing, and attribution settings.

1. New form: choose a key, name, and category, and write the schema as JSON. Every field needs a unique key and a recognized type (text, longtext, number, scale, boolean, date, datetime, choice, multichoice, table, signature, attachment, computed, codeLookup, or clientDataRef). visibleWhen and requiredWhen rules must reference a real field key. Scoring bands must not overlap. The new form saves as version 1, status Draft.
2. Edit: only Draft forms can be edited. Editing a Published or Retired form is rejected; clone it instead.
3. Publish: only from Draft. Publishing automatically retires the previously published version under the same key (if one exists) and links the new version to it. A published form's schema can be viewed (read only) by selecting its row.
4. Retire: only from Published. A retired form stays visible in history but can no longer be assigned to new documentation.
5. Clone: available from any status. Creates a new Draft at the next version number, copying the schema, name, category, and settings, so you can adjust before publishing.

The internal demo tenant is seeded with six published forms, each at version 1. The first is the PHQ-9 depression screener (phq9, category Screener): nine items scored 0 to 3 with a computed total (sum(q1..q9)), severity bands (minimal 0 to 4, mild 5 to 9, moderate 10 to 14, moderately severe 15 to 19, severe 20 to 27), and a non-suppressible critical alert when item 9 (the self-harm item) scores 1 or higher. Its attribution reads "PHQ-9 developed by Drs Robert L Spitzer, Janet B W Williams, and Kurt Kroenke and colleagues. No permission is required to reproduce, translate, display, or distribute it." Three more screeners are seeded beside it, each in category Screener with a computed total, severity bands and an attribution of its own: the GAD-7 anxiety screener (gad7), seven items scored 0 to 3 (sum(q1..q7); minimal 0 to 4, mild 5 to 9, moderate 10 to 14, severe 15 to 21); the PCL-5 post-traumatic stress checklist (pcl5), twenty items scored 0 to 4 (sum(q1..q20); below the provisional threshold 0 to 30, at or above it 31 to 80); and the AUDIT alcohol use screener (audit), ten items scored 0 to 4 (sum(q1..q10); low risk 0 to 7, increasing risk 8 to 15, higher risk 16 to 19, possible dependence 20 to 40), with a warning that can be suppressed when item 9 (an injury related to drinking) scores 2 or higher. The other two are the Progress note (progress_note, category Progress Note) and the Intake assessment (intake_assessment, category Intake), each with service time capture turned on, so signing one is refused until its start and end are filled in. New organizations start with no forms; use these as a reference for the schema shape when building your own library.

Workflowslink

Each workflow has a key, the record it moves (Document, Enrollment, Incident, Claim, or Referral), shown in the Record column and chosen under Record in the form, a list of states (comma separated), and a JSON list of transitions.

1. New workflow: choose a key and the record it moves, list the states, and define transitions as JSON. A workflow that moves a Document must include both a signed and a voided state; the system will not let you remove the signature lock from a document workflow.
2. Edit: only Draft workflows can be edited.
3. Publish: only from Draft. As with forms, publishing a new version automatically retires the previously published version under the same key.

Workflows have no retire or clone action. To supersede a published workflow, create a new draft under the same key and publish it; that retires the old one automatically.

11. Building a formlink

A form is built in a visual builder: open Settings, then Forms, then a Draft form. The JSON view is there too, on its own tab, and round-trips with the builder, so anything you build can be read and edited as JSON and back again.

Sections and fieldslink

A form is a list of sections; a section is a list of fields. Drag a section to reorder it and drag a field to move it within or between sections. Every field carries a key, which must be unique across the whole form, and a label, which is what the clinician reads.

Field types, exactly the set the renderer implements:

The builder only offers what the shared form engine implements. It is derived from the engine rather than listed beside it, so a rule you can build here is a rule the renderer and the server both understand.

Marking a field as protected health informationlink

Each field has a Contains protected health information switch. The panel explains it: "Marks the answer so it is handled and logged as clinical information."

Turn it on for anything that identifies a client or describes their care. Turn it off for administrative values that carry no clinical meaning. The flag drives how the answer is logged, exported and redacted, so getting it wrong is not cosmetic.

Conditional visibility and required ruleslink

Every section and every field can be shown conditionally. Leave the rule on Always to show it every time, or set Show this question when and pick a field, an operator and a value.

Operators: is, is not, is more than, is at least, is less than, is at most, is one of, includes. Numeric operators only accept a number; "is one of" only accepts a list.

Make this question required when works the same way, and it only applies while the question is shown. A hidden field is never required and is never saved.

A rule must name a field that actually exists on this form. The builder refuses a rule that points at nothing, because the engine would silently never match it.

Calculated values and scoringlink

A calculated value takes an expression, for example sum(q1..q9). The panel says the rule that matters: "Every name in it has to be the key of a question on this form."

The score is the form-level version of the same thing: an expression, a short label shown next to the total (for example "PHQ-9"), and a set of bands. Bands must not overlap and must cover the range the expression can produce.

An alert is a rule that fires on an answer rather than on the total: point it at a question, choose when it fires, choose a severity, and write what the clinician is told. An alert that cannot be dismissed is for the answers that must be acted on; leave Can be dismissed on for everything else.

Service timelink

Turn on service time capture for any form that records a billable service. The clinician then gets a start and an end on the note, and signing is refused until both are filled in.

The signature blocklink

The signature block sets who signs, which methods they may use (typed, drawn, PIN), and whether the client signs too.

Co-sign rules are written by role key. A rule names the role that must co-sign a note written by a given role, and the work item that routes a note to a supervisor uses those same keys. If a co-sign rule names a role key nobody in the organization holds, the note will have nobody to route to, so check the keys against your role assignments.

The print templatelink

The print template controls how the form prints and what a PDF contains: header, footer, which sections print, and whether the redisclosure notice is attached.

Previewlink

Preview renders the form exactly as the clinician sees it, using the same renderer. Conditional fields appear and disappear, calculated values recalculate, bands and alerts fire. It is a rehearsal, not a mock-up.

Nothing typed into the preview is saved. The panel says so.

Publishinglink

Publish is available from Draft. Publishing retires the previously published version under the same key and links the new version to it.

Before you publish, the builder shows anything worth a look before you publish: an empty section, a field with no label, a rule that names a missing field, overlapping bands. An empty section blocks publishing.

Publishing does not touch drafts already in flight. A note started on version 1 stays on version 1 and is signed on version 1, so the record says what the clinician actually saw. New notes start on the newly published version.

Cloning and retiringlink

Clone makes the next version as a Draft, copying everything, and is available from any status. That is how you make a change to a published form.

Retire takes a published form out of use. It stays readable in history and on every note already written on it, but it cannot be chosen for a new note.

12. Reminderslink

Open Settings, then the Reminders tab. Adding a template, changing one and switching one on or off are offered only to a holder of ehr.schedule.manage (Manage schedules), the permission the server saves a reminder template with, rather than the ehr.config.manage the other configuration tabs take (section 3). Anyone else reads the templates with no New reminder template button or edit control and each template's active switch disabled, under the line "Changing these settings needs the permission to manage the schedule. You can read them and nothing here asks you to change one."

Templateslink

A template is a channel, a lead time and a body. Channels are email and text message. The lead time is how far ahead of the appointment to send, in minutes, with quick picks for the common ones (one hour, one day, two days, one week).

A template is unique by channel and lead time, so there is one email at one day before, not three.

The body may carry only these placeholders, each in double braces, such as {{date}}: clientFirstName, the client's first name; date and time, the appointment's date and time in its time zone; location, the room or location name; orgName, the organization name; and confirmInstruction, the confirmation instruction. There is no placeholder for the clinician, and a body naming any other is refused, for example "Unknown placeholder clinician. A reminder may use only: clientFirstName, date, time, location, orgName, confirmInstruction". The preview renders them against a sample appointment so you can see the message a client would receive.

A body's confirmation instruction placeholder, {{confirmInstruction}}, reads the clinic's own instruction, kept with its scheduling settings (section 3). While that is blank, or was never set, the reminder sent and the preview both carry the default, "Reply C to confirm or call the office to reschedule."

The preview shows "What a standard client receives" beside "What a consent protected client receives". While the organization has no display name, {{orgName}} is sent and previewed as the default clinic name, NewInstance EHR. For an email, the standard client's From line reads "The sender set on your email channel": the product sets no sender name on a standard client's email, which goes out under the sender your email channel holds. It sets one only on a protected client's email, NewInstance EHR, which the protected client's preview shows.

Deactivating a template stops it planning new reminders. Reminders already planned for existing appointments still send.

The organization email channellink

Email reminders go out through the organization's own email channel. If the organization has not configured one, email reminders do not send. Set it up before you rely on them.

Text message consent and STOPlink

A text reminder is sent only to a number the client has consented to be reached on. No consent, no text, and no error: the reminder simply is not planned on that channel.

A client who replies STOP, STOPALL, UNSUBSCRIBE, CANCEL, END or QUIT has their consent for that number removed at once, so a reply of CANCEL stops texts to that number and cancels no appointment. C, CONFIRM, YES or Y confirms the next appointment within seven days, except from a number more than one client shares, where it confirms nothing and the reply is recorded as ignored. The inbound route is authenticated by the provider signature, not by an API key.

Protected clientslink

For an appointment belonging to a client under 42 CFR Part 2, the body you wrote is replaced entirely with neutral wording that carries only the date and the time. No clinic name, no location, no program, no instructions. This is not configurable, and a template cannot opt out of it.

Reading reminder statuslink

An appointment lists its pending reminders, each with its template name, channel and lead time. After a reminder has been attempted the status says whether it was sent, is queued, or was not sent because no consented contact method existed.

13. Importing clientslink

Open the Clients page and press Import clients.

Preparing the filelink

A CSV with a header row. The importer reads these targets, named as the import screen names them:

• Record number, First name, Middle name, Last name, Preferred name, Name suffix, Date of birth, Sex, Pronouns, Social security number, Language
• Phone, Email, Address line 1, Address line 2, City, State, Postal code
• External id, External id system

A mapping to anything else is refused with "These mapping targets are not supported", followed by the targets it named.

First name, last name and date of birth are required. The organization's numbering assigns every imported client's record number. A record number mapped from the file is kept beside it, as an external identifier under the system import-mrn; an External id the row maps is kept under its External id system, or import when none is mapped, and a row mapping both keeps both. A record number longer than 80 characters fails its row, in the dry run and on commit, in words naming the column it was mapped from and not repeating the number, for example "mrn in column chart must be at most 80 characters" for a column headed chart, and that row is not imported.

Mappinglink

Step two maps each column in your file to a target. The wizard suggests a mapping from the header names and you correct it. A required target left unmapped blocks the next step, and the wizard names which one.

The dry runlink

Step three runs the whole file without writing anything. It reports how many rows would be created and lists every row it could not accept, each naming the row number and the column at fault, for example a date of birth that is not a date.

Read the error list before committing. A dry run that reports five importable rows and one error will, on commit, create exactly five clients.

Committinglink

Commit creates the good rows and skips the bad ones. The import then shows its final counts as Rows in the file, Clients created and Rows with a problem. Rows that failed are listed under the counts, each by its data row with what needs fixing, and raise no work item, so fix those rows and import them again.

What an import does and does not createlink

It creates one client record for each row it accepts, with the status Prospective client, carrying the names, date of birth, sex, pronouns, social security number, phone, email, address, language and external id the row maps, and the record number it maps, under import-mrn, and nothing more. It creates no enrollment and no caseload assignment.

It does not create episodes, consents, coverages, documents, appointments or problems. It does not merge into existing clients: a row whose details look like an existing client is still created, and the pair lands on the Possible duplicate clients queue for a person to decide.

A malformed file, one the importer cannot parse as CSV, is refused before the mapping step.

14. Work queueslink

The EHR home shows a card for each queue that has anything on it, with the open count and the overdue count, and today's schedule beside them. The overdue count, which also puts an Overdue badge beside the queue's name on the Work queues screen, counts only the open items whose due date has passed. An item with no due date, such as an unsigned note, is never counted overdue, just as the queue itself never marks one Overdue.

The clinical, duplicate and integration queues:

The billing queues, from denied claims to authorizations running low on units, are described in the billing guide.

An abandoned draft. A draft whose author's staff profile is no longer active is abandoned: nobody else can finish or sign it. On its open Unsigned notes item, someone who holds Void documents (ehr.document.void) and Author documents (ehr.document.author), EHR Admin and Clinical Supervisor among the seeded roles, is offered Delete this abandoned draft. Its dialog says "Its author is no longer active, so nobody else can finish or sign it. The draft is deleted and cannot be brought back, and its item comes off this queue. The reason is kept in the audit log.", and Delete the draft waits for a Reason of at least three characters. The deletion writes the access log entry an author's deletion writes, with the reason, closes the item as completed, and is written to the audit log with the reason once it is saved. The server refuses a draft whose author is still active, "This draft's author is still active, so the draft stays theirs to finish or delete. Nothing was deleted.", and a deletion with no reason, "Say why this abandoned draft is being deleted, so the next person reading this record knows. Nothing was deleted.", writing nothing for either. Each work item serves whether this is possible as actions.deleteAbandonedDraft, and the deletion is deleteEhrDocumentDraft with its reason.

On the Work queues screen, the Assigned to column names the member of staff an item is assigned to, or a role by the name it carries, such as EHR Admin or Biller. A role that is not one of the ten in section 2 reads "A role your clinic set up", and an item assigned to nobody reads "Nobody yet".

An item is assigned only to somebody who can open its queue, or to a role whose permissions open it. Anyone else is refused, in words naming the queue, and nothing is changed: "This person cannot open the Visits that captured no charge queue, so they would never see this item. Nothing was changed. Assign it to somebody who can open that queue.", and for a role "This role cannot open" in the same words, which is also the answer for a role the organization has no permission group for. The Assign list on a queue offers only the active members of staff who can open that queue, by the same rule, and so does Give it to on a denial, for the Denied claims queue.

An item opening, being assigned or closing shows on an open Work queues screen, and in the queue counts on the EHR home, as it happens, without a reload. That includes the items the product raises by itself: the break the glass reviews and failed webhook deliveries the daily sweep raises and the signature chain mismatches the nightly integrity check finds. A change shows once what caused it is saved, and never for something that failed to save.

An item, whatever its status, also leaves an open Work queues screen, and the queue counts on the EHR home, without a reload once the person reading can no longer see it: when an enrollment in a program through which they reached its client is discharged, when their caseload assignment for that client is ended at once, or, ended with today as its last day, closes at the clinic's midnight (told by the background worker's ehr.caseload.closing job, which runs every five minutes unless EHR_CASELOAD_CLOSING_CRON gives it another schedule), when their staff profile loses a program or is made inactive, when a program is taken off those assigned to them under Assign programs on their EHR product access, when a change of permissions narrows what they can see, because a permission group they hold was changed or deleted, their role or permission groups were changed, or the platform resynced its system permission groups at startup, when a break the glass session of theirs is ended with End session, ends because break glass was taken away from them, or its window passes (section 15), when a signed 42 CFR Part 2 consent naming them is revoked, for an item about its client that the consent let them see, when the client's record becomes protected under 42 CFR Part 2, by an enrollment in a Part 2 program or by a merge with a protected record, and when two clients are merged, for an item of the merged record that they could see only through a break the glass session on the merged record, or, where the record that survives was already protected under 42 CFR Part 2 and the merged record was not, that they could see through a caseload assignment for the merged record, a program it was enrolled in that they are assigned to, or the reach of every client. Each possible duplicate pair a merge closes also leaves an open Work queues screen, and the queue counts on the EHR home, without a reload for whoever saw it through a caseload assignment for the merged record or a program the merged record was enrolled in that they are assigned to. It reaches only someone who could see the item before and cannot now.

An item also comes onto an open Work queues screen, and into the queue counts on the EHR home, without a reload once the person reading can newly see it: when they are given a caseload assignment for its client whose From date is today, an earlier day or left empty, or, given one whose From date is a later day, once that day starts in the clinic's time zone (told by the same ehr.caseload.closing job), when its client is enrolled in a program they are assigned to, when their staff profile gains a program or is made active again, when a program is assigned to them under Assign programs on their EHR product access, when a change of permissions widens what they can see, because a permission group they hold was changed, their role or permission groups were changed, or the platform resynced its system permission groups at startup, when two clients are merged and they reach the record that survives, through a caseload assignment for it, a program it is enrolled in that they are assigned to, or breaking the glass for it, when they break the glass for its client, and when a signed 42 CFR Part 2 consent naming them is recorded, for an item about its client that the consent lets them see.

Only someone who can merge clients, EHR Admin among the seeded roles, sees the Possible duplicate clients queue and works it. A client is checked when it is recorded, whoever records it, the front desk and a clinician whose reach is a caseload included: it is compared with the clients that person can reach, and no others, and that person is told nothing either way. The access log records the person who recorded it reading both records of each pair found, as it does for every registration. Each pair found opens one item, which opens the Clients page where the pair is merged or marked not a duplicate, and either one closes the item as completed. A record that holds claims is not merged: a merge whose record being merged holds a claim, sent or not, is refused with "The record being merged has been billed and holds claims, so nothing was merged. A record that holds claims keeps them and is not merged." Before a merge is sent, the Merge these records dialog says under "This cannot be undone" what it moves: every note, appointment, attachment, enrollment and treatment plan on the record being merged moves to the record that survives, consents stay on the record they were signed against, a record that holds claims is not merged, and the merged record stops being a chart and becomes a pointer to the surviving record. An item opening or closing shows on an open Work queues screen, and in the queue counts on the EHR home, as it happens, without a reload. Mark a pair that is two people as not a duplicate rather than dismissing its item, or a later scan that finds the pair raises it again.

An item is unique by queue, reference type and reference id, so the same note does not appear twice. Each queue's heading on the Work queues screen says what else takes an item off it, for example, on Unsigned notes, "An item comes off this queue when its note is signed, sent for co-signature or deleted as a draft, or when somebody completes or dismisses it.", and, on a queue nothing else closes, "An item stays on this queue until somebody completes or dismisses it."

Completing against dismissinglink

Both close an item and both take it off the count. They do not mean the same thing.

Complete says the work was done: the note was signed, the review was recorded.

Dismiss says the work was not needed. A dismissal takes a note, and the note is what tells the next person why nothing happened.

Reporting counts them separately. Dismissing to clear a backlog makes the numbers look like work that never happened, so it is worth saying this to a team once.

15. The audit pagelink

Open the Audit page from the EHR navigation. It has three tabs: Access log, Break glass, and Disclosures.

Access loglink

Every PHI-scoped action is written to an immutable log before the response is returned. Nothing here can be edited or deleted, even by an administrator. Actions logged, as the Action column and filter name them: Viewed, Searched, Created, Changed, Signed, Exported, Printed, Disclosed, Deleted, Used by the assistant, Broke the glass, and Withheld. Broke the glass is written when a break-the-glass session starts. Withheld is written automatically, for each client an event names, when the event is held back from webhooks because a client it names is protected under 42 CFR Part 2 or has no record, or because whether one is protected cannot be checked. This log exists so every access to a client's protected health information can be reconstructed for compliance, breach investigation, and the accounting-of-disclosures a patient can request. Opening a client's chart to watch it update live is logged the same way, as a read of that client, and carries the break-the-glass session when that is how it was opened.

Each entry records:

• The actor and, once relevant, where the access happened, as the Surface column names it: Dashboard, Client portal, Mobile app, Connected app, Health record exchange, or Automatic. The Actor column names a member of staff by name, or "Unknown staff" when there is no staff profile to name them by, and any other actor without a name by what they were: Client, Someone acting for the client, Connected app, or Automatic. It never shows an id in place of a name.
• The client and the resource type and ID accessed.
• The purpose of use: Treatment, Payment, Clinic operations, Emergency, Client request, Research, or Legal.
• Whether the access happened during an active break-the-glass session, and which session.
• Whether the record is Part 2.
• Request metadata (IP address, timestamp). Never the clinical content itself.

Filter the log by Client ID, User ID, Action, a From and To date, and a "Break-glass only" switch. Select Apply to run the filter or Clear to reset it. A Client ID that names no client of the organization is refused with "Client not found", and so is a client protected under 42 CFR Part 2, for someone without access to Part 2 records and without an active break the glass session on that client. Nothing is written to the log for either.

Break glasslink

A break-the-glass session is started from the client's chart (clinician guide, section 2), and also from this tab, by anyone who may break the glass:

1. Enter the Client ID and a Justification (at least 3 characters).
2. Select Break the glass. This fails if the organization's Break the glass setting (General settings) is turned off.
3. The session lasts for the tenant's configured access window (4 hours by default) and every reviewer role (EHR Admin and Clinical Supervisor by default) is notified that a session started.
4. While the session is active, the staff member can access that one client outside their normal caseload or program scope. Every PHI log entry created during the session is tagged with the session, and its access count increases.
5. The session holder, or a reviewer, can end it early with End session; this is audited and emits an ehr.breakglass.ended event, and the register's Why it ended names which of the two did it. A session also ends by itself, at once, the moment anything takes break glass away from its holder: a permission group they held changed or was deleted, their role or other permission groups changed, they were removed from the organization, the organization was deleted, their access to the health record was disabled or removed, break glass was switched off for the organization, their seat was paused because the plan has fewer seats than members, or the platform resynced its system permission groups at startup. This also emits an ehr.breakglass.ended event, and the session shows as Ended at once, with when and Why it ended; it is never shown as Active again. Only the access window passing on its own ends a session with no event and no reason shown. A session that ends that way is told once to whoever held it, by the background worker's ehr.breakglass.expiry job, which runs every five minutes unless EHR_BREAKGLASS_EXPIRY_CRON gives it another schedule: each run tells the holder's open Work queues screen and EHR home of every session whose window passed since the run before, so the work items it let them see leave both without a reload. Getting the permission back does not revive an ended session: breaking the glass again starts a new one, with a new justification and a new review.

Filter sessions by status: All, Active, Ended, Unreviewed, or Reviewed. Active shows a session nobody ended whose window has not passed, and Ended every other session, one that was ended or whose window has passed, so each session is under the one of the two its badge names. Each session names the member of staff who broke the glass, or "Unknown staff" when there is no staff profile to name them by. An ended session, however it ended, stays Unreviewed until a reviewer acts, since the access it gave happened regardless of why it stopped. A reviewer (someone with ehr.breakglass.review, such as a Clinical Supervisor or EHR Admin) selects Review on an unreviewed session to record an outcome, except their own: reviewing your own break-the-glass session is refused unless you are the organization owner.

• Outcome: Approved, Questioned, or Violation.
• Notes: optional context for the decision.

A session still unreviewed seven days after it started is put on the Break the glass reviews work queue by a daily sweep, once for each session and assigned to nobody, and the organization's owners are notified. Opening the item brings you to the session on this tab, and reviewing the session closes the item as completed. To find sessions waiting for review before then, use the Unreviewed filter.

Disclosureslink

Enter a Client ID to view that client's disclosure history. Once a client ID is entered, select Record disclosure to log one:

The disclosures table lists date, who the records were disclosed to, purpose, method, record types, and whether the Part 2 notice was given. Viewing a client's disclosure history writes a Viewed entry to the access log; recording one writes a Disclosed entry. A disclosure entry is never edited or deleted once created. One a person recorded by hand in error is corrected instead: while it is not yet corrected, its row offers Correct, which opens Correct this disclosure and asks What happened, for example that the records were never sent, in up to 1000 characters. Record correction keeps the entry as it was recorded and shows the correction beside it, as "Corrected, not a disclosure" with its statement, which reads "Correction to disclosure" followed by the entry's identifier, "of" the day the entry is dated, in the clinic's time zone, and what happened; the entry is then no longer counted as a disclosure, and the correction is written to the access log as a Changed entry. An entry is corrected once: a second correction is refused with "This entry in the accounting of disclosures has already been corrected, and an entry is corrected once." An entry the system recorded as claims and statements left is refused with "Only a disclosure a person recorded by hand can be corrected here. This one was recorded by the system when the records were sent or produced, so only whoever supports this system can correct it." Nothing is written by either refusal.

Recording a disclosure, and correcting one, requires the ehr.client.export permission, a stricter permission than the ehr.audit.view used for the rest of this page. Of the ten seeded roles, only EHR Admin holds ehr.client.export by default, so Auditor and Quality Assurance can view this page but cannot record or correct a disclosure from it. Viewing, recording and correcting also require the client to be in scope, the same caseload, program, ehr.client.all, or active break-the-glass rule described in section 2 and the Break glass tab above. An entry on a client whose record was later merged into another is listed under the record that survived, and one recorded by hand is corrected there by whoever may write that record. A disclosure can also name a consent (consentId on recordEhrDisclosure), which must be one of that client's own consents, in any status, a revoked one included. Anything else is refused with "Consent not found", and nothing is recorded.

16. Webhookslink

Open Webhooks from the EHR navigation to manage outbound event subscriptions. Managing webhooks requires the ehr.integrations.manage permission (held by EHR Admin by default), and creating, editing, rotating the secret of, pausing, resuming or deleting a subscription also requires the reach of every client (ehr.client.all), because a webhook is sent events about every client. Each of those saves records the member who made it, and the webhook is delivered only while that member is in the organization and reaches every client; once they leave or lose that reach, its deliveries fail with a reason saying so, and a member who reaches every client takes it over by saving it again and redelivering what failed. The page lists every subscription with its name, URL, an events summary badge (hover for the full list), status, failure count, and last successful delivery.

Creating a subscriptionlink

1. Select New subscription.
2. Provide a name and the destination URL. It must be HTTPS and reachable from the internet: loopback, private, link-local, multicast, and NAT64 addresses are rejected, as is every form of an IPv4-mapped IPv6 address. A hostname that cannot be resolved by DNS is accepted here, but every delivery attempt against it will fail until it resolves.
3. Choose one or more event types, or select All events.
4. If the subscription should ever receive protected health information in event payloads, turn on Include PHI and write an acknowledgment of at least 20 characters confirming a Business Associate Agreement covers the endpoint. Leave it off, the default, and every PHI field the catalog lists for an event type, including clientId on the break-the-glass events, is left out of every payload sent to this subscription.
5. Optionally add custom headers (key and value rows) sent with every delivery. When editing an existing subscription, leave this section untouched to keep the stored headers as they are; add or remove a row to replace the stored set entirely, or remove every row to clear them.
6. Save. A Webhook secret dialog opens showing the signing secret in clear text once, with a Copy button and a Save to Secret Manager option. Copy or save it now; it cannot be shown again. From then on, only a masked preview (for example whsec_••••ab12) is shown.

Managing a subscriptionlink

Each row's action menu offers:

• Edit: change the name, URL, events, PHI settings, or headers.
• Rotate secret: replaces the secret and reopens the same one-time reveal dialog.
• Pause or Resume: manually pause or resume delivery, independent of the automatic pause described below.
• Send test: queues a synthetic ehr.webhook.test event and delivery so you can verify your receiver end to end. Available only while the subscription is active; the menu prompts you to resume it first otherwise.
• Deliveries: opens a log of delivery attempts (event type, attempt number, status, response code, next attempt time, error), filterable by status, with a Redeliver action on any failed or dead delivery to retry it immediately.
• Delete: stops the subscription from receiving further events. This cannot be undone from the dashboard.

Send test and Redeliver share a single throttle per subscription: once every 10 seconds. Using one right after the other on the same subscription, even for different deliveries, waits out the same 10 seconds.

Retries, pausing, and retentionlink

• A delivery is attempted immediately, then retried on the schedule in api.md (1, 5, 15, 60, 240, 720, and 720 minutes between attempts) for up to 8 attempts total. After the 8th failed attempt, the delivery is marked dead.
• A subscription that accumulates 100 dead deliveries (delivery attempts that exhausted all 8 tries; any successful delivery resets the count to zero) is automatically paused.
• While paused, due deliveries are not attempted; they stay pending and are rechecked every 15 minutes, so resuming the subscription delivers the backlog rather than losing it.
• A deleted subscription, or one that is otherwise not active and not paused, fails its pending deliveries immediately instead of retrying them.
• Delivery records are removed automatically 30 days after they are created, regardless of subscription or delivery status. Events themselves are removed 7 days after being dispatched, unless a pending, failed, or dead delivery still references them, which is what keeps Redeliver able to find the event to resend.

See api.md for the exact event envelope, signature headers, and a signature-verification example.