Querying and Reporting XML Serivce (QRXS) Client Program User Guide

NATIONAL PRACTITIONER DATA BANK (NPDB)

UERYING AND REPORTING XML SERVICE (QRXS)

CLIENT PROGRAM USER GUIDE

Version 2.03

August 2021

U.S. Department of Health and Human Services

Health Resources and Services Administration

Bureau of Health Workforce

Division of Practitioner Data Bank

Parklawn Building, Room 11SWH03

5600 Fishers Lane

Rockville, Maryland 20857

QRXS Client Program User Guide Version 2.03

August 2021 i

DOCUMENT CHANGE HISTORY

The table below identifies changes incorporated into each baseline of this document.

Date

Version #

Change Description

10/17/2005

1.01

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.01. Effective October 17, 2005,

this document version 1.01 replaces version 1.0. The changes in this

version are indicated below:

• Updated sample code for obtaining error message text using the

Application Programming Interface (API). Sections 5.3.3 and 5.3.4.

• Modified and added status codes. See Section 3.3.

5/8/2006

1.02

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.02. Effective May 8, 2006, this

document, version 1.02 replaces version 1.01. The changes in this

version are indicated below:

• The Data Banks’ website is now located at http://www.npdb-

hipdb.hrsa.gov. The Data Banks are using a .gov domain name to

help prevent fraud by showing Data Banks’ users that the NPDB-

HIPDB website is under the Government-run domain. Please update

your Internet bookmarks to reference the .gov address for the Data

Banks’ website. NPDB-HIPDB website references in this document

now refer to the new website address.

• Due to the NPDB-HIPDB website address change, all ITP and

QRXS client programs must be upgraded to a new version. Updated

client programs are now available on the NPDB-HIPDB website.

While the current versions of the ITP and Querying and Reporting

XML Service (QRXS) client programs will continue to function for a

limited time, all ITP and QRXS users must upgrade their client

program to the new version no later than September 18, 2006.

• Updated the commons-fileupload jar to version 1.1.

7/31/2006

1.03

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.03. Effective July 31, 2006, this

document, version 1.03 replaces version 1.02. The changes in this

version are indicated below:

• Updated installation instructions for JRE 1.5 and the QRXS client

software. See Sections 2.2 and 2.3.

1/14/2008

1.04

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.04. Effective January 14, 2008,

this document, version 1.04 replaces version 1.03. The changes in this

version are indicated below:

• Added new status code -57. See Section 3.3.

QRXS Client Program User Guide Version 2.03

August 2021 ii

Date

Version #

Change Description

3/31/2008

1.05

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.05. Effective March 31, 2008,

this document, version 1.05 replaces version 1.04. For transaction

submissions prior to March 31, 2008, readers should refer to version 1.04

of the Querying and Reporting XML Service (QRXS) User Guide

available at

http://www.npdb.hrsa.gov/QRXS. The changes in this version are

indicated below:

• Added consent to monitoring notice paragraph. See Section 1.1.

• Added Section 1.2, User Account Security.

• Added Section 1.3, Contact Information.

• Updated software requirements. See Section 2.2.

• Updated software installation instructions. See Section 2.3.

• Clarified the use of the Entity Data Bank Administrator’s ID for

transactions. See Section 3.2.

• Updated and changed the format of the status codes. See Section 3.3.

• Updated notes in Section 3.5, Uploading Files.

• Updated notes in Section 3.6, Downloading Files.

• Added Section 3.8, Password Changes.

• Updated Section 5.3, Using the API.

7/28/2008

1.06

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.06. Effective July 28, 2008, this

document, version 1.06 replaces version 1.05. For transaction

submissions prior to July 28, 2008, readers should refer to version 1.05

of the Querying and Reporting XML Service (QRXS) User Guide

available at

http://www.npdb.hrsa.gov/QRXS. The changes in this

version are indicated below:

• Corrected output in the sample download.lst file in section 3.6.

• Updated Note 2 in Section 3.8 to indicate that password rejection

files are returned immediately.

3/02/2009

1.07

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.07. Effective March 2, 2009, this

document, version 1.07 replaces version 1.06. The changes in this

version are indicated below:

• Added Section 4 - Testing the QRXS.

3/11/2009

1.08

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.08. Effective March 11, 2009,

this document, version 1.08 replaces version 1.07. The changes in this

version are indicated below:

• Corrected the qrxs.properties file in Section 4.2.

• Added a note to Section 4.3.

QRXS Client Program User Guide Version 2.03

August 2021 iii

Date

Version #

Change Description

6/15/2009

1.09

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.09. Effective June 15, 2009, this

document, version 1.09 replaces version 1.08. The changes in this

version are indicated below:

• Added support for PDS transactions to the QRXS test environment in

Section 4.

8/31/2009

1.10

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.10. Effective August 31, 2009,

this document, version 1.10 replaces version 1.09. The changes in this

version are indicated below:

• Added support for proxy server authentication. See changes

described in Section 5.4, Proxy Server.

• Added a showversion command. See changes described in Section

3.9, Show Version Number.

• Added the capability to change and reset passwords directly from the

command line. See changes described in Section 3.8.2, Command

Line Password Transactions.

• Updated the required JRE version to 1.6.

01/25/2009

1.11

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.11. Effective January 25, 2010,

this document, version 1.11 replaces version 1.10. The changes in this

version are indicated below:

• Added specifications for receiving test responses. See Section 4,

QRXS Test Environment.

08/30/2010

1.12

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.12. Effective August 30, 2010,

this document, version 1.12 replaces version 1.11. The changes in this

version are indicated below:

• Updated Section 1.2, User Account Security.

• Updated Section 3.3, Status Codes.

• Introduced 1,000 file response limit. See the change described in

Section 3.6, Downloading Files.

01/24/2011

1.13

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.13. Effective January 24, 2011,

this document, version 1.13 replaces version 1.12. The changes in this

version are indicated below:

• Updated Section 3.3, Status Codes. Code C02 was modified.

• Updated Section 4.2.3, PDS. Corrected the Data Bank Subject ID to

be 888000000000111.

QRXS Client Program User Guide Version 2.03

August 2021 iv

Date

Version #

Change Description

8/22/2011

1.14

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.14. Effective August 22, 2011,

this document, version 1.14 replaces version 1.13. The changes in this

version are indicated below:

• Changed PDS references to Continuous Query throughout entire

document.

• Updated software installation instructions. See Section 2.3.

• Changed NPDB-HIPDB references in Status Code Descriptions to

Data Bank. See Table 2.

Reserved.

1.15

Reserved.

8/22/2011

1.16

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.16. Effective August 22, 2011,

this document, version 1.16 replaces version 1.14. The changes in this

version are indicated below:

• Updated Section 1.2.2, User Account Password Policies to state that

password restrictions and guidelines can be found at

http://www.npdb.hrsa.gov/Passwords

• Removed Section 1.2.4, Password Restrictions.

• Updated Section 3.7, Encoding the Password to state that password

restrictions and guidelines can be found at

http://www.npdb.hrsa.gov/Passwords

• Updated the passwords. See sections 3.7, 3.8.2, 5.1, 5.4, 6.3.1.2,

6.3.2, and 6.3.5.

1/23/2012

