OQ Analyst Web Service Interface Specifications. Version 2.0

Transcription

1 OQ Analyst Version 2.0

2 1. Introduction This document outlines the current specifications for the OQ -Analyst Web Service Interface (also referred to as the WSI) that can be used to allow external programs to access data stored in the OQ -Analyst application. The WSI is the primary method by which OQ -Analyst can be integrated with Electronic Medical Record (EMR) systems or other databases used by mental health facilities. Integration will allow the system to be more efficient by decreasing data entry time and increasing the quality of input data. The WSI allows a clinic to import and export data from the system using predefined methods designed for specific tasks such as adding a new client or retrieving questionnaire results. Web services do not provide user interfaces for direct interaction by users but instead are links into the application that must be utilized by external programs. See the WSI Summary documentation for instructions on how to access the WSI. 1.1 Definitions, Acronyms and Abbreviations OQ -Analyst (OQ -A) - a third generation software product with the first version appearing in 1996 and the second version in This enhanced version was created with user input to improve the features and functionality of the software product. Client a patient receiving mental health treatment. EMR electronic medical record AdministrationID a unique integer identifier generated within the OQ -Analyst system to identify an administration of a questionnaire Medical Record Number a unique optional external identifier provided to the OQ -Analyst system while creating a client record PersonID a unique 6 digit integer identifier generated within the OQ -Analyst system to identify clients and clinicians Alphanumeric consisting only of letters, numbers, spaces, dashes and underscores 1.2 Instrument Definitions Instrument ID Instrument Code Instrument Description Instrument Details 1 OQ452E OQ Adult self report 2 Y-OQ20E YOQ -2.0 Youth parent report 3 Y-OQ20ESR YOQ -2.0SR Youth self report PHASE 2 Instruments 4 OQ30E OQ Adult self report (short form) 5 Y-OQ30ESR YOQ 30.2SR Youth self report (short form) 6 Y-OQ30EPR YOQ 30.2PR Youth parent report (short form) 7 S-OQ20E SOQ -2.0 Severe Outcome Questionnaire 8 BPRS-E24E BPRS-E Companion measure for SOQ Page 2

3 1.3 Role and Access Level table The OQ Analyst security system is made up of Roles and Access levels. A user s role defines their function in the system and the access level determines what records they will be able to view. Not all combinations of roles and access levels are valid. The below table outlines what combinations are valid and invalid. See the OQ Analyst security manual for more information. Role (down), Access Level (across) Standard User Administrative Executive User System Admin Not Assigned Clerical Invalid Valid Invalid Valid Valid Clinician Valid Valid Invalid Valid Valid Corporate Invalid Invalid Valid Valid Valid Supervisor Valid Valid Invalid Valid Valid 1.4 Field Constraints Medical Record Number Unique, Alphanumeric, 10 characters or less o Starts with 3 digit agency code to make sure value is unique (i.e. VMH ) Alphanumeric, 20 characters or less Middle Name Alphanumeric, 20 characters or less Alphanumeric, 20 characters or less Birth Date / Start Date / End Date MM/DD/YYYY format Diagnosis Select from diagnosis list in OQ Analyst (default Unknown) Gender Male, Female, or Unknown Client PersonID User with client role (use GetAllClients for user list) Clinician PersonID User with clinician/supervisor role (use GetAllClinicians for user list) Supervisor PersonID User with supervisor role (use GetAllClinicians for user list) Clinic Select from clinic list in OQ Analyst Username / Login Name Unique, Alphanumeric, 20 characters or less Password 20 characters or less Role Select from Clerical, Clinician, Corporate, or Supervisor (see section 1.3) Access Level Select from Standard User, Administrative, Executive User, System Admin, or Not Assigned (see section 1.3) Instrument (see section 1.2) Completed By Code Select from Self (client completed measures) or Caseworker, Clinician, Father, Guardian, Mother, Other (other completed measures) Page 3

4 2. Available Methods 2.1 Web service function GetAllClinicians GetAllClinicians requires the following input parameters: Username username of A System Admin account used for WSI authentication Password password of A System Admin account used for WSI authentication GetAllClinicians will return an ML data set listing all clinicians currently in the system (this includes all employees in the system that have a role of Supervisor or Clinician ). The list will include the following fields at the clinician level: PersonID Role Access Level Login Name GetAllClinicians will return an error if the WSI username or password is not correct. 2.2 Web service function GetClinician GetClinician requires the following input parameters: PersonID (of the clinician to retrieve) GetClinician will return an ML data set containing the clinician that matches the PersonID supplied as the input parameter. The list will include the following fields at the clinician level: PersonID Role Access Level Login Name GetClinician will return an error if the WSI username or password is not correct. 2.3 Web service function GetAllClients GetAllClients requires the following input parameters: GetAllClients will return an ML data set listing all clients currently in the system. The list will include the following fields at the client level: PersonID Page 4

