Documentation

Registering the backend app with your EHR once.

Clinical Extract is registered with your EHR vendor as a backend app: a signed-JWT client authentication, read-only system scopes, the study Group. Your organization enables it once, and later studies reuse the connection. This page covers the registration as the specification defines it, then each vendor's version.

Request a demo By EHR

1 The three steps

Register, activate, export.

  1. Register at the vendor's app registration, outside your environment. Clinical Extract is a backend app with system access; its client authentication is a signed JWT (RS384) with its public key as a JWKS, and its scopes are one system/<Resource>.read per exported type. The vendor issues the client ID.
  2. Activate at your organization's EHR: the client is enabled, the FHIR base URL is given and the study Group is named.
  3. Export from Clinical Extract in your environment: the token request, the Group kickoff, the status poll, the NDJSON downloads and the two files it writes.
Registering Clinical Extract with your EHRThree numbered steps from left to right. Step 1, register, at Your EHR vendor (app registration), outside your environment: Application: backend app, system access; Client authentication: signed JWT, RS384, Clinical Extract’s public key, as a JWKS; System scopes: system/Patient.read, system/Group.read, system/Encounter.read, system/Condition.read, system/Observation.read, system/MedicationRequest.read, system/Procedure.read; Issued: client ID. An arrow carries the client ID to step 2. Step 2, activate, at Your EHR (your organization): Application: enabled for your organization; FHIR base URL: your organization’s certified endpoint; Group: the study cohort, by Group ID. An arrow carries the base URL and Group ID to step 3. Step 3, export, from Clinical Extract in your environment: request POST {token-endpoint} (grant_type=client_credentials, client_assertion: JWT signed RS384, scope=system/Patient.read …); request GET {fhir-base}/Group/{id}/$export (?_type=Patient,Encounter,Condition,Observation,MedicationRequest,Procedure, Prefer: respond-async), highlighted; response 202 Accepted (Content-Location: {status-url}); request GET {status-url} (202 Accepted while the export runs, with Retry-After); response 200 OK, JSON manifest (transactionTime, request,, requiresAccessToken, error[],, output[{type, url, count}]); request GET {output-url} (NDJSON, one resource per line); result study.csv, data-dictionary.json (flattened, approved variables only).1REGISTERYour EHR vendorapp registrationAPPLICATIONbackend app, system accessCLIENT AUTHENTICATIONsigned JWT, RS384Clinical Extract’s public key, asa JWKSSYSTEM SCOPESsystem/Patient.readsystem/Group.readsystem/Encounter.readsystem/Condition.readsystem/Observation.readsystem/MedicationRequest.readsystem/Procedure.readISSUEDclient ID2ACTIVATEYour EHRyour organizationAPPLICATIONenabled for your organizationFHIR BASE URLyour organization’s certifiedendpointGROUPthe study cohort, by Group ID3EXPORTClinical Extractin your environmentrequestresponsePOST {token-endpoint}grant_type=client_credentialsclient_assertion: JWT signed RS384scope=system/Patient.read …GET {fhir-base}/Group/{id}/$export?_type=Patient,Encounter,Condition,Observation,MedicationRequest,ProcedurePrefer: respond-async202 AcceptedContent-Location: {status-url}GET {status-url}202 Accepted while the exportruns, with Retry-After200 OK, JSON manifesttransactionTime, request,requiresAccessToken, error[],output[{type, url, count}]GET {output-url}NDJSON, one resource per linestudy.csv, data-dictionary.jsonflattened, approved variables onlyclient IDbase URLGroup ID
Registering Clinical Extract with your EHRThree numbered steps from left to right. Step 1, register, at Your EHR vendor (app registration), outside your environment: Application: backend app, system access; Client authentication: signed JWT, RS384, Clinical Extract’s public key, as a JWKS; System scopes: system/Patient.read, system/Group.read, system/Encounter.read, system/Condition.read, system/Observation.read, system/MedicationRequest.read, system/Procedure.read; Issued: client ID. An arrow carries the client ID to step 2. Step 2, activate, at Your EHR (your organization): Application: enabled for your organization; FHIR base URL: your organization’s certified endpoint; Group: the study cohort, by Group ID. An arrow carries the base URL and Group ID to step 3. Step 3, export, from Clinical Extract in your environment: request POST {token-endpoint} (grant_type=client_credentials, client_assertion: JWT signed RS384, scope=system/Patient.read …); request GET {fhir-base}/Group/{id}/$export (?_type=Patient,Encounter,Condition,Observation,MedicationRequest,Procedure, Prefer: respond-async), highlighted; response 202 Accepted (Content-Location: {status-url}); request GET {status-url} (202 Accepted while the export runs, with Retry-After); response 200 OK, JSON manifest (transactionTime, request,, requiresAccessToken, error[],, output[{type, url, count}]); request GET {output-url} (NDJSON, one resource per line); result study.csv, data-dictionary.json (flattened, approved variables only).1REGISTERYour EHR vendorapp registrationAPPLICATIONbackend app, system accessCLIENT AUTHENTICATIONsigned JWT, RS384Clinical Extract’s public key, as a JWKSSYSTEM SCOPESsystem/Patient.readsystem/Group.readsystem/Encounter.readsystem/Condition.readsystem/Observation.readsystem/MedicationRequest.readsystem/Procedure.readISSUEDclient IDclient ID2ACTIVATEYour EHRyour organizationAPPLICATIONenabled for your organizationFHIR BASE URLyour organization’s certified endpointGROUPthe study cohort, by Group IDbase URLGroup ID3EXPORTClinical Extractin your environmentrequestresponsePOST {token-endpoint}grant_type=client_credentialsclient_assertion: JWT signed RS384scope=system/Patient.read …GET {fhir-base}/Group/{id}/$export?_type=Patient,Encounter,Condition,Observation,MedicationRequest,ProcedurePrefer: respond-async202 AcceptedContent-Location: {status-url}GET {status-url}202 Accepted while the export runs, withRetry-After200 OK, JSON manifesttransactionTime, request,requiresAccessToken, error[],output[{type, url, count}]GET {output-url}NDJSON, one resource per linestudy.csv, data-dictionary.jsonflattened, approved variables only
Figure 1. Registering Clinical Extract with your EHR. The backend app is registered once with your EHR vendor, with Clinical Extract’s public key and read-only system scopes; your organization enables the client ID and names the study Group; Clinical Extract then runs the Group export in your environment. Every EHR page shows this figure in its own vendor’s terms. Resource lists are abridged.