1.17

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.17. Effective January 23, 2012,

this document, version 1.17 replaces version 1.16. The changes in this

version are indicated below:

• Updated Section 4.2.3, Continuous Query.

4/2/2012

1.18

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 1.18. Effective April 2, 2012, this

document, version 1.18 replaces version 1.17. The changes in this

version are indicated below:

• Added status codes C68 and C69. See Section 3.3.

QRXS Client Program User Guide Version 2.03

August 2021 v

Date

Version #

Change Description

6/13/2013

2.00

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 2.00. Effective June 13, 2013, this

document, version 2.00 replaces version 1.18. The changes in this

version are indicated below:

• Up

dated URLs to the Data Bank’s Informational Website:

http://www.npdb.hrsa.gov

• Updated the email address for the NPDB Customer Service Center to

[email protected]rsa.gov

• Removed references to the HIPDB to reflect the merge of the two

separate Data Banks into the NPDB.

• Updated Section 1.2.3, Resetting Passwords to state that users may

reset their own passwords from the Data Bank Sign In page.

9/3/2013

2.01

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 2.01. Effective early 2014, this

document, version 2.01 will replace version 2.00. The changes in this

version are indicated below:

• Section 4.2.1 and Section 4.3.1, the InputURL was updated to

https\://qa.npdb.hrsa.gov/qrxs/servlet/XMLInputServlet

and

the OutputURL was updated to

https\://qa.npdb.hrsa.gov/qrxs/servlet/XMLOutputServlet

• Modified Section 3.5 to make the maximum submission file size 512

KB.

• Section 6.3.1.2, the final String url was updated to

https://qa.npdb.hrsa.gov/qrxs/servlet/

9/12/2016

2.02

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 2.02. Effective September 12,

2016, this document, version 2.02 will replace version 2.01. The changes

in this version are indicated below:

• Updated minimum required Java version to 1.8

• Updated URLs to https

8/20/2021

2.03

Below is a summary of changes to the Querying and Reporting XML

Service (QRXS) User Guide version 2.03. Effective August 20, 2021,

this document, version 2.03 will replace version 2.02. The changes in

this version are indicated below:

• Updated a reference to error code S2 to comply with the new

password length requirements

• Updated the example passwords to be in compliance with the

new password length and complexity requirements.

QRXS Client Program User Guide Version 2.03

August 2021 vi

Table of Contents

1. Introduction ........................................................................................................................................ 1

1.1 Scope ........................................................................................................................................... 1

1.2 User Account Security ................................................................................................................. 1

1.2.1 User Accounts ......................................................................................................................... 1

1.2.2 User Account Password Policies ............................................................................................. 1

1.2.3 Resetting Passwords ................................................................................................................ 2

1.3 Contact Information ..................................................................................................................... 2

1.4 Conventions ................................................................................................................................. 2

2. Installation .......................................................................................................................................... 3

2.1 System Requirements .................................................................................................................. 3

2.2 Software Requirements................................................................................................................ 3

2.3 Software Installation .................................................................................................................... 3

3. Client Configuration and Execution ................................................................................................... 4

3.1 Executing the QRXS Client ......................................................................................................... 4

3.2 Preparing the Initialization File ................................................................................................... 4

3.3 Status Codes ................................................................................................................................ 5

3.4 QRXS Status File ........................................................................................................................ 7

3.5 Uploading Files ........................................................................................................................... 8

3.6 Downloading Files ....................................................................................................................... 8

3.7 Encoding the Password ................................................................................................................ 9

3.8 Password Changes ..................................................................................................................... 10

3.8.1 Types of Password Change Transactions .............................................................................. 10

3.8.2 Command-

Line Password Transactions ................................................................................ 11

3.8.3 File-Based Password Transactions ........................................................................................ 11

3.9 Show Version Number .............................................................................................................. 12

4. QRXS Test Environment .................................................................................................................. 13

4.1 Overview ................................................................................................................................... 13

4.2 Submitting Test Files ................................................................................................................. 13

4.2.1 Configuration ........................................................................................................................ 13

4.2.2 Payment ................................................................................................................................. 14

4.2.3 Continuous Query ................................................................................................................. 14

4.2.4 Reports .................................................................................................................................. 15

4.3 Receiving Test Files .................................................................................................................. 15

4.3.1 Configuration ........................................................................................................................ 15

4.3.1.1 Requesting Multiple Response Files ................................................................................. 16

4.3.1.2 Requesting Response File Versions .................................................................................. 16

4.3.2 Continuous Query ................................................................................................................. 16

5. Sample Configuration and Execution ............................................................................................... 17

5.1 Configuration ............................................................................................................................. 17

5.2 Uploading Submission Files ...................................................................................................... 17

5.3 Downloading Response Files .................................................................................................... 18

5.4 Proxy Server .............................................................................................................................. 18

6. Application Programming Interface ................................................................................................. 20

6.1 Overview ................................................................................................................................... 20

6.2 When to use the API .................................................................................................................. 20

.3 Using the API ............................................................................................................................

QRXS Client Program User Guide Version 2.03

August 2021 vii

6.3.1 Configuration ........................................................................................................................ 20

6.3.1.1 Using a File ....................................................................................................................... 20

6.3.1.2 Using Parameters .............................................................................................................. 21

6.3.2 Encoding ............................................................................................................................... 21

6.3.3 Sending .................................................................................................................................. 22

6.3.4 Receiving ............................................................................................................................... 23

6.3.5 Changing The Password ........................................................................................................ 23

6.3.6 Resetting The Password ........................................................................................................ 23

6.3.7 Retrieving Version Number .................................................................................................. 24

List of Tables

Table 1: Initialization File Properties ................................................................................................... 5

Table 2: Status Codes Returned ........................................................................................................... 6

Table 3: Report DCNs for Testing ..................................................................................................... 15

QRXS Client Program User Guide Version 2.03

August 2021 1

1. Introduction

1.1 Scope

The National Practitioner Data Bank (NPDB) provides the Querying and Reporting XML Service

(QRXS) to users who wish to send and receive machine-readable responses. These instructions provide

details on installing and configuring the QRXS client software.

The QRXS client is a stand-alone program that transmits files containing transaction data to, and receives

response files from, the NPDB. These transactions can be a one-time query, a report, a Continuous Query

transaction, or a password change request. For security, data is transmitted over a Secure Socket Layer

(SSL) connection. This program can be executed as a stand-alone program, or it can be executed under

the control of other programs. An Application Programming Interface (API) is also available for

additional flexibility when integrating QRXS transactions into existing software systems.

File formats for QRXS submissions and responses are defined in the Interface Control Documents (ICDs)

published by the NPDB, available on-line at https://www.npdb.hrsa.gov/QRXS

When using the QRXS, you are accessing a U.S. Government information system. System usage may be

monitored, recorded, and subject to audit. Unauthorized use of this system is prohibited and subject to

criminal and civil penalties. Use of this system indicates consent to monitoring and recording. Should

you have questions concerning your responsibilities, please contact the NPDB Customer Service Center

immediately as specified in Section 1.3, Contact Information.

1.2 User Account Security

1.2.1 User Accounts

Each entity has two types of accounts to access the NPDB, the Data Bank administrator account and user

