Skip to content

Commit

Permalink
Use templateId instead of template for Relationships (#308)
Browse files Browse the repository at this point in the history
* feat: use templateId instead of template within Query Relationships use case

* feat: apply new query parameter of Query Relationships use case to scenarios
  • Loading branch information
britsta authored Mar 5, 2025
1 parent c1e1cd0 commit 5914bd7
Show file tree
Hide file tree
Showing 4 changed files with 6 additions and 8 deletions.
4 changes: 2 additions & 2 deletions _docs_integrate/establish-relationships.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ The [Request Module]({% link _docs_explore/61-runtime.md %}#request-module) enab

Accepting the Request is done by following the instructions of the [Accept incoming Request]({% link _docs_use-cases/use-case-consumption-accept-incoming-request.md %}) use case and providing the `id` of the Request as well as an appropriate input to build the [Response]({% link _docs_integrate/data-model-overview.md %}#response) of the initiator to the Request. In case of success, the `status` of the LocalRequest will change from `"ManualDecisionRequired"` to `"Decided"` and the `consumption.incomingRequestStatusChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) will be triggered. The Response of the initiator to the Request will be contained within the `response.content` property of the LocalRequest. By accepting the Request, a data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` is created and the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) is triggered. The Relationship's `creationContent.response` property contains the initiator's Response to the Request.

It is not necessary, but you can query this Relationship by proceeding as described in the [Query Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) 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.
It is not necessary, but you can query this Relationship by proceeding as described in the [Query Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) use case documentation, using the query parameter `templateId=<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.
{: .notice--info}

Note that it is of course also possible to reject the incoming Request, if the initiator 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]({% link _docs_use-cases/use-case-consumption-reject-incoming-request.md %}) use case. More detailed information about how to [reject]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#reject) as well as how to [accept]({% link _docs_integrate/requests-via-relationshiptemplates.md %}#accept) an incoming Request can also be found in the [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}) guide.
Expand Down Expand Up @@ -235,7 +235,7 @@ After the initiator has initiated the Relationship, the Integrator of the templa

### Receive the Pending Relationship

The templator must first [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) in order to receive the data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` previously created by the initiator. The synchronization causes the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) to be triggered. To view the created Relationship, proceed as described in the [Query Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) use case documentation and specify `<ID of RelationshipTemplate>` as the value for the `template.id` query parameter. In particular, the `id` of the Relationship can be read from the `result`.
The templator must first [synchronize the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}) in order to receive the data object of type [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) with `"Pending"` as `status` previously created by the initiator. The synchronization causes the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) to be triggered. To view the created Relationship, proceed as described in the [Query Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) use case documentation and specify `<ID of RelationshipTemplate>` as the value for the `templateId` query parameter. In particular, the `id` of the Relationship can be read from the `result`.

{% include copy-notice description="Read the `id` of the Relationship from the `result` for the next step." %}

Expand Down
2 changes: 1 addition & 1 deletion _docs_integrate/integration-example.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ To do so, we [synchronize updates of the Backbone]({% link _docs_use-cases/use-c
{% include rapidoc api_route_regex="^post /api/v2/Account/Sync$" %}

The synchronization causes the `transport.relationshipChanged` [Connector event]({% link _docs_integrate/connector-events.md %}) to be triggered, which should be listened to in order to get the Relationship in status `Pending`.
We can also [get the Relationship]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) via `GET /api/v2/Relationships`. Should you be repeating this tutorial, you could e.g. filter by the `id` of the RelationshipTemplate from earlier via `GET /api/v2/Relationships?template.id=<id>` if you use a different RelationshipTemplate.
We can also [get the Relationship]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) via `GET /api/v2/Relationships`. Should you be repeating this tutorial, you could e.g. filter by the `id` of the RelationshipTemplate from earlier via `GET /api/v2/Relationships?templateId=<id>` if you use a different RelationshipTemplate.

{% include rapidoc api_route_regex="^get /api/v2/Relationships$" %}

Expand Down
6 changes: 2 additions & 4 deletions _docs_integrate/requests-via-relationshiptemplates.md
Original file line number Diff line number Diff line change
Expand Up @@ -209,7 +209,7 @@ The Sender, then, can fetch it by [synchronizing the updates of the Backbone]({%
However, if there is no active Relationship between the Connectors yet, a Relationship will be created, which has the `status` `"Pending"` for now.
Its creation content is of type [RelationshipCreationContent]({% link _docs_integrate/data-model-overview.md %}#relationshipcreationcontent) and contains the Response to the Request.
This Relationship is sent back to the Sender via a Message.
Then, the Request is set to `status` `"Completed"` and you can [query the Relationship]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) using the query parameter `template.id=<ID of RelationshipTemplate>`.
Then, the Request is set to `status` `"Completed"` and you can [query the Relationship]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) using the query parameter `templateId=<ID of RelationshipTemplate>`.
As long as the Relationship is `"Pending"`, no new Request is created by [loading the RelationshipTemplate](#receive-the-request-by-loading-the-relationshiptemplate).

The Sender can fetch the Relationship by [synchronizing the updates of the Backbone]({% link _docs_use-cases/use-case-transport-synchronize-updates-of-backbone.md %}).
Expand All @@ -218,9 +218,7 @@ The new Relationship looks as follows:
```jsonc
{
"id": "REL...",
"template": {
// ...
},
"templateId": "RLT...",
"status": "Pending",
"peer": "did:e:...",
"creationContent": {
Expand Down
2 changes: 1 addition & 1 deletion _docs_use-cases/use-case-transport-query-relationships.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ This use case queries [Relationships]({% link _docs_integrate/data-model-overvie

- `peer` is the enmeshed address of the peer.
- `status` is the status of the Relationship.
- `template.id` is the id of the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) that was used to initiate the Relationship.
- `templateId` is the `id` of the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) that was used to initiate the Relationship.

## On Success

Expand Down

0 comments on commit 5914bd7

Please sign in to comment.