Integrate enmeshed

Communication and sharing of information between two Identities requires the existence of a Relationship between them. This guide describes how a Connector can establish an active Relationship to another Identity. Firstly, we explain how to create a RelationshipTemplate on a Connector, the so-called Templator, and how to make the RelationshipTemplate available to the other Identity. The RelationshipTemplate can then be used by the other Identity, the so-called Requestor, to send a RelationshipRequest to the Templator. This RelationshipRequest can finally be accepted by the Templator in order to establish an active Relationship between them.

Create a RelationshipTemplate

The creation of a RelationshipTemplate on the Templator is the first required step in the process of establishing a Relationship. A RelationshipTemplate is a formal description of the aspects of a Relationship that can be established between two Identities. In particular, it can specify a Request sent from the Templator to the Requestor, which must be accepted by the Requestor as a prerequisite for the establishment of the Relationship.

Input for creating a RelationshipTemplate

To create a RelationshipTemplate on the Templator, you need to follow the instructions described in the Create own RelationshipTemplate use case documentation using the following JSON payload as input:

{
  "maxNumberOfAllocations": <maximum number of allocations>,
  "expiresAt": "<expiration date of RelationshipTemplate>",
  "content": {
    // Content of RelationshipTemplate
    ...
  }
}

You need to replace the placeholders marked with <...> appropriately as usual. The maxNumberOfAllocations property is optional, so you can omit it. If you need help filling the content property or the maxNumberOfAllocations property with appropriate values, see the RelationshipTemplate description in the Data Model Overview. It is important to note that if you intend to use the RelationshipTemplate to establish a Relationship between the Templator and an App user, you must use a RelationshipTemplateContent as the value of the content property. In this case, the input must be as follows:

{
  "maxNumberOfAllocations": <maximum number of allocations>,
  "expiresAt": "<expiration date of RelationshipTemplate>",
  "content": {
    // RelationshipTemplateContent
    "@type": "RelationshipTemplateContent",
    "title": "<title of RelationshipTemplate>",
    "metadata": <custom metadata>,
    "onNewRelationship": {
      // Specification of a Request
      ...
    },
    "onExistingRelationship": {
      // Specification of another Request
      ...
    }
  }
}

The properties content.title, content.metadata and content.onExistingRelationship are optional, so you can omit them. In case the content property of the RelationshipTemplate contains a RelationshipTemplateContent and therefore in particular at least one Request, you should check the Requests’ validity before you create the RelationshipTemplate. An Identity to which the RelationshipTemplate will be made available and which does not yet have a Relationship to the Templator will receive the Request specified in the onNewRelationship property of the RelationshipTemplateContent. However, if a Relationship already exists between them and a Request has been specified in the onExistingRelationship property of the RelationshipTemplateContent, the Identity will receive this Request instead.

How to send a Request via a RelationshipTemplate is explained in detail in the Requests via RelationshipTemplates guide.

Successfully created RelationshipTemplate

If you have successfully created the RelationshipTemplate on the Templator, you will receive a success response from which you can read its id. As the Templator is the creator of the RelationshipTemplate, the createdBy property contains the Address of the Templator. For this reason, the value of the isOwn property is set to true in this context.

Save the id of the RelationshipTemplate so that you can refer to it and make it available to other Identities later. For the same reason, save the values of the properties truncatedReference and secretKey.

Make the RelationshipTemplate available

Before an Identity can establish a Relationship to the Templator, it must send a RelationshipRequest using a valid RelationshipTemplate which is owned by the Templator. Depending on whether the Identity is a Connector or an App user, a different approach must be used to make the RelationshipTemplate available to the Identity:

Make it available to a Connector

If a Connector wants to send a RelationshipRequest to the Templator, it must first load a RelationshipTemplate, which is owned by the Templator, onto itself. This can be done by following the Load RelationshipTemplate created by others use case description and providing the input:

{
  "reference": "<truncated reference of RelationshipTemplate>"
}

In doing so, it is necessary to insert the value of the truncatedReference property read from the created RelationshipTemplate into the reference property. Alternatively, it is possible to specify the id and the secretKey of the created RelationshipTemplate and use the following input:

{
  "id": "<ID of RelationshipTemplate>",
  "secretKey": "<secret key of RelationshipTemplate>"
}

