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

• Computed Views

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 agent to write code for you. Navigate to the 'Co-pilot' tab on the right hand side, and start chatting with the AI to describe what you need.

The AI agent is also able to look at your current code, so you can ask it to help you debug 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:

Description	Variable / Function
Getting entities	seal.get_entity(entity_id) 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. get_entity() will return the latest version of the entity. Getting a specific version of an entity: seal.get_entity(entity_id, version) Getting entities by their title: seal.get_entities_by_title(title) Note that exact titles are necessary. Since multiple entities can share the same title, this returns an array.
Get records from a preceding step in the run	seal.get_previous_step_records(?relative_index) where relative_index is the nth step before the script step Note that the n is optional. If not specified, it defaults to the immediately preceding step.
Get all records produced by a specific step	seal.get_step_records(step_id, ?step_version)
Get a file from the file store	seal.download_file(file_id) The file is downloaded to the local filesystem of the virtual machine instance. download_file() returns the file path as a string.
Upload a file to Seal	seal.upload_file(file_path, file_name). Returns the id of the file in Seal

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.

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
}

Importing packages

Seal comes with many common Python packages pre-installed. If there are other python packages you 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)