Document Exchange Usage

If you have integrated your Document Store service with an S3 Bucket or Azure Blob container, any pre-existing files in those services will be displayed within the DOCUMENTS section of the service.  Kaleido neither persists nor automatically hashes any of these files.  There is simply a one-to-one mapping of your current storage state, along with the inheritance of any nested directory structures in your bucket or container.  In addition to mirroring your cloud storage utility, Kaleido also uploads a lightweight permissions test file - kaleido-permissions-test - to verify the Document Store integration with your cloud storage.  You can delete this file at any time with no impact to the service.  If you are using Kaleido-hosted storage, your DOCUMENTS section will initialize in an empty state.

Sending Files via the console

In order to send a document using the service, another member in your environment needs:

• A deployed instance of the Document Exchange service
• A fully-completed destination within their Document Exchange service

Kaleido will query the On-Chain Registry for available destinations and surface these, along with the owning member, under the DIRECTORY tab.  Think of your counterpart's destination as an inbox or email address for the secure transfer of data.

From your DOCUMENTS tab navigate to the relevant file you wish to send.  Click on the send icon beneath the ACTIONS column.

This will open a new panel for you to configure:

• Receiver Membership - The member you wish to send the document to
• Receiver Destination - The specific destination you wish to send the document to
• Sender Destination - Your destination you wish to send the document from

Once you have configured the transfer, click the TRANSFER button at the bottom of the modal

The file is encrypted in transit with the receiving member's destination certificate and signed with the private key of the sending member's destination certificate.  More details on asymmetric encryption and transfer mechanics are explained in the Transfer and Receipt Architecture.

After clicking SEND DOCUMENT you will be automatically redirected to the TRANSFERS tab to the see the status of the transfer.  The three states are:

• transfer sent
• transfer received
• transfer failed

Transfers usually take a few seconds to fully complete.

Sending files via API

Data can also be sent, received and managed programmatically using Kaleido's simple RESTful APIs, with socket.io connections available for reliable event notifications. Detailed documentation for the Document Exchange APIs can be found HERE and code snippet samples can be found in the documentstore-snippets repository.

The service provides two primary RESTful endpoints:

• /documents for upload, download, query, overwrite, hash calculation and deletion of documents in the service
• /transfers  for the transfer of documents to destinations in your environment

The following additional endpoints are also available:

• /config - to see the configuration of your service
• /search - to search for files by name or hash
• /sync_hashes - resets all hashes; useful for cleaning the internal database when deleting documents outside the Document Store API

The socket.io connection allows you to listen for three event notifications:

• document_sent - returns metadata for a transfer initiated by you, as well as a status of sent
• document_received - a document has been sent to one of your destinations
• transfer_acknowledgement - acknowledgement from the recipient that the document was received

As a simple example, use a standard REST client like Postman and:

• POST to the /transfers endpoint
• set Authorization to basic auth with the displayed app credentials and set the body to raw with "Content-Type: Application/json"
• provide the following JSON object as the body

{"from":"your_destination", "to":"recipient_destination", "document":"filename_or_pathTofile"}

Receiving Files

Any files sent to you will appear in a "received" folder at the root of your DOCUMENTS tab.  They are then further scoped by the destination they have been sent to.  For example, you may have multiple destinations for contracts, insurance claims, provider data, etc...  The structure is as follows:  DOCUMENTS -> Received -> destination(s)

The received document will then be available for you to download, send or delete.

Receiving Files via API

Use the socket.io connection and listen for the document_received event.  As the name indicates, this notification will be fired every time your Document Store service receives a file.   The event will emit metadata around the document, including the sender, transfer ID and most importantly the hash.

Use GET and the /search endpoint to query the hash and retrieve the document name.

Use GET and the /documents endpoint (specifying the full path to the file) to download the file.  If you specify a directory, the call will return a listing of files in the directory.  If a query parameter of details_only is passed as true, the metadata for the document will be returned.

Searching for files in the console

Click on the SEARCH tab within the service.  You have the option to search for files by name or by hash.

If you have files in your document store that are missing hashes, you will have the option to calculate all missing hashes.  This scenario occurs when you have files that have not been uploaded or received via the Document Store API.  In other words, the file is present in your external cloud storage but has not been hashed in Kaleido.  All received files will, by default, have their hash calculated.

The typical convention is to reference files by hash on the blockchain.  Therefore, if you're interested in the contents of a referenced file you can easily search by hash and subsequently calculate any missing hashes to determine if you are in possession of the file.  If you are missing the file, you can follow your network's business conventions to purchase the file or request transfer from a member in possession.

Searching for files via API

Use GET and the /search endpoint to search for files.

To search for files by name, pass the file name as a string.

To search for files by hash, set the query parameter by_hash to true and pass the full hash or a portion of the hash as a string.

Logs and Settings

The LOGS tab will display current and historical logs for the service.  Use the logs for devops and troubleshooting purposes.

The SETTINGS tab enables you to:

• Change the name
• Change runtime size
• Name of the 'receive' folder
• Restart the runtime
• Delete the runtime