How do I connect Nookal?

Cliniko and Nookal connections require a paid plan.

You connect your practice software once, then choose the exact appointment and patient each time you record. Small Mercy reads your diary only when you ask it to, never mirrors your patient list in the background, and writes nothing into your practice software until you confirm a note or a letter.

Nookal is connected once for the whole practice by an organisation owner or an integration administrator, and then each clinician is mapped to their own Nookal practitioner and location. If you are a clinician and Settings → Integrations → Nookal says your Nookal practitioner and location have not been mapped yet, the rest of this page is for your practice admin — send them the link.

Australian and New Zealand organisations, on the AU cell, connect through Nookal’s Australian API service. United Kingdom organisations connect through Nookal’s European API service. In every one of those regions, the connection brings in today’s appointments, files a confirmed note as a draft treatment note, and can file a confirmed letter as a PDF copy on the patient’s record. Neither a Basic Key nor the API service it connects through says where Nookal stores the account — check that with Nookal.

Before you start

• You are the organisation owner or an integration administrator in Small Mercy, and you can complete a second sign-in check — your authenticator code, your Small Mercy password, or a passkey.
• Australian and New Zealand organisations are connected to Nookal’s Australian API service, and United Kingdom organisations to Nookal’s European API service. Small Mercy does not determine an account’s storage region from the Basic Key alone, and the API service’s region does not establish it either.
• You can sign in to Nookal as a user who may manage Practice → Connections.

1. Create an API v3 OAuth client for Small Mercy in Nookal

In Nookal, open Practice, then Connections → API v3.0, and choose Create New Client.

Nookal creates the client the moment you choose Create New Client. The form that opens is already editing a live client with its Client ID assigned; Cancel does not undo the creation. If you abandon one, remove it from the list rather than leaving an ungranted client behind.

Make it a dedicated client for Small Mercy — never reuse one built for another product — and grant only what Small Mercy uses:

• Client Note — write Small Mercy, so anyone reading the list later knows what the client is for.
• Locations — only the locations whose diaries Small Mercy may read.
• Queries — Locations, Staff, Clients and Appointments for diary and patient preview. Add Clinical Notes only if you will file draft notes, so Small Mercy can read them back. If you will file letters, also grant the client-file query group used by clientFile and multipleClientFile, so Small Mercy can read the uploaded PDF back after activation. Small Mercy does not query Cases.
• Mutations — none for appointment reads or linking a Nookal patient in Small Mercy. For note filing, grant only addTreatmentNote. If you will file letters, also grant uploadClientFile and activateUpload. Leave the other mutations off.

Grant the least you can. A wider grant is a wider blast radius if the credential is ever misused. The reads above and the filing functions you use are the only Nookal permissions Small Mercy needs.

The Client ID is shown on the form. The Basic Key is behind Reveal the ‘Basic Key’ – One time Only: it is the password-equivalent secret and Nookal will not show it again, so reveal it only when you are ready to paste it straight into Small Mercy in the next step — not into a document or a message. Choose Save once the grants are set.

Nookal expires an OAuth client that has not been used for 30 days. Ordinary use of Small Mercy keeps it alive; if the list ever shows Client Expired against Small Mercy’s client, create a new one and connect it — the old key is dead at source.

2. Connect it as the practice, in Small Mercy

Go to Settings → Integrations → Nookal. Only an organisation owner or integration administrator sees Connect your practice.

Fill in:

• Client label — what your practice calls this connection. For your reference only.
• Client ID — for your reference only. Small Mercy does not authenticate with it.
• Basic Key — the secret from step 1. Small Mercy encrypts it on its own server and never returns it — not to you, not to anyone else in your practice.

You will be asked to prove it is you a second time before the credential is stored. Small Mercy also refuses a credential that is already connected to a different Small Mercy organisation.

Once connected, the page shows your practice’s Nookal locations and staff as Small Mercy read them, and a Re-check action that reads them again. Small Mercy remembers what it saw; if a location’s time zone or the staff list changes in Nookal later, Re-check is how Small Mercy learns about it, and it will ask you to before it acts on a mapping that no longer matches.

3. Map each clinician

A practice credential on its own never lets every Small Mercy user act as every Nookal practitioner. Under Clinician authority, map each participating clinician to one Nookal practitioner and one location.