accounts. The Data Bank administrator account is used to create and manage the user accounts. User

accounts are used to submit transactions and retrieve responses from the NPDB. The NPDB has

established security policies in order to reduce the risk of unauthorized access to user accounts and protect

the confidentiality of practitioner reports.

The NPDB ensures that QRXS transactions are verified as originating with your organization. This

process involves a system that stores IP addresses for computers that have been "whitelisted" as

belonging to your organization. IQRS administrators are responsible for maintaining this list. A page in

the IQRS has been created to enable the Data Bank administrator to easily complete this task.

More information can be found on the QRXS Security web page:

https://www.npdb.hrsa.gov/software/qrxsSecurity.jsp

1.2.2 User Account Password Policies

A user must provide their organization’s DBID, their User ID, and user account password each time they

access the IQRS or the QRXS. If a valid password is not provided after three consecutive attempts, the

user account is locked and the user must contact the Data Bank administrator to submit a user account

password reset request.

Users are required to change their passwords periodically. A password change request can be submitted

at any time to change an account’s password. Password restrictions and guidelines can be found at

https://www.npdb.hrsa.gov/Passwords

To ensure the security and privacy of user account passwords when using the QRXS, the response

to a file-based password change request transaction can only be downloaded by the same user

account that submitted the transaction.

QRXS Client Program User Guide Version 2.03

August 2021 2

1.2.3 Resetting Passwords

When a user or administrator forgets his or her password, or is locked out of the IQRS Service, he or she

may reset it from the NPDB Sign In page. From the Reset Password page, the user will answer pre-

established Challenge Question(s) and enter a new password. An email confirming the password reset

will be sent to the user with a link to the NPDB Sign In page. This link is valid for one hour.

If using the QRXS, only the administrator can submit and download transactions to reset user passwords.

The administrator cannot reset his or her own password. A password change transaction should be

submitted instead of a password reset transaction.

1.3 Contact Information

The QRXS is updated periodically by the NPDB. It is strongly recommended that users join the QRXS

Mailing List at https://www.npdb.hrsa.gov/MailingLists

to receive notice of updates.

The NPDB makes an effort to notify users at least 1 month in advance of an update to code lists. Users

should expect code lists to be updated quarterly. Additional updates to the QRXS specifications are

required periodically. Users will be notified 6 months in advance of updates to the QRXS specifications

that are not backward compatible. If you are already registered for the QRXS Mailing List and would

like to be removed, contact the NPDB Customer Service Center.

For additional information, visit the NPDB website at

https://www.npdb.hrsa.gov/software/aboutSoftware.jsp

. If you need assistance, contact the NPDB

Customer Service Center by email at [email protected] or by phone at 1-800-767-6732

(TDD 703-802-9395). Information Specialists are available to speak with you weekdays from 8:30 a.m.

to 6:00 p.m. (5:30 p.m. on Fridays) Eastern Time. The NPDB Customer Service Center is closed on all

Federal holidays.

1.4 Conventions

Names of files, URLs, parameters, example Data Bank Identification Numbers (DBIDs), example

passwords, or documents are presented in italics.

ttp://www.oracle.com/

ata that must be entered into the computer, commands you must enter, contents of files, and contents of

directories are presented in a different font (Verdana).

java com.npdbhipdb.QRXS send

here the explicit use of upper or lower case letters are necessary due to the system interpreting upper

and lower case letters as distinct characters, the text will clearly identify the command as “case sensitive.”

QRXS Client Program User Guide Version 2.03

August 2021 3

2. Installation

2.1 System Requirements

1. One of the following supported Microsoft Windows versions: Windows 2000, Windows XP,

Windows 7, 8, and 10. The software can be expected to run on other platforms that support the

required Java Runtime Environment (JRE), but only the supported versions have been tested.

2. Access to the Internet and SSL port (443).

2.2 Software Requirements

1. JRE version 1.80 or higher. It is recommended that the latest JRE version available is used.

The JRE can be downloaded from Oracle’s JRE download page:

http://www.java.com

Follow the instructions provided on the web page to download and install the JRE. If the default

installation is followed, the JRE will install in C:\Program Files\Java\jre.

2. The QRXS-v1_05.zip distribution available at https://www.npdb.hrsa.gov/QRXS

The following files are provided in the zip file:

commons-codec-1.3.jar

commons-fileupload-1.1.jar

commons-httpclient-2.0.jar

commons-logging.jar

QRXS-Javadoc-Files-v1_05.zip

QRXS-Readme.txt

qrxs-v1_05.jar

qrxs.properties

2.3 Software Installation

1. Install the JRE. Instructions are provided at Oracle’s JRE download page, referenced above.

2. Create a working directory for running the client. For example:

mkdir c:\QRXS

3. Install the JAR files from the QRXS-v1_05.zip distribution. Copy the .jar files (qrxs-v1_05.jar,

commons-codec-1.3.jar, commons-fileupload-1.1.jar, commons-httpclient-2.0.jar, and

commons-logging.jar) to the JRE’s library extension directory. For example (using the default

JRE installation directory):

c:\Program Files\Java\jre\lib\ext

4. Install the initialization file. Copy the file qrxs.properties to the directory from which the QRXS

client executes (your working directory, e.g., c:\QRXS).

Note: Previous versions of QRXS-related files should be removed before installing newer versions in

order to ensure the latest files are used.

QRXS Client Program User Guide Version 2.03

August 2021 4

3. Client Configuration and Execution

3.1 Executing the QRXS Client

The client is controlled via command-line parameters. The following are the only supported commands:

java com.npdbhipdb.QRXS send (for sending submission files) or

java com.npdbhipdb.QRXS receive (for receiving response files) or

java com.npdbhipdb.QRXS encode <password> (for encoding a password in the initialization file)

