Before you can use the qpp-conversion-tool application, you must install and configure the following products on your machine:
Git and/or the GitHub application.
GitHub's Guide to Installing Git is a good source of information.
Java Runtime (version
It is important that you have the right version of
javaon your path.
# When you run 'java -version', you should get 11. For example: java -version java version "11" ...
Sometimes the Java Runtime installer doesn't update your path. So you must do it manually. Alternatively, download and install the Java Development Kit (version
>= 1.8). The JDK is better at updating your path.
Maven is used to build the application, manage dependencies, and run tests. After you unzip the Maven archive, you need to add the
bindirectory to your path, as described the Maven installation instructions.
# When you run 'mvn -v', you should get 3.8.4. For example: mvn -v Apache Maven 3.8.4 ...
Docker is not required but is an alternative to the above requirements if all you need is to run the converter.
Getting the Converter
Use the GitHub application or the command line to clone this repository.
# Clone the GitHub repository. git clone https://github.com/CMSgov/qpp-conversion-tool.git # Go to the qpp-conversion-tool directory. cd ./qpp-conversion-tool
Running the Converter
ReST API via Docker
The Conversion Tool can be executed through a ReST API. Using the ReST API has the added benefit of having the
QPP validated if you so choose. For the examples below, make sure you're in the
Starting the API Endpoint
# Build the Docker image and run the container using docker-compose. docker-compose -f ./docker-compose.test.yaml up
Invoking the Endpoint
curl -X POST \ http://localhost:3000 \ -H 'cache-control: no-cache' \ -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \ -F file=@./qrda-files/valid-QRDA-III-latest.xml
The response body will either be the QPP JSON on success or error JSON on an error.
The HTTP Status will be
201 Created on success or
422 Unprocessable entity on an error.
While the converter will validate the format of the QRDA-III file and some basic semantics, deeper semantic checks are only available if you enable the public submission validation API. If any errors are found by the public submission validation API, error JSON will be returned from the ReST API like normal.
To enable the public submission validation API, modify the
.env file with
VALIDATION_URL=https://qpp.cms.gov/api/submissions/public/validate-submission and then
restart the ReST API endpoint.
Ensure the environment variable
CPC_END_DATE is set to a valid date, in the format
YYYY-MM-DD, or a validation error may be thrown.
For the examples below, make sure you're in the
Note: If you are using Windows, replace
./convert.sh in the examples below with
Convert a File
# Try the convert script. If the JAR isn't built yet, the script will build it for you first. ./convert.sh ./qrda-files/valid-QRDA-III-latest.xml
If a QRDA-III XML file is successfully converted, a QPP JSON file is created in the current working directory.
The file name will have the same name as the input file but with the extension
When an invalid file is provided to the converter, an error JSON file is created in the current working directory.
The file name will be the same as the input file but with the extension
not-a-QRDA-III-file.err.json. This error file contains descriptions and XPaths that help in identifying the
errors in the provided input file.
View all commands with
Sample QRDA-III files that cover all of the eCQM, PI, and IA measures as well as other scenarios can be found in the sample-files folder.
Want to Contribute?
Want to file a bug or contribute some code? Read up on our guidelines for contributing and developer instructions.
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.
See the formal LICENSE file.