Unmapped clinicians are told their Nookal practitioner and location have not been mapped yet, and can go no further. If a practitioner or location later disappears from Nookal, Small Mercy drops the mapping rather than quietly acting on a stale one, and an admin re-maps it. Re-mapping a clinician to a different practitioner or location takes effect on their next diary read.

4. Set the draft-note template

Small Mercy files a confirmed note into Nookal as a Draft treatment note, written into one text field of a template you choose. Build a purpose-made template rather than reusing a clinical one.

In Nookal, open Manage → Clinical → Clinical Templates and choose Create Template. Build a treatment-note template with a single text field, and name it so it is obviously Small Mercy’s — for example Small Mercy Clinical Note. (Setup → Extensions → Create Template is a different thing: those are plan and NDIS templates, and Small Mercy does not use them.)

Then, in Small Mercy under Draft-note template, enter the Template name, the Template ID and the Text field ID:

• Template ID — in Nookal, open the template for editing (Manage → Clinical → Clinical Templates → Edit). The address bar ends /clinicaltemplates/edit/<number>, and that number is the Template ID — for example 19. You can also paste that address straight into the Template ID box; Small Mercy reads the number out of it.
• Text field ID — Nookal’s screens do not show a field id. Nookal numbers a template’s fields from 0, so for the single-text-field template above, the Text field ID is 0. If a template has more than one field, count from the top starting at 0.

Save this template becomes available only after the name, Template ID and Text field ID are valid. A name on its own does not configure the template.

Small Mercy always writes the note as a Draft and then reads the created record back to confirm it landed on the exact patient, case, appointment and practitioner it was aimed at. See Sending notes and letters, and what to do when a delivery stops for what that check does and does not prove.

5. Each clinician links patients and starts consults

With the practice connected and their mapping in place, every clinician can:

• see today’s appointments for their mapped practitioner and location on the dashboard and in Capture, and start a consult on one with a single tap — see Today’s appointments and starting a consult;
• open Your Nookal diary on the integration page for any day, pick an appointment, preview the Nookal client, and explicitly link or import the Small Mercy patient.

Nothing is linked automatically. Small Mercy suggests local matches on exact name and date of birth, but you either confirm an existing Small Mercy patient or add a new one from the minimum demographics — name, date of birth, sex. No clinical history is copied in either direction.

Troubleshooting

• Small Mercy cannot read which locations a practitioner works at (nookal_practitioner_all_locations) — in Nookal, set each visible practitioner’s staff record to their specific location(s), rather than All locations. Small Mercy cannot safely guess which diaries that setting permits.
• The API client is not granted every practitioner location (nookal_locations_not_granted) — grant the client every location its practitioners use, or restrict those practitioners to the locations already granted.
• No active locations (nookal_no_active_locations) — grant the API client at least one active location.
• No active providers (nookal_no_active_practitioners) — make sure at least one practitioner is an active provider at a granted location.
• Inactive location returned (nookal_inactive_location) — check the client’s location grants and that each covered location is active.
• Inactive practitioner returned (nookal_inactive_practitioner) — check that practitioner’s active status and provider setting.
• Unsupported location time zone (nookal_location_timezone_unsupported) — set that location’s time zone in Nookal to a standard time zone.

These are practice-admin changes. If you are connecting for the first time, make the change in Nookal and retry Connect with the Basic Key you have just revealed. If the practice is already connected, the owner or integration administrator should use Re-check in Small Mercy after the Nookal change; Nookal does not show the existing Basic Key a second time. A clinician who meets one of these errors while using their diary should ask their practice admin to make the change and re-check the connection.

• “Nookal returned an unusable response” — this remains the fallback when Nookal returns malformed data or an older client cannot identify a specific remedy. Ask your practice admin to review the client grants and contact Small Mercy support with the error if it persists.
• The API v3 client is missing the query grant — it needs the Queries grant described in step 1 above. Without it, Nookal refuses the connection.

Turning it off

Use Disconnect on the Nookal page. That removes the organisation credential and every clinician mapping that hung off it. Then delete the OAuth client in Nookal as well, so it is dead at source and not merely unused.

Disconnecting — or deleting data in Small Mercy — does not remove notes or letters already filed into Nookal. Those live in your practice’s own Nookal account and are managed there.

If any delivery is still in an uncertain state, Small Mercy asks you to resolve it first — disconnecting would throw away the only record of what may have been written.