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

❌ - Not Implemented ✅ - Implemented

Status	Description	Route
❌	Resolve the organization client from the current subdomain	GET /api/organization/resolve
❌	Get the current organization details	GET /api/organization
❌	Updates the current organization settings	PATCH /api/organization
❌	Create a group	POST /api/groups
❌	List groups	GET /api/groups
❌	Update a group	PATCH /api/groups/:gid
❌	Delete a group	DELETE /api/groups/:gid
❌	List group members	GET /api/groups/:gid/members
❌	Add a group member	PUT /api/groups/:gid/members/:mid
❌	Delete a group member	DELETE /api/groups/:gid/members/:mid
✅	Create a role	POST /api/roles
✅	List roles	GET /api/roles
✅	Get a role	GET /api/roles/:rid
✅	Update a role	PATCH /api/roles/:rid
✅	Delete a role	DELETE /api/roles/:rid
❌	List role assignments	GET /api/resources/:rid/assignments
❌	Add a role assignment	PUT /api/resources/:rid/assignments
❌	Delete a role assignment	DELETE /api/resources/:rid/assignments
❌	Resolve permissions for a given resource	GET /api/resources/:rid/permissions/session
✅	Create a user	POST /api/users
✅	Delete a user	DELETE /api/users/:uid
✅	Get a user	GET /api/users/:uid
✅	List users	GET /api/users
✅	Update a user	PUT /api/users/:uid
✅	Get the current user	GET /api/user
❌	Update the current user’s MFA settings	PUT /api/user/mfa
❌	Delete the current user’s MFA settings	DELETE /api/user/mfa
❌	Update the current user’s preferences	PATCH /api/user/preferences
❌	Get the current user’s preferences	GET /api/user/preferences
❌	Update the current user’s state	PATCH /api/user/state
❌	Get the current user’s state	GET /api/user/state
❌	Create an API keys	POST /api/apikeys
❌	List API keys	GET /api/apikeys
❌	Delete API keys	DELETE /api/apikeys/:id
✅	Create a workspace	POST /api/workspaces
✅	Delete a workspace	DELETE /api/workspaces/:wid
✅	List workspaces	GET /api/workspaces
✅	Update a workspace	PATCH /api/workspaces/:wid
✅	Search audit events	POST /api/audit/events/search
✅	Create a custom metric	POST /api/metrics/custom
✅	List custom metrics	GET /api/metrics/custom
✅	Get a custom metric	GET /api/metrics/custom/:id
✅	Delete a custom metric	DELETE /api/metrics/custom/:id
✅	Update a custom metric	PUT /api/metrics/custom/:id
✅	Create a scorecard template	POST /api/metrics/templates
✅	List scorecard templates	GET /api/metrics/templates
✅	Get a scorecard template	GET /api/metrics/templates/:msid
✅	Delete a scorecard template	DELETE /api/metrics/templates/:msid
✅	Update a scorecard template	PUT /api/metrics/templates/:msid
❌	Create an organization metric objectives set	POST /api/metrics/objectives
❌	List organization metric objectives sets	GET /api/metrics/objectives
❌	Update an organization metric objectives set	DELETE /api/metrics/objectives/:id
✅	Perform a renaming rule search	POST /api/renaming/search
✅	List renaming rules	GET /api/renaming/rules
✅	Update renaming rules	PUT /api/renaming/rules
✅	Execute a renaming rule	POST /api/renaming/rules/:id/exec
❌	Create a checklist template	POST /api/checklists/templates
❌	List checklist templates	GET /api/checklists/templates
❌	Update a checklist template	PUT /api/checklists/templates/:id
❌	Delete a checklist template	DELETE /api/checklists/templates/:id
❌	Create a structure set template	POST /api/structuresets/templates
❌	List structure set templates	GET /api/structuresets/templates
❌	Update a structure set template	PUT /api/structuresets/templates/:id
❌	Delete a structure set template	DELETE /api/structuresets/templates/:id
✅	Create a collection	POST /api/collections
✅	List collections	GET /api/collections
✅	Get a collection	GET /api/collections/:id
✅	Delete a collection	DELETE /api/collections/:id
✅	Update a collection	PUT /api/collections/:id
❌	Update workspaces for a collection	PATCH /api/collections/:id/workspaces
❌	Get analysis data for a collection	GET /api/collections/:id/analysis/:tag
✅	Add patients to a collection	PUT /api/collections/:id/workspaces/:wid/patients
✅	Delete patients from a collection	DELETE /api/collections/:id/workspaces/:wid/patients
✅	List collection patients	GET /api/collections/:id/patients
❌	List ROIs observed in a collection	GET /api/collections/:id/rois
❌	List patients in collection with specified ROI	GET /api/collections/:id/rois/patients
❌	List analysis ROIs configured for a collection	GET /api/collections/:id/rois/analysis
❌	Update analysis ROIs configured for a collection	PUT /api/collections/:id/rois/analysis
❌	List collection computed metrics	GET /api/collections/:id/metrics/computed
❌	List collection computed metric values	GET /api/collections/:id/metrics/computed/values
❌	Add computed metrics to a collection	PUT /api/collections/:id/metrics/computed
❌	Delete computed metrics from a collection	DELETE /api/collections/:id/metrics/computed
❌	List collection custom metrics	GET /api/collections/:id/metrics/custom
❌	List collection custom metric values	GET /api/collections/:id/metrics/custom/:metric
❌	Create a bookmark for a collection	POST /api/collections/:id/bookmarks
❌	List bookmarks for a collection	GET /api/collections/:id/bookmarks
❌	Delete a bookmark from a collection	DELETE /api/collections/:id/bookmarks/:aid
❌	Update a bookmark for a collection	PUT /api/collections/:id/bookmarks/:aid
✅	Create a scorecard for a collection	POST /api/collections/:id/metrics/sets
✅	List scorecards for a collection	GET /api/collections/:id/metrics/sets
✅	Get a scorecard for a collection	GET /api/collections/:id/metrics/sets/:msid
✅	Delete a scorecard from a collection	DELETE /api/collections/:id/metrics/sets/:msid
✅	Update a scorecard for a collection	PUT /api/collections/:id/metrics/sets/:msid
❌	List prescriptions observed in a collection	GET /api/collections/:id/prescriptions
✅	Create a patient	POST /api/workspaces/:wid/patients
✅	List patients	GET /api/workspaces/:wid/patients
✅	Get a patient	GET /api/workspaces/:wid/patients/:id
✅	Update a patient	PUT /api/workspaces/:wid/patients/:id
✅	Delete a patient	DELETE /api/workspaces/:wid/patients/:id
✅	Update metadata for a patient	PATCH /api/workspaces/:wid/patients/metadata
❌	Get patient state	GET /api/workspaces/:wid/patients/:id/state
✅	Lookup patients	POST /api/workspaces/:wid/patients/lookup
❌	Update patient collections	PATCH /api/workspaces/:wid/patients/:id/collections
❌	Move a patient	POST /api/workspaces/:wid/patients/:id/move
✅	Create a scorecard for a patient	POST /api/workspaces/:wid/patients/:id/metrics/sets
✅	List scorecards for a patient	GET /api/workspaces/:wid/patients/:id/metrics/sets
✅	Get a scorecard for a patient	GET /api/workspaces/:wid/patients/:id/metrics/sets/:msid
✅	Delete a scorecard from a patient	DELETE /api/workspaces/:wid/patients/:id/metrics/sets/:msid
✅	Update a scorecard for a patient	PUT /api/workspaces/:wid/patients/:id/metrics/sets/:msid
❌	Update patient state	POST /api/workspaces/:wid/patients/:id/state
❌	Create a checklist for a patient	POST /api/workspaces/:wid/patients/:id/checklists
❌	List checklists for a patient	GET /api/workspaces/:wid/patients/:id/checklists
❌	Update a checklist for a patient	PUT /api/workspaces/:wid/patients/:id/checklists/:cid
❌	Delete a checklist from a patient	DELETE /api/workspaces/:wid/patients/:id/checklists/:cid
❌	Create an item for a patient checklist	POST /api/workspaces/:wid/patients/:pid/checklists/:cid/items
❌	Update an item for a patient checklist	PUT /api/workspaces/:wid/patients/:pid/checklists/:cid/items/:id
❌	Update a batch of items for a patient checklist	POST /api/workspaces/:wid/patients/:pid/checklists/:cid/items/update
❌	Reorder items for a patient checklist	POST /api/workspaces/:wid/patients/:pid/checklists/:cid/items/order
❌	Delete items from a patient checklist	POST /api/workspaces/:wid/patients/:pid/checklists/:cid/items/delete
❌	Create a note for a patient	POST /api/workspaces/:wid/patients/:id/notes
❌	List notes for a patient	GET /api/workspaces/:wid/patients/:id/notes
❌	Update a note for a patient	PUT /api/workspaces/:wid/patients/:id/notes/:nid
❌	Delete a note from a patient	DELETE /api/workspaces/:wid/patients/:id/notes/:nid
❌	Create a document for a patient	POST /api/workspaces/:wid/patients/:id/documents/:name
❌	Download a document for a patient	GET /api/workspaces/:wid/patients/:id/documents/:did/:name
❌	List documents for a patient	GET /api/workspaces/:wid/patients/:id/documents
❌	Update a document for a patient	PUT /api/workspaces/:wid/patients/:id/documents/:did
❌	Delete a document from a patient	DELETE /api/workspaces/:wid/patients/:id/documents/:did
❌	Create a patient copy operation	POST /api/workspaces/:wid/patients/copies
❌	Get patient copy operation details	GET /api/patients/copies/:id
✅	Create a task for a patient	POST /api/workspaces/:wid/patients/:id/tasks
✅	List tasks for a patient	GET /api/workspaces/:wid/patients/:id/tasks
✅	Get a task for a patient	GET /api/workspaces/:wid/patients/:id/tasks/:tid
✅	Delete a task from a patient	DELETE /api/workspaces/:wid/patients/:id/tasks/:tid
✅	Update a study for a patient	PUT /api/workspaces/:wid/studies/:id
✅	Create an upload	POST /api/workspaces/:wid/uploads
✅	List uploads	GET /api/workspaces/:wid/uploads
✅	Delete matching uploads	DELETE /api/workspaces/:wid/uploads
✅	Delete an upload	DELETE /api/workspaces/:wid/uploads/:id
❌	Resolve upload conflicts	POST /api/workspaces/:wid/uploads/resolve
✅	Get chunk information	GET /api/uploads/chunks
✅	Post an upload chunk	POST /api/uploads/chunks
❌	Create a download request	POST /api/workspaces/:wid/downloads
❌	Create a download of audit archives	POST /api/audit/archives
❌	Get the status of a download	GET /api/downloads/:id/status
❌	Download a file	GET /api/downloads/:id/:file
✅	Update an entity	PUT /api/workspaces/:wid/entities/:id
✅	Update the parent of an entity	PUT /api/workspaces/:wid/entities/:id/parent/:pid
✅	Delete an entity	DELETE /api/workspaces/:wid/entities/:id
✅	Update a batch of entities	PATCH /api/workspaces/:wid/entities
✅	Get an image set	GET /api/workspaces/:wid/imagesets/:id
❌	Get PET information for an image set	PUT /api/workspaces/:wid/imagesets/:id/pet
✅	Download an image for an image set	GET /api/workspaces/:wid/imagesets/:id/images/:iid/dicom
✅	Create a structure set	POST /api/workspaces/:wid/structuresets
✅	Get an structure set	GET /api/workspaces/:wid/structuresets/:id
✅	Get ROI data for a structure set	GET /api/structuresets/:id/rois/:tag
✅	Create a draft for a structure set	POST /api/workspaces/:wid/structuresets/:id/draft
✅	Get a lock for a structure set draft	GET /api/workspaces/:wid/structuresets/:id/draft/lock
✅	Renew a lock for a structure set draft	PUT /api/workspaces/:wid/structuresets/:id/draft/lock/:lid
✅	Release a lock for a structure set draft	DELETE /api/workspaces/:wid/structuresets/:id/draft/lock/:lid
✅	Create an ROI for a structure set draft	POST /api/workspaces/:wid/structuresets/:id/draft/rois
✅	Update an ROI for a structure set draft	PUT /api/workspaces/:wid/structuresets/:id/draft/rois/:rid
✅	Update ROI data for a structure set draft	PUT /api/workspaces/:wid/structuresets/:id/draft/rois/:rid/data
✅	Delete an ROI from a structure set draft	DELETE /api/workspaces/:wid/structuresets/:id/draft/rois/:rid
✅	Commit the draft as new version of a structure set	POST /api/workspaces/:wid/structuresets/:id/draft/approve
✅	Discard the structure set draft	POST /api/workspaces/:wid/structuresets/:id/draft/discard
✅	List versions of a structure set	GET /api/workspaces/:wid/structuresets/:id/versions
✅	Get the status of a structure set version	GET /api/workspaces/:wid/structuresets/:id/versions/:vid/status
✅	Download the DICOM for a structure set version	GET /api/workspaces/:wid/structuresets/:id/versions/:vid/dicom
✅	Update a version of a structure set	PUT /api/workspaces/:wid/structuresets/:id/versions/:vid
✅	Delete a version from a structure set	DELETE /api/workspaces/:wid/structuresets/:id/versions/:vid
✅	Revert to a version of a structure set	POST /api/workspaces/:wid/structuresets/:id/approve/:vid
✅	Get a plan	GET /api/workspaces/:wid/plans/:id
✅	Download the DICOM for a plan	GET /api/workspaces/:wid/plans/:id/dicom
✅	Create a plan	POST /api/workspaces/:wid/plans
❌	Update the prescription information for a plan	PUT /api/workspaces/:wid/plans/:id/prescription
❌	Update the opportunity DVH parameters for a plan	PUT /api/workspaces/:wid/plans/:id/opportunity
❌	Get the opportunity DVH for a plan	GET /api/plans/:id/opportunity/:tag
✅	Get a dose	GET /api/workspaces/:wid/doses/:id
✅	Download the DICOM for a dose	GET /api/workspaces/:wid/doses/:id/dicom
✅	Get the analysis data for a dose	GET /api/doses/:id/analysis/:tag
✅	Update computed metrics for a dose	PUT /api/workspaces/:wid/doses/:id/metrics
✅	Get computed metrics for a dose	GET /api/workspaces/:wid/doses/:id/metrics
❌	Create an SRO	POST /api/workspaces/:wid/sros
✅	Get an SRO	GET /api/workspaces/:wid/sros/:id
✅	Delete an SRO	DELETE /api/workspaces/:wid/sros/:id
❌	Update an SRO	PATCH /api/workspaces/:wid/sros/:id
❌	Get the status of an SRO	GET /api/workspaces/:wid/sros/:id/status
✅	Download the DICOM for an SRO	GET /api/workspaces/:wid/sros/:id/dicom

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 not https://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.

Guides

• Computed Metrics
  • Instructions
  • Metric List
• Using Find Methods
  • Basics
  • Keyword Arguments
  • Predicate
  • Other Important Points
• Using Contouring Data
• Dose Analysis
• pydicom Primer
  • Reading Files
  • Accessing Sequence Data
  • Attribute Dump
• Scorecard Objectives
  • Exercise 1
  • Exercise 2
• Patient Tasks
  • Dose Composition