Managing Queries

There are two types of queries in Vault EDC: system and manual queries. Vault generates system queries by running checks on data and creating a query when data doesn’t meet specifications defined during study design. For example, Vault creates a system query when an entered date is outside a certain range. Manual queries are those created by a Clinical Research Associate (CRA) or Data Manager.

For query information specific to Clinical Research Coordinators (CRCs) and Principal Investigators, see Answering Queries.

Prerequisites

Required Permissions

Users with the standard CDMS Clinical Research Associate, CDMS Data Manager, and CDMS Lead Data Manager study roles can perform the actions described above by default. If your vault uses custom Study Roles, your role must have the following permissions:

Type Permission Label Controls
Standard Tab Review Tab

Ability to access the Review tab
Functional Permission Open Query

Ability to create new (open) queries and comment on queries without moving them into the Answered status
Functional Permission Close Query

Ability to close queries

If your Study contains restricted data, you must have the Restricted Data Access permission to view it.

Learn more about Study Roles.

Answering Queries: If you have the Open Queries permission, commenting on a query will not move it into the Answered status.

Viewing Queries

From Review > My Studies > Queries, you can see a listing of all queries, including Event Date queries, from Sites that you have permission to access. Vault lists totals of queries by status at the Site and Subject levels, in the Open Queries and Answered Queries columns. See below for details about those statuses.

Click to open a query. Vault automatically opens the Form or Event that the query is on. From here, you can comment on or close the query.

Note that if an Item with an open query is hidden in Data Entry, review users can only close the query, not comment on it.

You can view closed queries with three (3) or more comments from the form that the query is on. The closed query is displayed next to the Event Date (for Event Date queries) or Item (for Item queries) that the query was opened about.

Query Teams

Each query has a badge indicating which team created it. The Query Team for a query is only shown for queries when the study is enabled for Team Query Restrictions in Studio.

If your study uses the Team Query Restrictions feature, only members of the same team as the query creator can close a query, unless you have the Close All Queries permission, in which case you can close any query regardless of Query Team. If a query is created by one team, for example, the Clinical team, then only members of that team can close the query. In this example, a member of the Data Management team would be able to comment on the query, but that user wouldn’t be able to close it. You can still view and comment on queries created by other teams. The selected Query Team will be visible in the UI and will display in the Query Detail Listing and the SYS_Q dataset of the Study Data Extract.

When a user has multiple Study Roles, that user can use the dropdown menu in the Query Team field to select the role in which they are responding to a query. Users with multiple roles in different query teams at different sites can only select a team based on the user’s role at the site that received the query.

When Team Query Restrictions are enabled, users can choose which Query Team to assign to System queries in study-level settings. Learn more about study settings.

Enabling Team Query Restrictions and the Query Detail Listing: When the Team Query Restrictions study setting is not enabled, the Role column in the Query Detail Listing is populated with the user’s current role at the time of job generation. This information is not recorded in the query record. When the Team Query Restrictions setting is enabled in an ongoing study, the user’s role and team are stored on the query record at the time of the query action for queries moving forward and will populate in the Roles and Teams columns in the Query Detail Listing. Queries that were created prior to the Team Query Restrictions setting being enabled are not assigned a query team. If you want to keep the current roles for existing queries in the Query Detail Listing, we do not recommend that you enable Query Teams in an ongoing study.

System Queries

Vault runs a check and creates a system query on any item value that is out of a defined range. That range is defined during study design.

Queries on Items Hidden by Progressive Display: While Vault doesn’t create edit check queries on hidden or disabled Items, rule-based queries may still open on Items that have been hidden or disabled by Progressive Display depending on the controlling Item.

The following system query types are defined automatically:

  • Required: When creating an Item Definition, a study designer can choose to mark a field as required. If this field is left empty when a form is submitted, Vault creates a system query (“This field is required.”).
  • Range: When creating an Item Definition, a study designer can define a range for a field value. If the entered value is outside of that range, Vault creates a system query (Value is out of range.). Note that this query type is only for numeric values, not dates.
  • Future Date: When creating an Item Definition, a study designer can disallow future dates. If a user enters a future date, Vault creates a system query (Future dates are not allowed.).
  • Future Date (Event Dates): When creating an Event Definition, a study designer can indicate that future dates aren’t allowed. Vault can then create a system query on any Event Date that is later than the current date when entered.
  • Out of Window (Event Dates): When creating an Event Definition, a study designer can create a window of allowed dates for an Event. If configured, Vault can create a system query any time an Event Date falls outside of this window.

Study designers can define additional data validation rules in Studio. Based on those rules, Vault EDC can create additional system-generated queries.

