Query Connector

← Back to Documentation

Query Connector User Guide

Query Connector is a tool that helps public health staff quickly get the patient data they need from hospitals and clinics—without having to call or fax anyone. It connects to many healthcare systems using existing agreements your jurisdiction already has in place, and follows national standards for health data sharing like DURSA and TEFCA.

What does it do?

Query Connector helps you find case-specific information more quickly and easily by:

  • Letting you search for a specific patient using basic details like name and date of birth
  • Running custom clinical queries (based on SNOMED, LOINC, and other standard codes) to find only the data that’s relevant to your needs
  • Showing results in a clear, easy-to-read format—right in your web browser

Behind the scenes, Query Connector is a FHIR client, meaning it speaks the same language many healthcare systems use to share data. It also offers:

  • A web-based interface (UI) for staff who want to search and view data manually
  • An API for jurisdictions that want to connect QC to their own tools or automate their workflows

Why it matters

With Query Connector, you get:

  1. Automated workflows – no more chasing down records by phone or email
  2. Only the data you need – no more digging through large files for one piece of information
  3. Stronger privacy and security – because queries are always focused on just one patient at a time, they return only the minimum necessary information

By helping you find the right data, fast, Query Connector gives you more time to focus on what matters: investigating and protecting public health.

Who is this guide for?

This guide is for anyone using Query Connector – general users seeking additional patient information for their investigations or reporting, admin users who need to create and assign queries to help their teams access necessary information, and super admins who can create and manage user groups, configure servers, create custom queries, and more.

This guide may also be a helpful resource for people hoping to learn more about Query Connector, what it does, and how it could benefit their health department or organization. Because this guide provides in-depth information about features and functionality, it provides a good window into possible use cases for Query Connector (and benefits it could offer your organization).

If there are topics you feel are missing from this guide, we’d like to know – feel free to contact us at dibbs@cdc.gov. We welcome your feedback!

Running a basic query

Running a query allows you to access relevant information from a patient’s medical records, providing contextual knowledge for your investigation, reporting, or research. For example, let’s say you’re conducting an investigation on a patient who tested positive for a certain STI; you may need information about other positive STI test results this patient has received to give you the insights you need for your investigation.

Running a basic query has four steps:

Step 1: Enter patient information

  1. Begin on the Patient Information page. Here, you’ll find a form into which you can input various pieces of patient information.
  2. Enter as much information as you can about your patient – entering all available information increases your likelihood of surfacing the correct medical record. Note: You need to enter at least one piece of patient information in order to run your query. Available form fields include:
    1. First and last name
    2. Phone number
    3. Date of birth
    4. Home address
    5. Medical Record Number (MRN)

If you have super admin user privileges, you’ll also need to choose the Health Care Organization (HCO) you’d like to use; changing the HCO will change the data source you’re querying.

The Patient Information page can also pre-fill certain form fields from URL parameters. Available parameters are:

  • first (First name)
  • last (Last name)
  • dob (Date of birth, formatted as YYYY-MM-DD)
  • phone (Phone number)
  • street (Street Address)
  • street2 (Address line 2)
  • city (Address city)
  • state (Address state abbreviation, e.g. MN)
  • zip (Zip code)
  • mrn (Medical Record Number)
  • server (Health Care Organization)

For example, if you navigate to /query?first=Hyper&last=Unlucky&dob=1975-12-06, the First name, Last name, and Date of birth fields would be pre-filled; the Phone number, Home address, and Medical Record Number fields would be blank.

  1. Once you’ve completed the form on this page, click the Search for Patient button.

Step 2: Select your patient

The Select a Patient page displays a summary of all the patient records that match the search criteria you entered on the previous page. Choose the record you need and then click Select Patient in the Actions column.

Step 3: Select your query

On the Select a Query page, use the dropdown menu to see a list of all the queries you can run against the patient’s records.

Queries in the menu are added by your admin team based on your needs and area(s) of specialization. If you don’t see the query you need, please contact a member of your admin team.

Once you’ve chosen the query you need, click Submit.

Step 4: View patient records

The Patient Record page contains your patient’s medical record. The page is divided into four sections:

  • Patient Demographic Information
  • Observations
  • Encounters
  • Conditions

Use the left navigation to skip ahead to a given section, and browse the content on this page until you find the information you need.

To protect patient privacy, Query Connector doesn’t allow you to download or export patient records.

Advanced features (for admins and super admins)

Query building

Building a query using a template

Admin users are able to create queries for their team – in other words, they’re the ones determining which diagnoses, lab test results, observations, and more (related to given conditions) their teams can search patients’ medical records for. Only admin and super admin users are able to create queries; standard users are only able to run queries.

  1. To build a new query, visit the Query Library page. This page lists all of your team’s existing queries.
  2. Click the Create Query button at the upper-right corner of the screen. This will bring you to the Custom Query page.
  3. If the medical condition(s) you’re looking for are already in the template library, select them using the checkboxes. If you don’t see the condition(s) you need in the list, you’ll need to create a custom query.
  4. For custom queries: First, add a name for your query – something short and descriptive is best.
  5. Select all of the conditions to be encompassed by this query. If, for example, you’re creating a query related to an STI panel, you might select Chlamydia, Gonhorrea, and Syphilis. Selected conditions will appear in blue boxes beneath the search bar. When you’ve selected the conditions you want, click the Customize Query button.
  6. Next, select all of the lab tests, conditions, and medications you’d like to include in your query. Click into each category to reveal the available list of options, and select options using the checkboxes.
  7. When you close out of the side panel, you will see that the number to the right of the value set row has updated to indicate how many codes are included in the query.
  8. To add a new condition, click on + ADD on the left side next to the Conditions label.
  9. When you’re done, click the Save Query button. Your query will now be available to all system users.