When the RelationshipTemplate of the Templator is successfully loaded onto the Connector, the transport.peerRelationshipTemplateLoaded Connector event is triggered and a success response is sent. This success response looks like the success response you receive when you have successfully created a RelationshipTemplate on the Templator, except that the value of the property isOwn is now false instead of true. Assuming that there is no Relationship between the Connector and the Templator yet and that the RelationshipTemplate contains a RelationshipTemplateContent in its content property, the Connector will additionally receive a new incoming Request. The Integrator of the Connector can accept it if they want to send a RelationshipRequest to the Templator.

Make it available to an App user

If an App user wants to send a RelationshipRequest to the Templator, the App user must first scan a QR Code that contains the reference to a RelationshipTemplate which is owned by the Templator. To create this QR Code on the Templator, proceed as described in the documentation of the Get RelationshipTemplate use case, use the id of the created RelationshipTemplate and specify the value image/png in the Accept header field. After scanning the QR Code, the App user receives the conditions for establishing a Relationship to the Templator as specified in the RelationshipTemplate. If these are accepted, the App user can now send a RelationshipRequest to the Templator.

Send a RelationshipRequest

After the Templator has created a RelationshipTemplate and made it available to another Identity, this Identity can use it to send a RelationshipRequest to the Templator. For this reason, this other Identity is also referred to below as the Requestor.

Send it as a Connector

Assuming that the Requestor in this section is a Connector, our starting situation is that the Requestor has successfully loaded the created RelationshipTemplate onto itself. The received RelationshipTemplate may or may not contain a RelationshipTemplateContent in its content property. We now describe separately in both cases how the Requestor can use the RelationshipTemplate to send a RelationshipRequest to the Templator. An overview of this procedure is given in the following diagram.

RelationshipTemplate with RelationshipTemplateContent

We assume that there is no Relationship between the Requestor and the Templator yet and that a RelationshipTemplateContent is used within the RelationshipTemplate. In this case, the Requestor receives a new incoming Request after loading the RelationshipTemplate and the consumption.incomingRequestReceived Connector event is triggered. By proceeding as described in the Query incoming Requests use case documentation and specifying source.reference=<ID of RelationshipTemplate> as a query parameter, this Request can be queried on the Requestor. The result contains the corresponding LocalRequest, from which you can read the id of the Request.

Save the id of the incoming Request so that you can accept or reject it.

The content of the LocalRequest is the Request specified in the onNewRelationship property of the RelationshipTemplateContent. This Request defines the conditions for establishing an active Relationship between the Requestor and the Templator. If the Requestor agrees to them, it can send a RelationshipRequest to the Templator by accepting the Request. This is done by following the instructions of the Accept incoming Request use case and providing the id of the Request as well as an appropriate input to build the Response of the Requestor to the Request. In case of success, the status of the LocalRequest will change from "ManualDecisionRequired" to "Decided" and the consumption.incomingRequestStatusChanged Connector event will be triggered. The Response of the Requestor to the Request will be contained within the response.content property of the LocalRequest. By accepting the Request, a data object of type Relationship with "Pending" as status is created additionally and the transport.relationshipChanged Connector event is triggered. An associated RelationshipChange, which has "Creation" as type and "Pending" as status, can be found within the changes property of the Relationship. The request.content.response property of the RelationshipChange contains the Response of the Requestor to the Request.

It is not necessary, but you can query this Relationship by proceeding as described in the Query Relationships use case documentation, using the query parameter template.id=<ID of RelationshipTemplate>. If you decide to do this, you will receive a result as response from which you can read the id of the Relationship and the id of the associated RelationshipChange.

Note that it is of course also possible to reject the incoming Request, if the Requestor does not wish to establish an active Relationship to the Templator under the given conditions. In order to do this, make use of the documentation of the Reject incoming Request use case. More detailed information about how to reject as well as how to accept an incoming Request can also be found in the Requests via RelationshipTemplates guide.

RelationshipTemplate without RelationshipTemplateContent

We now consider the situation in which the RelationshipTemplate loaded onto the Requestor does not contain a RelationshipTemplateContent in its content property. In this case, the Requestor does not receive an incoming Request. Nevertheless, it can send a RelationshipRequest to the Templator by explicitly creating a data object of type Relationship with "Pending" as status based on the RelationshipTemplate. To do this, follow the instructions of the Create Relationship with RelationshipTemplate use case and provide as input:

