Skip to content

Exchange data between applications

Two applications that share a project — a QGIS session and a Python script, say — can pass data back and forth without anyone watching for it. Each one keeps a small held folder that remembers which version of each item it holds. Three actions work from that folder:

  • check tells you what is newer than what you hold, what is new, and what you can no longer see;
  • get saves the latest version of an item and then holds it;
  • send sends a file as a new item, or as the next version of an item you hold and wrote (or that a colleague wrote, when the project names you both as members who add versions to each other’s results).

Nothing changes in your folder until you get, and nothing changes in the project until you send. Every action ends in one sentence that says what happened. The command line also exits with a code: 0 done, 1 refused, 3 access, 4 not found or someone else was first, 5 try again.

You need the SDK, a project access key, and configuration.json for the project (see Build on Ophiolite). The examples read the key from OPHIOLITE_ACCESS_KEY. To send, the key must be able to write. The examples name an item the way you see it in the project, here “Picked points”; nobody copies an identifier.

Terminal window
ophiolite check

The first check in a new folder only notes what you can see. After that it answers, for example, 1 newer: Porosity points, version 2 by Alice Example, 5 minutes ago. — or Nothing is newer than what you hold. A check never saves anything but that note.

Terminal window
ophiolite get --name "Picked points" --output received

The folder received then holds the original file as it was sent, with data.json and descriptor.json beside it, and the held folder remembers the version and the name you used: Got Picked points, version 2 by Alice Example, 5 minutes ago. You now hold it; saved in /home/you/work/received. (the folder in full). Running it again says You already hold the latest version of Picked points, saved in /home/you/work/received. If the item is renamed later, the same command still finds it. When two items you can see have the same name, nothing is saved and the answer lists them, for example More than one item you can see is called Top Rotliegend: a horizon by Ada (version 2) and a point set by Ben (version 1). Name the type as well. Add --type horizon.

Add --stay to keep the version you have: the first time it gets the latest, and later runs save nothing new and say when there is a newer one: You stay on version 3 of Picked points. Version 5 is newer; get it with --latest to take it. One get with --latest takes the latest version, and from then on every get does. Without either, the folder does what you last asked. A well log needs the curves you want (--curve GR, repeated). A scalar map arrives as map.tif, a GeoTIFF generated from the stored map — not the file that was imported — with source.txt and manifest.json; its fingerprints are checked before anything is kept.

When a get is complete, the project’s Activity records that an application received that version. You see it under your access key’s name; other members of the project see “An application”, never the key. A get that stops before the files are saved records nothing.

Terminal window
PICKED=$(ophiolite get --name "Picked points" --output received --json | python3 -c 'import json, sys; print(json.load(sys.stdin)["technical"]["asset_id"])')
ophiolite send porosity.csv --profile points-csv/1 --name "Porosity points" --how kriging --based-on "$PICKED"

--based-on names the items you hold that your result is built from (one to 32). It takes the item’s id, which the get’s --json answer carries (technical.asset_id), so the first line asks for it rather than anyone copying it. The answer is Sent Porosity points as a new item; it is private until you share it. To send the next version of an item you wrote, add --of with its id, from the send’s own --json answer: Sent Porosity points as version 3. Version 2 is kept. State what the file says about itself with --declare, for example --declare crs=EPSG:28992; what you do not declare stays unknown.

An item you uploaded takes its next version the same way. Add --rights-confirmed to confirm that you may share this version, and name only that item with --based-on. Without the flag nothing is sent: The project refused this: confirm that you may share this version with --rights-confirmed. Nothing was sent. The project compares the file and its declarations with every version it has: if they are the same as one of them, nothing is sent and the answer names that version.

A send replaces only the version your folder holds. If a colleague — or your other application — added a newer version first, nothing is overwritten:

Version 3 was added by Alice Example, 2 minutes ago. Your change was not sent. Either get version 3 and look at it, or send yours as a new item.

There are two ways out, and both are yours to choose: get the newer version, look at it, and send again with --of; or send yours without --of, as a new item beside it.

The whole request is saved in the held folder before it is sent. If the connection drops, the answer is Could not reach the project. Nothing was changed; for send, run the same command again: it will not publish twice. Run the same send again: it either finds the version that arrived or sends it now, never both.

The same three actions, with the same sentences, from a script:

held = client.exchange(".ophiolite-held")
print(held.check().sentence)
got = held.get(name="Picked points", output="received", stay=True)
print(got.sentence)
sent = held.send("porosity.csv", name="Porosity points", profile="points-csv/1",
how="kriging", based_on=[got.technical["asset_id"]])
print(sent.sentence)

type="horizon" picks between items with the same name, as --type does. stay=True keeps the version the folder holds and stay=False takes the latest, as --stay and --latest do; the sentence then says stay=False where the command line says --latest. held.fetch(..., stay=True) gives an application that places the data itself the version it holds, with no output folder needed; confirm() on what it returns answers You stay on ….

A refusal raises an error whose sentence says what happened and what to do; outcome names it for your code. There is no background watcher: a script that must react as things change calls check() in its own loop, or keeps a full local copy as in Keep in step with Workspace.

AnswerWhat to do
You stay on version …Nothing new was saved. Get with --latest (stay=False) when you want the newer version.
More than one item you can see is called …Add the type it names (--type, type=).
No item you can see is called …Check the spelling, or ask whether the item is shared with you.
You can no longer see …The item was removed or is no longer shared with you; ask its author.
This kind of item cannot be received by this script yet: …Read it another way (part of a seismic volume, or its slices in Python), or name the curves of a well log.
The project did not allow this with this access key …Use a key for this project that can write, or ask the item’s author.
You can only build on items you hold …Get the item first.
Your access key is not accepted any more …Ask for a new key.
Another program is using this folder …Wait for it to finish; one folder per application.