Skip to content

Commit

Permalink
feat: prepare enmeshed onboarding package
Browse files Browse the repository at this point in the history
  • Loading branch information
@britsta
britsta committed Oct 30, 2023
1 parent 7fa0ed9 commit 70597d3
Showing 1 changed file with 23 additions and 20 deletions.
43 changes: 23 additions & 20 deletions _includes/scenarios/integrate/prepare-enmeshed-onboarding-package.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Communication and sharing of information between a Connector and another Identity requires the existence of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between them. This guide describes how to create an onboarding package on a Connector that can then be used by other Identities to send a Relationship Request to the Connector. The creation of a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is the first required step in this process.<!--- Fundamental to this is an understanding of how to create a [Relationship Template]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate).---> <!--- Or receive Relationship Requests? --->
Communication and sharing of information between a Connector and another Identity requires the existence of a [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between them. This guide describes how to create an onboarding package on a Connector that can then be used by other Identities to send a Relationship Request to the Connector. The creation of a [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is the first required step in this process.<!--- Fundamental to this is an understanding of how to create a [Relationship Template]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate).--->

## Create a RelationshipTemplate

Expand Down Expand Up @@ -28,7 +28,7 @@ You need to replace the placeholders marked with <...> appropriately. The `maxNu
"content": {
//RelationshipTemplateContent
"@type": "RelationshipTemplateContent",
"title": "<your Relationship Template's title>",
"title": "<your RelationshipTemplate's title>",
"metadata": <custom metadata>,
"onNewRelationship": {
//Specification of a Request
Expand All @@ -51,9 +51,6 @@ For more details on how to send a Request to create a RelationshipTemplate, see

<!---{% include rapidoc api_route_regex="^post /api/v2/RelationshipTemplates/Own$" %}--->

<!---In case the `"content"` property of the Relationship Template is supplied and contains a data object of type [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent), you should [test the Requests' Validity][TODO: Link] of the Requests specified in the `"onNewRelationship"` and `"onExistingRelationship"` properties before you create the Relationship Template. The way of how to share a Request over a Relationship Template is explained in detail in the [Requests over Templates]({% link _docs_integrate/requests-over-templates.md %}) guide.
{: .notice--info} --->

### Success Response

If you have successfully created the RelationshipTemplate on your Connector on a certain Device, you will receive a success response in the following form:
Expand All @@ -71,14 +68,14 @@ If you have successfully created the RelationshipTemplate on your Connector on a
//Content of the RelationshipTemplate
...
},
"truncatedReference": "<truncated reference>",
"truncatedReference": "<your RelationshipTemplate's truncated reference>",
"maxNumberOfAllocations": "<maximum number of allocations>",
"secretKey": "<secret key>"
"secretKey": "<your RelationshipTemplate's secret key>"
}
}
```

{% include copy-notice description="The ID of the RelationshipTemplate can be read from the `id` property. Save it so that you can refer to your RelationshipTemplate later. For the same reason, save the value of the `truncatedReference` property." %}
{% include copy-notice description="The ID of the RelationshipTemplate can be read from the `id` property. Save it so that you can refer to your RelationshipTemplate later. For the same reason, save the values of the `truncatedReference` and `secretKey` properties." %}

## Onboarding

Expand All @@ -87,41 +84,47 @@ Before an Identity can establish a Relationship with your Connector, it must sen
- Onboarding of an App user: Scan the QR Code of the RelationshipTemplate.
- Onboarding of another Connector: Load the RelationshipTemplate onto it.

![High level architecture diagram of enmeshed components and layers]({{ '/assets/images/integrate/Prepare enmeshed onboarding package.svg' | relative_url }}){: .align-center}
[![High level architecture diagram of enmeshed components and layers]({{ '/assets/images/integrate/Prepare enmeshed onboarding package.svg' | relative_url }}){: .align-center}]({{ '/assets/images/integrate/Prepare enmeshed onboarding package.svg' | relative_url }})

### Onboarding of an App user
<!--- Not magnifiable version: ![High level architecture diagram of enmeshed components and layers]({{ '/assets/images/integrate/Prepare enmeshed onboarding package.svg' | relative_url }}){: .align-center} --->

If we want to use the enmeshed App to send a Relationship Request to our Connector, we now have to create a QR Code one can scan with the App to retrieve the RelationshipTemplate... <!---This then can be used to send a Relationship Request to the Connector.--->
### Onboarding of an App user

For this, execute the `GET /api/v2/RelationshipTemplates/{id}` route (Accept Header: image/png) to create a QR Code. Use the ID of the RelationshipTemplate from the [previous step]({% link _docs_integrate/prepare-enmeshed-onboarding-package.md %}#success-response) as the value for `{id}`.
If an App user wants to send a Relationship Request to your Connector, the App user must first scan a QR Code that contains the reference to a RelationshipTemplate owned by your Connector. By sending the Request `GET /api/v2/RelationshipTemplates/{id}`, specifying the value `image/png` in the `Accept` header field, you can create this QR Code on your Connector. You must replace the placeholder `{id}` in the URL with the ID of the RelationshipTemplate obtained from the [success response]({% link _docs_integrate/prepare-enmeshed-onboarding-package.md %}#success-response) above.

For more details on how to send a Request to create a QR Code containing the reference to the RelationshipTemplate, see the description of the [Get RelationshipTemplate]({% link _docs_use-cases/use-case-transport-get-relationship-template.md %}) usecase.
For more details on how to send a Request to create a QR Code containing the reference to a RelationshipTemplate, see the description of the [Get RelationshipTemplate]({% link _docs_use-cases/use-case-transport-get-relationship-template.md %}) usecase.
{: .notice--info}

<!---{% include rapidoc api_route_regex="^get /api/v2/RelationshipTemplates/{id}$" %}--->

After scanning the QR Code, the App user receives the conditions for establishing a Relationship with your Connector as specified in the RelationshipTemplate. If these are accepted, the App user can now send a Relationship Request to your Connector.

### Onboarding of another Connector

If we want to establish a Relationship between another Connector and our Connector, we have to load the RelationshipTemplate on this Connector. You can do so by calling the `POST /api/v2/RelationshipTemplates/Peer` route with the following content. Use the value of the `truncatedReference` property you saved [before]({% link _docs_integrate/prepare-enmeshed-onboarding-package.md %}#success-response):
If another Connector wants to send a Relationship Request to your Connector, it must first load a RelationshipTemplate owned by your Connector onto itself. This can be done by sending the Request `POST /api/v2/RelationshipTemplates/Peer` on the other Connector with the following JSON payload: <!--- reference: UkxU... --->

```jsonc
{
"reference": "<UkxU...>"
"reference": "<your RelationshipTemplate's truncatedReference>"
}
```

Alternatively you can use:
In doing so, it is necessary to insert the value of the `truncatedReference` property read from the [success response]({% link _docs_integrate/prepare-enmeshed-onboarding-package.md %}#success-response) above into the `reference` property. Alternatively, it is possible to use the following JSON payload specifying the ID and the secret key of the RelationshipTemplate obtained from the same [success response]({% link _docs_integrate/prepare-enmeshed-onboarding-package.md %}#success-response):

```jsonc
{
"id": "<string>",
"secretKey": "<string>"
"id": "<your RelationshipTemplate's ID>",
"secretKey": "<your RelationshipTemplate's secret key>"
}
```

For more details on how to send a Request to load a RelationshipTemplate created by a Connector onto another Connector, see the description of the [Load RelationshipTemplate created by others]({% link _docs_use-cases/use-case-transport-load-relationship-template-created-by-others.md %}) usecase.
{: .notice--info}

<!--- Other Connector: Can Accept the incoming Request (after loading the RelationshipTemplate) in order to send Relationship Request. --->
When the RelationshipTemplate of your Connector is successfully loaded onto the other Connector, a success response is sent. Assuming that there is no Relationship between the two Connectors yet, the other Connector will additionally receive an internally created new incoming Request. The user of the other Connector can accept it if it is wanted to send a Relationship Request to your Connector.

## What's next?

You have learned in this guide how to create an onboarding package on your Connector and make it available to other Identities. How a Connector can use it to send a Relationship Request and how to finally establish a Relationship is explained in the [Process received enmeshed onboarding package and create relationship]({% link _docs_integrate/process-received-enmeshed-onboarding-package-and-create-relationship.md %}) guide.
You have learned in this guide how to create an onboarding package on your Connector and make it available to other Identities. How another Connector can use it to send a Relationship Request and finally establish a Relationship to your Connector is explained in the [Process received enmeshed onboarding package and create relationship]({% link _docs_integrate/process-received-enmeshed-onboarding-package-and-create-relationship.md %}) guide.

<!--- There is a similar article for an App user that receives an onboarding package --->

0 comments on commit 70597d3

Please sign in to comment.