SAMS - programmatic access ("API")

Integrate SAMS as an iframe

The SAMS search interface can be readily integrated into hospital information systems as an HTML5 iframe and will return a GA4GH Phenopacket. No data is stored on our server. Simply include the following code:

<iframe src="https://www.genecascade.org/sams-cgi/enter_phenotype.cgi"
 style="position: fixed; top: 0px; bottom: 0px; right: 0px; width: 100%; border: none;
	margin: 0; padding: 0; overflow: hidden; z-index: 999999; height: 100%;">
</iframe>

An example implementation can be found on this page. The style parameters can be adjusted to fit your needs.

Capture SAMS phenotypic data from an iframe

When using SAMS in an iFrame as described above and saving data to SAMS's database, SAMS will post messages with the uploaded data encoded 1) in SAMS format and 2) as Phenopacket. Note that you must be logged in to use this feature.
The following code in the website embedding the iframe will capture SAMS's output:

HTML

<div id="sams-data">Placeholder for data from SAMS.</div><br>
<div id="sams-phenopacket">Placeholder for Phenopacket from SAMS.</div>

JavaScript

<script>
function addSAMS_data (evt) {
	if (evt.data) {
		let sams_data=document.getElementById("sams-data");
		let phenopacket=document.getElementById("sams-phenopacket");
		if (sams_data) sams_data.innerHTML=evt.data[0];
		if (phenopacket) phenopacket.innerHTML=evt.data[1];
	}
}
window.addEventListener("message", addSAMS_data, false);
</script>

Access SAMS via the command line or linkouts

Linking to SAMS from external systems

Please note that you have to be logged into SAMS in your browser to access your patient data.
In the examples below, replace myPatID, the patient ID (parameter: external_id), with the pseudonomised ID you have given to your patient.

Record and edit a visit

Link to the interface for recording a visit for a specific patient. You may also provide the visit date and details about the patient.
If a patient with the given external ID does not yet exist, it will be created.
If a visit for the given date already exists, you may edit this visit.

Call entry.cgi with mode=visit and your chosen parameters for external_id, sex, consanguinity and visit_date.

Parameters:

external_id is the only obligatory parameter.
sex can take the values m for male or f for female. If no parameter is given the sex is recorded as other/unknown. If a new patient is created, this value will be used. Note that this does not change the sex of an exisiting patient with this external id.
consanguinity can be true, if the patient has consanguineous patients or false if the patient has non-consanguineous parents. If no parameter is given the consanguinity is recorded as unknown. Note that this does not change the consanguinity of an exisiting patient with this external id.
visit_date is the date of the visit that you want to create or edit. Provide the date in the following format: yyyy-mm-dd (e.g. 2023-01-05 for fifth of January 2022). Note that if you do not provide the date here, it is possible that you will overwrite an existing visit.

Example link:
https://www.genecascade.org/sams-cgi/entry.cgi?external_id=myPatID&sex=m&consanguinity=true&visit_date=2023-07-12&mode=visit

Show patient overview

Link to the overview of all previous visits of a specific patient.

Call entry.cgi with mode=show and your external_id.

Example link:
https://www.genecascade.org/sams-cgi/entry.cgi?external_id=myPatID&mode=show

Export patient record as Phenopacket

Export all recorded visits of a specific patient as a GA4GH Phenopacket in JSON format.

Call export_phenopacket.cgi with your external_id.

Example link:
https://www.genecascade.org/sams-cgi/export_phenopacket.cgi?external_id=myPatID

Downloading data via the command line interface

Currently, you have to provide your credentials (username and password) to obtain a session cookie to be able to use the export functions.

1. Get session cookie

curl -X POST -L -c sams_cookie.txt -d email=USERNAME -d password=PASSWORD https://www.genecascade.org/sams-cgi/login.cgi

The sams_cookie.txt file contains the session cookie.

2. Download phenopackets

Now you can use the obtained session cookie to proceed with a direct HTTP-Request to an Export-Script:

curl -b sams_cookie.txt https://www.genecascade.org/sams-cgi/export_phenopacket.cgi?external_id=PATIENTID

Or get the session cookie from the file and replace "SECRET_ID" with it:

curl --cookie "SAMSI-SieWarSoWeich=SECRET_ID" https://www.genecascade.org/sams-cgi/export_phenopacket.cgi?external_id=PATIENTID

You may of course also use the functionality to export all phenopackets created by one user with
https://www.genecascade.org/sams-cgi/export_all_phenopackets.cgi

Integrating SAMS into your sytems

If you are interested in syncing the SAMS patient management functionality with a local patient management system, please contact us.