java com.npdbhipdb.QRXS resetpassword <userid> (for resetting a users' password) or

java com.npdbhipdb.QRXS changepassword <password> (for changing your password) or

java com.npdbhipdb.QRXS encodeproxypwd <password> (for encoding a proxy server password

in the initialization file) or

java com.npdbhipdb.QRXS showversion (to display the version number of the QRXS client)

te: The program name and the command-line parameter values are case sensitive.

3.2 Preparing the Initialization File

On startup, the qrxs.properties file is read for initialization information. The qrxs.properties file resides

in the working directory as described in Section 2.3, Software Installation, Step 4. A sample

qrxs.properties file is provided in the zip file. All the required properties in the initialization file must be

complete and valid. If the information is missing or invalid, the program terminates. Users may configure

their own qrxs.properties files to reflect their desired download directory location, upload/download list

file locations, and to specify use of a proxy server.

Certain characters may be interpreted as instructions by the user’s operating system or by the QRXS

client. For this reason, the qrxs.properties file must be written in such a way that each character is

interpreted literally, and not as an instruction. In order to accomplish this, characters that may be

interpreted as instructions must be escaped; i.e., a backslash (“\”) character is placed in front of the

character that may be interpreted as an instruction.

The following is a sample qrxs.properties file:

DBID=123400000000123

Password=UuhUh5owKFEeue

UserID=myuserid

DownloadDir=c:\\QRXS\\download

UploadListFile=upload.lst

DownloadListFile=download.lst

tes:

1. The properties are case sensitive.

2. The password is encoded and must be set using the client’s encode command. Instructions on

setting the password are in Section 3.7, Encoding the Password.

3. The backslash character itself must be escaped, because in this case it must be interpreted

literally; this is the reason for the two backslashes in the directory values.

4. The properties within the file may appear in any order.

QRXS Client Program User Guide Version 2.03

August 2021 5

Table 1: Initialization File Properties

he following properties are allowed. Users must enter any properties that they do not wish to use the

default values for:

Properties

Descriptions

DBID*

The Data Bank Identification Number (DBID).

UserID*

The User ID of a user registered with the NPDB. Do not use the Entity

Data Bank Administrator’s ID except for password-related transactions.**

Password*

The encoded NPDB password (also known as the IQRS password).

DownloadDir*

Directory to hold the downloaded QRXS response files .

UploadListFile

Name of the file containing one or more names of QRXS submission files;

defaults to upload.lst.

DownloadListFile

File containing names of the QRXS response files downloaded; defaults to

download.lst.

LogFile

Name of the file containing error messages; defaults to qrxs.log.

ProxyHostName

Name of the proxy host (usually an IP Address). Only required when

using a proxy server (see Section 5.4, Proxy Server for more information).

ProxyPort

Port number of the proxy server. Only required when using a proxy server

(see Section 5.4, Proxy Server for more information).

ProxyUser

User name for authenticating with the proxy server. Only required when

using a proxy server requiring authentication (see Section 5.4, Proxy

Server for more information).

ProxyPassword

The encoded password for authenticating with the proxy server. Only

required when using a proxy server requiring authentication (see Section

5.4, Proxy Server for more information).

ProxyDomain

The Windows domain name used by the proxy server for NTLM

authentication. Only required when using a proxy server using NTLM

authentication (see Section 5.4, Proxy Server for more information).

* Required property.

** For detailed information on maintaining User IDs and passwords refer to

https://www.npdb.hrsa.gov/Passwords

or UploadListFile, DownloadDir, LogFile, and DownloadListFile, acceptable values of the properties

include the file name only, or a path name and the file name. If the value is the file name only, then the

file is assumed to be located in the working directory.

3.3 Status Codes

The QRXS client provides status in three ways. First, an exit code containing the status code value is

always returned; second, a file called qrxsstat.dat, which contains the status code, is created in the

program’s working directory; and third, unsuccessful status codes and corresponding messages are

appended to a log file located in the program’s working directory. A status code of “C00” indicates that

the transaction was successful, and any other status code indicates that the transaction failed.

QRXS Client Program User Guide Version 2.03

August 2021 6

Table 2: Status Codes Returned

The following status codes are returned:

Status

Code

Description

C00

Success, no errors.

C01

Error on NPDB server, reattempt transfer.

C02

Authentication failed; DBID, UserID, or Password are invalid, or the user account is

inactive.*

C03

Password expired for DBID and UserID.*

C04

No filenames specified for upload.

C05

Error sending files to server, reattempt transfer.

C06

Client sent an invalid request.

C07

Inactive DBID.

C08

Maximum upload file size exceeded; reduce file size and reattempt transfer.

C09

All uploaded files are invalid.

C10

Unable to communicate with NPDB server, reattempt transfer.

C12

Database error on NPDB server, reattempt transfer.

C13

Not all of the files were processed successfully.

C16

The DBID for your organization must be renewed before you can access NPDB services. The

NPDB requires all registered entities to periodically renew their registration information.

Re-registration enables the NPDB to maintain accurate entity contact information and

provides the entity with the opportunity to review the legal requirements and verify their

compliance for participation with the Data Bank. The certifying official for your organization

must review the NPDB statutory authorities, available at

https://www.npdb.hrsa.gov/resources/aboutLegsAndRegs.jsp, as part of the renewal process.

Once the statutory authorities have been reviewed, complete the on-line registration renewal

form by logging in to the IQRS and selecting Renew Registration on the registration

confirmation screen. The completed form must be signed and mailed to the Data Bank for

processing. If your organization has already mailed the registration renewal to the NPDB, it

will be processed within 1 business day of its receipt by the NPDB. Data Bank

Correspondence will be sent once the NPDB has successfully processed your registration

renewal form. If necessary, you may complete a new form by selecting Renew Registration

below. If you need further assistance, please contact the NPDB Customer Service Center at 1-

800-767-6732.

C17

The DBID for your organization must be renewed before you can access NPDB services. The

NPDB requires all registered entities to periodically renew their registration information.

Re-registration enables the NPDB to maintain accurate entity contact information and

provides the entity with the opportunity to review the legal requirements and verify their

compliance for participation with the Data Bank. The certifying official for your organization

must review the NPDB statutory authorities, available at

https://www.npdb.hrsa.gov/resources/aboutLegsAndRegs.jsp, as part of the renewal process.

Contact the Entity Data Bank Administrator of your organization so they can renew the

registration. If you need further assistance, please contact the NPDB Customer Service

Center at 1-800-767-6732.

C21

Client error, refer to log file for more information.

C22

Usage error, check command-line parameter.

C23

Error in reading Initialization file qrxs.properties, check that qrxs.properties file is in working

directory.

C24

Unable to open program log file, check that disk space is available.

C30

Error validating property in qrxs.properties, a property is missing or value is invalid.

QRXS Client Program User Guide Version 2.03

August 2021 7

Status

Code

Description

C31

Error validating UploadListFile, upload file missing or a file listed in the upload file does not

exist.

C32

Error validating DownloadDir, directory does not exist.

C40

Error opening connection to NPDB server, check Internet connection and reattempt transfer.

C43

Error during client startup.**

C54

Error downloading response files, reattempt transfer.

C56

Error getting the list of response files downloaded, reattempt transfer.

C57

Your password has expired. You may login to the IQRS to reset your password or contact

your Entity Data Bank Administrator or the NPDB Customer Service Center.***

C58

Your account has been locked. Contact your Entity Data Bank Administrator to reset the

password. If you are using an Entity Data Bank Administrator account, contact the NPDB

Customer Service Center to reset the password.

C59

Your account has been locked. The number of invalid login attempts has exceeded the

allowable login limit. Contact your Entity Data Bank Administrator to reset the password. If

you are using an Entity Data Bank Administrator account, contact the NPDB Customer

Service Center to reset the password.

C60

Your password must be changed before other transactions can be submitted.

C61

Error changing the password.

C62

Error resetting the password.

C64

No more than one password change transaction can be submitted at one time. Reduce the

number of password change transactions to one, reattempt transfer.

C68

To ensure account security, your Entity Data Bank Administrator must authorize this

connection.****

C69

To ensure account security, the account holder must contact the NPDB Customer Service

Center at 1-800-767-6732 to access the system.

* For detailed information on maintaining User IDs and passwords refer to

https://www.npdb.hrsa.gov/Passwords

** Either two instances of the client program are running or one instance of the program was terminated

prematurely. If it is the latter, remove the qrxslock file from the program’s working directory and try

again.

*** Under specific circumstances the IQRS password reset service is available to obtain a new password.

user account to use this service. You may also contact your Entity Data Bank Administrator to reset the

password. If you are using an Entity Data Bank Administrator account, you may also use the IQRS

password reset service or contact the NPDB Customer Service Center to reset the password.

**** For more information about account security visit the QRXS Security page:

https://www.npdb.hrsa.gov/software/qrxsSecurity.jsp

3.4 QRXS Status File

The qrxsstat.dat file contains the final status of the QRXS client execution. This file is created in the

working directory immediately upon program completion. The file contains two lines. The first line

indicates the overall status of “Done” or “Not Done.” The second line contains a status code of “C00” or

another status code indicating failure (see Section 3.3, Status Codes, for error codes that may be returned).

Sample qrxsstat.dat file for a successful execution:

Overall status = Done

StatusCode=C00

QRXS Client Program User Guide Version 2.03

August 2021 8

Sample qrxsstat.dat file for an unsuccessful execution:

Overall status = Not Done

StatusCode=C22

3.5 Uploading Files

The upload file contains the names (including the full or relative path) of the submission files that are sent

to the NPDB. The name of the upload file must be specified in the qrxs.properties file using the

UploadListFile property. If it is not specified, it defaults to upload.lst.

A sample upload file with four submission files to upload, using a full path:

c:\QRXS\upload\0000001.xml

c:\QRXS\upload\0000002.xml

c:\QRXS\upload\0000004.xml

c:\QRXS\upload\0000005.xml

A sample upload file with three submission files to upload, using a relative path:

upload\file0001.xml

upload\file0002.xml

upload\file0003.xml

Notes:

1. I

n the upload file, the backslash is not escaped.

2. A file name can contain a relative or full path as noted above. Each set of files above is specified

differently, but all the files are located in c:\QRXS\upload, and the working directory is c:\QRXS.

3. A submission file listed in the upload file may be a report, a one-time query, a Continuous Query

transaction, or a password change transaction. No more than one password change transaction can be

included at any time.

4. Submission files must not exceed 512 KB.

3.6 Downloading Files

Response files are stored in the download directory after being successfully downloaded from the Data

Bank. The names of the files are in the following format: ####################.xml (i.e., a unique

20-digit ID number with the ‘xml’ extension).

