Usage
Read this guide to learn how to install ProKnow SDK and get started with your first script.
Installation
Use pip
to install:
pip install --upgrade proknow
Basic Usage
To use the SDK, you’ll need two important items:
Base URL: This is the URL that will be used to make API requests to ProKnow. It’s the first part of the web address you see when you are signed in to your ProKnow DS account. The form of this URL is typically
https://your-domain.proknow.com
.API Token: You can generate an API token in the ProKnow DS user interface. Always keep your API Token secret. Once you have your
credentials.json
, make note of the file path.
The code snippet below can be used to test your installation of the proknow
package. Please be sure to replace https://example.proknow.com
with your organization’s Base URL described above, and replace ./credentials.json
with the path to your credentials file:
from proknow import ProKnow
pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
workspaces = pk.workspaces.query()
print("The workspaces are as follows:")
for workspace in workspaces:
print(workspace.name)
If an adaptation of the script above does not work for you see the troubleshooting section below.
Feature List
For an updated picture of the pieces of the API that have been implemented in the Python SDK, please visit our Feature List page on the project Wiki.
Troubleshooting
Connection errors
These can be caused by the failure to replace https://example.proknow.com
as your base_url
. https://example.proknow.com
is not a real endpoint and will not work. If you’ve already replaced the base URL, login to your ProKnow DS account and check to make sure it matches the base URL shown in the address bar.
If you are able to login to your ProKnow DS account and have verified that the base URLs match, there is also a chance that your organization’s firewall is configured to block traffic originating from unknown sources like your Python script. If this is the case please contact your IT department to request special permission for your script to access the ProKnow API from inside your organization’s network.
File not found errors
If you specified a credentials_file
in the ProKnow constructor, but are receiving a message saying that the file or directory does not exist, you may have a typo in your credentials file path. Correct the file path, and try again. Note that relative file paths are usually relative to the directory from which the python
executable is being invoked.
Type or Assertion errors
These indicate that you’ve provided invalid parameters to the ProKnow
contructor. The error message can usually point you in the right direction. Correct the parameters, and try again.
Copying examples without modification
The examples shown throughout this documentation are meant to be representative and are not likely to work without modification. Let’s take a look at the example for the method proknow.Patients.PatientItem.set_metadata()
:
from proknow import ProKnow
pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
meta = patient.get_metadata()
meta["Genetic Type"] = "Type II"
patient.set_metadata(meta)
patient.save()
This script will not work in your set up for several reasons:
Your
base_url
for your ProKnow account is nothttps://example.proknow.com
.Your
credentials.json
file may not be located at the path “./credentials.json.”You probably do not have a patient with the MRN “HNC-0522c0009” in a workspace called “Clinical.”
You probably do not have a custom metric called “Genetic Type.”
If you run into problems while running your script, examine the error message and make sure you didn’t copy a code example without making the proper modifications. Values may need to be replaced or additional setup code may need to be added before the code you copied in order for your script to function properly.