Integrate enmeshed

Communication between Identities involves exchanging uploaded Files with each other, for example:

  • A language school wants to send a student their language certificate.
  • A university wants to send a student their certificate of enrollment.
  • An applicant wants to send their curriculum vitae to a company.

This guide describes how an Integrator of a Connector can use a certain kind of Attribute to share a File with a peer. Furthermore, an understanding of this kind of Attribute is also necessary to make use of further options for exchanging Files, such as requesting the reading of a File from a peer.

The peer with whom a File is exchanged using Attributes can be an Integrator of another Connector or an App user. The File exchange flow described in this guide remains the same, even if some steps are performed automatically in the App.

Upload a File

In order to be able to share a File with a peer, its content must first be uploaded to the Backbone in encrypted form. To do this, consult the documentation of the Upload own File use case. By uploading the File, it has been assigned an id and a truncatedReference with which it can be identified from now on. Both can be specified as a parameter when executing the Get File metadata use case in order to display the metadata information of the File. In the context of exchanging Files, particular attention should be paid to the truncatedReference property of the File. All Identities that know its value can download the encrypted content of the File from the Backbone and decrypt it.

Share a File With a Peer

After uploading a File, a certain kind of Attribute can be used to share the value of the truncatedReference property of the File with other Identities. To be more precise, this is an IdentityAttribute that has IdentityFileReference as its value.@type. An IdentityFileReference stores the value of the truncatedReference property of the File within its value property. By sending a suitable Request, this IdentityAttribute can be shared with a peer of an already existing Relationship or in the process of establishing a Relationship.

Create an IdentityFileReference

After uploading the File, an IdentityAttribute with an IdentityFileReference as its value.@type and the truncatedReference of the uploaded File as its value.value can be created by proceeding as described in the documentation on how to create an IdentityAttribute for yourself. The following content can be used during the creation process, with its properties validFrom, validTo and tags being optional:

{
  "content": {
    "validFrom": "<start of IdentityFileReference's validity>",
    "validTo": "<end of IdentityFileReference's validity>",
    "value": {
      "@type": "IdentityFileReference",
      "value": "<truncatedReference of File>"
    },
    "tags": ["<tag of IdentityFileReference to be created>", ...]
  }
}

If an App user uploads a File, such an IdentityAttribute with an IdentityFileReference as its value.@type and the truncatedReference of the uploaded File as its value.value is created automatically in the background. For this reason, it is directly available to the App user for sharing. Furthermore, knowledge of this automation in the App should motivate Integrators of Connectors to strive to exchange Files using Attributes in order to achieve File management compatibility between them and App users.

Share an IdentityFileReference

After the IdentityAttribute that has IdentityFileReference as its value.@type and the truncatedReference of the uploaded File as its value.value has been created, the Integrator of the Connector must send a suitable Request to share it. More details on how to share Attributes can be found in the Share Attributes with peer scenario documentation.

Load a Referenced File

Once the shared IdentityAttribute that has IdentityFileReference as its value.@type has been obtained, its recipient has knowledge of its value.value and thus also of the truncatedReference of the File to be shared. In order for the recipient to be authorized to download the encrypted content of the File from the Backbone and decrypt it, they must first load the metadata information of the File. This is done by executing the Load File use case and specifying the truncatedReference of the File as the required reference.

Please note that it is also possible to store the truncatedReference of a Token for the File within the value.value property of the IdentityAttribute of IdentityFileReference value.@type instead of the truncatedReference of the File itself. In this case, the Token for the File must be created beforehand. The advantage of using Tokens is that they can be personalized or password protected. When executing the Load File use case, the truncatedReference of the Token can be specified as the reference. If the Token is password protected, the password must additionally be entered for loading.

Further Options for Exchanging Files

As for all other kinds of Attributes, the IdentityAttributes of IdentityFileReference value.@type can be read from a peer, created for a peer and proposed to a peer by proceeding as described in the corresponding scenario documentation. In addition, there is the option of updating by succession and deletion. However, the deletion of an IdentityAttribute that has IdentityFileReference as its value.@type does not additionally lead to the deletion of the associated uploaded encrypted content of the File on the Backbone. This must be done separately if required.

Utilization of a ProprietaryFileReference

Furthermore, it is possible to represent uploaded Files within a Relationship utilizing a RelationshipAttribute that has ProprietaryFileReference as its value.@type and the truncatedReference of the File as value.value. It is advantageous to use such a RelationshipAttribute instead of an IdentityAttribute of IdentityFileReference value.@type if the File fits more into the context of the Relationship and is less attributable to a single Identity. An overview of the available options for creating a RelationshipAttribute can be found in the corresponding scenario documentation.