The download list file contains the names of downloaded files. The name of the download list file must be

specified in the qrxs.properties file with the DownloadListFile property. If it is not specified, it defaults

to download.lst.

The following is the content of a download list file that might be created:

10000000000000000001.xml

10000000000000000002.xml

10000000000000000003.xml

10000000000000000004.xml

tes:

QRXS Client Program User Guide Version 2.03

August 2021 9

1. The downloaded response files have unique names. If files from a previous download exist in the

directory, then the new files will be added to the directory without affecting the existing files.

2. The download list file is recreated on every successful download of response files. The download list

file is not created if there are no response files to download or if there was an error downloading

response files.

3. Response files will not exceed 1MB. Responses that are larger than 1MB are separated into multiple

response files. Responses for a file-based password change request will always be returned in a

single response file. Users should read response files in numerical order.

4. The maximum number of responses that will be returned from the NPDB in one connection is 1,000.

You may download more than 1,000 responses by performing a receive multiple times.

5. Responses to report, one-time query, and Continuous Query submissions are available for download

within an average of 2 to 4 hours after submission. Under certain circumstances, additional

processing time may be required. Please do not re-submit your report, one-time query, or Continuous

Query transaction on the subject in question, since this will result in duplicate transactions and

duplicate fees. If your submission file is not formatted properly, the NPDB may not be able to

process the file. If you do not receive your response within 2 to 3 business days of submission, please

call the NPDB Customer Service Center.

6. Continuous Query Report Disclosures will be available within one day of a report being received.

7. Responses to file-based password change request submissions are generally available for download

within several minutes.

3.7 Encoding the Password

In order to maintain the integrity and confidentiality of the NPDB information, the QRXS initialization

file must contain a valid encrypted NPDB password. A valid password and UserID is required for the

successful execution of all upload and download transactions. The password is associated with a

registered NPDB user, and will expire periodically. Password restrictions and guidelines can be found at

https://www.npdb.hrsa.gov/Passwords

. The command listed below must be executed prior to the first

upload or download transaction, and each time the NPDB user updates their password.

The password is encoded by executing the encode command of the client and providing the password as a

command-line parameter. The password is encoded and written to qrxs.properties. The password must

be entered using this encode method for login validation to succeed. The following is an example of

how to perform the encoding:

java com.npdbhipdb.QRXS encode OakTreesGrowTa11

The encrypted password is then written to the qrxs.properties file:

Password=2MhEB2Fsue1I7eqJLDyI

If your organization uses a proxy server to connect to the internet and the proxy server requires

authentication, you will also have to encode the proxy password in the properties file. The proxy

password is encoded by executing the encodeproxypwd command and providing the password as a

command-line parameter. The proxy password is encoded and written to qrxs.properties. The proxy

QRXS Client Program User Guide Version 2.03

August 2021 10

password must be entered using this encode method for proxy authentication to succeed. The

following is an example of how to perform the encoding:

java com.npdbhipdb.QRXS encodeproxypwd myPa$$w0rd

The encrypted password is then written to the qrxs.properties file:

ProxyPassword=V5dbDONep3sh0/Yg49OYpQ\=

Notes:

1. T

he commands and the passwords are case sensitive.

2. The encoding process may cause some characters in qrxs.properties to be escaped; this is denoted by

a backslash in front of the escaped characters.

3. The encoding process may cause the lines in qrxs.properties to be reordered; this does not affect the

operation of the client.

3.8 Password Changes

As explained in Section 1.2.2, User Account Password Policies, a valid password is required to submit

transactions to and download responses from the NPDB.

here are three methods for QRXS users to change user account passwords within the NPDB:

1. Interactively via the Internet using the Integrated Querying and Reporting Service (IQRS).

2. Through a QRXS command-line operation.

3. Through a QRXS transaction file submission, with data provided in the format specified in the

Password Change XML ICD.

3.8.1 Types of Password Change Transactions

assword changes can be one of two types:

hange: Used by an entity user or Entity Data Bank Administrator to change their own account

password. For file-based password change transactions, the response file can only be downloaded by the

same user account that submitted the transaction. File-based password changes must be re-encoded

before using. Command-line password changes are automatically encoded.

Rese

t: Used by the Entity Data Bank Administrator to reset a user’s password when the account is locked

or the password is unknown. Only the Entity Data Bank Administrator is permitted to reset a user’s

password. For file-based password reset transactions, only the Entity Data Bank Administrator may

download the response file. An Entity Data Bank Administrator may not “reset” their own password, but

may “change” their password. The reset transaction returns a system-generated temporary password.

This password must be encoded into the qrxs.properties file before use, and the user must perform a

password “change” transaction before submitting any other transaction.

QRXS Client Program User Guide Version 2.03

August 2021 11

3.8.2 Command-Line Password Transactions

Users and Entity Data Bank Administrators can change their own NPDB password using the

changepassword command:

java com.npdbhipdb.QRXS changepassword OakTreesGrowTa11

If the status code "C00" is indicated after submitting a changepassword command, the password change

was successful and the qrxs.properties file was updated with the correct encoded Password parameter:

Password=XShrjh5blOsXCNX3SyxiZ6dweHs\=

