REST API

Fortelinea ships a RESTful API with Prima. Customers and third party vendors may feel free to interact with Prima to pull or push information. The API follows OpenAPI standards and presents a Swagger endpoint for documentation and development. The Api framework is built on top of Microsoft's OData platform, which allows for rich querying capabilities.

Security

The API, which is located at each customer installation can be fully controlled by IT and the lab staff. Access to the API is controlled through an admin page on the internal website. Access to UI features (e.g. Swagger) may be granted to developers via the customer's authentication system (e.g. LDAP) and refined using internal website roles. Access to the API is granted completely from the internal website via JWT tokens (optionally with refresh tokens). Token lifetime, read/write capabilities and much more can be configured by stakeholders.

Getting Started

Usually, the most difficult part of working with the API is understanding the structure of data within the lab, knowing what to look for and understanding inheritance in the model structures.

Lab Data

A brief over view of the pathology lab is really the best way to start. There are many different workflows, so we will try and start with the simplest and work our way up.

Clinical

The workflow in a clinical lab is usually straightforward and the most streamlined.

Clinical labs are primarily driven by cases. A case is a sample collection. If a patient visits a doctor and has a samples of his liver and lung taken, this will be a case with two specimens. If he goes back later in the week and gets another sample of liver taken, this will result in a new case with one specimen.

Orders are placed on cases and their constituent samples to specify work to be completed or end products. At least one order is created per case, but there can be many. When all orders are completed, we can mark a case as closed. In the clinical world, this usually takes 48 hours and sometimes up to a week.

We define the items received or created in the lab as trackables. We do so because each of these items will be labeled, barcoded and tracked throughout the workflow process.

Trackables

• Specimens
• Cassettes (Blocks)
• Slides

These items can further be broken down by how they arrive in the lab or the type of material that they contain

Specimens

Biopsy Specimen

Sample that is taken by surgical means and is placed in a fixation solution

Frozen Specimen

Sample that is taken by surgical means and is quickly frozen in order to prevent degradation and make it easier to slice

*Surgical Specimen

This is either a Frozen specimen or a biopsy specimen, as it was taken by surgical means

Cytology Specimen

Urine or vaginal material

Hematology Specimen

A small vial of blood

Specimen Workflow

Biopsy Specimen

1. Sample is taken by surgical means
2. Sample is placed in a jar with a fixative solution and becomes a specimen
3. Specimen arrives in lab and is accessioned (info is recorded and labels are printed)
4. Specimen goes to Trimming (aka Prosect or Grossing)
   1. Specimen is examined and given a preliminary diagnosis (each lesion is also given a diagnosis) with morphologies and notes
   2. Cassettes are printed with label and barcode
   3. Tissue is trimmed into pieces of interest and placed into cassettes
5. Specimen is sent to archival or immediately thrown away (when sent to archival, the specimen follows a usual 'hold' period of 7 days before disposal)

Frozen Specimen

1. Sample is taken by surgical means
2. Sample is quickly frozen and sent to the lab
3. Specimen arrives in lab and is accessioned (info is recorded and labels are printed)
4. Specimen goes to the Cryostat (equipment used for processing frozen samples)
   1. Specimen is trimmed
   2. Frozen slides (cryoslides) are printed with label and barcode
   3. Paper-thin slices are cut from the specimen and placed on the slides
   4. Optionally, cassettes are printed with label and barcode and filled with larger pieces of the specimen (frozen or OCT blocks)
5. Specimen is sent to placed in fixative and sent to archival or immediately thrown away (when sent to archival, the specimen follows a usual 'hold' period of 7 days before disposal)

Cytology Specimen

1. Sample is taken by with a collection kit (there are a few standard kits named by the brand)
2. Specimen arrives in lab and is accessioned (info is recorded and labels are printed)
3. Specimen goes to the Cytology station
   1. Specimen placed on a centrifuge so that suspended solids are separated
   2. Cytology (cyto) slides are printed and fluid containing cells is dropped onto the slide
   3. Optionally, a cassette is printed and the left-over cell clump is placed in the cassette, wrapped in waxed paper (called a button)
4. Specimen is disposed

Hematology Specimen