5 Medical Record Number Middle Name Birth Date Diagnosis Gender (Female/Male/Unknown) Clinician PersonID Clinician First Name Clinician Last Name Clinic Instrument (Using Instrument Description, see section 1.2) GetAllClients will return an error if the WSI username or password is not correct. 2.4 Web service function GetClient GetClient requires the following input parameters: Medical Record Number (for the requested client) GetClient will return an ML data set containing the information for the requested client. The list will include the following fields at the client level: PersonID Medical Record Number Middle Name Birth Date Diagnosis Gender (Female/Male/Unknown) Clinician PersonID Clinician First Name Clinician Last Name Clinic Instrument (Using Instrument Description, see section 1.2) GetClient will return an error if the WSI username or password is not correct. Page 5

6 2.5 Web service function GetQuestionnaires GetQuestionnaires requires the following input parameters: Start Date (MM/DD/YYYY) End Date (MM/DD/YYYY) GetQuestionnaires will return an ML data set containing a listing of all questionnaires in the system that have an administration date between the Start Date and End Date (inclusive) provided as input parameters. The list will include the following parameters on the questionnaire level: AdministrationID PersonID MedicalRecordNumber Middle Name Administration Date Outpatient Session Number Completed By Code Instrument (Using Instrument Description, see section 1.2) Total Score (as defined by OQ -Analyst application) Clinic Setting of Care InstrumentID Count of Questions Unanswered Answers to each question in numeric format o o OQ, YOQ and SOQ instruments values are 0-4, or 99 for unanswered BPRS values are 1-7, or 99 for unanswered GetQuestionnaires will return an error if the WSI username or password is not correct or if the dates provided are unable to be converted to a proper date format. 2.6 Web service function InsertClient InsertClient requires the following input parameters: Medical Record Number (optional but must be unique if provided) Page 6