If the password change transaction fails, the reasons for failure will be displayed on the console:

java com.npdbhipdb.QRXS changepassword xxyyzz

QRXS Changing Password...

Error code: S2: The new password must be between 15 and 64 characters long.

S9: The new password did not contain enough different characters.

Status Code: C61

Entity Data Bank Administrators can reset any user's password (except their own) using the

resetpassword command along with the User ID of the account to be reset:

java com.npdbhipdb.QRXS resetpassword bobjones

If the status code "C00" is indicated after submitting a resetpassword command, the password reset was

successful.

QRXS Resetting Password...

New Password: 862ewjc9w

Status Code: C00

A system-generated password is displayed. This password must be encoded and changed by the user

(using the changepassword command). The user may then use the password to submit QRXS files.

3.8.3 File-Based Password Transactions

File-based password change transactions are submitted as XML files through the QRXS. The Password

Change XML ICD details the necessary file-format specifications.

If status code "C00" is indicated after submitting a file-based password change request transaction, the

password for the specified DBID/User ID was changed successfully. The new password must be encoded

into the qrxs.properties file in order to download the password change response, submit additional

transactions, and download responses. For that process, follow the instructions specified in Section 3.7,

Encoding the Password.

If status code "C00" is not indicated after submitting a password change request transaction, the password

change request for the specified DBID/User ID was unsuccessful. The password rejection file will be

returned immediately and stored as specified in the download.lst file. Refer to the Code Lists document

at https://www.npdb.hrsa.gov/Codes

for a list of rejection codes.

It is recommended when submitting a file-based password change transaction that you do not submit any

other transactions until the password change has been successfully processed and the response file

QRXS Client Program User Guide Version 2.03

August 2021 12

downloaded. No more than one password change transaction can be included in the upload file at any

time.

3.9 Show Version Number

You can use the showversion command to determine the current version of the QRXS client program in

use:

java com.npdbhipdb.QRXS showversion

The current version will be shown in the response on the console:

QRXS Version: 1.05

Status Code: C00

QRXS Client Program User Guide Version 2.03

August 2021 13

4. QRXS Test Environment

The following sections guide you through configuring the QRXS Client to connect to the QRXS test

environment. The QRXS test environment enables you to test network connectivity to the NPDB system

and to validate your submission files are well-formed and meet the mandatory data requirements.

4.1 Overview

• Submissions that are well-formed and meet the data requirements will receive an immediate

status of success.

• Rejected submissions will result in an immediate rejection response file.

• Submission files will not be processed through the system. Sample QRXS response files will be

returned via QRXS Receive. See the Querying And Reporting XML Service (QRXS) Response

File Test Mappings document for a full listing of available sample files that may be received. If

no particular response file is specified (see Section 4.3 Receiving Test Files below), a sample

Continuous Query Enrollment and Continuous Query Report Disclosure will be returned. In

addition, sample response files may be found in the QRXS File Format Specifications zip file.

• QRXS test environment submissions will NOT be billed.

• Transactions can be submitted either as an entity or as an agent on behalf of an entity.

• In order to access the QRXS test environment you must obtain a “vendor ID” from

https://www.npdb.hrsa.gov/software/softwareSignIn.jsp

. Use your Vendor ID as your User ID to

submit transactions.

4.2 Submitting Test Files

The entityDBID and agentDBID inside each XML submission file should be modified to match the test

DBID listed within the qrxs.properties initialization file.

4.2.1 Configuration

Configure your qrxs.properties initialization file as follows to submit files to the QRXS test environment:

UserID=<your vendor ID>

#The entity DBID below should be 800000000000000.

#To test as an agent, use DBID=800000000000001.

DBID=800000000000000

DownloadListFile=download.lst

DownloadDir=download

UploadListFile=upload.lst

Password= bSTIrO3yVunS8272zwvjPb6fIpM\=

InputURL=https\://qa.npdb.hrsa.gov/qrxs/servlet/XMLInputServlet

OutputURL=https\://qa.npdb.hrsa.gov/qrxs/servlet/XMLOutputServlet

VerificationURL=https\://qa.npdb

.hrsa.gov/qrxs/servlet/XMLResponseVerificationServlet

QRXS Client Program User Guide Version 2.03

August 2021 14

4.2.2 Payment

User

s submitting one-time queries, or Continuous Query enrollments, or renewals may use either:

o A pre-configured EFT account.

</payment>

o The credit card number 4111111111111111. The credit card expiration date may be any

future date.

<cardholderName>JOE SMITH</cardholderName>

</cardholderAddress>

</creditCard>

</payment>

4.2.3 Continuous Query

ontinuous Query enrollments, renewals, updates, cancellations, and status requests can be tested by

sending Continuous Query submission files to the QRXS test environment. On submission there will be

an immediate confirmation file returned.

NPDB Subject IDs 888000000000111 and 888000000000222 may be used to test renewals, updates,

cancellations, and status requests. databankSubjectID 888000000000111 should be used for transactions

submitted by the entity, and databankSubjectID 888000000000222 should be used for transactions

submitted by the agent on behalf of the entity.

Updates may be validated against the following subject data (which will match the sample report).

Remember, if more than 3 fields are updated in one update the update will reject.

<name>

</name>

<address>123 MAIN STREET</address>

<city>FAIRFAX</city>

QRXS Client Program User Guide Version 2.03

August 2021 15

</workAddress>

<school>SCHOOL</school>

</professionalSchool>

</occupationAndLicensure>

</individual>

4.2.4 Reports

User

s may validate Correction Reports and Revision-to-Action Reports against test reports in our system.

Use the DCNs below to test Correction and Revision-to-Action Report submissions.

able 3: Report DCNs for Testing

DCN

Type of Report

2000000000000001

Individual State Licensure Initial Report

2000000000000013

Individual State Licensure Revision to Action

Report

2000000000000002

Organization State Licensure Initial Report

2000000000000012

Organization State Licensure Revision to Action

Report

4.3 Receiving Test Files

Users may specify the type of response file they wish to receive by referring to the Querying And

Reporting XML Service (QRXS) Response File Test Mappings. The Response Type column lists the

exact <Response Type> to place in the UserID field of the qrxs.properties initialization file. If no

particular response file is specified, a sample Continuous Query Enrollment and Continuous Query

Report Disclosure will be returned. The sample response files returned are identical to the response files

found in the QRXS File Format Specifications zip file. Please note, the vendor ID returned within the

sample files is invalid and should be ignored.

4.3.1 Configuration

Configure your qrxs.properties initialization file as follows to receive files from the QRXS test

environment:

UserID=<your vendor ID>|<Response Type>

#The entity DBID below should be 800000000000000.

#To test as an agent, use DBID=800000000000001.

DBID=800000000000000

QRXS Client Program User Guide Version 2.03

August 2021 16

DownloadListFile=download.lst

DownloadDir=download

UploadListFile=upload.lst

Password= bSTIrO3yVunS8272zwvjPb6fIpM\=

InputURL=https\://qa.npdb.hrsa.gov/qrxs/servlet/XMLInputServlet

OutputURL=https\://qa.npdb.hrsa.gov/qrxs/servlet/XMLOutputServlet

