Overview
When a patient exists in Ritten, the CRM can now fill Ritten's own forms on the patient's chart with the answers already captured in the CRM (Intake Opportunity, Account, Pre-Assessment, and Treatment Episode fields, plus CRM tables such as Medications). The answers become editable, reportable chart data in Ritten instead of a flat PDF attachment. The PDF attachment feature stays available for anything that cannot be mapped.
Before You Begin
A Ritten account must be connected in Settings → EMR → Ritten.
The patient must already exist in Ritten (the Opportunity shows the Ritten patient link, created by "Admit and Send to Ritten").
Your role must be allowed to push data to the EMR (Settings → Roles).
Part 1 — Administrator Setup (Once per Ritten Account)
1. Open the Forms Tab
Go to Settings → EMR → Ritten and open the Forms tab (next to "Data Sync"). It holds the row "Forms on the patient chart."
2. Turn On Form Sending
Switch Send CRM forms to Ritten on. The setting is saved at once and the Fetch Forms button and the View Form Mapping link appear below the switch. Switching it off hides them again and stops users from sending forms.
3. Fetch the Forms
Click Fetch Forms. The CRM downloads the list of forms configured in your Ritten clinic and the clinic's visit types. A message tells you how many forms were listed. The fields of a form are downloaded only when you enable that form (next step), so the list stays light. Repeat "Fetch Forms" whenever the forms change in Ritten: it refreshes the fields of the forms you use and forgets the fields of forms nobody enabled or mapped.
Every Ritten form belongs to a visit. The CRM creates one visit per patient Opportunity the first time a form is sent and reuses it for later forms. There is nothing to choose: the CRM uses your clinic's first visit type that is not billable, or its first individual (non-group) type when every type is billable. The message shown after a send names the visit type that was created.
4. Configure Form Mapping
Click View Form Mapping. You see one panel per Ritten form.
Tick Enabled for sending and click Save. The first time you enable a form its fields are downloaded from Ritten and the panel fills with them. To look at a form's fields without enabling it, or to pick up a field you added in Ritten, click the refresh icon next to the panel's Save button.
For each Ritten field, choose the CRM field that should fill it. Fields are grouped by Intake Opportunity, Account, Pre-Assessment, and, when your clinic uses the Treatment Episodes module, Treatment Episode (values come from the Opportunity's most recent episode).
Default value is sent when the CRM field is empty (or when no CRM field is chosen). Use it for values that are always the same.
For choice fields, type next to each Ritten option the CRM value(s) that mean the same thing (separate several with commas). A CRM value with no match is left blank on the chart and reported to the user.
A Ritten table ("Table - Text" or "Table - Number" section, for example a Medications table) is filled from a CRM table: its picker offers only CRM tables (Medications, Substances of Abuse, Treatment History, Related Contacts, grouped by module). Pick the table, and next to each Ritten column choose what fills it: a column of that table (columns with the same name are pre-picked) or a record field such as the Account's name, which is then repeated on every row. The CRM rows are sent in order; if the Ritten table has a fixed number of rows, only that many are sent and the message after sending says so. Turn on "Dynamic Table Rows" on the Ritten section to receive every row.
Fields marked Not mappable (choice tables, display-only or calculated fields, signatures) cannot be filled through the API.
Required marks fields Ritten insists on. If such a field has no value at send time, the form is not sent and the user is told which field is missing.
Click Save on each form panel you changed.
After a "Fetch Forms" or a refresh, fields or forms that Ritten removed or changed are marked "Needs review" / "No longer in Ritten." Review their mapping.
Part 2 — Sending a Form (Users)
1. Open the Send Option
Open the patient's Pre-Assessment and click Send to Ritten as Form. The same picker is available on the Intake Opportunity as Send Forms to Ritten.
2. Select Forms to Send
Tick the forms to send. A form already on the chart shows "Submitted." Sending it again creates a NEW copy on the chart (Ritten forms cannot be updated), so the CRM asks you to confirm.
3. Send and Review the Result
Click Send To Ritten. The message names each form and what happened:
"submitted to the Ritten chart (n fields)" — done; unmapped or empty fields were left blank.
"already on the Ritten chart (sent); nothing to send" — the values did not change since the last send.
"was not sent: Ritten requires a value for [field]" — fill that CRM field (or ask an administrator to map it) and send again.
"value(s) had no matching Ritten option and were left blank" — the CRM value is not one of Ritten's options; an administrator can map it on the Form Mapping screen.
"the Ritten grid has n row(s): n of m CRM rows sent" — the Ritten table is smaller than the CRM table; turn on Dynamic Table Rows in Ritten to receive every row.
Under the message, Payload shows exactly what was sent to Ritten and Response shows what Ritten answered, so a failed send can be understood and reported without leaving the page.
In Ritten, the form appears on the patient's chart under the visit the CRM created, unsigned, ready for the clinician to review and sign.
Good to Know
Dates are sent in Ritten's date format, numbers as numbers, picklists as the matching Ritten option, names of related records (for example the Account) as text.
Nothing is written to the chart when any check fails: the CRM validates first.
Two clinics (two Ritten accounts) keep separate form lists, mappings, and history.