Connect your own source from scratch

Pilot, reviewed 24 September 2026. A connection defines how to reach a source; a project selection chooses which data to use. Registering a connection imports nothing and creates no selection. Stage 0 makes mapping, fidelity and history limits visible; it does not introduce automatic scientific approval or retained releases.

Who configures what?

Step	Person / place	What is configured
Register connection	Deployment administrator, gateway terminal	Source address/path, account grants, credential-file references, supported reader/table scope
Select and interpret data	Authorized project user, Workspace	Asset/table, scientific column mapping, units/CRS/depth meaning, follow or pin
Inspect and export	Authorized project user, Workspace	Exact revision, evidence, missing values, history limits and portable source bundle

The current pilot does not provide browser connection creation or a credential vault. The new guided terminal command produces the same registry consumed by the gateway. It does not require editing application code. Database column types are detected; their scientific meaning must still be mapped.

Start with an empty registry

On the host running the gateway, use its Connectors Python environment:

python -m asset_connectors.source_setup --registry /private/path/connections.json --wizard

The path may be new; its parent must be a private administrator-controlled directory. The command creates a 0600 registry and asks for source type, connection ID, display name, stable source namespace and an authorized Ophiolite account ID. Do not assume an email address is the account ID. Keep source namespaces stable: changing the namespace changes source identity. Duplicate IDs/namespaces are refused.

For subsequent connections, rerun the same command with the same registry. Existing connections are preserved. To add more files/tables or account grants to one connection, an administrator can edit its JSON configuration and run --check before restarting. Do not put passwords or tokens directly in the registry.

Set OPHIOLITE_SOURCES_CONFIG to this absolute registry path in the gateway’s service environment, then restart the gateway. Changing an environment variable in an unrelated terminal does not change an already-running service. The registry is loaded at startup. Source credentials are reread from their private files on requests.

Choose a source type

A file: LAS or GeoTIFF

Choose file, supply an existing gateway-host file path, then las2/1 or geotiff/1, a stable logical asset key and display name. A laptop path is not accessible to a remote gateway. Copy/mount the file onto that host, or use Workspace upload for an independent snapshot. A browser upload does not establish continuing laptop access.

Supported profiles are LAS 2.0 and bounded single-band GeoTIFF. Files must be stable before reading; after writing, wait at least two seconds and retry a pending read. Replacement of a watched file may make its prior revision unavailable. Pinning alone is not a backup. Source reading does not grant retention or redistribution rights.

SQLite or PostgreSQL wells

Choose sqlite with a gateway-host database path, or postgresql with a private 0600 file containing a connection string. Provision the upstream database account separately, preferably with SELECT access to only the permitted tables.

Choose a logical table key, actual table name and display name; PostgreSQL also asks for the database schema. The wizard enables reading only. It grants no SQL writeback. SQL Server, arbitrary joins, free-form SQL and change-data capture are not supported. Use a table with one row per well; the current bound is 1,000 rows / 4 MiB.

In Workspace, browse the table and map identifier, name, X, Y and optional depth, operator and additional metadata. Choose source CRS, depth unit/type/reference and an additional missing marker only if the source defines one. A real SQL NULL already means missing; zero remains a value unless you explicitly declare it a sentinel. Validate the preview, save the mapping version, then review and add the source.

OSDU

Choose osdu; provide a private 0600 bearer-token file, HTTPS origin, partition, exact approved schema kind and reader profile. Supported readers are osdu-record/1 for approved well/wellbore records and osdu-welllog-parquet/1 for qualified WellLog DDMS Parquet. For example, a qualified WellLog kind is osdu:wks:work-product-component--WellLog:1.2.0.

A version string is an exact allowlist entry, not automatic support for arbitrary schema extensions. WellLog reading also needs the Wellbore DDMS endpoint and rights to its data. Authentication/token renewal is provided by your deployment; the wizard does not implement customer OAuth delegation. Project access does not grant OSDU rights. Only an explicitly selected loopback qualification lab may use HTTP; production origins use HTTPS. Do not use another person’s token to grant team access.

OSDU needs less manual column mapping because a qualified reader recognizes the approved schema. Its read-only mapping report still shows the interpretation, exact schema version and unresolved references. Review missing scientific context explicitly. OSDU publication is not enabled by this setup.

Test, then select in Workspace

python -m asset_connectors.source_setup --registry /private/path/connections.json --check
python -m asset_connectors.source_setup --registry /private/path/connections.json \
  --test my-connection --account MY_ACCOUNT_ID

For OSDU add --kind with the exact configured kind. --check validates structure, not connectivity. --test reads bounded file/SQL data; for OSDU it tests search only. Inspecting a selected OSDU revision separately verifies record/data access. A zero-item search is not proof of DDMS access. The CLI does not print source records or secrets.

After restarting the configured gateway, open Connections → Browse connections. Open your connection, browse data, inspect its mapping/context, acknowledge unresolved meaning, choose Follow or Pin, and Add source to project. Then open Data, filter by its scientific type and source, and inspect Source qualification.

If nothing appears, check the registry path used by the running service and the exact account ID. A 401 means source sign-in failed/expired; a 403 means access is denied. Schema drift requires review rather than guessing a new interpretation.

Missing values and an independent example

Download synthetic LAS or CSV: depth 100 has value 0, depth 101 is missing, depth 102 has value 30. CSV blank numeric fields mean missing in this example; they never mean zero. Keep this convention with the export.

LAS retains the original declared NULL marker. Internally it becomes a missing state; the curve renderer breaks the line at that sample. Editing/export keeps genuine zero separate. A value colliding with the LAS NULL marker is refused; use explicit missing instead. No automatic fill or interpolation is performed. These synthetic numbers are not field measurements, and no vertical datum is inferred.

See source qualification and the independent export demo.