Creating a query by adding additional codes (not using a template)

It’s possible that the template library doesn’t have the query you need; in this case, you’ll need to create a query without relying on a template. To do so, follow these steps:

  1. Create a query (see above) and select the Start from scratch link underneath Start from template(s).
  2. Select the relevant checkboxes for a value set or code that you would like to add to the query. A value set is a collection of related codes for easy reference.
  3. Once you’ve selected the checkboxes for the codes you would like to add to the query, click on the Next: Update query button at the top-right corner.
  4. You have created the query. If you would like to add additional codes, click on Additional codes from library on the lefthand side of the page. Then click on the Add from code library button in the upper-right corner.

Managing codes

You may need to update value sets to reflect your team’s current areas of focus. To edit the codes contained in different value sets, visit the Manage codes page and take the following steps:

  1. Click on the settings gear in the upper-right corner to navigate to the Code library page.
  2. Check or uncheck the relevant value set to show the codes in the value set.
  3. Click Edit codes in the codes section for the value set. Note: You can edit only the value sets that you have created.
  4. You can search for or filter codes at the top of the page to find the codes you’re looking for.
  5. If you want to add a new value set to the code library, you can click on Add value set in the top-right corner.

Audit log

The audit log provides an easy-to-use view into your team’s activity. Here, you can see which queries your team members are running, and when.

You can search for a specific user or query by using the search box at the upper-right corner of the page. To refine your results list, filter by user name, action(s) (in other words, the query or queries the user ran), and date range.

Because snippets in the Message column may contain patient ID numbers, you can’t currently download or export audit log content.

Security features

Access management

Once a user’s identity has been verified (authenticated), super admins can manage permissions for that user – in other words, determine what functionality they can access within the app.

Super admins can manage all users’ permissions on the User management page. Here, you assign each user a permission level (standard, admin, or super admin), and also assign users to a team (called a group in the app). When you create a user on this page, you can add their name and permission level, but each user will still need to authenticate with the IdP before accessing QC. By default, when a user first logs into Query Connector without this preconfiguration step, they will have the lowest permission level (standard) and not be assigned to any user groups.

User groups function as an additional safeguard to manage access. Assigning users to a group simplifies the process of providing access to queries; rather than giving individual users access to queries one at a time, you can provide or revoke query access to a group, saving time. This also ensures that authenticated individuals do not have the ability to access any patient data that is not pertinent to their investigative focus.

To manage a user group, take the following steps:

  1. Click on the settings gear in the upper-right corner to navigate to the User management page.
  2. Click the User tab to view existing users, their permissions levels, and the group(s) they belong to.
  3. Click the Add user button to enter the first name, last name, and email address of a user. You can also set their permission level at this time.
  4. Click on the User groups tab to view existing user groups.
  5. Click the Create group button to enter the name of a user group. Give the group a unique, descriptive name.
  6. Click the Next: Assign members button to select which members of the organization should be a part of this group.
  7. Members and assigned queries can be further modified by clicking on their respective hyperlinks. Standard users will only have the ability to run queries that are associated with the group assignment(s).
  8. You can also edit group names here, and delete a group if it’s no longer relevant or active.

FHIR server authentication

Users with super admin privileges can configure connections to the servers the Query Connector uses on the FHIR server configuration page. To add a new server, take the following steps:

  1. Click the Add server button at the top-right corner of the page. This will bring up a dialog box.
  2. In the dialog box, add the server name, its URL, and the authentication method you’d like to use. You can also choose to disable certificate validation, although this isn’t recommended if you’re working with servers that contain real patient data.
  3. Click the Add server button to add the server to your library.

Query Connector currently supports the following three authentication methods:

  1. Provide a valid Auth Bearer token that Query Connector sends along with our FHIR requests
  2. Standard client_credentials OAuth flow where you provide a client ID and client secret
  3. SMART on FHIR with asymmetric key exchange

Note: The authentication method available to you is determined by the server you’re using.

Single Sign On (SSO)

Query Connector relies on external Identity Providers (IdPs) for access management and supports a wide range of IdPs, which means that your team can choose the option that works best for you.

Single sign-on (SSO) is configured as one of the Identity Provider (IdP) options Query Connector supports. SSO simplifies access by allowing users to log in through their preferred, trusted Identity Provider, reducing the administrative burden of accessing Query Connector. It also improves security by centralizing permission management and minimizing the risk of unauthorized access. When a user clicks the Sign in button, they’ll be redirected to their organization's Identity Provider and authenticated using their existing credentials.