CreateSearch - Save a new search EditSearch - Edit a search DeleteSearch - Delete a search GetSearch - Retrieve details of a search GetSearchesForUser - Retrieve a list of searches that the specified user has permission to view GetSearchQueue - View searches in the queue AddSearchToQueue - Add a search to the queue UpdateJobSchedule - Schedule a search CancelSearchQueueItem - Cancel a queued search DeleteSearchQueueItem - Remove a search from the queue LoadSearchResults - Retrieve the results of a completed search in columnar view LoadSearchResultsFrequencyView - Retrieve the results of a completed search in frequency view LoadSearchResultsCrossTabulationView - Retrieve the results of a completed search in cross tabular view GetRequestedEforms - Retrieve the details of all eForms with Requested status for all subjects in a study |
These routines cover a range of Data Reporter search tasks.
This page includes lists of the classes and enumerations required.
CreateSearch |
Create and save a new search.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
query |
QueryManagement.QueryDefinition |
Definition of the search which is to be stored in the database |
public static eSearchAdminResult CreateSearch(UserProperties user, QueryDefinition query) |
Output
· Return code indicating success or failure
EditSearch |
Edit the parameters of an existing search.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
query |
QueryManagement.QueryDefinition |
Definition of the search to be edited |
public static eSearchAdminResult EditSearch(UserProperties user, QueryDefinition query) |
Output
· Return code indicating success or failure
DeleteSearch |
Delete an existing search definition from the database. This is not the same as removing a search from the queue.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
queryName |
string |
Name of the search to be deleted |
sharingLevel |
QueryManagement.eSharingLevel |
Indicates who can see the search (private, public, site or subject group) |
sharingScope |
string |
The user, site or subject group that this search is shared with. Leave this blank for a public search, or specify the user, site code or subject group code. |
public static eSearchAdminResult DeleteSearch(UserProperties user, string queryName, eSharingLevel sharingLevel, string sharingScope) |
Output
· Return code indicating success or failure
GetSearch |
Retrieve the details of a saved search.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
queryName |
string |
Name of the search to be retrieved |
sharingLevel |
QueryManagement.eSharingLevel |
Indicates who can see the search (private, public, site or subject group) |
sharingScope |
string |
The user, site or subject group that this search is shared with. Leave this blank for a public search, or specify the user, site code or subject group code. |
queryDefinition |
QueryManagement.QueryDefinition |
Definition of the search to be populated and retrieved |
public static eSearchAdminResult GetSearch(UserProperties user, string queryName, eSharingLevel sharingLevel, string sharingScope, ref QueryDefinition queryDefinition) |
Output
· Return code indicating success or failure
· QueryManagement.QueryDefinition
GetSearchesForUser |
Retrieve a list of searches that the specified user has permission to view.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
public static List<QueryDefinitionInfo> GetSearchesForUser(UserProperties user) |
Output
· List<QueryManagement.QueryDefinitionInfo>
GetSearchQueue |
View the searches that are in the queue. Only includes searches that the current user has permission to view.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
public static List<QueryQueueItem> GetSearchQueue(UserProperties user) |
Output
· List<QueryManagement.QueryQueueItem>
AddSearchToQueue |
Add a search to the queue.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
serviceLocation |
string |
Location of the QueryManagement service |
queryName |
string |
Name of the search to be added |
sharingLevel |
QueryManagement.eSharingLevel |
Indicates who can see the search (private, public, site or subject group) |
sharingScope |
string |
The user, site or subject group that this search is shared with. Leave this blank for a public search, or specify the user, site or subject group code. |
jobId |
string |
ID of the search to be added |
runImmediate |
bool |
Specify 'true' to run the search immediately, or 'false' to run it based on the associated schedule |
public static eSearchAdminResult AddSearchToQueue(UserProperties user, string serviceLocation, string queryName, eSharingLevel sharingLevel, string sharingScope, ref string jobId, bool runImmediate) |
Output
· Return code indicating success or failure
· String (via the jobId “ref” parameter)
UpdateJobSchedule |
Update the schedule for a search in the queue.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
serviceLocation |
string |
Location of the QueryManagement service |
jobId |
string |
ID of the search to be scheduled |
schedule |
string |
Details of the schedule View formats |
public static eSearchAdminResult UpdateJobSchedule(UserProperties user, string serviceLocation, string jobId, string schedule) |
Output
· Return code indicating success or failure
CancelSearchQueueItem |
Cancel a queued search so that it does not run/stops running. If the search has been scheduled, all further scheduled runs will also be cancelled. After cancellation, the search will remain in the queue.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
searchQueueItemId |
string |
ID of the search to be cancelled |
public static eSearchAdminResult CancelSearchQueueItem(UserProperties user, string searchQueueItemId) |
Output
· Return code indicating success or failure
DeleteSearchQueueItem |
Remove a search from the queue. This does not delete the search from the database.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
searchQueueItemId |
string |
ID of the search to be removed |
public static eSearchAdminResult DeleteSearchQueueItem(UserProperties user, string searchQueueItemId) |
Output
· Return code indicating success or failure
LoadSearchResults |
Retrieve the results of a completed search as a standard columnar table. The results will be filtered to only include subjects and data that the current user has permission to view.
Input
Parameter |
|
Description |
user |
User.UserProperties |
Details of the current user |
jobId |
string |
ID of the search to be scheduled |
fileStore |
string |
Location of the search results |
enforceUserAccessPermissions |
bool |
Specify 'true' to only retrieve data that the user has permission to view. Specify 'false' to retrieve all data irrespective of permissions. |
public static QueryResult LoadSearchResults(UserProperties user, string jobId, string fileStore, bool enforceUserAccessPermissions) |
Output
· QueryManagement.QueryResult
LoadSearchResultsFrequencyView |
Retrieve the results of a completed search as a frequency table.
Input
Parameter |
Type |
Description |
user |
User.UserProperties |
Details of the current user |
jobId |
string |
ID of the search to load results for |
fileStore |
string |
Location of the search results |
enforceUserAccessPermissions |
bool |
Specify 'true' to only retrieve data that the user has permission to view. Specify 'false' to retrieve all data. |
searchName |
string |
Default filename for downloaded frequency report (omit this parameter to only view results in browser) |
public static DataTable LoadSearchResultsFrequencyView(UserProperties user, string jobId, string fileStore, bool enforceUserAccessPermissions, out string searchName) |
Output
· DataTable (C#)
· String (via the searchName “out” parameter)
LoadSearchResultsCrossTabulationView |
Retrieve the results of a completed search as a cross tabular table.
Input
Parameter |
Type |
Description |
user |
User.UserProperties |
Details of the current user |
jobId |
string |
ID of the search to be scheduled |
fileStore |
string |
Location of the search results |
enforceUserAccessPermissions |
bool |
Specify 'true' to only retrieve data that the user has permission to view. Specify 'false' to retrieve all data. |
verticalQuestion |
string |
Code of the question whose values will form the columns of the output |
horizontalQuestion |
string |
Code of the question whose values will form the rows of the output |
searchName |
string |
Default filename for downloaded cross tabular report (omit this parameter to only view results in browser) |
public static DataTable LoadSearchResultsCrossTabulationView(UserProperties user, string jobId, string fileStore, bool enforceUserAccessPermissions, string verticalQuestion, string horizontalQuestion) |
Output
· DataTable (C#)
· String (via the searchName “out” parameter)
GetRequestedEforms |
Retrieve the details of all eForms with Requested status for all subjects in a study.
Input
Parameter |
Type |
Description |
user |
User.UserProperties |
Details of the current user |
studyId |
id |
ID of the study |
public static List<QueryEform> GetRequestedEforms(UserProperties user, int studyID) |
Output
· List<QueryManagement.QueryEform>
Property |
Type |
Description |
Name |
string |
The name of the search |
Description |
string |
The description of the search |
SharingLevel |
QueryManagement.eSharingLevel |
Indicates who can see the search (private, public, site or subject group) |
SharingScope |
string |
The user, site or subject group that this search is shared with. Leave this blank for a public search, or specify the user, site or subject group code. |
StudyName |
string |
The name of the study that this search applies to |
EnforceUserAccessPermissions |
bool |
Specify 'true' to only retrieve data that the user has permission to view. Specify 'false' to retrieve all data. |
SubjectFilter |
QueryManagement.QueryFilter |
The conditions by which subjects should be considered for inclusion |
PopulationFilter |
QueryManagement.QueryFilter |
The conditions by which subjects should be included in the results |
DataItemFilter |
QueryManagement.QueryFilter |
The conditions by which data should be included in the results |
RecordFilter |
QueryManagement.RecordFilter |
The data items which should be included as columns in the output |
AttributeFilter |
QueryManagement.QueryFilter |
The attributes (status, comments, notes, DCRs, SDVs, frozen/locked, clinical coding, creation details) on which to filter data |
LastUpdatedBy |
string |
The user who last updated the search definition |
Keywords |
string |
The keywords describing the search definition |
CreatedBy |
string |
The user who created the search definition |
CreatedDate |
decimal |
The date on which the search definition was created |
LastModifiedDate |
decimal |
The date on which the search definition was last modified |
CreatedDateTZ |
int |
The timezone in which the search definition was created |
LastModifiedDateTZ |
int |
The timezone in which the search definition was last updated |
StudyNameFlag |
int |
Indicates whether or not to display the study name in the report (1 to display, 0 to hide) |
SiteCodeFlag |
int |
Indicates whether or not to display the site code in the report (1 to display, 0 to hide) |
SubjectLabelFlag |
int |
Indicates whether or not to display the subject label in the report (1 to display, 0 to hide) |
SubjectIdFlag |
int |
Indicates whether or not to display the subject ID in the report (1 to display, 0 to hide) |
SearchSchedule |
string |
The schedule type, period and time in xml format View formats |
Property |
Type |
Description |
Id |
string |
The ID of the filter |
Join |
QueryManagement.eJoin |
Indicates how the logic in the filter bands should be joined for this filter |
EnforceContext |
QueryManagement.eEnforceContext |
The context in which the results of the filter bands should be considered when performing the join |
FilterBands |
List<QueryManagement.FilterBand> |
The list of filter bands which determine the logic for this filter |
Property |
Type |
Description |
Id |
string |
The ID of the band |
FilterConditions |
List<QueryManagement.FilterCondition> |
The list of conditions which determine the logic for this band |
Join |
QueryManagement.eJoin |
Indicates how the logic in the filter conditions should be joined for this band |
EnforceContext |
QueryManagement.eEnforceContext |
The context in which the results of the filter conditions should be considered when performing the join |
Name |
string |
The name of the band |
Property |
Type |
Description |
Id |
string |
The ID of the condition |
ConditionType |
QueryManagement.eConditionType |
The type of condition |
Operand |
QueryManagement.Operand |
The description of how to determine which questions should be included in the condition |
Operator |
QueryManagement.eOperator |
Indicates how the value should be compared against the operand |
Value |
string |
The value to compare the operand against |
Property |
Type |
Description |
Visit |
string |
The visit code |
VisitOperator |
QueryManagement.eOperator |
The operator to use when filtering the visit cycle. |
VisitCycle |
int |
The visit cycle |
Eform |
string |
The eForm code |
EformOperator |
QueryManagement.eOperator |
The operator to use when filtering the eForm cycle. |
EformCycle |
int |
The eForm cycle |
Question |
string |
The question code |
QuestionOperator |
QueryManagement.eOperator |
The operator to use when filtering the question cycle. |
QuestionCycle |
QueryManagement.QueryFilter |
The question cycle |
Property |
Type |
Description |
Id |
string |
The ID of the record filter |
RecordFilterItems |
List<QueryManagement.RecordFilterItem> |
The collection of columns which should be included in the output |
Property |
Type |
Description |
Id |
string |
The ID of the record filter item |
Operand |
QueryManagement.Operand |
The operand describing the questions which should be included as columns in the output |
RecordFilterContext |
QueryManagement.eEnforceContext |
The context in which the columns should be included, based on the results of the data item filter |
Property |
Type |
Description |
Result |
QueryManagement.eResult |
The result of running the search |
StudyName |
string |
The name of the study that this search applies to |
Data |
List<QueryManagement.QuerySubjectRecords> |
The collection of data that has been returned for each subject in the results |
ErrorMessage |
string |
The details of any errors that occurred while running the search |
RequestedEforms |
List<string> |
The list of eForms with Requested status when specified as a data attribute |
Property |
Type |
Description |
Subject |
QueryManagement.QuerySubject |
The ID of the record filter |
Records |
List<QueryManagement.QueryRecord> |
The list of records returned for this subject |
Property |
Type |
Description |
Study |
string |
The study that the subject belongs to |
Site |
string |
The site that the subject belongs to |
Id |
int |
The subject ID |
LocalIdentifier1 |
string |
The first local identifier for the subject |
LocalIdentifier2 |
string |
The second local identifier for the subject |
SSID |
string |
The study/site/subject ID |
LockStatus |
int |
The lock status of the subject |
NoteStatus |
int |
The note status of the subject |
SdvStatus |
int |
The SDV status of the subject |
DcrStatus |
int |
The DCR status of the subject |
Property |
Type |
Description |
StudyId |
int |
ID of the study containing the response |
StudyName |
string |
Name of the study containing the response |
Site |
string |
Code of the site containing the response |
SubjectId |
int |
Subject ID of the subject containing the response |
VisitId |
int |
ID of the visit containing the response |
VisitCode |
string |
Code of the visit containing the response |
VisitCycle |
int |
Cycle number of the visit containing the response |
VisitOrder |
int |
Order of the visit containing the response |
EformId |
int |
ID of the eForm containing the response |
EformCode |
string |
Code of the eForm containing the response |
EformCycle |
int |
Cycle number of the eForm containing the response |
EformOrder |
int |
Order of the eForm containing the response |
QuestionId |
int |
ID of the question containing the response |
QuestionCode |
string |
Code of the question containing the response |
QuestionCycle |
int |
Cycle of the question containing the response |
QuestionOrder |
int |
Order of the question containing the response |
Value |
int |
Question response value |
ValueCode |
int |
Code of question response value |
StandardValue |
double |
Date/time question response value converted to double |
QGroupCode |
string |
Code of repeating question group containing the response |
QGroupOrder |
int |
Order of repeating question group containing the response |
DatabaseTimestamp |
double |
Date/time response was last changed |
DatabaseTimezone |
int |
Timezone in which date/time response was last changed |
UserName |
string |
User name of user who created/updated value |
ResponseStatus |
int |
Status of response |
LockStatus |
int |
Lock status of response |
NoteStatus |
int |
Note status of response |
SdvStatus |
int |
SDV status of response |
DcrStatus |
int |
DCR status of response |
CodingStatus |
int |
Clinical coding status of response |
ThesaurusType |
string |
Thesaurus type for question |
CodingCode |
string |
Thesaurus code for question |
CodingDecode |
string |
Thesaurus question text |
ThesaurusLanguageCode |
string |
Language of thesaurus used |
ThesaurusVersion |
string |
Version of thesaurus used |
CtcGrade |
string |
CTC grade of response |
LaboratoryCode |
string |
Code of laboratory for response |
LabResult |
string |
Laboratory question text |
Comments |
string |
Comments for response |
QnFormat |
string |
Format of response, based on question type |
SubjectLockStatus |
int |
Lock status of subject |
SubjectNoteStatus |
int |
Note status of subject |
SubjectSdvStatus |
int |
SDV status of subject |
SubjectDcrStatus |
int |
DCR status of subject |
VisitLockStatus |
int |
Lock status of visit |
VisitNoteStatus |
int |
Note status of visit |
VisitSdvStatus |
int |
SDV status of visit |
VisitDcrStatus |
int |
DCR status of visit |
EformLockStatus |
int |
Lock status of eForm |
EformNoteStatus |
int |
Note status of eForm |
EformSdvStatus |
int |
SDV status of eForm |
EformDcrStatus |
int |
DCR status of eForm |
EformTaskId |
int |
ID for combination of site/subject/visit (ID and cycle), eForm (ID and cycle) |
QnDataType |
int16 |
Data type of response |
QnDataItemLength |
int16 |
Question length of response |
Property |
Type |
Description |
EformName |
string |
Name of eForm |
EformId |
int |
ID of eForm |
EformCode |
string |
Code of eForm |
StudyId |
int |
ID of study |
SubjectId |
int |
Subject ID |
Site |
string |
Code of site |
Private |
0 |
Site |
1 |
SubjectGroup |
2 |
Public |
3 |
None |
4 |
AND |
1 |
OR |
2 |
DoNotEnforceContext |
0 |
EnforceVisitInstanceContext |
1 |
EnforceEformInstanceContext |
2 |
EnforceQGroupInstanceContext |
3 |
EnforceQuestionInstanceContext |
4 |
Site |
1 |
SubjectGroup |
2 |
SubjectId |
3 |
SubjectLabel |
4 |
Data |
5 |
DcrStatus |
6 |
SdvStatus |
7 |
NoteStatus |
8 |
LockStatus |
9 |
ResponseStatus |
10 |
Username |
11 |
CodingStatus |
12 |
ThesaurusType |
13 |
SubjectDcrStatus |
14 |
SubjectSdvStatus |
15 |
SubjectNoteStatus |
16 |
SubjectLockStatus |
17 |
VisitDcrStatus |
18 |
VisitSdvStatus |
19 |
VisitNoteStatus |
20 |
VisitLockStatus |
21 |
EformDcrStatus |
22 |
EformSdvStatus |
23 |
EformNoteStatus |
24 |
EformLockStatus |
25 |
Comments |
26 |
CreatedFromDate |
27 |
CreatedToDate |
28 |
EqualTo |
1 |
GreaterThan |
2 |
LessThan |
3 |
GreaterThanOrEqualTo |
4 |
LessThanOrEqualTo |
5 |
NotEqualTo |
6 |
IsNotNull |
7 |
IsNull |
8 |
BeginsWith |
9 |
EndsWith |
10 |
Contains |
11 |
DoesNotContain |
12 |
Equals |
13 |
DoesNotEqual |
14 |
Max |
15 |
Min |
16 |
None |
17 |
Success |
0 |
InvalidStudy |
1 |
StudyPermissionError |
2 |
QueryFormatError |
3 |
InvalidQuestion |
4 |
QueryAlreadyRun |
5 |
QueryCancelled |
6 |
ResultsNotFound |
7 |
QueryPermissionError |
8 |
UnknownError |
99 |
These return codes are of type eSearchAdminResult with the following values:
Code |
Value |
Description |
0 |
Success |
The operation was successful |
1 |
PermissionsError |
The user does not have the relevant MACRO permissions to perform the action |
2 |
InvalidSearchName |
The specified search is null or empty, or does not exist |
3 |
InvalidStudy |
The specified study is null or empty, does not exist, or does not have the required status |
4 |
StudyPermissionError |
The user has attempted to create a search for a study they do not have access to |
5 |
SitePermissionError |
The user has attempted to share a search with a site they do not have access to |
6 |
SubjectGroupPermissionError |
The user has attempted to share a search with a subject group they do not have access to |
7 |
SearchAlreadyExists |
The specified search already exists |
8 |
InvalidQueryStructure |
The specified query structure is invalid |
9 |
DatabaseError |
An unexpected error occurred while accessing the database |
10 |
SearchDoesNotExist |
The specified search is null or empty or does not exist |
11 |
SearchPermissionError |
The user has attempted to update, run, or view results for a search they do not have access to |
12 |
SearchQueueItemDoesNotExist |
The specified search queue item is null or empty or does not exist |
13 |
ServiceError |
An error occurred when trying to access the query management service, or a service configuration error occurred |
99 |
Unknown |
An unknown error occurred |