When a system query is manually closed, that same system query will not re-fire when forms are resubmitted.

If you have the View Query Rules permission, and you are able to access the EDC Tools area, you can view a list of all data validation rules for queries in EDC Tools > Query Rules.

Opening Manual Queries

You can open queries from a Form in the Review tab. To open a query in the Reviews tab:

  1. From the Review tab, navigate to the Form or Item you want to open a query on.

  2. For Item queries, click the Open Query icon on the Item. Query on an Item in the Review Tab

  3. For Event Date queries, click the Open Query icon on the Event Date. Query on an Event Date in the Review Tab

  4. Enter your comment in the text entry field. New Query Dialog Note that query messages have a 500 character limit. A best practice is to avoid using special characters, as they may not appear correctly in export files.
  5. Click Save. Vault creates the query.

Your new query now displays to data entry users as an Open query that they need to answer. This query also displays in the Queries listing in the Review tab.

Querying Read-only Items and Cross-Form Derived Items: Vault doesn’t allow you to open manual queries against read-only Items or Cross-Form Derived Items.

Commenting on a Query

You can comment on a query.

  1. Navigate to the Event, Form, or Item on which there is an open query.
  2. Click the Open Query icon.
  3. Click Reply (for manual queries) or Comment (for system queries).
  4. Enter a comment.
  5. Click Save.

Commenting on a query will only move it to the Answered status if you have the Answer Query permisssion.

Commenting on Queries against Read-only Items: Vault doesn’t allow you to comment on system-generated queries against read-only Items.

Closing Queries

Once a system or manual query is resolved, and no further actions are required, you can close a query. Note that you can immediately close a query you create, without a user answering the query.

Vault automatically closes system queries if a user updates the value to value that passes the associated edit check.

  1. Navigate to the open query. The Answered Query icon indicates that the query was answered.
  2. Optional: Enter a comment.
  3. Click Close Query.

Reopening Queries

You can reopen a manual query if additional action or discussion is required. Note that you may only reopen queries with three (3) or more comments.

To reopen a query:

  1. Navigate to the closed query.
  2. Click Reopen.
  3. Enter a comment.

Vault returns the query to the Open status.

External Queries

You can push queries from external sources to EDC using the Query API. With the Query API, you can define source information when opening, answering, or performing other query actions.

Some or all of the following source information can be pushed:

  • Source System Name: Name of the system that added the query from outside of EDC
  • Source User: Name of the user that added the query from outside of EDC
  • Source Type: Source type of the query
  • Source ID: Unique identifier from the source of the query

Open query displaying source information

The character limit for Source System Name is 100 characters. For example, “JReview.” The character limit for Source User is also 100 characters. The limit for Source Type is 30 characters and the limit for Source ID is 64 characters.

The source information is displayed in the Data Entry UI and the Review UI for queries on Events and Items when the source type is “external_v.”

Retrieving Data

Query source information can be obtained from the Query Detail Listing job CSV file, system datasets (SYS_Q and SYS_QT) in the Study Data Extract file, and the Query API.

The information displayed in each location is as follows:

Location Source Information
Query Detail Listing CSV Source User, Source Type, Source System Name, Source ID
SYS_Q Dataset Source User, Source Type, Source System Name, Source ID
SYS_QT Dataset Message Source User, Message Source Type, Message Source System Name, Message Source ID
Query API Check the Queries source system information chart on the CDMS Developer Portal

Query Statuses & Icons

Queries in Vault have three statuses: Open, Answered, and Closed. These statuses indicate which actions have been taken and what still needs to occur on a query.

Vault displays the badge icons on top of the Event or Form status icons. Vault then displays the full status icon for queries in the query itself.

Badge Icon Name Status
Open Query Badge Open Open indicates that a query has not been answered. The Open Query badge displays in the casebook schedule on the queried event or form's existing status icon, while the Open Query icon displays on the query itself. Vault lists open queries in the task bar.
Answered Query Badge Answered Answered indicates that a query has been addressed. For example, the site has responded with a reason for the queried value. The Answered Query badge appears in the casebook schedule on the queried Event or Form’s existing status icon, while the Answered Query icon displays on the query itself.
N/A Closed Closed indicates that a query requires no further action or discussion. A CRA or Data Manager can reopen a closed query if needed.

Rules in EDC Tools

Lead data managers and other users with access to the EDC Tools area can perform additional actions on rules there:

  • In EDC Tools > Rules, you can view details about a rule, including its expression.
  • In EDC Tools > Job History, you can view a history of any Run Rules jobs that have been run.

See Managing Rules for details.