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.

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.

Before you start

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. Find an item’s id with ophiolite list; the examples below use it as $ITEM.

Check

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.

Get

ophiolite get --item "$ITEM" --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: Got Porosity points, version 2. 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 Porosity points, saved in /home/you/work/received. 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.

Send

ophiolite send porosity.csv --profile points-csv/1 --name "Porosity points" --how kriging --based-on "$ITEM"

--based-on names the items you hold that your result is built from (one to 32). 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: 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.

When someone else was first

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.

When a send is interrupted

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.

From Python

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

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

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.

What each answer means

Answer	What to do
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 (a seismic volume’s 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.