Scripts

Seal allows you to write and execute your own custom Python code within the platform, enabling powerful custom solutions and automations.

Scripts is the umbrella term for objects that can contain and run code in Seal - the specific object types are:

• Script Steps

• Triggers

This page documents functionality common to all types of Scripts.

If this is your first time using Python, then there are great reference materials online such as: https://docs.python.org/3.10/tutorial/

What if I don't know how to code?

Not to worry - Seal comes with a built in AI Copilot to write code for you. Navigate to the 'Copilot' tab on the right hand side, and start chatting with the AI to describe what you need.

The AI agent has access to your current code, as well as the surrounding procedure or run if you're coding a Script Step or Record, so you can ask it to help you debug specific issues or add to the existing code.

Once you're happy with the code, click on 'Accept code' to use it in your Script.

Note that the generated code may not fully be fit for your purpose - we recommend checking over the results.

Seal Module

The Seal module is a Python package for interacting programatically with the Seal platform.

It is automatically available in every Script's Python environment - you don't need to import it manually. The Seal module consists of a collection of methods on the seal object:

Getting entities

seal.get_entity(entity_id, ?version)

Returns the entire json blob of data for that entity. The entity id can be copied from the entity's URL in Seal - it's the final section of the url, after the entity title. Just passing an entity_id returns the latest version or draft of the entity. To get a specific version of an entity, include the version as a second argument.

seal.get_entities_by_title(title)

Get entities by their title (string). Note that exact titles are necessary. Since multiple entities can share the same title, this returns an array.

Getting Records

seal.get_previous_step_records(?relative_index)

Returns an array of the records in a specific previous step.

relative_index (optional) is the nth step before the script step. If not specified, it defaults to the immediately preceding step.

seal.get_step_records(step_id, ?step_version)

Get all records produced by a specific Step entity. Returns an array of Record entities.

Handling files

seal.download_file(file_entity_id, ?version)

The file is downloaded to the local filesystem of the virtual machine instance. The value returned is the local file path as a string.

seal.upload_file(file_path, file_name)

Returns the id of the new File Entity in Seal

AI data extraction

seal.extract_data_from_file(file_entity_id, version, ?=prompt)

Parameters:

• file_entity_id: ID of the file entity to extract data from

• version: (Optional) Specific version of the file entity

• prompt: (Optional, keyword-only) Custom prompt to guide the data extraction

Returns: json Example:

data = seal.extract_data_from_file(
    "9351e027-d26c-4769-a395-507f4f148cb4",
     prompt="Extract all temperature readings by day"
)

Seal entities

Everything in Seal is an entity. Entities are self contained blobs of JSON data that conform to our schema.

Types of entities include procedures, runs, steps, records, documents, files and computed views.

All entities share these common fields:

id, // uuid
schemaVersion, // string
type, // "PROCEDURE" | "RUN" | "STEP" | "RECORD" | "DOCUMENT" | "COMPUTED_VIEW" | "FILE"
title, // string | null
version, // string | null
previousVersion // string | null
reviewConfig, // review config obj or null
assignees: // array of role uuids
tags: // array of tag uuids
metadata: {
  createdAt, // iso datetime string
  lastUpdatedAt, // iso datetime string
  createdByRoleId, // role uuid
  lastUpdatedByRoleId // role uuid
  editors, // array of role uuids
},

The status field

All entities also have a top level status field. There are two types of entity lifecycle that define the possible status values - continuous and completable.

Procedures, Steps, Documents and Computed Views all have continuous lifecycles - they are designed to be reused and improved over time. Continuous entities have numbered versions - the version number increases every time you publish a new version.

Runs and Records have completable lifecycles - they represent a discrete piece of work carried out at a specific time, and therefore are usually not modified once they've been finished. If mistakes are identified, you can make a new revision of the completable entity.

Steps

Steps are reusable templates which describe how to carry out a piece of work and how to record the results. There are two types of Steps - Data Steps and Script Steps.

