Establish Relationships
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 |
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: Load the RelationshipTemplate onto it.
- Make it available to an App user: Scan the QR Code of the RelationshipTemplate.
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 |
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 |
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.