1. Sample is taken via any number of blood withdrawal methods and placed in a eppendorf tube
2. Specimen arrives in lab and is accessioned (info is recorded and labels are printed)
3. Specimen goes to the Hematology station
   1. Hematology slides are printed with label and barcode
   2. Blood is aliquot-ed onto the slides (often a drop is placed between two slides, which are then dragged apart and called smears)
4. Specimen is disposed

Cassette/Block Workflow

Fresh Tissue in a cassette Biopsy Specimen -> Cassette

1. Fixed tissue was placed in a cassette, as described above, at the Prosect station
2. Cassette goes to Tissue Processing
   1. Cassettes are grouped together by tissue and sample size
   2. Optionally, some tissues will soak overnight in a solution (e.g. bone in a de-calcification solution)
   3. Cassettes groups are placed into a tissue processor
   4. Over a period of several hours, the tissue processor soaks the tissue a a series of solutions to draw water out of the cells and draw paraffin wax into the cells
   5. Cassettes are removed from the processor
3. Cassette goes to Embedding
   1. Cassettes are dipped into a form with hot paraffin wax
   2. Cassettes are placed onto a cold plate where the wax hardens into a block with the cassette attached to the top (plastic casing is partially embedded in the wax)
4. Cassette/Block goes to Microtomy
   1. Slides are printed with label and barcode
   2. A microtome is used to cut paper-thin pieces of wax and tissue onto the slides

Slide Workflow

Surgical Slides Surgical Specimen -> Cassette -> Slide

1. Tissue sections were placed on a slide at Microtomy, as described above
2. If a slide is to remain unstained for later potential use, it is send to either Delivery or Archival
3. Slide goes to a drying station
   1. Slides are placed on a rack in a low temperature oven
   2. This workflow step is optional
4. Slide goes to staining
   1. Slides are grouped together by Stain Test Category (IHC, Routine, ISH, etc.)
   2. Slides are placed into a stainer that is specific to the category of stain
   3. A rotating bath of chemicals are washed over the tissue to bind dies to certain proteins, etc. This is called a stain protocol or stain test (specified list of chemicals, temperatures, periods of time)
   4. Some newer stainers will coverslip the slide
   5. Slides are removed from the stainer
5. Slide goes to Cover-Slipping
   1. If the stainer did not add a coverslip, then that is added at this station
6. Slide goes to Stain Review
   1. Optional piece in the workflow to check (or spot check) the quality of the stains being applied
7. Slide goes to Imaging
   1. If a lab has imagers, then stained slides are received here
   2. Slides are inserted into the imager, which will take a very high resolution shot of the stained area and the barcoded label (most will read the label)
   3. Files are stored in a network drive
8. Slide goes to Delivery
   1. The Delivery station stages slides in folders to be delivered to: the customer, the pathologist or archiving
   2. Slides will usually visit this station several times
   3. Stained slides (and sometimes unstained slides) are sent to the Pathologist for review
   4. If a customer has requested the slide, it is returned. Otherwise, it is taken to archival
9. Archival
   1. Slides are held here in large boxes and are usually organized by case
   2. Unstained slides may be pulled from a container to receive a stain, if the Pathologist needs, or if a new test is otherwise ordered.
   3. After a period of time, boxes are moved to an off-site underground storage area for 30 years.

Research

The workflow in a research lab is based on that of a clinical lab and therefore generally the same. However, workflow is complicated by a number of eccentricities:

• There is not a fixed start or end for any trackable. Blocks may be submitted to have slides made, but not reviewed.
• The concept of studies is introduced that ties cases together.
• Several new item types exist (may not exist explicitly in Prima):
  • Tissue Micro Arrays (TMA) is a block made from many> samples (e.g. 256 different samples from 256 different patients)
  • Multiple stains on the same slide
  • Multiple tissues from multiple patients on the same slide
  • Long term use of frozen blocks (blocks of frozen tissue trimmed from a frozen specimen)

Studies

Studies are groups of cases that have a goal. A growing list of study types exist to track the purpose of the study. For instance, Drug Studies are studies that track one of more drugs. Studies also introduce cohorts (groups of patients that designed to show statistical significance within the study - e.g. a control group). Studies have phases through which they progress, a principal investigator that owns the study and optionally a researcher that is doing the work in conjunction with the PI.