{
  "templateId": "<ID of RelationshipTemplate>",
  "content": {
    // Customized content
    ...
  }
}

Note that the content property is optional and can therefore be omitted. In case of success, the transport.relationshipChanged Connector event will be triggered and you will receive a result as response, which contains the created data object of type Relationship and in particular an associated RelationshipChange. The RelationshipChange has "Creation" as type and "Pending" as status. If you have specified a customized content within the content property of the input, it is contained within the request.content property of the RelationshipChange.

Saving the id of the Relationship and the id of the associated RelationshipChange is useful if you want to return to the created Relationship later in order to retrace changes to the Relationship.

Send it as an App user

As already mentioned in the description of the input for creating a RelationshipTemplate, a RelationshipTemplateContent must be used as the value of the content property of the RelationshipTemplate if you intend to use the RelationshipTemplate to establish a Relationship between the Templator and an App user. Assuming that there is no Relationship between them yet, the App user receives the Request specified in the onNewRelationship property of the RelationshipTemplateContent after scanning the QR Code associated with the RelationshipTemplate. The App user has the option of accepting or rejecting the Request. If they accept the Request appropriately, a RelationshipRequest is sent to the Templator. Internally, this corresponds to the creation of a data object of type Relationship with "Pending" as status and an associated RelationshipChange within its changes property. The RelationshipChange has "Creation" as type and "Pending" as status. The Response of the App user to the Request is contained within the request.content.response property of the RelationshipChange.

Please note that the general procedure is the same if an App user instead of a Connector wants to send a RelationshipRequest to the Templator. The difference is that the RelationshipTemplate does not need to contain a RelationshipTemplateContent in its content property if it is intended to be used by a Connector.

Establish an active Relationship

After the Requestor has sent the RelationshipRequest, the Integrator of the Templator can accept it if they want to establish an active Relationship to the Requestor. We now explain all required steps for establishing an active Relationship, including the necessary synchronization of the Templator and any other Connector that may be involved at certain points in time. Please note that the synchronization can also be automated by using the Sync Module.

Receive the RelationshipRequest

The Templator must first synchronize the updates of the Backbone in order to receive the data object of type Relationship with "Pending" as status previously created by the Requestor and therefore the RelationshipRequest. The synchronization causes the transport.relationshipChanged Connector event to be triggered and the result of the response after synchronization contains the information about the created Relationship. In particular, the id of the Relationship and the id of the associated RelationshipChange with "Creation" as type and "Pending" as status can be read from it.

Read the id of the Relationship from the relationships.id property and the id of the RelationshipChange from the relationships.changes.id property of the synchronization result for the next step.

Accept the RelationshipRequest

If the Templator accepts the RelationshipRequest, the status of the data object of type Relationship will change from "Pending" to "Active" and therefore an active Relationship between the Templator and the Requestor will be established. In addition, the transport.relationshipChanged Connector event will be triggered. To accept the RelationshipRequest, consult the Accept RelationshipChange use case description and specify the id of the Relationship and the id of the associated RelationshipChange.

For rejecting the RelationshipRequest and therefore not establishing an active Relationship between the Templator and the Requestor, take a look at the documentation of the Reject RelationshipChange use case.

Get informed about the acceptance of the RelationshipRequest

Assuming the Requestor is a Connector, it must synchronize the updates of the Backbone after the Templator has accepted the RelationshipRequest. The synchronization causes the transport.relationshipChanged Connector event to be triggered and the result of the response after synchronization shows in particular that the status of the Relationship has been changed from "Pending" to "Active" and that the status of the associated RelationshipChange with "Creation" as type has been changed from "Pending" to "Accepted". Now the Requestor is informed that the Templator has accepted the RelationshipRequest and therefore an active Relationship has been established between them. If the Requestor is an App user instead, they are informed about the acceptance of the RelationshipRequest analogously.

What’s next?

After an active Relationship between the two Identities is established, they are able to share information with each other. For example, they can exchange Messages. A possible scenario that demonstrates how a Connector can send a Message to another Identity with which it has an active Relationship is described in the Requests via Messages scenario documentation.