OQ Analyst Web Service Interface Specifications. Version 2.0

(1)

OQ

®

Analyst

Web Service Interface Specifications

(2)

Email: [email protected]

Web Service Interface Specifications

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 1999. 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®-45.2 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®-30.2 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

©OQ Measures, LLC 2008 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. VMH0123456) • First Name – Alphanumeric, 20 characters or less

• Middle Name – Alphanumeric, 20 characters or less • Last Name – 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)

(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 XML 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 • First Name • Last Name • 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:

• Username – username of a System Admin account used for WSI authentication • Password – password of a System Admin account used for WSI authentication • PersonID (of the clinician to retrieve)

GetClinician will return an XML 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 • First Name • Last Name • 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:

• Username – username of a System Admin account used for WSI authentication • Password – password of a System Admin account used for WSI authentication

GetAllClients will return an XML data set listing all clients currently in the system. The list will include the following fields at the client level:

• PersonID

(5)

• Medical Record Number • First Name • Middle Name • Last 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:

• Username – username of a System Admin account used for WSI authentication • Password – password of a System Admin account used for WSI authentication • Medical Record Number (for the requested client)

GetClient will return an XML data set containing the information for the requested client. The list will include the following fields at the client level:

• PersonID

• Medical Record Number • First Name • Middle Name • Last 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.

(6)

2.5 Web service function GetQuestionnaires

GetQuestionnaires 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 • Start Date (MM/DD/YYYY)

• End Date (MM/DD/YYYY)

GetQuestionnaires will return an XML 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 • First Name • Middle Name • Last 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 OQ, YOQ and SOQ instruments – values are 0-4, or 99 for unanswered o 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:

• Username – username of a System Admin account used for WSI authentication • Password – password of a System Admin account used for WSI authentication • Medical Record Number (optional but must be unique if provided)

• First Name

(7)

• Middle Name (optional) • Last Name

• 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:

• Username – username of a System Admin account used for WSI authentication • Password – password of a System Admin account used for WSI authentication • Medical Record Number – record number of client to be updated

• New Medical Record number (optional, use ##BLANK## to set MRN to blank) • First Name (optional)

• Middle Name (optional) • Last Name (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:

• Username – username of a System Admin account used for WSI authentication • Password – password of a System Admin account used for WSI authentication • Medical Record Number

(8)

GetSecondaryClinicians will return an XML 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:

• Username – username of a System Admin account used for WSI authentication • Password – password of a System Admin account used for WSI authentication • 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.

2.10 Web service function RemoveSecondaryClinician

RemoveSecondaryClinician 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 • 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.

2.11 Web service function InsertEmployee

InsertEmployee requires the following input parameters:

• Username – username of a System Admin account used for WSI authentication

Phone: (801) 649-5449 • Password – password of a System Admin account used for WSI authentication

(9)

• First Name • Last Name

• 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.

2.12 Web service function UpdateEmployee

UpdateEmployee 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 • Employee PersonID – PersonID of the client to be updated

• First Name (optional) • Last Name (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.

2.13 Web service function AddClinicToEmployee

AddClinicToEmployee 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 • Employee PersonID

• Clinic Name

(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.

2.14 Web service function RemoveClinicFromEmployee

RemoveClinicFromEmployee 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 • 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.

2.15 Web service function GetEmployeeClinics

GetEmployeeClinics 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 • Employee PersonID (Use -1 to get a list of all clinics for WSI login account)

GetEmployeeClinics will return an XML 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.

2.16 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 XML data set listing all employees currently in the system. The list will include the following fields at the employee level:

• PersonID • First Name • Last Name • Role • Access Level ©OQ Measures, LLC 2008 Page 10 Phone: (801) 649-5449 • Login Name

(11)

GetAllEmployees will return an error if the WSI username or password is not correct.

2.17 Web service function MergeRecords (NOTE: CURRENTLY NOT AVAILABLE)

MergeRecords 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 • 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 XML 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.

2.18 Web service function InsertQuestionnaire

InsertQuestionnaire 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

• Xml Data outlining questionnaire to be added to the system (See appendix for XML 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 X GetAllClients X – as “GetClientList” X GetClinician X GetAllClinicians X – as “GetClinicianList” X GetQuestionnaires X X ©OQ Measures, LLC 2008 Page 11 Phone: (801) 649-5449

(12)

Email: [email protected] InsertClient X X UpdateClient X GetAllEmployees X InsertEmployee X UpdateEmployee X AddClinicToEmployee X RemoveClinicFromEmployee X GetEmployeeClinics X InsertQuestionnaire X GetSecondaryClinicians X AddSecondaryClinician X RemoveSecondaryClinician X

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: https://demo.oqanalyst.com/OQAHS/services/ExportImportService.asmx

WSDL Address: https://demo.oqanalyst.com/OQAHS/services/ExportImportService.asmx?WSDL

Username: admin Password: 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: https://demo.oqanalyst.com/OQAHS/

Employee Username: admin Employee Password: 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.