Skip to main content

Sharing Data

Sethealth is not only a medical data visualization tool. In fact, Sethealth API makes it very easy and safe to share medical data, allowing its users to upload it to the cloud.

In this section you can see how to do it.

Access token#

First of all, in order to upload data and use the cloud services, it's required an access token. This access token allows the SDK to upload and download data in a safe and controlled way.

Once you generate a token, it must be passed to the SDK using the auth module.

await sethealth.auth.setAccessToken(token);

Notice that access tokens are short-lived, meaning it expires few hours after its creation, so they must be generated on-demand in your own backend.

Learn how to create access tokens from a service account.

Uploading data with ensureSources()#

This method can be called from the workspace API and it uploads data only when strictly necesary. This method returns a SerializableWorkspace as under the hood calls to workspace.serialize().

import * as sethealth from "@sethealth/core";
const json = await sethealth.workspace.ensureSources({
workspaces: [myWorkspace];
});

This method can be called from med or geometry too, thus avoiding creating a Workspace object. Under the hood, calling this method form workspace uses med.ensureSources() and geometry.ensureSources(). If any MedHandler or Geometry have a source yet, the method will skip.

Serializing a Workspace with serialize()#

The workspace.serialize() returns a SerializableWorkspace given a Workspace. A SerializableWorkspace is a JSON-safe serializable object created in order to share a workspace or store it for persistence.

import * as sethealth from "@sethealth/core";
const json = await sethealth.workspace.serialize({
workspace: myWorkspace,
medSource: url,
});

The field medSource is not required in order serialize a Workspace. If it is not used, the MedHandler contained by the Workspace must have a MedSource (it can be achive with the ensureSources() method). Althought, if you want to serialize a Workspace without a MedSource is possible too, specifying a null value in opts.medSource that will overwrite the actual MedHandler value. For further information check out the docs.

Uploading a SerializableWorkspace to sethealth with uploadMetadata()#

Using workspace.serialize() or workspace.ensureSources() will return a SerializableWorkspace, but it is not uploaded yet. As mentioned, a SerializableWorkspace is a JSON-safe serializable object so it could be uploaded to sethealth with the uploadMetadata() method of the storage API

import * as sethealth from "@sethealth/core";
const jsonstring = JSON.stringify(json);
const secret = await sethealth.storage.uploadMetadata(jsonstring);

Now this secret is a string that contains an URL to share all the files attached.

Downloading a SerializableWorkspace from sethealth with loadMetadata()#

After uploading data, let's see how to download it. With the secret generated before, we will be able to download the JSON that represents a SerializableWorkspace.

import * as sethealth from "@sethealth/core";
const jsonstring = await sethealth.storage.loadMetadata(secret);
const json = JSON.parse(jsonstring) as SerializableWorkspace;

With the SerializableWorkspace now it is possible to create again the same workspace as before as it contains all the sources needed to download MedHandler and Geometries attached. To see how check out to the next fragment

Creating a Workspace from a SerializableWorkspace#

Now let's see how to use a SerializableWorkspace to create the Workspace again.

import * as sethealth from "@sethealth/core";
const result = await sethealth.workspace.loadFromWorkspace(json);
if (result.error) {
console.error(result.error);
}
const workspace = result.value;

First a MedHandler should be created as will be used to create the workspace. Then the Workspace can be restored by using workspace.create() passing the MedHandler and the previously serialized SerializableWorkspace. For further information check out the docs.