Data Steps contain a recordConfig field, which describes the shape of Records that it will make when being carried out in a Run. They also contain page content (document content) that will be copied into each created Record - this is where you put instructions, images, charts etc describing how to carry out the work.

recordConfig: {
  allowMultiple, // boolean
  fields: {
    // e.g. a NUMBER field
    [fieldName]: {
      dataType: 'NUMBER',
      value, // number | null
      type: 'NUMBER',
      config: {
        format, // '0.X' | '0.00' | '0.000' | ...
      }
    }
  },  
  pageContent, // plate.js schema - see https://platejs.org/

Procedures

Procedures allow you to assemble a series of Steps into a larger reusable sequence of work.

Procedures contain a stages field which contains its array of steps:

stages: [
    {
      id, // uuid - Unique stage id for easy referencing, reordering and diffing
      step: { id, version}, // References the step entity. Version optional in procedure, required in run
      connection, // connection config - connections allow you to automatically link up
                  // records between stages in a Run - see the connections docs for more info. 
    }),

Runs

A Run represents a specific execution of a Procedure at a point in time, e.g. the specific run of some repeatable lab work that a technician did on 29/10/2024.

When executed in a Run, Data Steps can produce one or multiple Records, and Script Steps can also optionally produce Records.

sourceProcedure: {id, version}, // Version required, should always be executing a published version
stages: [
  {
    id, // uuid - Unique stage id for easy referencing, reordering and diffing
    step: {id, version}, // Version optional in procedure, required in run
    connection, // see above
    status, // Computed from the record's status (the source of truth), useful to store here
    records: [{id, version}, ...] // Revision optional, will be null for active / in revision records
    // Script steps are instantiated to script records when creating a new run. The
    // records the script (optionally) produces go into the `records` array, so we store
    // the script record separately.
    scriptRecord: {id, version} // only for script steps
  }),

Records

There are two types of Records - Data Records and Script Records. Data Steps produce Data Records, Script Steps produce Script Records (and also optionally Data Records).

Data Records contain fields and pageContent - they are instantiations of Data Steps.

Script Records contain:

scriptCode, // string - the code
scriptOutput?: { // only once the script has been executed in the run
  logs, // array of strings - log lines.
  recordsToCreate, // array of {[fieldName]: value} objects, for outputting Data Records
  executedAt: // string - timestamp of the event which executed the script
  executedByRoleId // role uuid
}

Fields

Data Steps and Data Records can have Fields to contain data, usually inputted by a technician while doing a Run of a Procedure, or populated by a Script for automations. Fields have unique names (within that Entity), and a specifc data types.

Fields are stored in the entity blob as an object called fields, keyed by the unique field names. Every field object has the following fields:

• id - a unique UUID given to every field, so it can be referenced. When a Data Record is created from a Data Step, it will have the same fields with matching ids

• the field's type

• the field's dataType (usually the same as the type, but multiple field types may use the same underlying data type). type is how it appears in the UI, dataType refers to the underlying data type

• value - the actual data. All field values are nullable - they are usually null in Data Steps (unless you want a default value for produced Records), and then populated in Data Records when a lab technician is doing data entry, for example.

• config - certain field have additional config, for example specifying a number display format, or whether the field can contain multiple values.

For example:

  "fields": {
    "CSV file": {
      "id": "f1714b77-d081-4a1e-bfc4-427289fce204",
      "type": "REFERENCE",
      "value": [
        {
          "id": "e9a49732-49a0-4674-b683-c6991fac160a",
          "version": "12"
        }
      ],
      "config": {
        "allowMultiple": false
      },
      "dataType": "ENTITY"
    },
    "Group name": {
      "id": "0519bc74-7086-4ba2-b769-994b62a48945",
      "type": "STRING",
      "value": "A23-Z",
      "config": {},
      "dataType": "STRING"
    },
    "Sample weight": {
      "id": "70c33317-16ae-48b2-9907-fc5112677773",
      "type": "NUMBER",
      "value": 52.3,
      "config": {
        "format": "0.000"
      },
      "dataType": "NUMBER"
    }
  }

Field Types

Type: NUMBER

Description: Numeric value.

Value: A valid JSON number or null.

Config:

format // '0.X' | '0.00' | '0.000' | '0,0.00' | '0.0%' | '0.00%' | '0.0a' | 'SCI' | 'SCI3' | 'EU' | 'IND' | 'Rounded'

Type: STRING

Description: Text.

Value: A string or null. The string must be at least length 1 - to represent an empty value, use null.

Config: None

---

Type: BOOLEAN

Description: True/false.

Value: A JSON boolean or null.

Config: None

---

Type: DATE

Description: A date in ISO 8601 format.

Value: An ISO date string or null

Config: None

---

Type: DATETIME

Description: A datetime in ISO 8601 format, requiring a timezone.

Value: A timezone aware ISO datetime string or null

Config:

format // 'PPpp' | 'PPppp' | 'Pp' | "yyyy-MM-dd'T'HH':'mm':'ssXXX" | 'dd-MM-yyyy HH:mm:ss'

---

Type: SELECT

Description: An array of enum-like strings. Displayed in the UI as a dropdown/select field with multiple options.

Value: An array of strings.

Config:

selectOptions // array of strings specifying the enum options
allowMultiple // bool, whether multiple values are allowed

---

Type: REFERENCE

Description: An entity reference field for referencing other entities (of any kind), including File entities for referencing files.

Value: An array of {id, version} objects.

Config:

allowMultiple // bool

---

Type: LOOKUP

Description: Lookups allow you to pull out field values from referenced entities. Useful for additive data building across steps. The value from the other entity is copied into the lookup field.

Value: Whatever the looked-up value is.

Config:

refFieldId //The ID of the reference field in this entity that specifies which other entity to look into.
lookupFieldName // The name of the field in the other entity to get the value from.

Importing packages

Seal comes with many common Python packages pre-installed. If there are other python packages you regularly require, please contact Seal support.

Available packages to import include:

• altair

• annotated-types

• attrs

• blinker

• cachetools

• certifi

• cffi

• charset-normalizer

• click

• cloudevents

• contourpy

• cryptography

• cycler

• deprecation

• et-xmlfile

• flask

• fonttools

• functions-framework

• gcloud

• google-api-core

• google-auth

• google-cloud-appengine-logging

• google-cloud-audit-log

• google-cloud-core

• google-cloud-error-reporting

• google-cloud-logging

• google-cloud-storage

• google-crc32c

• google-resumable-media

• googleapis-common-protos

• grpc-google-iam-v1

• grpcio

• grpcio-status

• gunicorn

• httplib2

• idna

• itsdangerous

• jinja2

• joblib

• jsonschema

• jsonschema-specifications

• jwcrypto

• kiwisolver

• lxml

• markupsafe

• matplotlib

• numpy

• oauth2client

• openpyxl

• packaging

• pandas

• pillow

• proto-plus

• protobuf

• pyasn1

• pyasn1-modules

• pycorn

• pycparser

• pycryptodome

• pydantic

• pydantic-core

• pyparsing

• pyrebase4

• python-dateutil

• python-docx

• python-jwt

• pytz

• referencing

• requests

• requests-toolbelt

• rpds-py

• rsa

• scikit-learn

• scipy

• setuptools

• six

• tabulate

• threadpoolctl

• toolz

• typing-extensions

• urllib3

• vl-convert-python

• watchdog

• werkzeug

• xlrd

These packages are automatically imported in every Script, so don't need to be manually imported:

• altair (also aliased as alt)

• Chart (alias of altair.Chart)

• pandas (also aliased as pd)

To temporarily install a package when running the script:

import subprocess
subprocess.check_output("pip install {name of package}".split())