VerificationURL=https\://qa.npdb.hrsa.gov/qrxs/servlet/XMLResponseVerificationSer

vlet

4.3.1.1 Requesting Multiple Response Files

Users may request multiple response files with a QRXS receive by indicating multiple <Response Type>

names in the User ID field. The names must be separated by a “|” character.

or example: UserID=<your vendor ID>|SL_Ind_Initial|SL_Ind_Void|SL_Ind_Appeal

Will r

eturn the following three response files:

_Ind_Initial_Response.xml

SL_Ind_Void_Response.xml

SL_Ind_Appeal_Response.xml

.3.1.2 Requesting Response File Versions

Occasionally, multiple versions of a response file may exist. This may be due to an anticipated system

change, where a response file will show a future file specification. Users may specify a particular file

version by indicating the <Response Version> after the <Response Type>. They must be separated by a

“:” character. If a version is not specified, the most current version will be provided. The version

number for a particular sample file is found in the Read Me text of the sample response files.

or example: UserID=<your vendor ID>|SL_Ind_Initial:1.05|Query_Ind_Single

:1.01|SL_Ind_Appeal:1.05

Will return the following three response files:

_Ind_Initial_Response.xml

Ind_Single_Success_Response.xml

SL_Ind_Appeal_Response.xml

4.3.2 Continuous Query

mple Continuous Query Report Disclosure and sample Continuous Query Enrollment Responses will

be returned with report information that matches the Sample Report with DCN 2000000000000001,

specified in Section 4.2.4.

QRXS Client Program User Guide Version 2.03

August 2021 17

5. Sample Configuration and Execution

The following sections guide you through a sample configuration and execution of the QRXS client. This

is only a sample configuration and may be changed if desired.

5.1 Configuration

The client is installed in the directory c:\QRXS for entity DBID 123400000000123, UserID BobJones,

and password OakTreesGrowTa11. The initialization file is configured with the download directory

c:\QRXS\download, upload file updlist.fil, download list file qrxsresp.fil, and log file qrxserrors.fil. The

submission files for upload are located in c:\QRXS\upload. The user creates the new directories:

cd QRXS

mkdir download

mkdir upload

The following is a listing of files in directory c:\QRXS:

qrxs.properties

<DIR> download

<DIR> upload

he working directory is c:\QRXS. Encode the password by executing the following command:

java com.npdbhipdb.QRXS encode OakTreesGrowTa11

he following is a printout of the qrxs.properties initialization file (the order of properties may vary; this

is normal):

UploadListFile=updlist.fil

Password=2MhEB2Fsue1I7eqJLDyI

DownloadDir=download

DBID=123400000000123

UserID=BobJones

DownloadListFile=qrxsresp.fil

LogFile=qrxserrors.fil

5.2 Uploading Submission Files

The submission files must first be uploaded to the NPDB. Submission files 0000001.xml, 0000002.xml,

0000003.xml, and 0000004.xml are placed in the upload directory c:\QRXS\upload. The upload file,

updlist.fil, is placed in the working directory c:\QRXS. The following is a printout of updlist.fil:

c:\QRXS\upload\0000001.xml

c:\QRXS\upload\0000002.xml

c:\QRXS\upload\0000003.xml

c:\QRXS\upload\0000004.xml

Execute the following command, either from the command prompt or from a user application, to upload

files to the NPDB. This command is case sensitive and must be executed exactly as shown here:

java com.npdbhipdb.QRXS send

QRXS Client Program User Guide Version 2.03

August 2021 18

After execution of this command, the submission files are uploaded to the NPDB successfully. The

submission may generate some immediate responses, depending on the processing required to handle

the submissions. The number of responses received will be displayed:

QRXS Sending…

Received 2 response(s)

Status Code: C00

he response files are downloaded to the download directory, c:\QRXS\download. The download list file

qrxsresp.fil is created in the directory c:\QRXS.

The file qrxsstat.dat is created in the working directory c:\QRXS. The qrxsstat.dat file indicates a

successful status code of “C00.” The following is a printout of the qrxsstat.dat file that is created:

Overall status=Done

Status Code=C00

5.3 Downloading Response Files

The remaining response files may be downloaded after they have completed processing. To download

response files, execute the QRXS client in receive mode:

java com.npdbhipdb.QRXS receive

fter execution of this command the response files are downloaded from the NPDB successfully. The

number of responses received will be displayed:

QRXS Receiving...

Received 4 response(s)

Status Code: C00

he four response files are downloaded to the download directory, c:\QRXS\download. The directory

c:\QRXS\download contains the following files:

10000000000000000001.xml

10000000000000000002.xml

10000000000000000003.xml

10000000000000000004.xml

e download list file qrxsresp.fil is created in the directory c:\QRXS. The following is a printout of the

qrxsresp.fil file:

c:\QRXS\download\10000000000000000001.xml

c:\QRXS\download\10000000000000000002.xml

c:\QRXS\download\10000000000000000003.xml

c:\QRXS\download\10000000000000000004.xml

he status file qrxsstat.dat is also created in the directory c:\QRXS. The following is a printout of the

qrxsstat.dat file that is created:

Overall status=Done

StatusCode=C00

5.4 Proxy Server

A proxy server is a program that mediates requests between the local network and the workstations on

them and the Internet beyond. Contact your network administrator for proxy server information. To

QRXS Client Program User Guide Version 2.03

August 2021 19

enable the QRXS to work with proxy servers, the qrxs.properties file needs the parameters

ProxyHostName (specifies the host name of the proxy server; usually an IP Address), and ProxyPort

(specifies the port number the proxy server connects to).

The QRXS client supports Basic, Digest and NTLMv1 authentication with proxy servers. If your proxy

server requires authentication, the qrxs.properties file needs the parameters ProxyUser and

ProxyPassword. The ProxyPassword parameter can only be set with the encodeproxypwd command:

java com.npdbhipdb.QRXS encodeproxypwd myPa$$w0rd

If your proxy server uses NTLM authentication, the qrxs.properties file will also need the parameter

ProxyDomain. Set this parameter to name of the Windows domain used for authentication.

Once all required proxy parameters are set, sending and receiving from the QRXS proceeds as normal.

The following is a printout of the qrxs.properties initialization file for use with a Proxy Server requiring

NTLM authentication:

UploadListFile=updlist.fil

Password=2MhEB2Fsue1I7eqJLDyI

DownloadDir=download

DBID=123400000000123

UserID=BobJones

DownloadListFile=qrxsresp.fil

LogFile=qrxserrors.fil

ProxyHostName=111.111.111.111

ProxyPort=1000

ProxyUser=bobjones

ProxyPassword=V5dbDONep3sh0/Yg49OYpQ\=

ProxyDomain=NTDOMAIN

QRXS Client Program User Guide Version 2.03

August 2021 20

6. Application Programming Interface

6.1 Overview

The QRXS Application Programming Interface (API) is a Java-based library that provides the capability

to interface with the QRXS. The API provides the same capabilities available in the QRXS client

program. In fact, the QRXS client is built on top of the API. Javadocs for the QRXS API can be found

on-line at https://www.npdb.hrsa.gov/QRXS

6.2 When to use the API

The provided client program is appropriate for most users. The API may be beneficial for users who wish