7 Middle Name (optional) Birth Date (MM/DD/YYYY) Gender (Female/Male/Unknown) Clinic Clinician PersonID (the PersonID of the clinician that the new client is to be assigned to) Instrument (Using Instrument Code, see section 1.2) InsertClient will return an error if the provided Medical Record Number is already in use within the system. All required fields must be provided and be valid or the record will be rejected and an error will be returned. InsertClient will return an error if the WSI username or password is not correct. InsertClient will return the PersonID of the new client after successfully adding it to the system. 2.7 Web service function UpdateClient UpdateClient requires the following input parameters: Medical Record Number record number of client to be updated New Medical Record number (optional, use ##BLANK## to set MRN to blank) (optional) Middle Name (optional) (optional) Birth Date (optional) Gender (optional) Diagnosis (optional) Clinic (optional) Clinician PersonID (optional) Instrument Code (optional) UpdateClient will return an error if the provided Medical Record Number is not valid within the system. Optional fields that are left blank will not be updated; non-blank fields will be updated with the new value. UpdateClient will return an error if the WSI username or password is not correct. 2.8 Web service function GetSecondaryClinicians GetSecondaryClinicians requires the following input parameters: Medical Record Number Page 7

8 GetSecondaryClinicians will return an ML data set containing a listing of all secondary clinicians in the system for the provided client having the Medical Record Number. The list will include the following parameters for each clinician: Count of Secondary Clinicians Client Medical Record Number Clinician PersonID Clinician First Name Clinician Last Name Role Access Level Login Name GetSecondaryClinicians will return an error if the WSI username or password is not correct. 2.9 Web service function AddSecondaryClinician AddSecondaryClinician requires the following input parameters: Client Medical Record Number Clinician PersonID AddSecondaryClinician will add the provided Clinician PersonID to the secondary clinician list for the provided Client identified by the Medical Record Number. AddSecondaryClinician will return an error if the WSI username or password is not correct. AddSecondaryClinician will not return an error if the Clinician PersonID is already in the list and will simply ignore the input if it is a duplicate secondary clinician Web service function RemoveSecondaryClinician RemoveSecondaryClinician requires the following input parameters: Client Medical Record Number Clinician PersonID RemoveSecondaryClinician will remove the provided Clinician PersonID from the secondary clinician list for the provided Client identified by the Medical Record Number. RemoveSecondaryClinician will return an error if the WSI username or password is not correct. RemoveSecondaryClinician will not return an error if the Clinician PersonID is not in the list Web service function InsertEmployee InsertEmployee requires the following input parameters: Page 8

9 Employee Username Employee Password Access Level (See section 1.3) Role (See section 1.3) Clinic Supervisor PersonID (Optional, the PersonID of the supervisor they will be assigned to) InsertEmployee will return an error if the provided Employee Username is already in use within the system. All required fields must be provided and be valid or the record will be rejected and an error will be returned. InsertEmployee will return an error if the WSI username or password is not correct. InsertEmployee will return the PersonID of the new employee after successfully adding it to the system Web service function UpdateEmployee UpdateEmployee requires the following input parameters: Employee PersonID PersonID of the client to be updated (optional) (optional) New Username (optional) New Password (optional) Access Level (optional) Role (optional) Supervisor PersonID (optional) UpdateEmployee will return an error if the provided Employee PersonID is not valid within the system. Optional fields that are left blank will not be updated; non-blank fields will be updated with the new value. The user role cannot be changed if they currently have clients (as a clinician or supervisor) or employees (as a supervisor) assigned to them. UpdateEmployee will return an error if the WSI username or password is not correct Web service function AddClinicToEmployee AddClinicToEmployee requires the following input parameters: Employee PersonID Clinic Name Page 9

10 AddClinicToEmployee will add the provided Clinic to the access list of the selected Employee. AddClinicToEmployee will return an error if the WSI username or password is not correct. AddClinicToEmployee will not return an error if the Clinic is already in the list and will simply ignore the input if it is a duplicate entry Web service function RemoveClinicFromEmployee RemoveClinicFromEmployee requires the following input parameters: Employee PersonID Clinic Name RemoveClinicFromEmployee will remove the provided Clinic from the access list of the selected Employee. RemoveClinicFromEmployee will return an error if the WSI username or password is not correct. RemoveClinicFromEmployee will not return an error if the Clinic has already been removed from the list and will simply ignore the request Web service function GetEmployeeClinics GetEmployeeClinics requires the following input parameters: Employee PersonID (Use -1 to get a list of all clinics for WSI login account) GetEmployeeClinics will return an ML data set containing a listing of all clinics assigned to the provided employee. The list will include the following parameters for each clinic: Clinic ID Unique value assigned to each clinic Clinic Name GetEmployeeClinics will return an error if the WSI username or password is not correct Web service function GetAllEmployees GetAllEmployees requires the following input parameters: Username username of A System Admin account used for WSI authentication Password password of A System Admin account used for WSI authentication GetAllEmployees will return an ML data set listing all employees currently in the system. The list will include the following fields at the employee level: PersonID Role Access Level Login Name Page 10

11 GetAllEmployees will return an error if the WSI username or password is not correct Web service function MergeRecords (NOTE: CURRENTLY NOT AVAILABLE) MergeRecords requires the following input parameters: Source Medical Record Number Destination Medical Record Number MergeRecords will take all questionnaires from the Client record identified by the Source Medical Record Number and move them to the client identified by the Destination Medical Record Number. MergeRecords will return an ML data set containing the following information: Source Medical Record Number Destination Medical Record Number Count of Questionnaires moved by the function MergeRecords will return an error if the WSI username or password is not correct Web service function InsertQuestionnaire InsertQuestionnaire requires the following input parameters: ml Data outlining questionnaire to be added to the system (See appendix for ML format) InsertQuestionnaire can be used to manually insert questionnaire data into the system. InsertQuestionnaire will return an error if the WSI username or password is not correct. 3. Security Security for the WSI is provided through the use of a system administrator username and password for a given agency. These values are a required parameter when using the WSI to prevent unauthorized users from accessing data within the system. The WSI also uses Secure Socket Layer (SSL) technology to encrypt all communication between the client and the OQ -Analyst server. 4. WSI Return Messages See the appendix for examples of the success and error messages returned by each method. 5. OQ -Analyst Web Service List The following table lists the available web services and the interface that must be used to access each: Web Service Name Web Service Interface Program Web Service Raw Interface GetClient GetAllClients as GetClientList GetClinician GetAllClinicians as GetClinicianList GetQuestionnaires Page 11

12 InsertClient UpdateClient GetAllEmployees InsertEmployee UpdateEmployee AddClinicToEmployee RemoveClinicFromEmployee GetEmployeeClinics InsertQuestionnaire GetSecondaryClinicians AddSecondaryClinician RemoveSecondaryClinician 6. Demonstration Version A working example of the raw web service interface can be found at the web address listed below; however, the exact methods could change depending on the services offered through the WSI. The demonstration includes fictitious clients and outcome data and you can add additional clients if desired, however all data will be deleted on a periodic basis. WSI Web Address: WSDL Address: Username: Password: admin admin You can also login to the employee page using the information listed below. This user name and password will give full access to all features and clients data; however, users would normally login using their own unique account and would only be able to view the sections and client data for which they are authorized. Employee Login Web Address: Employee Username: Employee Password: admin admin 7. Additional Information See the WSI user manual for detailed instructions on how to setup and access the WSI. For a preview of this document please contact OQ Measures Support using the information listed below. Page 12