Invite a partner ​

2Write the configuration ​

alcove init writes alcove.yaml from your file's columns and fills the connection block from the address you give it.

alcove init --identity "Northside Health Plan" sftp://[email protected]/exchanges/plan-coc input.csv

    password: "@passwd"

alcove init --identity "Northside Health Plan" file:///mnt/share/exchanges/plan-coc input.csv

alcove init --identity "Northside Health Plan" input.csv

connection:
  channel: webrtc
  server:
    host: signal.data-bridge.org
    path: /api/
  role: inviter

You should see: wrote a configuration template to ./alcove.yaml.

3Set the terms in alcove.yaml ​

Make each edit you agreed on. What each one means: Agree on terms.

Columns you send (What each of you sends). Columns alcove init did not recognize are listed, commented out, at the end of the metadata block. Remove the # marks from each one you agreed to send:

  - name: Renewal.Date
    type: other
    role: payload
    is_payload: true

A column with is_payload: false, or not listed, is not sent.

Your ID column. Set your own ID column, whatever it is called: its entry reads role: identifier. Your result then starts each row with your own ID. With is_payload: false your partner never receives it; to send it for matched records, change that to is_payload: true. Alcove recognizes common ID names, such as id, Client ID, MRN, and case_number (inference table), and writes an entry for the first one with is_payload: false, taking a record number such as case_number only when the file has no other ID column. A name Alcove does not recognize is listed commented out at the end of metadata with is_payload: true. Do not just remove the # marks from its listed entry: that entry sends it. Write its entry as below in place of the listed one, with your column's name. With no ID column, your result holds row numbers only, counting from 0.

  - name: Client_Number
    type: identifier
    role: identifier
    is_payload: false

Columns you ask your partner for. Optional. Under linkage_terms, add the columns your partner agreed to send, and your partner sees them as a request when accepting; if linkage_terms already has a payload: line, add receive: under it. Without the request, the first exchange records whichever columns your partner sends, and later runs refuse a different list. For example:

  payload:
    receive:
      - name: Case_Manager_Phone_Number

Keys (What you match on). linkage_terms.linkage_keys holds the Broader matching keys your file supports. To leave out the three less certain keys, delete the entries named LN + FN + DOB, swap(LN, FN) + DOB and split(LN) + FN + DOB, each with every line under it. The comment above linkage_keys that begins "To run the highest-precision rules only" names the further keys to delete.

Who receives the result (Who receives the result). Set linkage_terms.output:

A list or only a count (A list or only a count). For a count, set algorithm: psi-c, delete every key in linkage_keys but one, set every column to is_payload: false, and add no payload.receive.

4Create the invitation ​

alcove invite takes its terms from alcove.yaml and prints the invitation. Run it without -it, so only the invitation goes into the file:

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD":/work ghcr.io/georgetown-mdi/alcove:latest invite --expires-in 2d input.csv > invitation.txt

docker run --rm -v "${PWD}:/work" ghcr.io/georgetown-mdi/alcove:latest invite --expires-in 2d input.csv | Set-Content -Encoding ascii invitation.txt

docker run --rm -v "$PWD":/work ghcr.io/georgetown-mdi/alcove:latest invite --expires-in 2d input.csv > invitation.txt

podman run --rm --userns=keep-id:uid=1000,gid=1000 -v "$PWD":/work ghcr.io/georgetown-mdi/alcove:latest invite --expires-in 2d input.csv > invitation.txt

The invitation lasts 1 hour without --expires-in. Give it time for your partner to accept and for the first exchange: 2d is 2 days, and 365d is the longest.

You should see: derived the invitation's linkage terms from ./alcove.yaml, then the expiry in your local time. .alcove.key is now in the folder.

The terms are fixed once the invitation exists. To change them, delete .alcove.key, which also withdraws the invitation, edit alcove.yaml, and run alcove invite again.

5Send your partner the invitation ​

Send:

• invitation.txt, as an attachment over encrypted email or your secure file transfer. It runs to about 9,000 to 10,300 characters, so it cannot be read aloud. It holds a one-time secret: anyone who has it can take your partner's place.
• The page to follow: Accept an invitation for a partner on the command line. For the console or the web app, see If your partner uses the console or the web app.
• On SFTP: the server's host name and port, their account, the directory, and the server's fingerprint (below, If you run the SFTP server).
• When you both run the first exchange, before the invitation expires.

2Invite again ​

From the new folder, run step 4 and send the new invitation as in step 5. On SFTP or a shared folder, check the directory is empty before the real run: a file from another exchange stops it.

2Make the directory ​

Make one directory both accounts can read and write, used by this exchange only. A file from another exchange in it stops the run.