Skip to content

Commit

Permalink
feat: add personalization
Browse files Browse the repository at this point in the history
  • Loading branch information
Magnus-Kuhn committed Nov 14, 2024
1 parent 5035251 commit e636b53
Show file tree
Hide file tree
Showing 10 changed files with 51 additions and 6 deletions.
2 changes: 2 additions & 0 deletions _docs_integrate/data-model-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ A Token has the following properties:
| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone |
| createdAt | `string` | {% include descr_createdAt class="Token" %} | |
| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | |
| forIdentity | `string` | Can be set to an enmeshed Address. If set, then only the Identity with that Address can retrieve the Token from the Backbone. |
| truncatedReference | `string` | {% include descr_truncatedReference class="Token" %} | saved only locally |
| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its truncatedReference. |

Expand All @@ -79,6 +80,7 @@ A RelationshipTemplate serves two purposes:
| content | [`RelationshipTemplateContent`](#relationshiptemplatecontent) \| [`ArbitraryRelationshipTemplateContent`](#arbitraryrelationshiptemplatecontent) | The content of the RelationshipTemplate. If it is intended for a User of the enmeshed App, `RelationshipTemplateContent` has to be used. Otherwise, an `ArbitraryRelationshipTemplateContent` can also be used, which can be filled with anything and serves as a fallback if the `RelationshipTemplateContent` is not sufficient. | |
| expiresAt | `string` | {% include descr_expiresAt class="RelationshipTemplate" %} | will be encrypted before sent to the Backbone |
| maxNumberOfAllocations | `number` \| `undefined` | Can be set to limit the number of allocations of this RelationshipTemplate. A RelationshipTemplate is allocated by another Identity when it is first retrieved by it from the Backbone. After this value is reached, the Backbone rejects each request of any new Identity that wants to retrieve it. Identities that already allocated it will still be able to retrieve it. | |
| forIdentity | `string` | Can be set to an enmeshed Address. If set, then only the Identity with that Address can retrieve the RelationshipTemplate from the Backbone. | |
| truncatedReference | `string` | {% include descr_truncatedReference class="RelationshipTemplate" %} | saved only locally |

## Relationship
Expand Down
14 changes: 14 additions & 0 deletions _docs_integrate/establish-relationships.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,20 @@ If you have successfully created the [RelationshipTemplate]({% link _docs_integr

{% include copy-notice description="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 value of the property `truncatedReference`." %}

### Personalize the RelationshipTemplate

If the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is only for creating a Relationship with a single known Identity, you can set that Identity's Address in the RelationshipTemplate:

```jsonc
{
...,
"content": {...},
"forIdentity": "<Address that the RelationshipTemplate is intended for>"
}
```

Only that Identity will be able to continue with establishing a Relationship. This also protects sensitive data of that Identity contained in the RelationshipTemplate from outside access.

## Make the RelationshipTemplate Available

For an Identity to initiate a Relationship with the templator, it must use a valid [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relat
- `expiresAt` is the ISODateTime the RelationshipTemplate expires at. This should be set as small as possible and cannot be in the past.
- `content` describes the structure of the RelationshipTemplate. If an enmeshed App user shall receive this RelationshipTemplate, a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) is required as structure, otherwise an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) containing any data can be used.
- `maxNumberOfAllocations` is the number of times the RelationshipTemplate can be accessed by different Identities to initiate a Relationship. The Backbone returns an error, if one accesses a RelationshipTemplate with no allocations left. Accessing the same RelationshipTemplate with the same Identity multiple times doesn't affect the number of allocations. The allocation counts, even if the Identity does not accept the RelationshipTemplate by discarding it.
- `forIdentity` can be set to an enmeshed Address. If set, only the Identity with that Address can access the RelationshipTemplate.

## On Success

Expand Down
1 change: 1 addition & 0 deletions _docs_use-cases/use-case-transport-create-own-token.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that
- `content` an arbitrary JSON structure of the data to share via the Token.
- `expiresAt` is the ISODateTime the Token expires at.
- `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored.
- `forIdentity` can be set to an enmeshed Address. If set, only the Identity with that Address can load the Token from the Backbone.

## On Success

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a
- `fileId` is the `id` of the File the Token should be created for.
- Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at.
- Optionally, `ephemeral` can be specified, which indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) and don't need to be stored.
- Optionally, `forIdentity` can be specified, which names the Address of the only Identity that will be able to load the Token from the Backbone.

## On Success

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,10 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a

## Parameters

- `fileId` is the id of the File the Token should be created for.
- `templateId` is the id of the RelationshipTemplate the Token should be created for.
- `expiresAt` is the ISODateTime the Token expires at.
- `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored.
- `forIdentity` can be set to an enmeshed Address. If set, only the Identity with that Address can load the Token from the Backbone.

## On Success

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md %

- `fileId` is the `id` of the File the Token and its QR code should be created for.
- Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at.
- Optionally, `forIdentity` can be specified, which names the Address of the only Identity that will be able to load the Token from the Backbone.

## On Success

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
# Start automatic generation
permalink: use-case-transport-create-token-qr-code-for-own-relationshiptemplate
published: false
published: true
title: "Create Token QR code for own RelationshipTemplate"
type: use-case
toc: true
Expand All @@ -18,8 +18,8 @@ properties:
- feature category: Consent required before any data is shared
- tech category: RelationshipTemplates
- status: DONE
- documentation status:
- comments:
- documentation status: DONE
- comments: "Accept: image/png"
- actor: Identity
- trigger:
- precondition:
Expand All @@ -29,10 +29,32 @@ properties:
- size: n/a
- created_at:
- changed_at:
- api_route_regex:
- api_route_regex: POST /api/v2/RelationshipTemplates/Own/{id}/Token
- published: default
- link: use-case-transport-create-token-qr-code-for-own-relationshiptemplate
require:
required_by:
api_route_regex: ^POST /api/v2/RelationshipTemplates/Own/{id}/Token$
# End automatic generation
---

{{properties.description}}

{% include properties_list.html %}

Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md %}#token) of a given [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate)

## Parameters

- `templateId` is the id of the RelationshipTemplate the Token and its QR code should be created for.
- `expiresAt` is the ISODateTime the Token expires at.
- `forIdentity` can be set to an enmeshed Address. If set, only the Identity with that Address can load the Token from the Backbone.

## On Success

- Returns the created QR code encoded as Base64.

## On Failure

- `templateId` does not resolve to a RelationshipTemplate.
- `expiresAt` lies in the past
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ api_route_regex: ^POST /api/v2/RelationshipTemplates/Peer$

{% include properties_list.html %}

This use case loads a peer's [RelatonshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) from the Backbone by a given reference to the RelationshipTemplate.
This use case loads a peer's [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) from the Backbone by a given reference to the RelationshipTemplate.

## Parameters

Expand All @@ -65,3 +65,4 @@ There are two different options to use this use case, depending on the actual in
- The RelationshipTemplate does not exist.
- The RelationshipTemplate is expired.
- The `maxNumberOfAllocations` of the RelationshipTemplate are depleted.
- The RelationshipTemplate is personalized to a different Identity (via the property `forIdentity` of the RelationshipTemplate)
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,4 @@ You can execute this use case if you know the `truncatedReference` of the peer's
- The parameters are malformed.
- The Token does not exist.
- The Token is expired.
- The Token is personalized to a different Identity (via the property `forIdentity` of the Token)

0 comments on commit e636b53

Please sign in to comment.