to integrate their QRXS interaction into existing Java software. Submitting files and examining responses

and error codes can be done programmatically, eliminating the need to write code to parse the text results

that are generated by the client program.

6.3 Using the API

Install the libraries as described in Section 2.3, Software Installation. The QRXS API is in the

com.npdbhipdb package. Import the package to make the API visible to the Java application.

import com.npdbhipdb.*;

6.3.1 Configuration

The QRXS Configuration class contains the properties needed to communicate with the QRXS. An

instance of the Configuration is created and the object is passed to the send() or receive() method. A

Configuration instance can be created using an existing initialization file (Section 3.2, Preparing the

Initialization File), or by providing the property values directly during instantiation.

6.3.1.1 Using a File

A Configuration object can be created using the same properties file format (Section 3.2, Preparing the

Initialization File) used for the client application. The password must be encoded in the file using the

client’s encode command (Section 3.7, Encoding the Password) or the API encode() method (Section

6.3.2, Encoding). Exceptions can be thrown if a required property is not defined or if the file cannot be

opened.

final String configFilename = "qrxs.properties";

/ create an instance of QRXS

QRXS qrxsClient = new QRXS();

QRXS.Configuration config;

try

{

// c

reate Configuration using the properties file

config = qrxsClient.new Configuration(configFilename);

}

catch (QRXS.Configuration.InvalidConfigurationException e)

{

// configur

ation property missing

System.out.println("Error: " + e.getCode());

}

catch (QRXSException e)

{

QRXS Client Program User Guide Version 2.03

August 2021 21

// problem encountered opening the file

System.out.println("Error: " + e.getCode());

}

6.3.1.2 Using Parameters

A Configuration object can be created by specifying the required properties as parameters to the

constructor. The constructor accepts all the required QRXS properties as arguments. Additional QRXS

properties including proxy server settings can be set using the “set” methods as shown below. With this

method there is no need to perform the password encoding required when using a file. An exception will

be thrown if a property value is invalid.

final String entityDBID = "123456787654321";

final String userID = "myusername";

final String password = "OakTreesGrowTa11";

final String downloadDir = "C:/QRXS/download";

QRXS.Configuration config;

// create an instance of QRXS

QRXS qrxsClient = new QRXS();

try

{

// create Configuration using the required values

config = qrxsClient.new Configuration(entityDBID, userID, password, downloadDir);

// QA environment

final String url = "https://qa.npdb.hrsa.gov/qrxs/servlet/";

config.setInputURL(url + "XMLInputServlet");

config.setOutputURL(url + "XMLOutputServlet");

config.setVerifyURL(url + "XMLResponseVerificationServlet");

config.setLogFileName("c:/qrxs/qrxs.log");

config.setProxyHostName("111.111.111.111");

config.setProxyPort("8080");

config.setProxyUser("username");

config.setProxyPassword("myPa$$w0rd");

config.setProxyDomain("NTDOMAIN");

}

catch (QRXS.Configuration.InvalidConfigurationException e)

{

// configuration property invalid

System.out.println("Error: " + e.getCode());

}

6.3.2 Encoding

Encoding is used to write an encrypted password to a configuration properties file. The file will be re-

written with the password value encoded. The ordering of the properties in the file may be changed by

the encoding process. The password in a configuration file must be encoded before sending and

receiving or authentication will fail.

final String password = "OakTreesGrowTa11";

final String configFilename = "qrxs.properties";

String status;

QRXS Client Program User Guide Version 2.03

August 2021 22

// create an instance of QRXS client

QRXS qrxsClient = new QRXS();

try

{

status = qrxsClient.encode(configFilename, password);

System.out.println("QRXS status: " + status);

}

catch (QRXSException e)

{

// unable to read/write the configuration file

System.out.println("Error: " + e.getCode());

}

6.3.3 Sending

The send process involves establishing the connection to the QRXS, uploading the specified submission

files, and receiving responses.

// create Lists to hold submissions and responses

List responseFilenames = new ArrayList();

List submissionFilenames = new ArrayList();

List errorFiles = new ArrayList();

String status;

populate the list of file(s) to upload

submissionFilenames.add("C:/QRXS/upload/000000001.xml");

// add the remaining files

try

{

// send the files

status = qrxsClient.send(config, submissionFilenames,

responseFilenames, errorFiles);

System.out.println("QRXS status: " + status);

}

catch (QRXSException e)

{

System.out.println("Error Code: " + e.getCode());

System.out.println("Error Message: " + e.getMessage());

}

Files returned in the response are stored to the location specified in the Configuration object. The

responseFilenames List contains the names of the response files. Sent files that could not be processed

are listed with the accompanying error code in a list of

ErrorFile objects. Each ErrorFile object also

contains one or more error messages giving a textual description of the error.

Iterator fileIter = errorFiles.iterator();

while (fileIter.hasNext())

{

QRXS.ErrorFile err = (QRXS.ErrorFile) fileIter.next();

System.out.println("File " + err.getFilename() + ", " + err.getCode());

String errorMessages[] = err.getErrorMessages();

for (int i=0; i<errorMessages.length; i++)

QRXS Client Program User Guide Version 2.03

August 2021 23

{

System.out.println("Error Message: " +

MessageFormat.format(errorMessages[i], new String[]

{err.getFilename()}));

}

6.3.4 Receiving

The receive process establishes the connection to the QRXS and downloads any response files that have

completed processing by the NPDB.

// create List to hold responses

List responseFilenames = new ArrayList();

String status;

{

status = qrxsClient.receive(config, responseFilenames);

System.out.println("QRXS status: " + status);

}

catch (QRXSException e)

{

System.out.println("Error Code: " + e.getCode());

System.out.println("Error Message: " + e.getMessage());

}

Files returned in the response are stored to the location specified in the Configuration object. The

responseFilenames List contains the names of the response files.

6.3.5 Changing The Password

The password can be changed and optionally encoded into a configuration file. If the fourth parameter is

true, the password will be encoded into the file specified in the third parameter. If the fourth parameter is

false, the third parameter is ignored.

try

{

// change the password and encode into c:/qrxs/qrxs.properties

status = qrxsClient.changePassword(config, "OakTreesGrowTa11",

"c:/qrxs/qrxs.properties", true);

System.out.println("QRXS status: " + status);

}

catch (QRXSException e)

{

System.out.println("Error Code: " + e.getCode());

System.out.println("Error Message: " + e.getMessage());

}

6.3.6 Resetting The Password

The Entity Data Bank Administrator can reset a user’s password if the user has lost the password or has

been locked out.

String userToReset = "JerrySmith";

QRXS Client Program User Guide Version 2.03

August 2021 24

try

{

// reset the password

status = qrxsClient.resetPassword(config, userToReset);

System.out.println("QRXS status: " + status);

}

catch (QRXSException e)

{

System.out.println("Error Code: " + e.getCode());

System.out.println("Error Message: " + e.getMessage());

}

System.out.println("Temporary password for " + userToReset + " is:" +

qrxsClient.getNewPassword());

6.3.7 Retrieving Version Number

The version number may be retrieved as a string value for printing or storing.

// retrieves the version number of the QRXS client

String

versionNumber = qrxsClient.getVersion();