2 What the vendor asks for

What every EHR vendor asks for at registration.

App type
Backend, system-level: no user launch, no patient login. Some vendors call it a System app or a Backend Systems app.
Client authentication
A signed JWT (private_key_jwt, RS384); the public key at Clinical Extract's JWKS URL, or as an uploaded certificate.
Scopes
Read-only system scopes, one per resource type the study reads, plus Group (Listing 1).
Redirect URI
None. A backend app has no browser flow.
Listing 1. The read-only system scopes for the example breast cancer study. Each study's token carries the resource types its protocol names.
system/Group.read          the study cohort, where the export starts
system/Patient.read
system/Encounter.read
system/Condition.read
system/Observation.read
system/MedicationRequest.read
system/Procedure.read

3 Your organization

Enable the client, give the base URL, name the Group.

Activation is your organization's side of the registration: enable the client ID for your instance, tenant or practice; hand Clinical Extract the FHIR base URL (and the token endpoint, when the vendor issues one rather than publishing it in the SMART configuration); and name the study Group, the FHIR Group resource the export runs against. The cohort builder gives your EHR team the criteria and the count for it.

4 By EHR

The same steps in each vendor's terms.

5 Questions

Questions about registration

What kind of app is Clinical Extract to the EHR?

A backend app with system access: no user launches it, no patient signs in. It authenticates with a signed JWT (SMART Backend Services) and asks for read-only system scopes, one per resource type the study reads.

Which scopes does it request?

system/Group.read for the cohort and one system/<Resource>.read per exported type: Patient, Encounter, Condition, Observation, MedicationRequest, Procedure for the example breast cancer study in Listing 1. A study that reads fewer types carries fewer scopes.

Does the vendor need our public key?

Once: as the JWKS URL Clinical Extract serves at /.well-known/jwks.json, or as an uploaded certificate where the vendor takes that. The private key stays in your environment.

What does our organization do after the vendor registration?

Enable the client for your organization, give Clinical Extract your FHIR base URL (and the token endpoint when the vendor issues one), and name the study Group. The EHR pages give each vendor’s exact steps.

How long does registration take?

The registration is a form. Most of the elapsed time is the vendor’s key sync and your organization’s activation, both one-time steps.

Next

See Clinical Extract run on one of your studies.

Tell us which EHR you run and what the study or registry needs. We reply within one business day to set a meeting time.

Request a demo