Sample service integration with the workspace service

Overview

The Sample service stores information about biological samples.

This document describes how to link WSS objects to samples such that when the object is shared via the Workspace API, the linked samples are shared (more specifically, made readable) as well. If a data type developer merely stored a sample ID in a workspace object as a string, sharing the object would not share the underlying sample, and sharees would not be able to access the sample.

Warning

Samples shared by the workspace are not unshared if the workspace object containing the sample is unshared. The samples can always be unshared via the Sample service API.

Warning

Sharing workspace objects containing links to samples shares the samples as well. If a workspace object is copied into a user’s workspace and that workspace is made public, the samples are set to publicly readable.

Warning

To create a workspace object containing a sample ID, the user must have administrative rights to the sample - users cannot create objects containing IDs of other users’ samples. This is because, effectively, saving an object containing a sample ID grants anyone with read permissions to that object partial administrative permissions to the sample.

Resources

Workspace typed objects describes how to create workspace types.

Creating objects linked to samples

The process of linking workspace objects to one or more samples is very similar to that described in Shock integration with the workspace service. Prior to saving objects, an appropriate type must exist that supports sample service IDs. The simplest possible type is:

/* @id sample */
typedef string sample_id;

typedef structure {
    sample_id sid;
} StructWithSampleID;

Assuming an appropriate type exists and that the user has created a sample in the sample service (or is an administrator of another user’s sample), the user saves an object containing the ID of said sample in the appropriate place in the object structure. For the toy type above, the object would look like:

{"sid": [sample ID string goes here]}

Otherwise, the saving process is identical to saving any other object. During the save, the workspace checks that the user administrates or owns the sample(s), and rejects the save if such is not the case.

Retrieving the data from the workspace also works normally, but there’s a couple of important points. When calling the get_objects2 method (or the deprecated get_objects, get_referenced_objects, get_object_subset, or get_object_provenance methods):

• The sample IDs found in the object are returned in the output as strings in the extracted_ids field.

• The Workspace makes a request to the Sample Service such that the caller of the method is given read access to the samples referenced by the IDs embedded in the object.

This means that, mostly invisibly, the samples embedded in a Workspace object are shared as the object is shared.

If the sample service is uncontactable or some other error occurs, the workspace will still return the workspace object. However, the error will be embedded in the returned data structure. The handle_error field will contain a brief description of the error, and the handle_stacktrace field will contain the full stacktrace. If these fields are populated the ACLs of some or all of the samples embedded in the object could not be updated.

Note

The handle_error and handle_stacktrace fields received their names before the Sample service integration existed. They should be called external_id_error and external_id_stacktrace, but are left as is to avoid field duplication and backwards compatibility issues.