From ea8e63caf8ddfe474769ddd7a5b05e153ffea543 Mon Sep 17 00:00:00 2001 From: Vinzent Lange Date: Mon, 26 Jun 2023 09:45:14 +0000 Subject: [PATCH 01/55] feat: add files to operate --- _config.yml | 13 + _data/navigation.yml | 68 +- _docs_operate/00-basics.md | 38 + _docs_operate/01-connector-tutorial.md | 259 ++++++ .../02-connector-create-relationships.md | 96 +++ _docs_operate/03-connector-modules.md | 45 + _docs_operate/10-connector-installation.md | 110 +++ _docs_operate/11-connector-configuration.md | 417 ++++++++++ .../12-connector-setup-troubleshooting.md | 49 ++ _docs_operate/13-connector-error-codes.md | 76 ++ _docs_operate/14-connector-helm-chart.md | 133 +++ _docs_operate/20-connector-api.md | 29 + _docs_operate/21-connector-scenarios.md | 184 +++++ _docs_operate/30-connector-sdks.md | 44 + _docs_operate/31-connector-modules.md | 6 + _docs_operate/32-connector-events.md | 69 ++ _docs_operate/40-connector-operations.md | 74 ++ _docs_operate/42-connector-security.md | 121 +++ _docs_operate/43-connector-privacy.md | 14 + _docs_operate/44-connector-performance.md | 8 + _docs_operate/50-connector-migration-v2.md | 143 ++++ _docs_operate/61-data-model.md | 521 ++++++++++++ _docs_operate/62-request-items.md | 338 ++++++++ _docs_operate/63-attribute-values.md | 772 ++++++++++++++++++ .../diagrams/Connector_API_!Template.pu | 28 + ...Connector_API_AcceptRelationshipRequest.pu | 31 + ...Connector_API_CreateRelationshipRequest.pu | 32 + .../diagrams/Connector_API_CreateTemplate.pu | 38 + .../diagrams/Connector_API_GetMessage.pu | 34 + ...nnector_API_GetOpenRelationshipRequests.pu | 33 + .../diagrams/Connector_API_GetTemplate.pu | 41 + .../Connector_API_PreRelationshipOverview.pu | 84 ++ .../diagrams/Connector_API_ReceiveMessage.pu | 65 ++ ...onnector_API_ReceiveRelationshipRequest.pu | 35 + .../diagrams/Connector_API_SendMessage.pu | 33 + .../Connector_Flow_CreateAuthToken.pu | 53 ++ .../diagrams/Connector_Flow_UpgradeProfile.pu | 102 +++ .../docker-compose-with-existing-mongodb.yml | 14 + .../examples/docker-compose-with-ferretdb.yml | 39 + .../examples/docker-compose-with-mongodb.yml | 29 + _docs_operate/examples/example.config.json | 22 + _docs_use/03-app-scenarios.md | 2 + index.md | 6 + 43 files changed, 4323 insertions(+), 25 deletions(-) create mode 100644 _docs_operate/00-basics.md create mode 100644 _docs_operate/01-connector-tutorial.md create mode 100644 _docs_operate/02-connector-create-relationships.md create mode 100644 _docs_operate/03-connector-modules.md create mode 100644 _docs_operate/10-connector-installation.md create mode 100644 _docs_operate/11-connector-configuration.md create mode 100644 _docs_operate/12-connector-setup-troubleshooting.md create mode 100644 _docs_operate/13-connector-error-codes.md create mode 100644 _docs_operate/14-connector-helm-chart.md create mode 100644 _docs_operate/20-connector-api.md create mode 100644 _docs_operate/21-connector-scenarios.md create mode 100644 _docs_operate/30-connector-sdks.md create mode 100644 _docs_operate/31-connector-modules.md create mode 100644 _docs_operate/32-connector-events.md create mode 100644 _docs_operate/40-connector-operations.md create mode 100644 _docs_operate/42-connector-security.md create mode 100644 _docs_operate/43-connector-privacy.md create mode 100644 _docs_operate/44-connector-performance.md create mode 100644 _docs_operate/50-connector-migration-v2.md create mode 100644 _docs_operate/61-data-model.md create mode 100644 _docs_operate/62-request-items.md create mode 100644 _docs_operate/63-attribute-values.md create mode 100644 _docs_operate/diagrams/Connector_API_!Template.pu create mode 100644 _docs_operate/diagrams/Connector_API_AcceptRelationshipRequest.pu create mode 100644 _docs_operate/diagrams/Connector_API_CreateRelationshipRequest.pu create mode 100644 _docs_operate/diagrams/Connector_API_CreateTemplate.pu create mode 100644 _docs_operate/diagrams/Connector_API_GetMessage.pu create mode 100644 _docs_operate/diagrams/Connector_API_GetOpenRelationshipRequests.pu create mode 100644 _docs_operate/diagrams/Connector_API_GetTemplate.pu create mode 100644 _docs_operate/diagrams/Connector_API_PreRelationshipOverview.pu create mode 100644 _docs_operate/diagrams/Connector_API_ReceiveMessage.pu create mode 100644 _docs_operate/diagrams/Connector_API_ReceiveRelationshipRequest.pu create mode 100644 _docs_operate/diagrams/Connector_API_SendMessage.pu create mode 100644 _docs_operate/diagrams/Connector_Flow_CreateAuthToken.pu create mode 100644 _docs_operate/diagrams/Connector_Flow_UpgradeProfile.pu create mode 100644 _docs_operate/examples/docker-compose-with-existing-mongodb.yml create mode 100644 _docs_operate/examples/docker-compose-with-ferretdb.yml create mode 100644 _docs_operate/examples/docker-compose-with-mongodb.yml create mode 100644 _docs_operate/examples/example.config.json diff --git a/_config.yml b/_config.yml index 4f91c5b4c..3b6e3303f 100644 --- a/_config.yml +++ b/_config.yml @@ -77,6 +77,9 @@ collections: docs_integrate: output: true permalink: /:collection/:path + docs_operate: + output: true + permalink: /:collection/:path docs_scenarios: output: true permalink: /:collection/:path @@ -159,6 +162,16 @@ defaults: sidebar: - title: "Integrate Enmeshed" nav: "docs_integrate" + # operate + - scope: + path: "" + type: docs_operate + values: + layout: single + author_profile: false + sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" # _pages - scope: path: "_pages" diff --git a/_data/navigation.yml b/_data/navigation.yml index d4eeed9d2..6fd63f4fc 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -5,6 +5,8 @@ main: url: /explore - title: "Integrate" url: /integrate + - title: "Operate" + url: /operate/basics - title: "Contribute" url: /contribute - title: "Blog" @@ -88,62 +90,78 @@ docs_integrate: url: /integrate/basics - title: "Connector Tutorial" url: /integrate/connector-tutorial + - title: use-cases + children: + - title: xyz + + - title: Handling events + children: + - title: "Connector Events" + url: /integrate/connector-events + + - title: Data Model + children: + - title: "Overview" + url: /integrate/data-model-overview + - title: "Request Items" + url: /integrate/data-model-request-items + - title: "Attribute Values" + url: /integrate/data-model-attribute-values + +docs_operate: + - title: Getting Started + children: + - title: "Basics" + url: /operate/basics + - title: "Connector Tutorial" + url: /operate/connector-tutorial - title: "Connector Modules" - url: /integrate/connector-modules + url: /operate/connector-modules - title: Setting up the Connector children: - title: "Installation" - url: /integrate/connector-installation + url: /operate/connector-installation - title: "Configuration" - url: /integrate/connector-configuration + url: /operate/connector-configuration - title: "Troubleshooting" - url: /integrate/connector-setup-troubleshooting + url: /operate/connector-setup-troubleshooting - title: "Error Codes" - url: /integrate/error-codes + url: /operate/error-codes - title: "Helm Chart" - url: /integrate/helm-chart + url: /operate/helm-chart - title: REST API children: - title: "API Documentation" - url: /integrate/connector-api + url: /operate/connector-api - title: Scenarios children: - title: "Connector-Scenarios" - url: /integrate/connector-scenarios + url: /operate/connector-scenarios - title: Programming children: - title: "Connector SDKs" - url: /integrate/connector-sdks + url: /operate/connector-sdks - title: "Custom Connector Modules" - url: /integrate/custom-connector-modules + url: /operate/custom-connector-modules - title: "Connector Events" - url: /integrate/connector-events + url: /operate/connector-events - title: "Migrate to v2" - url: /integrate/connector-migration-v2 + url: /operate/connector-migration-v2 - title: Operations children: - title: "Connector Operations" - url: /integrate/connector-operations + url: /operate/connector-operations - title: "Security Considerations" - url: /integrate/connector-security + url: /operate/connector-security - title: "Privacy Considerations" - url: /integrate/connector-privacy + url: /operate/connector-privacy - title: "Performance Considerations" - url: /integrate/connector-performance - - - title: Data Model - children: - - title: "Overview" - url: /integrate/data-model-overview - - title: "Request Items" - url: /integrate/data-model-request-items - - title: "Attribute Values" - url: /integrate/data-model-attribute-values + url: /operate/connector-performance docs_scenarios: diff --git a/_docs_operate/00-basics.md b/_docs_operate/00-basics.md new file mode 100644 index 000000000..34c81c342 --- /dev/null +++ b/_docs_operate/00-basics.md @@ -0,0 +1,38 @@ +--- +title: "Basics" +permalink: /operate/basics +--- + +You want to seamlessly use Enmeshed with your processes, solutions and software components? No worries, you are good to go! + +We've built the Enmeshed Connector exactly for this scenario: to operate existing systems with the Enmeshed approach with as little effort as possible. + +## What is the Connector? + +It is a software component which runs in the network of any organization, hosting a set of APIs to easily consume Enmeshed features. It is usually run with the provided Docker image. The Connector requires a document database to store its data. + +Going a bit more technical, the Connector uses NodeJS with Express to host an HTTP server. It spans up REST APIs used as the primary integration mechanism. However, it is also possible to write custom TypeScript/JavaScript Modules which are run on the Connector itself. The Connector makes use of the Enmeshed Runtime to provide all features of the Enmeshed Transport Layer as a consumable API. + +## Why does my organization need a Connector? + +Enmeshed consists of different layers, each of which provide a different set of functionality and abstractions. The very low levels introduce a common set of communication and encryption contracts, which are required for all the upper levels. Just like you do not want to implement your own network stack, you usually do not want to implement the contracts by yourself. + +The Connector stores required Enmeshed metadata on a central point within the organization network, making it possible for existing system to access all the features of the Connector. With this approach, it is not necessary to implement the whole stack of Enmeshed in each and every system, like user key management and encryption capabilities. + +Additionally, the Connector should be run within the organizations network, as it acts as the digital identity of the organization itself, as well as a secure gateway to Enmeshed. Although it could be hosted by a third-party as a software-as-a-service, we discourage this approach for production environments. The hosting provider would be able to impersonate the actual organization within the Enmeshed ecosystem and would be able to access the plaintext data of users, messages, files, an so on. + +If you ask yourself now "Why does Enmeshed itself host Connectors then?" - good catch! We do host Connectors but only for development, test or demo reasons. + +## So how does my organization get started? + +Unfortunately, there is no button with which you can switch on the digitalization. Processes need to be set up, old processes need to be digitalized, data might need to be mapped, and so on. However, one needs to start somehow and we can help you on your journey. + +We propose to set up a first test Connector by your IT department or let us do the hosting. Then you can decide how far Enmeshed and its supported features and processes work for you. + +If you like to try on your own: There is a Connector Tutorial in the next chapter which is a good starting point to set up the Connector on a try out basis. More details are available in the "Setting up the Connector" and integration sections. If you like to dig deeper, there are operation tutorials which might answer some questions with regards to overall security and privacy. + +## Support + +For assisted support with the Connector or the Backbone provided by the j&s-soft GmbH contact us via `support[at]enmeshed.eu`. + +Community support is a great way to get help and even contribute to the projects. Open bug reports and feature requests in the [Enmeshed Issue Tracker](https://github.com/nmshd/feedback/issues) or share your feedback with the Enmeshed team via the [Enmeshed Discussions](https://github.com/nmshd/feedback/discussions). diff --git a/_docs_operate/01-connector-tutorial.md b/_docs_operate/01-connector-tutorial.md new file mode 100644 index 000000000..5d24fc82c --- /dev/null +++ b/_docs_operate/01-connector-tutorial.md @@ -0,0 +1,259 @@ +--- +title: "Connector Tutorial" +permalink: /operate/connector-tutorial +toc: true +--- + +In this tutorial we go through the basic steps necessary to establish a Relationship to another Identity and send Messages between two Identities with an existing Relationship. This will create a better understanding of these processes, which will help you on automating them for your organization. + +The following steps include small interactive pieces of the Connector's API documentation that, when executed, fire requests on a Connector we provided for testing purposes. Example: + +{% include rapidoc api_route_regex="^get /health$" title="" %} + +So if you don't have your own Connector installed, feel free to use the samples directly by unfolding them and clicking on "Try". Otherwise you can use your own Connector either with a REST client (e.g. Insomnia or Postman) or by using the RapiDoc documentation (/docs/rapidoc) hosted on your Connector. + +The payloads for the requests that are sent during this tutorial contain placeholders marked with `<...>`. You need to replace them with values before you send the request. + +## Prerequisites + +- If you want to use your own Connector for executing the examples: + - [Install the Connector](https://enmeshed.eu/operate/connector-installation) + - Make sure the [Sync Module is disabled](https://enmeshed.eu/operate/connector-configuration#sync) (because in this tutorial we will synchronize manually via the HTTP endpoint) + - Make sure the [docs are enabled](https://enmeshed.eu/operate/connector-configuration#corehttpapi) for the documentation route to work + - Get the API key that was configured during installation of the Connector (it needs to be sent in the `X-API-KEY` header of every HTTP request) +- You need **version 2** of the [Enmeshed App]({% link _docs_use/01-basics.md %}) installed on your mobile device. + +## Establishing Relationships + +In order to communicate with another Identity, a Relationship to that Identity is required. In this first part of the tutorial you will learn how to establish a Relationship between your Connector and another Identity. In this case the other Identity will be the App, but it could be another Connector as well. + +### Connector: Create an Attribute + +In order to share an Attribute via a Relationship Template, we need to create one by executing `POST /api/v2/Attributes` with the following payload: + +```json +{ + "content": { + "@type": "IdentityAttribute", + "owner": "", + "value": { + "@type": "DisplayName", + "value": "Connector Tutorial" + } + } +} +``` + +You can query the Connector's Address under the route `/api/v2/Account/IdentityInfo`. If you are using the Demo Connector of this Tutorial, the Address is `id134nJmN7E4Carb6KyRJyePVnXxVHEYQgWD`. +{: .notice--info} + +{% include rapidoc api_route_regex="^post /api/v2/Attributes$" %} + +{% include copy-notice description="Save the `id` of the Attribute that you can find in the response. You will need it in the next step." %} + +### Connector: Test your Request's Validity + +In order to make sure the Request and its items are valid you can validate it by calling the `POST /api/v2/Requests/Outgoing/Validate` route. You can define your own payload for this Request, or you can just use the one below, which contains two [RequestItemGroups]({% link _docs_operate/61-data-model.md %}#requestitemgroup): + +- one with a [ShareAttributeRequestItem]({% link _docs_operate/61-data-model.md %}#shareattributerequestitem) that contains Attributes that will be shared with the peer +- one with [ReadAttributeRequestItem]({% link _docs_operate/61-data-model.md %}#readattributerequestitem)s that query Attributes of the peer + +```json +{ + "content": { + "items": [ + { + "@type": "RequestItemGroup", + "mustBeAccepted": true, + "title": "Shared Attributes", + "items": [ + { + "@type": "ShareAttributeRequestItem", + "mustBeAccepted": true, + "attribute": { + "@type": "IdentityAttribute", + "owner": "", + "value": { + "@type": "DisplayName", + "value": "Connector Tutorial" + } + }, + "sourceAttributeId": "" + } + ] + }, + { + "@type": "RequestItemGroup", + "mustBeAccepted": true, + "title": "Requested Attributes", + "items": [ + { + "@type": "ReadAttributeRequestItem", + "mustBeAccepted": true, + "query": { + "@type": "IdentityAttributeQuery", + "valueType": "GivenName" + } + }, + { + "@type": "ReadAttributeRequestItem", + "mustBeAccepted": true, + "query": { + "@type": "IdentityAttributeQuery", + "valueType": "Surname" + } + }, + { + "@type": "ReadAttributeRequestItem", + "mustBeAccepted": false, + "query": { + "@type": "IdentityAttributeQuery", + "valueType": "EMailAddress" + } + } + ] + } + ] + } +} +``` + +{% include rapidoc api_route_regex="^post /api/v2/Requests/Outgoing/Validate$" %} + +Even though the Requests are validated during the RelationshipTemplate creation you should not skip this step as it gives you additional information in case of validation errors. +{: .notice--info} + +### Connector: Create a Relationship Template + +Start by creating a so called Relationship Template on the Connector. You can do so by calling the `POST /api/v2/RelationshipTemplates/Own` route. Use the following JSON in the request body: + +```jsonc +{ + "maxNumberOfAllocations": 1, + "expiresAt": "2023-06-01T00:00:00.000Z", + "content": { + "@type": "RelationshipTemplateContent", + "title": "Connector Demo Contact", + "onNewRelationship": { + // + } + } +} +``` + +{% include rapidoc api_route_regex="^post /api/v2/RelationshipTemplates/Own$" %} + +{% include copy-notice description="Save the `id` of the Relationship Template that you can find in the response. You will need it in the next step." %} + +### Connector: Create a QRCode for the Relationship Template + +Since we will use the Enmeshed App to send a Relationship Request to the Connector, we now have to create a QR Code one can scan with the App to retrieve the Relationship Template and send a Relationship Request to the Connector. + +For this, execute the `GET /api/v2/RelationshipTemplates/{id}` route (Accept Header: `image/png`) to create a QRCode. Use the ID of the Relationship Template from the previous step as the value for `id`. + +{% include rapidoc api_route_regex="^get /api/v2/RelationshipTemplates/{id}$" %} + +### App: Send a Relationship Request + +Open the created QR Code and start the Enmeshed App. Depending on what you already did with the App, choose one of the following paths: + +- If this is the first time you use the App: + - click on "Scan code" + - hold the camera in front of the QR code +- If you want to use a new profile: + - click on the "+ New profile" button + - click on "Scan code" + - hold the camera in front of the QR code +- If you want to use an existing profile: + - select the existing profile + - navigate to "Contacts" + - click on "Add contact" + - hold the camera in front of the QR code + +All three paths should result in a screen similar to the one below, where you can see the information that you added as content to the Relationship Template. + +!["Add contact" screen]( {{ '/assets/images/add-contact-screen.jpg' | relative_url }} ) + +Finally, fill out the required fields and click on "Add contact" to send the Relationship Request. This will create a new Relationship between the App and the Connector. This Relationship has the status `Pending` for now. + +### Connector: Accept the Relationship Request + +In order to move the Relationship into the `Active` state, you now need to accept the Relationship Request with the Connector. In order to do so, first execute the `POST /api/v2/Account/Sync` route, which will fetch all changes that occurred since the last time this endpoint was executed. + +{% include rapidoc api_route_regex="^post /api/v2/Account/Sync$" %} + +In the response you will receive the created Relationship, which contains corresponding Relationship Creation Change. + +Example: + +```json +{ + "result": { + "messages": [], + "relationships": [ + { + "id": "RELmJj25x2bZW0VXzAiQ", + ... + "status": "Pending", + "peer": "id19Sy75wjCWhQSxsbMiGLn6iSBfWvQmot5b", + "changes": [ + { + "id": "RCHUwBw7BWlROPlEjb51", + ... + "status": "Pending", + "type": "Creation" + } + ] + } + ] + } +} +``` + +{% include copy-notice description="Save the `id` of the Relationship (`REL_________________`) as well as the `id` of the first Relationship Change (`RCH_________________`) in the `changes` array and use them as input to the `PUT /api/v2/Relationships/{id}/Changes/{changeId}/Accept` route. You can leave that request body as it is." %} + +{% include rapidoc api_route_regex="^put /api/v2/Relationships/{id}/Changes/{changeId}/Accept$" %} + +Now the Relationship is in the `Active` state, so we can start to communicate with the opposite Identity, which we will do in the next part of this tutorial. In order to do so we will need the Address of that Identity. So in the response of the last request look for the `peer` property and write down its value. It should start with `id1`. + +## Sending and Receiving Messages + +After you have established a Relationship to an Identity, you can start to exchange Messages. Enmeshed defines [different types of Messages]({% link _docs_operate/61-data-model.md %}#message). For this tutorial we will focus on Messages of type [Mail]({% link _docs_operate/61-data-model.md %}#mail), which you can compare to a classic email: you can specify one or more recipients, a subject and a body, as well as add some attachments. + +### Sending a Message with a Connector + +To send a Message, all you need to do is call the `POST /api/v2/Messages` endpoint. You can use the content below, while replacing the placeholders in `recipients` and `to` with the Address you copied previously. You can further modify the `subject` and `body` properties to add some custom content. + +```json +{ + "recipients": ["id_________________________________"], + "content": { + "@type": "Mail", + "to": ["id_________________________________"], + "subject": "Welcome", + "body": "Hello. We are pleased to welcome you as our customer." + } +} +``` + +{% include rapidoc api_route_regex="^post /api/v2/Messages$" %} + +After you have sent this request, you should receive a push notification on your phone. Open the Enmeshed App, navigate to "Contacts" and select your Relationship. You should see the Message in the list. You can show details by tapping on it. + +### Receiving a Message with a Connector + +Next we are going to send a Message from the App to the Connector. Therefore, open the App, navigate to "Contacts" and select your Relationship. Next, tap on "New Message". Enter subject and body an tap on "Send". + +In order to fetch the Message, we need to call the `POST /api/v2/Account/Sync` endpoint again. + +{% include rapidoc api_route_regex="^post /api/v2/Account/Sync$" %} + +The response should contain a Message with the content you entered in the App. + +## What's next? + +Now that you have successfully established a Relationship and exchanged Messages, you can further explore the Enmeshed API. You can for example: + +- explore the [Enmeshed data model]({% link _docs_operate/61-data-model.md %}) and learn more about the objects you used during this tutorial and the objects you will encounter in the future +- learn how to send [Requests over Messages]({% link _docs_scenarios/scenario-sc58.md %}) with your established Relationship +- dive deeper into creating and sending [Requests over RelationshipTemplates]({% link _docs_scenarios/scenario-sc59.md %}) diff --git a/_docs_operate/02-connector-create-relationships.md b/_docs_operate/02-connector-create-relationships.md new file mode 100644 index 000000000..481583a2c --- /dev/null +++ b/_docs_operate/02-connector-create-relationships.md @@ -0,0 +1,96 @@ +--- +title: "Create Relationships" +permalink: /operate/create-relationships +toc: true +published: false +--- + +For creating a relationship, we differentiate between "incoming" and "outgoing" flows: + +- Incoming means, that the Connector creates a template, shares it over a separate channel and receives a relationship request, which it then can accept or reject. From an organization's perspective, this is the common flow. +- Outgoing is the other way round: The Connector (or a business user of the organization) receives a relationship template created by another party, and sends out the relationship request to the other party, which can then be accepted (or rejected). + +## Incoming Flow + +The Connector creates the relationship template, renders it for a user and eventually receives a relationship request from the user. The relationship request is then accepted or rejected by the Connector based on the given content. + +### Create Relationship Template + +In order to receive relationship requests, a relationship template needs to be created first. This is done by calling the `POST /RelationshipTemplates/Own` route. + +{% include rapidoc api_route_regex="^post /api/v2/RelationshipTemplates/Own$" title="" %} + +![Create Relationship Template Sequence Diagram]({{ '/assets/diagrams/operate/Connector_CreateTemplate.png' | relative_url }} "Create Relationship Template") + +We differentiate between two types of relationship templates: + +- Identity-specific templates which are short-living personalized templates for known identities/users, which also could incorporate personal data to fill the user's identity when scanned. This is usually the case if the template is created for an authenticated user session. It must be ensured that only the user whose personal data is stored within the template has access to the template. +- Identity-agnostic templates for unknown identities/users or scenarios where personal information should not be available in the template. These templates are usually long-living templates for new user registrations or printouts. + +Once the relationship template is created, a token needs to be created for the template, as the token is the primary way to communicate with unknown identities. The POST /Token route for a specific relationship template is used for this. + +{% include rapidoc api_route_regex="^post /api/v2/RelationshipTemplates/Own/{id}/Token$" %} + +The "Accept" header defines which output format of the token should be returned: Either a png file with the QR code or a JSON-representation of the whole token (including the truncated reference which could be encoded as a link). + +### Communicate Token Reference + +There are multiple ways how the token reference can be communicated to the user: It could be for example a string (to copy&paste), a link (to open a browser or the App), a file (opened by the App) or a QR code (manually scan from a different device). The QR code can also be rendered on printouts like flyers, business cards or letters. + +### Receive Relationship Request + +Once the user has reviewed the relationship template and created the corresponding relationship request, it is submitted over the backbone (as a cipher only the organization can decrypt) to the organization's Connector. The Connector decrypts the cipher and stores the relationship request in the database. + +The relationship request can be accessed either manually via a REST API (pull) or it can be pushed to a [configurable custom HTTP endpoint]({% link _docs_operate/11-connector-configuration.md %}). + +![Get Open Relationship Requests Sequence Diagram]({{ '/assets/diagrams/operate/Connector_GetOpenRelationshipRequests.png' | relative_url }} "Get Open Relationship Requests") + +{% include rapidoc api_route_regex="^post /api/v2/Account/Sync$" %} + +### Check data + +The organization's business system can then use the structured data coming with the Relationship Request. For example, a manual or automated check can be performed, the data could be verified over third parties, or such like. This step can take from milliseconds to days, depending on the business scenario. +But please keep in mind that the user might not like to wait that long. If there are business processes taking such a long time, it might make more sense to first accept a Relationship Request and then start the long-running process, in order to be able to communicate with the user in parallel. + +### Respond to Relationship Request + +Once the data has been processed on the business system, it is time to respond to the relationship request: you can either accept or reject it. Both responses can transfer additional data to the requestor, e.g. the created customer id, contract id or suchlike (accept) - or the rejection reason, like an invalid required attribute or an insufficient financial score. + +If the change is accepted, the connection to the requestor is automatically generated and from this point in time, both parties may communicate over a secure, bi-directional tunnel. + +![Accept Relationship Request Sequence Diagram]({{ '/assets/diagrams/operate/Connector_AcceptRelationshipRequest.png' | relative_url }} "Accept Relationship Request") + +{% include rapidoc api_route_regex="^put /api/v2/Relationships/{id}/Changes/{changeId}/Accept|put /api/v2/Relationships/{id}/Changes/{changeId}/Reject$" %} + +## Outgoing Flow + +The Connector receives a Relationship Template (or Token) from an external party and sends out the Relationship Request. + +### Get an External Relationship Template + +In order to send out own relationship request to other parties, a template must be fetched from the external party. The template is created by the external party and then usually shared by a truncated reference over a link or QR code. This reference can be used to retrieve the actual template, for example with requested attribute. + +![Get Relationship Template Sequence Diagram]({{ '/assets/diagrams/operate/Connector_GetTemplate.png' | relative_url }} "Get Relationship Template") + +{% include rapidoc api_route_regex="^post /api/v2/RelationshipTemplates/Peer$" %} + +### Create a Relationship + +Once the external relationship template has been successfully read in, and the terms/requested content be found acceptable, one can answer the template with a relationship request. This is done by calling the POST /Relationships route. +This request contains - equivalent to incoming relationship creation changes - any information the other party requested, for example legal and contact information. Thus, one should parse the given relationship template correctly and send the required attributes within this request. Otherwise the other party might reject the relationship creation change, as requested attributes are not existing. + +![Create Relationship Request Sequence Diagram]({{ '/assets/diagrams/operate/Connector_CreateRelationshipRequest.png' | relative_url }} "Create Relationship Request") + +{% include rapidoc api_route_regex="^post /api/v2/Relationships$" %} + +### Check outgoing Relationship Changes + +In order to create relationships out of accepted relationship requests, the Connector needs to track the status of these requests. This can be done manually with the POST /Account/Sync route. The return values then contain possible changed relationships. + +{% include rapidoc api_route_regex="^post /api/v2/Account/Sync$" %} + +### Revoke outgoing change + +An existing outgoing change request can be revoked, as long as the change was not accepted or rejected yet. + +{% include rapidoc api_route_regex="^put /api/v2/Relationships/{id}/Changes/{changeId}/Revoke$" %} diff --git a/_docs_operate/03-connector-modules.md b/_docs_operate/03-connector-modules.md new file mode 100644 index 000000000..c331ac529 --- /dev/null +++ b/_docs_operate/03-connector-modules.md @@ -0,0 +1,45 @@ +--- +title: "Connector Modules" +permalink: /operate/connector-modules +toc: true +--- + +Since the Connector is based on the Runtime, [all Modules of the Runtime]({% link _docs_explore/61-runtime.md %}#runtime-modules) are also available in the Connector. + +Additionally, the Connector defines its own Modules that only make sense in the context of a Connector and are therefore not defined in the Runtime. + +Read more about the Module configuration on the icon in each title. + +### AMQP Publisher {#amqppublisher} + +This Module proxies all events in the internal event bus of the Connector to an exchange in a configurable AMQP server. + +Compared to [webhooks](#webhooksv2), this gives you the full feature set of a message broker. There are multiple scenarios where this Module outweighs the Webhooks Module. For example: + +- You need persistence for the triggered events. +- You want to operate Enmeshed into an already existing message broker. + +### Auto Accept Relationship Creation Changes {#autoacceptrelationshipcreationchanges} + +It is not recommended to use this Module for production scenarios. +{: .notice--danger} + +The `autoAcceptRelationshipCreationChanges` Module listens to the events about incoming Relationship Change Requests. It immediately accepts the Requests, using the configured `responseContent`. + +Keep in mind that you need to synchronize the state of the Connector with the Backbone in order to receive incoming Relationship Requests. The `sync` Module automates this, but you can also do this manually by calling the `/api/v2/Account/Sync` route. + +### Core HTTP API {#corehttpapi} + +This Module contains the HTTP API with all Enmeshed base functionalities. + +### Sync {#sync} + +The `sync` Module regularly fetches changes from the Backbone (e.g. new Messages / new incoming Relationship Requests). This process automatically triggers the events used by other Modules like the `webhooks` Module. + +### WebhooksV2 {#webhooksv2} + +With the REST API, pull mechanisms are supported. However, as there are many bidirectional scenarios within Enmeshed, a push mechanism is favorable: the Connector is synchronizing its state with the Backbone and notifies the organization's backend services about changes. + +For this, the Connector supports the configuration of webhooks which are called every time a specific [Connector Event]({% link _docs_operate/32-connector-events.md %}) is triggered (e.g. a new Message has been received => `transport.messageReceived`). + +Keep in mind that you need to synchronize the state of the Connector with the Backbone in order to receive events. The `sync` Module automates this, but you can also do this manually by calling the `/api/v2/Account/Sync` route. diff --git a/_docs_operate/10-connector-installation.md b/_docs_operate/10-connector-installation.md new file mode 100644 index 000000000..567883920 --- /dev/null +++ b/_docs_operate/10-connector-installation.md @@ -0,0 +1,110 @@ +--- +title: "Connector Installation" +permalink: /operate/connector-installation +toc: true +--- + +## Prerequisites + +### MongoDB + +The Connector requires a MongoDB database as its data storage. MongoDB is a document-oriented database. For compatibility and security reasons, the most up-to-date version of MongoDB should be used. +For more information, please see . + +### Container Runtime + +The Connector requires a Container Runtime like Docker or Kubernetes: Docker is a virtualization technology which introduces highly portable software containers. The Connector is shipped and updated as such a Docker container - the Docker Runtime is the runtime environment which can execute the Docker containers. For compatibility and security reasons, the most up-to-date version of the Docker Runtime should be used. +For more information, please see . + +Visit [the official docker docs](https://docs.docker.com/get-docker/) for installation guides. + +### Hardware Requirements + +No special hardware requirements have been identified so far and as always, hardware requirements strongly correlate with the envisoned usage scenario. + +A good starting point for hosting the Docker image of the Connector would be the following: + +- 1 CPU +- 512MB RAM +- 1GB HDD + +Depending on the usage scenario, higher hardware requirements might be necessary. + +### Internet Connectivity + +A reliable and fast internet connection is mandatory for running the Connector. However, the Connector is only communicating with the Backbone so the corresponding domain (e.g. `https://prod.enmeshed.eu`) can be whitelisted and the associated certificate can be additionally pinned. + +### List docker image tags + +Read more about listing available docker image tags [here]({% link _docs_explore/52-connector.md %}#connector-docker-image). + +### Familiarize with our policies + +Before setting up Enmeshed, you should familiarize yourself with our [Security Considerations]({% link _docs_operate/42-connector-security.md %}) and [Privacy Considerations]({% link _docs_operate/43-connector-privacy.md %}). + +## Installation with Docker + +Make sure that you have installed docker compose. Visit [the official installation guide](https://docs.docker.com/compose/install/) for more information. + +**ATTENTION:** The Docker compose files we provide in this tutorial are not recommended to use in production scenarios. Please read [Use Compose in production](https://docs.docker.com/compose/production/) for more information on how to write a production-grade compose file and our [Security Considerations]({% link _docs_operate/42-connector-security.md %}#docker-compose-file-security-considerations). +{: .notice--warning} + +### Option 1: docker compose including MongoDB + +Go through the following steps to start the Connector: + +1. place the file [examples/docker-compose-with-mongodb.yml](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_operate/examples/docker-compose-with-mongodb.yml) as `docker-compose.yml` in a folder of your choice +2. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_operate/11-connector-configuration.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_operate/examples/example.config.json). If you used the yml-file from the first step, the connection string looks as follows: + ```text + mongodb://:@mongodb:27017 + ``` +3. replace all `` in the compose file with the corresponding values +4. (optional) follow the steps under [log file mounting](#log-file-mounting) if you want to persist and access the log files on the host system +5. execute `docker compose up -d` in the shell + +### Option 2: docker compose with existing MongoDB + +Visit the official [MongoDB website](https://www.mongodb.com/) for installation without docker or cloud usage or the [docker hub page](https://hub.docker.com/_/mongo) for information about the installation with docker. + +Go through the following steps to start the Connector: + +1. make your existing MongoDB available for the connector +2. place the file [examples/docker-compose-with-existing-mongodb.yml](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_operate/examples/docker-compose-with-existing-mongodb.yml) as `docker-compose.yml` in a folder of your choice +3. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_operate/11-connector-configuration.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_operate/examples/example.config.json) +4. replace all `` in the compose file with the corresponding values +5. (optional) follow the steps under [log file mounting](#log-file-mounting) if you want to persist and access the log files on the host system +6. execute `docker compose up -d` in the shell + +### Option 3: docker compose with FerretDB + +Go through the following steps to start the Connector: + +1. place the file [examples/docker-compose-with-ferretdb.yml](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_operate/examples/docker-compose-with-ferretdb.yml) as `docker-compose.yml` in a folder of your choice +2. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_operate/11-connector-configuration.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_operate/examples/example.config.json). If you used the yml-file from the first step, the connection string looks as follows: `mongodb://ferretdb:27017` +3. replace all `` in the compose file with the corresponding values +4. (optional) follow the steps under [log file mounting](#log-file-mounting) if you want to persist and access the log files on the host system +5. execute `docker compose up -d` in the shell + +## Installation with Kubernetes and Helm + +Make sure that you have a running Kubernetes cluster and that you have installed [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) and [Helm](https://helm.sh/docs/intro/install/). + +You have to provide your own MongoDB instance. Visit the [MongoDB website](https://www.mongodb.com/) for installation without docker or cloud usage or the [docker hub page](https://hub.docker.com/_/mongo) for information about the installation with docker or install it [in kubernetes via Helm](https://artifacthub.io/packages/helm/bitnami/mongodb). + +For the installation and configuration head over to the dedicated [Connector Helm chart site]({% link _docs_operate/14-connector-helm-chart.md %}). + +## Validate the Connector installation + +You can validate the Connector installation by checking its health route. Simply access `/health` in your browser or using curl. + +If the swagger documentation is enabled you can also access it under `/docs` + +## Log file mounting + +1. Uncomment the volume mapping in the created `docker-compose.yml` file +2. Create a folder where the log files shall be placed. Make sure that the process in the container has write access to the folder e.g. by executing `chmod 777 ` on your created folder. +3. replace `` with the path to your created folder + +## Troubleshooting + +If you encounter any problems while setting up the Connector, head over to the [Troubleshooting]({% link _docs_operate/12-connector-setup-troubleshooting.md %}) site. diff --git a/_docs_operate/11-connector-configuration.md b/_docs_operate/11-connector-configuration.md new file mode 100644 index 000000000..ae8b82677 --- /dev/null +++ b/_docs_operate/11-connector-configuration.md @@ -0,0 +1,417 @@ +--- +title: "Connector Configuration" +permalink: /operate/connector-configuration +toc: true +--- + +## Mounting a config file + +1. Create a config file in JSON format in a folder of your choice. +2. Fill the config file with your desired configuration (it's sufficient to add values you want to change; the Connector will merge your config file with the default configuration) Example: + + ```jsonc + { + "infrastructure": { + "httpServer": { + "enabled": true, + "apiKey": "an-api-key" + } + } + } + ``` + +3. Mount the created config file into the Docker container (e.g. to `/config.json`). See the official [documentation](https://docs.docker.com/storage/bind-mounts/) for more information on how to mount files into a Docker container. This is also possible using [docker compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#volumes). +4. Set the environment variable `CUSTOM_CONFIG_LOCATION` to the path you mounted your config file to (e.g. `CUSTOM_CONFIG_LOCATION="/config.json"`). + +There is also an [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_operate/examples/example.config.json) available. It sets some default values, please only use the fields you require + +## Environment variables + +The configuration can also be done using environment variables. This feature is included in the Connector since version `2.2.1`. + +### Parsing rules + +1. Nested fields can be represented using a colon (`:`) as a separator. + + The `:` separator doesn't work with environment variable hierarchical keys on all platforms. The double underscore (`__`) is supported on all platforms (e.g. bash does not support the `:` separator but it supports `__` ). The Connector will therefore convert `__` to `:` so you can use it on that systems. + {: .notice--warning} + +2. The parameter casing must be the same as the config file casing. +3. The strings "true" and "false" are converted to the respective boolean values. +4. Number strings (`"1"` / `"1.1"`) will be converted to the respective number types. +5. Complex structures (arrays, objects) are not supported. (=> `modules:aModule:aKey='{"a": "x", "b": "y"}'` or `modules:aModule:aKey='["a", "b"]'` is not valid) + +### Example + +You want to configure the following values: + +```jsonc +{ + "infrastructure": { + "httpServer": { + "enabled": true, + "port": 8080, + "apiKey": "an-api-key" + } + } +} +``` + +- The first value can be configured using the variable `infrastructure:httpServer:enabled="true"`. Note that the value is represented as a string in the environment variable and the Connector will rewrite it to its boolean representation. +- The second value can be configured using the variable `infrastructure:httpServer:port="8080"`. Note that the value is represented as a string in the environment variable and the Connector will rewrite it to its number representation. +- The third value can be configured using the variable `infrastructure:httpServer:apiKey="an-api-key"`. + +## Configuration options + +The Connector provides the following configuration parameters: + +```jsonc +{ + "debug": false, + "transportLibrary": { + "baseUrl": "https://prod.enmeshed.eu", + "platformClientId": "CLIENT_ID", + "platformClientSecret": "CLIENT_SECRET" + }, + "database": { + "connectionString": "mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]", + "dbName": "a-db-name" + }, + "infrastructure": { ... }, + "modules": { ... } +} +``` + +You can validate the config using our [schema file](https://raw.githubusercontent.com/nmshd/cns-connector/main/config.schema.json). This is possible for example with [VSCode](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings) or online tools like [jsonschemavalidator.net](https://www.jsonschemavalidator.net). + +### debug `availbable since version 3.3.0` {#debug} + +⚠️ Do not turn on debug mode in production environments. +{: .notice--danger} + +The debug flag configures if the Connector is set to **production** or **debug** mode. Defaults to `false`. Can also be configured using the environment variable `DEBUG`. + +### transportLibrary + +- **baseUrl** `default: "https://prod.enmeshed.eu"` + + The base url is used to communicate with the Enmeshed platform. It can be changed to use a custom Enmeshed Backbone. + +- **platformClientId** `required` + + The client id is required to communicate with the Enmeshed platform. It can be acquired from the [Enmeshed Support]({% link _docs_operate/00-basics.md %}#support). + +- **platformClientSecret** `required` + + The client secret is required to communicate with the Enmeshed platform. It can be acquired from the [Enmeshed Support]({% link _docs_operate/00-basics.md %}#support). + +### database + +- **connectionString** `required` + + At this point the connection to the database can be configured. The connection string must follow the MongoDB [Connection String URI Format](https://docs.mongodb.com/manual/reference/connection-string/). + +- **dbName** `default: "default"` + + The `dbName` string is used as the name of the MongoDB database, prefixed with `acc-`. You can use any name you like, but keep in mind that changing it later will NOT rename the database. Instead a new database will be created, together with a new Enmeshed identity. Even though the old database will still exist, the Connector will not be able to access the data until you change the `dbName` back to its original value. + + If you would like to use multiple Connectors with distinct identities (one identity per Connector) running on the same database, you have to specify a unique `dbName` for each of them. + + **Note:** If you are using the Connector in combintation with a FerretDB, you have to pay attention to the database name restrictions specified in the [FerretDB documentation](https://docs.ferretdb.io/diff/). + {: .notice--warning} + +### infrastructure + +Each infrastructure can be enabled or disabled by passing true / false to `enabled`. + +#### httpServer + +The HTTP server is the base for the `coreHttpApi` Module. It opens an express HTTP server where Modules can register endpoints. + +**Sample Configuration:** + +```jsonc +{ + // ... + + "infrastructure": { + "httpServer": { + "enabled": true, + "cors": { + "origin": false + }, + "apiKey": "an-api-key" + } + } +} +``` + +- **enabled** `default: true` + + Enable or disable the HTTP server. + +- **cors** `default: { "origin": false }` + + configure the CORS middleware. Valid options can be found [here](https://github.com/expressjs/cors#configuration-options). + +- **apiKey** `required` + + Define the API-Key the Connector should use to authenticate requests. + + The API-Key can be chosen arbitrarily and has to be sent with every request in the `X-API-KEY` HTTP-Header. + + There are no limitations regarding the allowed characters. We recommend using an API-Key that is at least 20 characters long. + + The API-Key protects your Connector from unauthorized access and should therefore be kept secret. + +- **helmetOptions** `default: depending on the connector mode` + + Configure the [helmet](https://helmetjs.github.io/) middleware. + + Defaults to `{}` in `production` mode. In `debug` mode the following options are used: + + ```json + { + "contentSecurityPolicy": { + "directives": { + "defaultSrc": [], + "scriptSrc": ["'self'"], + "styleSrc": ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"], + "imgSrc": ["'self'", "https://enmeshed.eu", "data:"], + "connectSrc": ["'self'"], + "upgradeInsecureRequests": null + } + } + } + ``` + +### modules + +Every Module can be enabled or disabled by passing true / false to `enabled`. Read more about the Module by clicking on the icon in each title. + +#### amqpPublisher {#amqppublisher} + +**Sample Configuration:** + +```jsonc +{ + // ... + + "modules": { + "amqpPublisher": { + "enabled": false, + "url": "amqp://example.com:5672", + "exchange": "myExchange" + } + } +} +``` + +- **enabled** `default: false` + + Enable or disable the AMQP Publisher Module. + +- **url** `required` + + The URL of the AMQP server. + +- **exchange** `default: ""` + + The name of the AMQP exchange to publish to. + +#### autoAcceptRelationshipCreationChanges {#autoacceptrelationshipcreationchanges} + +It is not recommended to use this Module for production scenarios. +{: .notice--danger} + +**Sample Configuration:** + +```jsonc +{ + // ... + + "modules": { + "autoAcceptRelationshipCreationChanges": { + "enabled": false, + "responseContent": {} + } + } +} +``` + +- **enabled** `default: false` + + Enable or disable the autoAcceptRelationshipCreationChanges Module. + +- **responseContent** `default: {}` + + The content that is used to accept the incoming Relationship Request. + +#### coreHttpApi {#corehttpapi} + +**Sample Configuration:** + +```jsonc +{ + // ... + + "modules": { + "coreHttpApi": { + "enabled": true, + "docs": { + "enabled": false, + "rapidoc": { + "persistAuth": false + } + } + } + } +} +``` + +- **enabled** `default: true` + + Enable or disable the coreHttpApi Module. + +- **docs:enabled** `default: false` + + It is not possible to enable the docs in [production mode](#debug). + {: .notice--info} + + Enable / disable the `/docs/json` and `/docs/yaml` routes and the rendered swagger / rapidoc documentations. + +- **docs:rapidoc:persistAuth** `default: false` + + Authentication persistence can be a security risk. Use it with caution. + {: .notice--danger} + + If set to `true` rapidoc persists the API Key in the local storage of the browser. + +#### sync {#sync} + +**Sample Configuration:** + +```jsonc +{ + // ... + + "modules": { + "sync": { + "enabled": false, + "interval": 60 + } + } +} +``` + +- **enabled** `default: false` + + Enable or disable the sync Module. + +- **interval** `default: 60` + + The interval in seconds at which the sync Module will fetch changes from the Backbone. + +#### webhooksV2 {#webhooksv2} + +**Sample Configuration:** + +```jsonc +{ + // ... + + "modules": { + "webhooksV2": { + "enabled": false, + "targets": {}, + "webhooks": [] + } + } +} +``` + +- **enabled** `default: false` + + Enable or disable the webhooksV2 Module. + +- **targets** `default: {}` + + Here you can predefine targets so you can reuse them for multiple webhooks. + + A target consists of a URL as well as optional arbitrary headers, which the Connector should send as part of the request. Optionally, your URL can contain the placeholder {% raw %}`{{trigger}}`{% endraw %}, which at runtime will be replaced with the event name that triggered the webhook (e.g. transport.messageReceived). This way, you can reuse the same target for multiple webhooks and still have different URLs for different events. See the code below for an example. + + The server under the URL must respond to the request with a status code between 200 and 299. Otherwise the Connector will log a warning. + +
+ + **Example** + + ```jsonc + { + // a target with headers + "target1": { + "url": "https://example.com/enmeshed/webhook2", + + // the following headers will be sent as part of the webhook + "headers": { + "a-header": "a-value", + "another-header": "another-value" + } + }, + + // a target without headers + "target2": { + "url": "https://example.com/enmeshed/webhook" + }, + + // a target with the {% raw %}{{trigger}}{% endraw %} placeholder as part of the URL + "target3": { + "url": "https://example.com/enmeshed/webhook/{{trigger}}" + } + } + ``` + +- **webhooks** `default: []` + + The webhooks that will be called. A webhook consists of one or more [Connector Events]({% link _docs_operate/32-connector-events.md %}) on which the webhook should be triggered, as well as a target to which the request should be sent. The target either is an inline definition of target as described above, or a name of a target defined in the `targets` object. + +
+ + **Example** + + ```jsonc + [ + { + "triggers": ["transport.messageReceived"], + + // inline declaration of a target + "target": { + // see the targets section for a description of how to configure a target + } + }, + { + "triggers": ["transport.messageReceived"], + + // a reference to a target defined in the 'targets' object + "target": "target1" + } + ] + ``` + +##### Payload + +```jsonc +{ + // the event name (e.g. transport.messageReceived) that triggered the webhook + "trigger": "transport.messageReceived", + + // the data of the event + "data": {} +} +``` + +You can find type definitions of the event data in the [Connector Events]({% link _docs_operate/32-connector-events.md %}) section. + +## Troubleshooting + +If you encounter any problems while configuring the Connector, head over to the [Troubleshooting]({% link _docs_operate/12-connector-setup-troubleshooting.md %}) site. diff --git a/_docs_operate/12-connector-setup-troubleshooting.md b/_docs_operate/12-connector-setup-troubleshooting.md new file mode 100644 index 000000000..176774491 --- /dev/null +++ b/_docs_operate/12-connector-setup-troubleshooting.md @@ -0,0 +1,49 @@ +--- +title: "Troubleshooting" +permalink: /operate/connector-setup-troubleshooting +toc: true +--- + +## Troubleshooting Guide + +For any issues with the Connector make sure you checked the logs and the `/Monitoring/*` routes. The `/Monitoring/Support` route provides a lot of information about the current state of the Connector and you can for example detect misconfigurations. + +{% include rapidoc api_route_regex="/Monitoring/Support$" title="" %} + +## Common Errors + +### Config file mounting (`EISDIR` | `invalid mode: RO`) + +**Symptoms** + +One of the following errors are logged during the startup of the Connector: + +- `Error parsing your configuration file: [/config.json]: EISDIR: illegal operation on a directory, read` +- `ERROR: for connector Cannot create container for service connector: invalid mode: RO` + +**How to fix?** + +Given the following filesystem structure: + +```text +home/ +└── connector/ + ├── config.json + └── docker-compose.yml +``` + +If you mount `/home/connector:/config.json:ro`, the created `/config.json` in the container will be a directory. To fix this the mount has to be `/home/connector/config.json:/config.json:ro` or `./config.json:/config.json:ro` (docker compose translates relative links to absolute links). + +### Database Authorization Error + +**Symptoms** + +During the startup of the Connector, the following error is logged: + +```text +[ERROR] ConnectorRuntime - Could not connect to the configured database. Try to check the connection string and the database status. Root error: MongoServerError: Authentication failed. +``` + +**How to fix?** + +This error can show up when you misuse the environment variables `MONGO_INITDB_ROOT_USERNAME` and/or `MONGO_INITDB_ROOT_PASSWORD` of the MongoDB Docker image. Even though their name is self-explanatory, you can easily read over the "INITDB" part in them. This means that the username and password you specify here are only used to **initially** create a database user. When you change them and then restart the container, **the root username is not changed**. If you want to change the root user's name or password, look into the MongoDB documentation. diff --git a/_docs_operate/13-connector-error-codes.md b/_docs_operate/13-connector-error-codes.md new file mode 100644 index 000000000..cab50b54f --- /dev/null +++ b/_docs_operate/13-connector-error-codes.md @@ -0,0 +1,76 @@ +--- +title: ErrorCodes +permalink: /operate/error-codes +--- + +Please find a list of Enmeshed error codes below. Most often the errors occur on invalid input or actions. If you happen to find unexpected errors while using Enmeshed or cannot deduce the reason for your error, please report it in the [Enmeshed Issue Tracker](https://github.com/nmshd/feedback/issues). + +| ErrorCode | Description | +| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| {% include anchor a="error.connector.http.methodNotAllowed" %} | This method is not supported for the requested resource. | +| {% include anchor a="error.connector.http.notAcceptable" %} | The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. | +| {% include anchor a="error.connector.http.routeDoesNotExist" %} | The requested route does not exist. | +| {% include anchor a="error.connector.unauthorized" %} | Unauthorized. | +| {% include anchor a="error.connector.validation.invalidJsonInPayload" %} | The given payload is not a valid json object. | +| {% include anchor a="error.consumption.attributes.cannotSucceedAttributesWithAParent" %} | The Attribute you want to succeed has a parent. You cannot succeed Attributes with a parent. Instead, succeed the parent, which will implicitly succeed all its children. For example, if you want to change a HouseNumber, you should succeed the Address it is part of. | +| {% include anchor a="error.consumption.requests.decide.validation.invalidNumberOfItems" %} | The Request and the Response item count is different. | +| {% include anchor a="error.consumption.requests.decide.validation.itemAcceptedButParentNotAccepted" %} | You accepted an item of a Request or RequestItemGroup, but you rejected the parent. If you accept a RequestItem, you need to accept all parents up to the root. | +| {% include anchor a="error.consumption.requests.decide.validation.mustBeAcceptedItemNotAccepted" %} | The Request was accepted but an item that was flagged as 'mustBeAccepted' was not accepted. | +| {% include anchor a="error.consumption.requests.decide.validation.requestItemAnsweredAsRequestItemGroup" %} | You answered a RequestItem as a RequestItemGroup. | +| {% include anchor a="error.consumption.requests.decide.validation.requestItemGroupAnsweredAsRequestItem" %} | You answered a RequestItemGroup as a RequestItem. | +| {% include anchor a="error.consumption.requests.invalidRequestItem" %} | The given RequestItem is invalid. | +| {% include anchor a="error.consumption.requests.servalErrorDuringRequestItemProcessing" %} | A serialization / validation error occurred during the RequestItem processing. Check the type definitions of your used types. | +| {% include anchor a="error.consumption.requests.unexpectedErrorDuringRequestItemProcessing" %} | An unknown error occurred during the RequestItem processing. | +| {% include anchor a="error.runtime.alreadyInitialized" %} | The runtime is already initialized. The init method can only be executed once. | +| {% include anchor a="error.runtime.alreadyStarted" %} | The runtime is already started. You should stop it first for a restart. | +| {% include anchor a="error.runtime.cacheEmpty" %} | The cache of the requested entity is empty. | +| {% include anchor a="error.runtime.challenges.invalidChallenge" %} | The challengeString is invalid. | +| {% include anchor a="error.runtime.challenges.invalidSignature" %} | The signature is invalid. | +| {% include anchor a="error.runtime.files.invalidReference" %} | The given reference is not valid. The reference for a file must start with 'VE9L' or 'RklM'. | +| {% include anchor a="error.runtime.invalidTokenContent" %} | The given token has an invalid content for this route. | +| {% include anchor a="error.runtime.messages.fileNotFoundInMessage" %} | The requested file was not found in the given message. | +| {% include anchor a="error.runtime.notInitialized" %} | The runtime is not initialized. You must run init before you can start or stop the runtime. | +| {% include anchor a="error.runtime.notStarted" %} | The runtime is not started. You can only stop the runtime if you executed start before. | +| {% include anchor a="error.runtime.notSupported" %} | The requested feature is not supported. | +| {% include anchor a="error.runtime.recordNotFound" %} | The requested Record was not found. Make sure the ID exists and the record is not expired. | +| {% include anchor a="error.runtime.relationshipTemplates.cannotCreateQRCodeForPeerTemplate" %} | You cannot create a QRCode for a peer template. | +| {% include anchor a="error.runtime.relationshipTemplates.cannotCreateTokenForPeerTemplate" %} | You cannot create a token for a peer template. | +| {% include anchor a="error.runtime.relationshipTemplates.invalidReference" %} | The given reference is not valid. The reference for a relationship template must start with 'VE9L' or 'VE9L'. | +| {% include anchor a="error.runtime.requestDeserialization" %} | There was an error during the request deserialization. | +| {% include anchor a="error.runtime.servalError" %} | A serialization / validation error occurred. | +| {% include anchor a="error.runtime.startup.noActiveAccount" %} | No AccountController could be found. You might have to login first. | +| {% include anchor a="error.runtime.startup.noActiveConsumptionController" %} | No ConsumptionController could be found. You might have to login first. | +| {% include anchor a="error.runtime.startup.noActiveExpander" %} | No DataViewExpander could be found. You might have to login first. | +| {% include anchor a="error.runtime.unknown" %} | An unknown error occurred. Check the error message or the stack trace to learn more. | +| {% include anchor a="error.runtime.unknownType" %} | The given '@type' could not be found during the deserialization. | +| {% include anchor a="error.runtime.validation.invalidPayload" %} | The given combination of properties in the payload is not supported. | +| {% include anchor a="error.runtime.validation.invalidPropertyValue" %} | A property of the given payload is invalid. | +| {% include anchor a="error.transport.challenges.challengeTypeRequiresRelationship" %} | The challenge type 'Relationship' requires a relationship for the challenge creation. | +| {% include anchor a="error.transport.datawallet.currentBiggerThanTarget" %} | The current datawallet version is bigger than the target version. | +| {% include anchor a="error.transport.datawallet.encryptedPayloadIsNoCipher" %} | The given encrypted payload is no cipher. | +| {% include anchor a="error.transport.datawallet.insufficientSupportedDatawalletVersion" %} | The current SupportedDatawalletVersion is too low to perform the requested operation. | +| {% include anchor a="error.transport.datawallet.unsupportedModification" %} | A collection was recieved in a CacheChanged datawallet modification but is not supported in the current version of the library. | +| {% include anchor a="error.transport.devices.alreadyOnboarded" %} | The device that you try to create an onboarding code for has already been onboarded. | +| {% include anchor a="error.transport.files.cipherMismatch" %} | The actual hash of the cipher does not match the given cipherHash. Something went wrong while storing/transmitting the file. | +| {% include anchor a="error.transport.files.fileContentUndefined" %} | The given files content is undefined. | +| {% include anchor a="error.transport.files.invalidMetadata" %} | The metadata of the file is invalid. | +| {% include anchor a="error.transport.files.invalidTruncatedReference" %} | The given truncated reference is invalid. | +| {% include anchor a="error.transport.files.maxFileSizeExceeded" %} | The given file content size exceeds the max file size the backbone accepts. | +| {% include anchor a="error.transport.files.plaintextHashMismatch" %} | The actual hash of the plaintext does not match the given plaintextHash. Something went wrong while encrypting/decrypting the file. | +| {% include anchor a="error.transport.general.baseUrlNotSet" %} | The baseUrl was not set. | +| {% include anchor a="error.transport.general.platformClientIdNotSet" %} | The platform clientId was not set. | +| {% include anchor a="error.transport.general.platformClientInvalid" %} | The combination of platform clientId and clientSecret is invalid. | +| {% include anchor a="error.transport.general.platformClientSecretNotSet" %} | The platform clientSecret was not set. | +| {% include anchor a="error.transport.identity.realmLength" %} | The given realm is not 3 characters long. | +| {% include anchor a="error.transport.messages.noMatchingRelationship" %} | A Relationship with the given address does not exist. | +| {% include anchor a="error.transport.messages.ownAddressNotInList" %} | The recipients list of a message didn't contain an entry for the own address. This message should not have been received. | +| {% include anchor a="error.transport.messages.plaintextMismatch" %} | The own address was not named as a recipient within the signed MessagePlaintext. For example this can be caused by a replay attack. | +| {% include anchor a="error.transport.messages.signatureListMismatch" %} | The signature list didn't contain an entry for a given address. | +| {% include anchor a="error.transport.messages.signatureNotValid" %} | The digital signature on a message for a peer key is invalid. An impersonination attack might be the cause of this. | +| {% include anchor a="error.transport.notSupported" %} | The requested method is not yet supported. | +| {% include anchor a="error.transport.recordNotFound" %} | The requested record was not found. | +| {% include anchor a="error.transport.relationships.wrongChangeStatus" %} | The relationship change has the wrong status to run the requested operation. | +| {% include anchor a="error.transport.secrets.secretNotFound" %} | No secret was found for a specific type. | +| {% include anchor a="error.transport.secrets.wrongBaseKeyType" %} | The given secret type is not supported! | +| {% include anchor a="error.transport.signatureNotValid" %} | A signature is invalid. | +| {% include anchor a="error.transport.tokens.invalidTokenContent" %} | The given token content is invalid. | diff --git a/_docs_operate/14-connector-helm-chart.md b/_docs_operate/14-connector-helm-chart.md new file mode 100644 index 000000000..083961fba --- /dev/null +++ b/_docs_operate/14-connector-helm-chart.md @@ -0,0 +1,133 @@ +--- +title: Helm Chart +permalink: /operate/helm-chart +--- + +## Versions + +The available Helm chart versions can be found [here](https://github.com/nmshd/cns-connector/pkgs/container/connector-helm-chart/versions). + +We provide a new Helm chart version for each new Connector release and each Helm chart will deploy the Connector in the chart's version. (Helm chart version `3.2.1` deploys Connector version `3.2.1`) +You can override the Connector version by setting the `image.tag` value in the Helm chart. + +## Configuration + +The Helm chart can be configured using a [yaml file or the command line](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing). The following table lists the configurable parameters of the Helm chart and their default values. + +You can also query the available options using the command line: `helm show values oci://ghcr.io/nmshd/connector-helm-chart --version ` + +| Parameter | Description | Default | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | +| `image.pullPolicy` | The image's [PullPolicy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy) | `"IfNotPresent"` | +| `image.tag` | The image's tag. [Available tags](https://github.com/nmshd/cns-connector/pkgs/container/connector/versions) | The version of the Helm chart. | +| `config` | The configuration of the Connector in yaml or json format. [Configuration options](https://enmeshed.eu/operate/connector-configuration) | `{}` | +| | | | +| `pod.securityContext` | [SecurityContext](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context) for the pod. | `{}` | +| `pod.nodeSelector` | [NodeSelector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for the pod. | `{}` | +| `pod.tolerations` | [Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for the pod. | `[]` | +| `pod.affinity` | [Affinity](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#NodeAffinity) for the pod. | `{}` | +| | | | +| `pod.connector.environment` | A list of [environment variables](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#environment-variables) for the Connector container. Can be used for configuring secrets. | `[]` | +| `pod.connector.securityContext` | [SecurityContext](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context-1) for the Connector container. | `{}` | +| `pod.connector.resources` | [Resources](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#resources) for the Connector container. | `{}` | +| `pod.connector.containerPort` | The port the Connector is listening on. Must be the same as `infrastructure.httpServer.port` in the `config`. | `80` | +| | | | +| `pod.ferretdb.enabled` | Enables / disables the FerretDB sidecar. | false | +| `pod.ferretdb.image` | The image used to deploy the FerretDB sidecar. Can be `ferretdb` `ferretdb-dev` or `all-in-one` | `"ferretdb"` | +| `pod.ferretdb.tag` | The tag used to deploy the FerretDB sidecar. | `"latest"` | +| `pod.ferretdb.environment` | A list of [environment variables](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#environment-variables) for the FerretDB container. Can be used for configuring secrets. | `[]` | +| `pod.ferretdb.securityContext` | [SecurityContext](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context-1) for the FerretDB container. | `{}` | +| `pod.ferretdb.resources` | [Resources](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#resources) for the FerretDB container. | `{}` | +| | | | +| `service.type` | The [ServiceType](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) of the service. | `"ClusterIP"` | +| `service.port` | The port of the service. | `80` | + +### Example Configuration + +The following example shows how to configure the Helm chart. + +```yaml +config: + debug: true + modules: + coreHttpApi: + docs: + enabled: true + +pod: + connector: + environment: + - name: database__connectionString + valueFrom: + secretKeyRef: + name: db-connection-string + key: VALUE + + - name: transportLibrary__platformClientId + value: test + - name: transportLibrary__platformClientSecret + valueFrom: + secretKeyRef: + name: platform-client-secret + key: VALUE + + - name: infrastructure__httpServer__apiKey + valueFrom: + secretKeyRef: + name: api-key + key: VALUE +``` + +If you prefer json over yaml for the `config` section the following example is equivalent to the yaml example above. + +```yaml +config: { "modules": { "coreHttpApi": { "docs": { "enabled": false } } } } +# ... +``` + +## Installation + +Create a file named `values.yaml` with the desired configuration and run the following command to install the Helm chart. + +```bash +helm install oci://ghcr.io/nmshd/connector-helm-chart --version -f values.yaml +``` + +### Installation with FerretDB `all-in-one` + +The Helm chart can be configured to deploy a FerretDB `all-in-one` instance as a sidecar. This image does not provide persistence, therefore this is useful e.g. for testing purposes or for a quick start. + +```yaml +config: + debug: true + modules: + coreHttpApi: + docs: + enabled: true + database: + connectionString: "mongodb://localhost:27017" + +pod: + connector: + environment: + - name: transportLibrary__platformClientId + alueFrom: + secretKeyRef: + name: platform-client-id + key: VALUE + - name: transportLibrary__platformClientSecret + valueFrom: + secretKeyRef: + name: platform-client-secret + key: VALUE + + - name: infrastructure__httpServer__apiKey + valueFrom: + secretKeyRef: + name: api-key + key: VALUE + + ferretdb: + enabled: true + image: all-in-one +``` diff --git a/_docs_operate/20-connector-api.md b/_docs_operate/20-connector-api.md new file mode 100644 index 000000000..9c5977a96 --- /dev/null +++ b/_docs_operate/20-connector-api.md @@ -0,0 +1,29 @@ +--- +title: "Connector API" +permalink: /operate/connector-api +--- + +The primary integration capability of the Connector is the REST API. In order to use it, you should have received an API-Key for the respective Connector. An API-Key so far has all authorizations for accessing the API. + +## Interactive Documentation + +You can find the REST API documentation hosted on your Connector on the following HTTP endpoints. Swagger and Rapidoc are interactive websites hosted on the Connector with which you can try out the various APIs interactively. + +- /docs/swagger : The Swagger UI of the Connector's OpenAPI specification +- /docs/rapidoc : The Rapidoc UI of the Connector's OpenAPI specification + +**Note:** You have to authorize yourself first before using the Swagger or Rapidoc interactive documentations. For this, please use the API Key of the Connector and follow the authorization steps on the user interface. For Swagger this is on the top right (Authorize button with a lock symbol), for Rapidoc this is usually the third heading called "Authentication" and can also be found on the left navigation. +{: .notice--warning} + +### Open API Documentation + +To fetch the Open API documentation of the Connector's REST API, visit the following URIs: + +- /docs/yaml : The Connector's OpenAPI specification in YAML format +- /docs/json : The Connector's OpenAPI specification in JSON format + +You can view these files with the [Swagger Editor](https://editor.swagger.io/) or automatically import them within your favorite API Clients (e.g. Postman or Insomnia). + +## API Authentication + +X-API-Key header diff --git a/_docs_operate/21-connector-scenarios.md b/_docs_operate/21-connector-scenarios.md new file mode 100644 index 000000000..ad1cafae3 --- /dev/null +++ b/_docs_operate/21-connector-scenarios.md @@ -0,0 +1,184 @@ +--- +title: "Connector-Scenarios" +permalink: /operate/connector-scenarios +published: true +--- + + + + + + +{% assign scenarios = site.docs_scenarios | where: "type", "scenario" %} + + + + + + + + + {% for scenario in scenarios %} {% assign status = scenario.properties | map:"documentation status" %}{% if status contains "DONE" %}{% assign component = scenario.properties | map:"component" %}{% if component contains "Connector" %} + + + + + + {%- endif -%} {%- endif -%} {% endfor %} +
Title +
+
Category ⌄
+
    +
    +     		+
    +
    customer ⌄
    +
      +
      +       		+
      +
      Component ⌄
      +
        +
        +
        + {{ scenario.title }} + {{ scenario.properties | map:"category" }}{{ scenario.properties | map:"customer" }}{{ scenario.properties | map:"component" }}
        + + diff --git a/_docs_operate/30-connector-sdks.md b/_docs_operate/30-connector-sdks.md new file mode 100644 index 000000000..d309f5d30 --- /dev/null +++ b/_docs_operate/30-connector-sdks.md @@ -0,0 +1,44 @@ +--- +title: "Connector Software Development Kits" +permalink: /operate/connector-sdks +--- + +## TypeScript SDK + +There is an SDK written in TypeScript you can use to communicate with your Connector from your TypeScript/JavaScript application. It is avaliable on [npmjs](https://www.npmjs.com/package/@nmshd/connector-sdk). + +### Installation + +```bash +npm i @nmshd/connector-sdk +``` + +### Usage + +1. Initialize the `ConnectorClient` + + ```ts + const connectorClient = ConnectorClient.create({ + baseUrl: "https://", + apiKey: "" + }); + ``` + +2. Start using the client + + ```ts + const FILE_PATH = "path-to-file"; + const uploadOwnFileResponse = await client.files.uploadOwnFile({ + title: "My awesome file", + description: "Test file", + expiresAt: "2022-01-01T00:00:00Z", + file: await fs.promises.readFile(FILE_PATH), + filename: "my-awesome-file.txt" + }); + + if (uploadOwnFileResponse.isSuccess) { + console.log(uploadOwnFileResponse.result); + } else { + console.log(uploadOwnFileResponse.error); + } + ``` diff --git a/_docs_operate/31-connector-modules.md b/_docs_operate/31-connector-modules.md new file mode 100644 index 000000000..b74411a95 --- /dev/null +++ b/_docs_operate/31-connector-modules.md @@ -0,0 +1,6 @@ +--- +title: "Custom Connector Modules" +permalink: /operate/custom-connector-modules +--- + +> At the moment custom Connector Modules are not supported. diff --git a/_docs_operate/32-connector-events.md b/_docs_operate/32-connector-events.md new file mode 100644 index 000000000..ab538fc7f --- /dev/null +++ b/_docs_operate/32-connector-events.md @@ -0,0 +1,69 @@ +--- +title: "Connector Events" +permalink: /operate/connector-events +--- + +| Event | Data | Description (This event is triggered when ...) | +| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| consumption.attributeCreated | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute was created manually or through a Request. | +| consumption.attributeDeleted | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute was deleted manually or through a Request. | +| consumption.attributeSucceded | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute was succeeded manually or through a Request. | +| consumption.attributeUpdated | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute was updated manually or through a Request. | +| consumption.incomingRequestReceived | [LocalRequest]({% link _docs_operate/61-data-model.md %}#LocalRequest) | ... an incoming Request was received either by loading a Relationship Template or by receiving a Message | +| consumption.incomingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an incoming Request has changed. | +| consumption.messageProcessed | [MessageProcessedEventData](#messageprocessedeventdata) | ... a Message was processed by Modules like the `RequestModule` or `DeciderModule`. | +| consumption.outgoingRequestCreated | [LocalRequest]({% link _docs_operate/61-data-model.md %}#LocalRequest) | ... an outgoing Request was created. | +| consumption.
        outgoingRequestFromRelationshipCreationChange
        CreatedAndCompleted | [LocalRequest]({% link _docs_operate/61-data-model.md %}#LocalRequest) | ... an outgoing Request was created and directly completed.
        This happens if the Response came in with a new Relationship. | +| consumption.outgoingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an outgoing Request has changed. | +| consumption.relationshipTemplateProcessed | [RelationshipTemplateProcessedEventData](#relationshiptemplateprocessedeventdata) | ... a RelationshipTemplate was processed by Modules like the `RequestModule` or `DeciderModule`. | +| consumption.sharedAttributeCopyCreated | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute is copied for sharing with another identity. | +| transport.messageReceived | [Message]({% link _docs_operate/61-data-model.md %}#Message) | ... a Message is received during synchronization. | +| transport.messageSent | [Message]({% link _docs_operate/61-data-model.md %}#Message) | ... a Message was sent. | +| transport.peerRelationshipTemplateLoaded | [RelationshipTemplate]({% link _docs_operate/61-data-model.md %}#RelationshipTemplate) | ... a Relationship Template was loaded that belongs to another identity. | +| transport.relationshipChanged | [Relationship]({% link _docs_operate/61-data-model.md %}#Relationship) | ... a Relationship has changed. This can be due to one of the following cases:
        • you create a Relationship
        • you accept, reject or revoke a Relationship Change
        • a Relationship Change is received during synchronization | + +## Event structure + +Every event is structured as follows (TData depends on the actual event, e.g. `LocalAttribute`): + +```ts +interface Event { + namespace: string; + eventTargetAddress: string; + data: TData; +} +``` + +### RequestStatusChangedEventData + +> [LocalRequest]({% link _docs_operate/61-data-model.md %}#LocalRequest) + +```ts +export interface RequestStatusChangedEventData { + request: LocalRequest; + oldStatus: LocalRequestStatus; + newStatus: LocalRequestStatus; +} +``` + +### MessageProcessedEventData + +> [Message]({% link _docs_operate/61-data-model.md %}#Message) + +```ts +export interface MessageProcessedEventData { + message: MessageDTO; + result: "ManualRequestDecisionRequired" | "NoRequest" | "Error"; +} +``` + +### RelationshipTemplateProcessedEventData + +> [RelationshipTemplate]({% link _docs_operate/61-data-model.md %}#RelationshipTemplate) + +```ts +export interface RelationshipTemplateProcessedEventData { + template: RelationshipTemplateDTO; + result: "ManualRequestDecisionRequired" | "NonCompletedRequestExists" | "RelationshipExists" | "NoRequest" | "Error"; +} +``` diff --git a/_docs_operate/40-connector-operations.md b/_docs_operate/40-connector-operations.md new file mode 100644 index 000000000..702a59c5b --- /dev/null +++ b/_docs_operate/40-connector-operations.md @@ -0,0 +1,74 @@ +--- +title: "Connector Operations" +permalink: /operate/connector-operations +toc: true +--- + +## Basic Tasks + +### Stopping the Connector + +### Starting the Connector after a Downtime + +Be advised that before starting the Connector after a downtime, you should ensure that the data within the database is on the most up-to-date time. Once the Connector starts its internal synchronization mechanism, it will update the database with the new information from the Backbone and if there are any automatismns set up (e.g. automatically accept relationships) the Connector updates the database with this new information. Thus, if the database is not on the very last point in time, there would be two inconsistent versions split across two databases. + +## Update + +## Backup & Recovery + +All of the Connector data is stored in the MongoDB. Therefore we suggest you to use [MongoDB replicas](https://www.mongodb.com/basics/replication) in a productive setup, to avoid having data loss. + +Additionally, offline backups of the replicas might make sense. For backup and recovery methods visit the official [MongoDB docs](https://docs.mongodb.com/manual/core/backups/). These backups might come in handy if the data within the database was compromised. + +In general, there is no need to backup the Connector itself. However, it makes sense to backup configuration and log files. Additionally, it might speed up the recovery process if a complete system image of the Connector is available. + +For a recovery, you should be able to just start the Connector again with the recovered database. For recovering the database itself, please also refer the MongoDB documentation. + +## Proposed System Tasks + +### Check Health + +The Business Connector exposes a health route. You can check the health with a http request to `/health`. + +### Check Available Resources + +#### Check CPU Workload + +The CPU workload can be checked using tools like [htop](https://htop.dev/) or [ctop](https://ctop.sh/) on the host system. + +#### Check Memory Consumption + +The Memory Consumption can be checked using tools like [htop](https://htop.dev/) or [ctop](https://ctop.sh/) on the host system. + +#### Check Harddisk Quota + +The Harddisk Quota can be checked using linux tools like **df**. Please ensure, that sufficient free space is available. + +### Check for Connector Updates + +New Connector versions are regularly published to the given Docker registry. Depending on your installation method, the Docker image can be automatically updated by the provided Docker registry. + +### Check for System and Docker Updates + +Please consult the documentation of your operating system about system updates. Additionally, the Docker runtime should be regularly updated as well. +We recommend to keep your operating system and Docker as up to date as possible. + +### Check Error Logs + +You can check the log using `docker logs ` or by checking the [mounted log files]({% link _docs_operate/10-connector-installation.md %}#log-file-mounting) + +## Proposed Connector Tasks + +As some of the operative tasks should be done on a regular basis, please find a proposal for these tasks below. + +### Check Access to Key Material + +### Check old Material + +### Check Connector Systems + +- Every Connector instance and host system should be regularly checked for available resources (CPU, RAM, HDD) and system updates. + +### Check Third-Party Systems + +- Every third-party system (e.g. database, event buses, network components) and host system should be regularly checked for available resources (CPU, RAM, HDD) and system updates. diff --git a/_docs_operate/42-connector-security.md b/_docs_operate/42-connector-security.md new file mode 100644 index 000000000..3ffda3b12 --- /dev/null +++ b/_docs_operate/42-connector-security.md @@ -0,0 +1,121 @@ +--- +title: "Connector Security Considerations" +permalink: /operate/connector-security +toc: true +--- + +The most important thing you have to keep in mind that the Connector is usually running on your landscape and in your authority. This is why you are also responsible for the security of the Connector and its data. + +And as the Connector is handling very sensitive data (please see chapter Privacy), it should be treated as any other business system - with the same requirements in terms of privacy, security, access or network setup. + +## Updates + +As with every software, it is important that you update the Connector regularly from the official Docker repositories. We do our best to keep the whole Enmeshed project (of course including the Connector) as up-to-date as possible, having multiple checks with regards to security and the open-source-software lifecycle. + +Additionally, any software component the Connector or its data touches should be updated regularly. + +Examples are: + +- the Docker host system (operating system, virtual machine, ...) +- the Docker Runtime +- the database (e.g. MongoDB) +- the firewall +- the virus scanner +- the firmwares of any (network) component +- possible integration platforms and modules + +## Trust + +Although Enmeshed introduces a secure way of knowing who is sending messages to the Connector, and the corresponding Backbone is blocking messages from unknown parties, you shouldn't trust others to not send you invalid, incorrect, illegal, or outright harmful data over the secure connection. + +Especially the encrypted data coming from the Backbone - which hasn't been decrypted yet - might be harmful. We cannot check if the data is correctly encrypted. Only the Connector in your landscape does this automatically (in terms of decrypting the data and verifying its digital signature). + +This brings us to the next point: Virus Scans. + +## Virus Scans + +You should do Virus Scans regularly whenever sending or receiving data. However, the Connector has no integration capability for Virus Scanners (yet). This means, we cannot call for a virus scan while we are encrypting or decrypting Enmeshed payload. + +Thus please consider scanning the host systems and the database for viruses regularly. Additionally, even encrypted data sent to and received from the Backbone should be scanned for viruses. + +## Networking + +It is best practice to block unnecessary access from and to software components between networks. In this chapter it is described which access the Connector actually required and which requests could be blocked. + +### Outbound External Connection: Internet + +The Connector uses an TLS-secured Internet connection to the Enmeshed Backbone which runs on the domain `https://prod.enmeshed.eu`. Your firewall must not block access to this domain, otherwise the Connector won't work. + +To access the latest updates, other routes might need to be opened within the firewall settings. + +### No Inbound External Connections + +The Connector synchronizes itself with the Backbone by a long-polling mechanism (it accesses the Internet). There is no data transfer triggered by the Backbone (or other users) and thus, there is no need for opening up special ports or reverse proxies for inbound connections from the Internet. + +### Oubound Communication to Internal Networks + +The Connector does need to access its database. Access to other networks or systems from the Connector can be blocked unless there is a synchronization route (webhook) set up in the Connector configuration. Otherwise, the Connector needs to access the provided internal domains for submitting new data. + +### Inbound Communication from Internal Networks + +Depending on the integration setup, access to the Connector from the internal network could be blocked for the majority of requests. Usually, only requests from the integration systems, the developers or administrators need to be allowed. + +## Authentication and User Management + +So far, the Connector supports API-Key authentication to securely authenticate technical users. These API-Keys are random character strings with a high entropy and should be kept confidential at all times. Each internal system communicating with the Connector should receive its own API-Key. + +There is no authorization set up, thus every API-Key can call any API of the Connector API. + +End user authentication, e.g. business users accessing the system, should be done on the respective business system. Usually, there is no need for end users to access the Connector and thus they should not have access to the Connector (from a network and authentication perspective). + +## Kernel Dumps + +Kernel dumps can be a useful tool for diagnosing and troubleshooting system issues. However, they can also be a security risk if they contain sensitive information such as encryption keys. If an attacker gains access to a kernel dump file, they may be able to extract this information and use it to compromise the security of your system. + +As the Connector does not have access to the host system, it cannot directly control whether or not kernel dumps are enabled. Therefore, the administrator of the host system make a decision on whether or not to disable kernel dumps based on their own security policies and risk tolerance. + +The recommended course of action is to disable kernel dumps on the host system, outside a development environment, where the Connector is running. This is in line with the [recommendation of libsodium](https://libsodium.gitbook.io/doc/memory_management#locking-memory), the used encryption library. + +This can typically be done by modifying the kernel parameters or configuration settings. + +## API key rotation + +It is important to ensure that API keys are secure and cannot be easily compromised. One of the key aspects of API key security is regular rotation and expiration. If an API key is not rotated or expired, it can potentially be used by an attacker who has obtained the key through unauthorized means. + +## Docker Compose File Security Considerations + +Docker Compose is a tool to easily set up and host and complete landscape by running multiple Docker containers, configure them and link them together with a network. For development, testing and demonstration purposes, the enmeshed team provides Docker Compose files throughout this site or on GitHub. Please be aware, that those Docker Compose files should not be used in a public or productive environment, as they could contain insecure or otherwise unstable configurations, e.g. default passwords or the missing encryption at rest for MongoDB configuration. If you choose to use Docker Compose files in a public or production environment, it is important to educate yourself on how to create production-grade Docker Compose files to ensure the security of your system. + +## Setup Firewall + +A firewall is a security system that monitors and controls incoming and outgoing network traffic based on predetermined security rules. By implementing a firewall, you can block unauthorized access to your network and prevent malicious traffic from entering your system. + +Allowing for potentially insecure protocols such as HTTP may expose sensitive information in transit to malicious parties, putting the system and its users at risk of data theft or other cyber attacks. Furthermore, the use of unsupported protocols may result in unintended side effects that could compromise system functionality or stability. + +To mitigate this risk, it is recommended that the connector restricts the supported protocols to HTTPS, which is a secure protocol that encrypts information in transit. This will help prevent sensitive information from being exposed to malicious parties. Additionally, any feature that allows developers to override the protocol check should be explicitly enabled and documented to ensure that it is used judiciously and with caution. + +Furthermore, an allowlist can be used to limit access to the system to only trusted sources, reducing the risk of unauthorized access and potential security vulnerabilities. + +When configuring the allowlist for the connector, it is important to include all necessary URLs while keeping the list as minimal as possible. + +One important consideration when configuring the allowlist is the baseUrl of the used Backbone. The baseUrl should be the minimum required for the allowlist to ensure that the connector is fully functional. Including unnecessary URLs in the allowlist can increase the attack surface and create potential security vulnerabilities. + +However, it is also important to consider other URLs that may need to be included in the allowlist, such as update URLs for Docker Hub, images, GitHub, Linux update environments, and other sources. These URLs may be necessary for the proper functioning of the system and should be carefully evaluated and included in the allowlist if deemed necessary. + +To ensure the security and integrity of the system, it is recommended to regularly review and update the allowlist as necessary. This includes removing any URLs that are no longer needed and adding new URLs that may be required. + +## Database Security + +It is crucial to secure databases, and in the case of MongoDB, it is essential to implement proper security measures to mitigate the risks associated with its default insecure configuration. + +On this page we have summarized some tips for the use of [MongoDB](https://www.mongodb.com/docs/manual/administration/security-checklist/) and [FerretDB](https://docs.ferretdb.io/security/). A good source for further information on these tips is the website of the respective database. + +With this page, we address what we consider to be the most important security tips. Even if you follow these tips, a security incident may occur. + +1. **Data encryption:** Data stored in the database should be encrypted to ensure that even if an attacker gains access to the storage device, they cannot read the data. MongoDB provides built-in [encryption at rest](https://www.mongodb.com/docs/manual/core/security-encryption-at-rest/) features, which can be enabled to secure data. For all databases it is possible to perform data encryption with storage encryption at the file system level or the block level. On Linux, file system encryption options include eCryptfs or EncFS and Block level options include dm-crypt + LUKS. + +2. **Network access restrictions:** MongoDB should only be accessible through the connector and should not be directly accessible over the public network. This can be achieved through proper network configuration, such as setting up firewalls to restrict access. + +3. **Strong passwords and connection strings:** All user credentials and connection strings should be strong and complex, to prevent unauthorized access to the database. + +4. **Regular updates and maintenance:** Regular updates should be performed to keep the database up-to-date and to fix any known security vulnerabilities. diff --git a/_docs_operate/43-connector-privacy.md b/_docs_operate/43-connector-privacy.md new file mode 100644 index 000000000..923f2306d --- /dev/null +++ b/_docs_operate/43-connector-privacy.md @@ -0,0 +1,14 @@ +--- +title: "Connector Privacy Considerations" +permalink: /operate/connector-privacy +--- + +Please be aware that personal or sensitive plaintext data is processed and stored in the Connector and the corresponding MongoDB database. The same applies to secret and private keys which should be treated as strictly confidential. + +Thus the access to the Connector and its database should be kept to a bare minimum of authorized users or systems. Please refer to the [Security Considerations]({% link _docs_operate/42-connector-security.md %}) for details. + +As the Connector is running on the customer's infrastructure in the complete authority of the customer, it is in the customer's liability to ensure a secure and legal operation. + +## Which data is processed by the Connector? + +## Deleting Data diff --git a/_docs_operate/44-connector-performance.md b/_docs_operate/44-connector-performance.md new file mode 100644 index 000000000..604db2d58 --- /dev/null +++ b/_docs_operate/44-connector-performance.md @@ -0,0 +1,8 @@ +--- +title: "Connector Performance Considerations" +permalink: /operate/connector-performance +--- + +## Scaling Horizontally + +Using multiple connectors with the same identity to scale horizontally and balance the workload across all available connectors is not supported at the moment. diff --git a/_docs_operate/50-connector-migration-v2.md b/_docs_operate/50-connector-migration-v2.md new file mode 100644 index 000000000..51270c80a --- /dev/null +++ b/_docs_operate/50-connector-migration-v2.md @@ -0,0 +1,143 @@ +--- +title: "Migrate to v2" +permalink: /operate/connector-migration-v2 +toc: true +--- + +When migrating from v1 to v2, there are a few breaking changes, as well as a bunch of new features. This guide lists both of them and will help you migrate your integration coding. + +## Backwards incompatible data structure + +First and foremost, as we [already announced in our blog]({% link _posts/2022-06-27-announcing-enmeshed-v2.md %}), the underlying data structures of v2 are not compatible with the ones of v1 at all, and we are not planning to migrate any data. This means that before starting a v2 Connector, you need to make sure that the database is completely empty. You can achieve that e.g. by creating a new Docker volume for the MongoDB container or, if you host MongoDB outside of Docker, setting up a new MongoDB server. Of course, if you don't have any important data, you can also delete database. This will ensure that on startup of the Connector, a new Enmeshed Identity is created. After that, you can start to migrate your integration coding to v2. + +## Common + +There are two things that affect all HTTP routes: the route prefix and the error codes that are returned. + +### HTTP route prefix + +The prefix of each route of the Connector's HTTP API has changed from `/api/v1` to `/api/v2`. This means that you need to change all your API calls to the Connector to use the new prefix. + +### Error codes + +There are some error codes that have changed during our transition from v1 to v2. For a full list of error codes in v2, refer to [the corresponding page]({% link _docs_operate/13-connector-error-codes.md %}). + +## Attributes + +With v2 of Enmeshed, Attributes were completely revamped. We won't go into much detail here, but the following two paragraphs will give you links for further reading. + +**Data Model** + +You can find a description of Attributes in the [data model]({% link _docs_operate/61-data-model.md %}#attributes). + +**Endpoints** + +In order to manage Attributes with the Connector, the following endpoints exist (the endpoints listed below are interactive; feel free to execute them): +{% include rapidoc api_route_regex="/api/v2/Attributes" title="" %} + +Tip: go through the new [Connector tutorial]({% link _docs_operate/01-connector-tutorial.md %}) if you want an example of how to create An Attribute. +{: .notice--info} + +## Files + +There are a few minor changes to the data model and the endpoints for managing Files. + +**Data Model** + +The following properties were removed from the `File` entity: + +- `deletedAt` +- `deletedBy` +- `deletedByDevice` + +The reason for this is that these properties were added prematurely. At the moment it is not possible to delete files. This feature will be added in the future. But for now, we decided that the properties are misleading and removed them. + +There also is a new property named `truncatedReference`, which is similar to the `truncatedReference` of a Token. It is a short reference to a File containing its ID and secret key. In order to share the File with a user, you can either send the `truncatedReference` as text, or - even simpler - create a QR code for it with the new endpoint(see table below). When the user scans this QR code with the Enmeshed app, the File is automatically downloaded - No Relationship necessary. + +**Endpoints** + +The following endpoints have changed: + +| Route | Change Type | Description | +| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| POST /Files/Peer | Updated | You can now pass a `truncatedreference` of a File in the body of this endpoint. The other possibilities (id+secret key and a truncated Token reference) can still be used. | +| GET /Files/{id} | Updated | You can now pass a `truncated reference` of a File as the route parameter `id` (or `idOrReference`, as it is called now) of this endpoint. Of course, you can still pass an ID. | +| GET /Files/{id} | Updated | By setting the `Accept` HTTP header on this request to `image/png`, you can generate a QR code with the truncated File reference. | + +## Messages + +There are a few minor changes to the data model and the endpoints for managing Messages. + +**Data Model** + +The [recipient]({% link _docs_operate/61-data-model.md %}#recipient) of a `Message` now has the property `relationshipId`, which contains the ID of the Relationship the Connector has to the recipient. This is useful for example if you want to query all Messages that belong to a specific Relationship. + +**Endpoints** + +The following endpoints have changed: + +| Route | Change Type | Description | +| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| GET /Messages | Updated | As described above, there now is a `relationshipId` property on each object of the `recipients` array of a Message. You can use this property to filter for Messages of a specific Relationship by setting the query parameter `recipients.relationshipId` We further removed the query parameter `relationshipIds`, because it is not needed anymore. | + +## Relationships + +There are a few minor changes to the data model and the endpoints for managing Relationships. + +**Data Model** + +The following properties were removed from the `Relationship` entity: + +- `lastMessageReceivedAt` +- `lastMessageSentAt` + +These properties were never filled by the Runtime and were therefore removed. If you want for example the Relationships you sent a Message to in the last 24 hours, you can instead query the Messages and filter for the `createdAt` property in conjunction with createdBy set to your own Address. This gives you all the Messages you sent to in the last 24 hours. Now you just need to summarize the distinct `relationshipIds` of all these Messages. You can do similar to replace `lastMessageReceivedAt`. + +Further, we removed two Relationship status: + +- `Terminated`: Since we currently do not support termination of Relationships, we removed this status in order to reduce confusion. +- `Revoked`: With the introduction of Requests, we had to temporarily remove the possibility of revoking Relationship Creation Changes, because if the Response sent with the Relationship Creation Change was already created by the peer, this Response would have to be deleted as soon as the Relationship Creation Change was revoked - which is really hard to implement. In the future, revoking Relationship Creation Changes will probably be possible again, but at the moment this is not our top priority. + +**Endpoints** + +The following endpoints have changed: + +| Route | Change Type | Description | +| ------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| PUT /Relationships/{id}/Changes/{changeId}/Revoke | Removed | As described above, we removed the `Revoked` status of a Relationship. Therefore we also removed the endpoint that was responsible for moving a Relationship to this status. | +| GET /Relationships/{id}/Attributes | Added | This new route can be used to fetch all Attributes that exist in the context of the Relationship - so the ones you received from the peer as well as the ones you shared. | + +## Relationship Templates + +There are a few minor changes to the data model and the endpoints for managing Relationship Templates. + +**Data Model** + +The property `maxNumberOfRelationships` was removed from the `RelationshipTemplate` entity. It was replaced by the property `maxNumberOfAllocations` which offers similar functionality. The reason for this change is that with let's say a `maxNumberOfRelationships` of 5, it was possible for 10 users to download the Relationship Template and fill it out. But finally, when trying to create the Relationship, 5 of them would receive an error message, because the maximum number of Relationships is exhausted. This is why the Relationship Template now has the property `maxNumberOfAllocations`. Setting this property to e.g. 5 will ensure that the Template can only be fetched by 5 different Identities. The sixth will receive an error message when trying to fetch it, so it won't be able waste time by filling it out. + +There also is a new property named `truncatedReference`, which is similar to the `truncatedReference` of a Token. It allows you to create a reference to a Relationship Template containing its ID and secret key. With this, there is no need to create a Token for a the Relationship Template anymore. Just create a QR code for the Relationship Template directly (see the new endpoint below). When the user scans this QR code with the Enmeshed app, the Relationship Template is downloaded and displayed. + +**Endpoints** + +The following endpoints have changed: + +| Route | Change Type | Description | +| ------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| POST /RelationshipTemplates/Peer | Updated | You can now pass a `truncatedReference` of a Relationship Template in the body of this endpoint. The other possibilities (id+secret key and a truncated Token reference) can still be used. | +| GET /RelationshipTemplates/{id} | Updated | By setting the `Accept` HTTP header on this request to `image/png`, you can generate a QR code with the `truncatedReference` of the Relationship Template. | + +## Requests + +With v2 of Enmeshed, there is the new concept of "Requests", which are the new way to exchange Attributes between two Identities. And you can do a lot more with them. We won't go into much detail here, but the following two paragraphs will give you links for further reading. + +**Data Model** + +You can find a description of Requests in the [data model]({% link _docs_operate/61-data-model.md %}#request). Further, there is a [dedicated page]({% link _docs_operate/62-request-items.md %}) where you can find all existing Request Items. + +**Endpoints** + +In order to manage Requests with the Connector, the following endpoints exist: +{% include rapidoc api_route_regex="/api/v2/Requests" title="" %} + +Tip: go through the new [Connector tutorial]({% link _docs_operate/01-connector-tutorial.md %}) if you want an example of what you can do with Requests. +{: .notice--info} diff --git a/_docs_operate/61-data-model.md b/_docs_operate/61-data-model.md new file mode 100644 index 000000000..5a1ec5e3b --- /dev/null +++ b/_docs_operate/61-data-model.md @@ -0,0 +1,521 @@ +--- +title: "Enmeshed Data Model" +permalink: /operate/data-model-overview +toc: true +--- + +The Enmeshed data model can be divided into three parts: + +- Transport types +- Local types +- Content types + +The following diagram gives you an overview of all the existing types and how they are connected to each other. The subsequent chapters describe these types in more detail. + +
        +(note that you can click on each type in order to navigate to the paragraph with the corresponding description) + +At a first glance the amount of types is overwhelming. But in the following chapters all of them are explained in detail. + +# Transport Types + +Transport types like `RelationshipTemplate`, `Token` or `File` are types that are "exchanged" between Identities via the Backbone. They are created and updated by the [Transport Layer]({% link _docs_explore/42-transport-layer.md %}). In most cases they have a `content` property, which contains the actual payload that should be transferred between the Identities. This payload is being encrypted when it is sent to the Backbone, and decrypted by the other Identity when it is received. The following sections describe the different Transport types and their properties. + +Note that the properties of the types are the ones that exist locally (aka on the Connector/in the App). The Backbone does not necessarily know about them. The properties that only exist locally are marked accordingly in the tables below. Further there are properties that are confidential and are therefore encrypted before sent to the Backbone, in order to enable end-to-end encryption. Both kinds of these properties are marked accordingly in the "Remarks" column of the property tables below. + +## Token + +Tokens can be used to save arbitrary structured data on the Backbone, which is encrypted with a random symmetric key. You can then pass the ID of the Token, together with the random key, to another Identity, which can then retrieve the token and decrypt it, e.g. inside of a QR Code, which you send to the recipient via letter. Tokens can be handy in a lot of scenarios, for example: + +- You want to share secret information with someone you don't have a Relationship with. +- The Enmeshed App currently uses a Token to save a Backup of the Identity. ID and secret key are then encoded in a QR Code, which the user can print out and scan later in order to restore the Identity on a new device. + +A Token has the following properties: + +| Name | Type | Description | Remarks | +| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="Token" prefix="TOK" %} | +| createdBy | `string` | {% include descr_createdBy class="Token" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | | +| 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" %} | | +| secretKey | `string` | {% include descr_secretKey class="Token" %} | saved only locally | +| 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 id and secretKey. | + +## RelationshipTemplate + +A Relationship Template serves two purposes: + +1. It represents the permission to establish a Relationship. When sending a Relationship request, the sender has to attach the ID of a valid Relationship Template created by the recipient. Otherwise the Backbone blocks the Relationship request. And since the IDs are randomly generated, you can only obtain such an ID from the recipient. +2. It can contain data which is of interest for the one who uses the Relationship Template. The Enmeshed App for example expects a Relationship Template content which contains a `Request` which contains e.g. Attributes about the creator of the Template as well as queries for Attributes that the Template creator wants to receive together with the Relationship request. + +| Name | Type | Description | Remarks | +| ---------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | +| id | `string` | {% include descr_id class="Relationship Template" prefix="RLT" %} | | +| isOwn | `boolean` | {% include descr_isOwn class="Relationship Template" %} | saved only locally | +| createdBy | `string` | {% include descr_createdBy class="Relationship Template" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="Relationship Template" %} | | +| createdAt | `string` | {% include descr_createdAt class="Token" %} | | +| content | [`RelationshipTemplateContent`](#relationshiptemplatecontent) \| `unknown` | The content of the Relationship Template. You can add whatever you want here. However, if it is intended for a User of the Enmeshed App, `RelationshipTemplateContent` has to be used. Otherwise feel free to insert whatever you want or need. | | +| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | will be encrypted before sent to the Backbone | +| maxNumberOfAllocations | `number` \| `undefined` | Can be set to limit the number of allocations of this template. A Relationship Template 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. | | +| truncatedReference | `string` | {% include descr_truncatedReference class="RelationshipTemplate" %} | | + +## Relationship + +A Relationship between two Identities is the prerequisite for them to exchange Messages. If there is no Relationship, the Backbone blocks all Messages that are tried to be sent. This ensures that you only receive Messages from Identities you know, so you are protected from any harmful Messages like spam or phishing mails. + +| Name | Type | Description | Remarks | +| -------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | +| id | `string` | {% include descr_id class="Relationship" prefix="REL" %} | | +| template | `RelationshipTemplate` | The Relationship Template that was used to establish this Relationship. | | +| status | `"Pending"` \| `"Active"` \| `"Rejected"` \| `"Revoked"` | The status of this Relationship.
        {::nomarkdown}
        • Pending: the Relationship was created, but not yet accepted the recipient. In this state you cannot send Messages yet.
        • Active: this means that the Relationship is active. As long as it is active, both participants can exchange Messages.
        • Rejected: the Relationship was rejected by the recipient.
        • Revoked: the Relationship was revoked by the sender.
        {:/} | | +| changes | [`RelationshipChange`](#relationshipchange)`[]` | The history of changes made to this Relationship. You can find the definition of a Relationship Change below. | | +| peer | `string` | The Address of the Identity with which you have this Relationship. | saved only locally | + +### RelationshipChange + +Since a Relationship "belongs" to two Identities, each change on such a Relationship demands for the agreement of both parties. That's where Relationship Changes come into play. Whenever one party wants to make a change to the Relationship (like create or terminate it), it sends a Relationship Change to the other party, which has to accept it in order for the change to take effect. If the other party doesn't want to accept it, it can also reject it. And if the party that created the Relationship Change changes its mind, it can revoke the Relationship Change. The Backbone makes sure that a Relationship Change can only be completed in one of those three ways (accepted, rejected, revoked). So for example if you try to accept a Relationship Change that is already revoked, you will receive an error. + +| Name | Type | Description | Remarks | +| -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| id | `string` | {% include descr_id class="Relationship Change" prefix="RCH" %} | | +| status | `"Pending"` \|`"Accepted"` \|`"Rejected"` \|`"Revoked"` | The current status of the Relationship Change. | | +| type | `"Creation"` | The type of the Relationship Change. Currently the only existing type is `Creation`. As soon as the termination of Relationships is supported, `Termination` will be a second Relationship Change type. | | +| request | [`RelationshipChangeRequest`](#relationshipchangerequest) | Information about the request of the Relationship Change. | | +| response | [`RelationshipChangeResponse`](#relationshipchangeresponse) \| `undefined` | Information about the response of the Relationship Change. | | + +Note that RelationshipChangeRequest and RelationshipChangeResponse have nothing to do with [Requests](#request) and [Responses](#response), which we will discuss later. + +### RelationshipChangeRequest + +| Name | Type | Description | Remarks | +| --------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| createdBy | `string` | {% include descr_createdBy class="Relationship Change Request" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="Relationship Change Request" %} | | +| createdAt | `string` | {% include descr_createdAt class="Relationship Change Request" %} | | +| content | [`RelationshipCreationChangeRequestContent`](#relationshipcreationchangerequestcontent) \| `unknown` | The content of the Relationship Change Request. You can add whatever you want here. However, if the other party uses the Enmeshed App, and the type of the Relationship Change is `Creation`, [`RelationshipCreationChangeRequestContent`](#relationshipcreationchangerequestcontent) has to be used. Otherwise feel free to insert whatever you want or need. | will be encrypted before sent to the Backbone | + +### RelationshipChangeResponse + +| Name | Type | Description | Remarks | +| --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| createdBy | `string` | {% include descr_createdBy class="Relationship Change Response" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="Relationship Change Response" %} | | +| createdAt | `string` | {% include descr_createdAt class="Relationship Change Response" %} | | +| content | `unknown` | The content of the Relationship Change Response. You can add whatever you want here. Since the Enmeshed App doesn't expect any special content here, there is no need to watch out. | will be encrypted before sent to the Backbone | + +## Message + +A Message is a piece of data that can be sent to one or more recipients. The sender is completely free in what the content of the Message looks like. Though in order to enable a normalized communication, Enmeshed defines some content structures for Messages, and in the future there will be more of those. Consider that the Enmeshed App only supports those normalized Message contents. Currently there are: + +- [`Mail`](#mail) +- [`Request`](#request) +- [`ResponseWrapper`](#responsewrapper) + +You can read more details about each of these in the corresponding sections of the "Content Types" chapter. + +But if you are communicating with another Connector, feel free to settle on any content structure that fits your needs. + +| Name | Type | Description | Remarks | +| --------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="Message" prefix="MSG" %} | | +| content | `unknown` | The content of the Message. You can add whatever you want here. However, if it is intended for a User of the Enmeshed App, use either `Mail`, `Request` or `Response`. Otherwise feel free to insert whatever you want or need. | will be encrypted before sent to the Backbone | +| createdBy | `string` | {% include descr_createdBy class="Message" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="Message" %} | | +| recipients | [`Recipient`](#recipient)`[]` | An array of recipients of this Message. | | +| createdAt | `string` | {% include descr_createdAt class="Message" %} | | +| attachments | `string[]` | An array of [File](#file) IDs you want to attach to your Message. You receive the File ID after you uploaded a file to the Backbone. By attaching a File to a Message, you share the secret key used to encrypt/decrypt the File, which cannot be undone. | | + +### Recipient + +| Name | Type | Description | Remarks | +| ---------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | +| address | `string` | The Address of the recipient of the Message. | | +| relationshipId | `string` | The ID of the Relationship between the recipient and the sender of the Message. | saved only locally | +| receivedAt | `string` \| `undefined` | A timestamp that describes when the recipient retrieved the Message from the Backbone. `undefined` when the Message wasn't received yet. Caution: "received" does not mean that it was read, so don't mix this up with a read receipt. | | +| receivedByDevice | `string` \| `undefined` | The ID of the Device that first retrieved the Message. `undefined` when the Message wasn't received yet. This is of no interest for the sender of the Message, but rather for the recipient itself, since they can use it for audit purposes. sender | | + +## File + +The Backbone allows you to upload files, which are saved as - you guessed it - `Files`. + +| Name | Type | Description | Remarks | +| ------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="File" prefix="FIL" %} | | +| createdAt | `string` | {% include descr_createdAt class="File" %} | | +| createdBy | `string` | {% include descr_createdBy class="File" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="File" %} | | +| expiresAt | `string` | {% include descr_expiresAt class="File" %} | | +| filename | `string` | The name of the file as it was on the device that uploaded it. | will be encrypted before sent to the Backbone | +| filesize | `number` | The size of the plaintext file in bytes. | will be encrypted before sent to the Backbone | +| mimetype | `string` | The [mimetype](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the file. | will be encrypted before sent to the Backbone | +| title | `string` | A human readable title of the file, which can be defined when uploading the File. | will be encrypted before sent to the Backbone | +| description | `string` \| `undefined` | A human readable description of the file, which can be defined when uploading the File. | will be encrypted before sent to the Backbone | +| secretKey | `string` | The key that was used to encrypt the File. | saved only locally | +| isOwn | `boolean` | {% include descr_isOwn class="File" %} | saved only locally | +| truncatedReference | `string` | {% include descr_truncatedReference class="File" %} | saved only locally | + +A File further has its content, of course. But since this is not a JSON property, it is not included in this table. You can download the content of the File separately. + +# Local Types + +In addition to the types that are shared between Identities via the Backbone, there are certain types that only exist within one Identity. These types usually contain metadata about [Content types](#content-types) that should not be transferred to other Identities. They are created and updated by the [Consumption Layer]({% link _docs_explore/43-consumption-layer.md %}). + +Currently there are two main Local types: + +- LocalRequest +- LocalAttribute + +Each of them further describes some sub types. + +This chapter explains all of those types, together with their properties. + +## LocalRequest + +A Local Request contains the local metadata for a [Request](#request). + +| Name | Type | Description | +| --------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| id | `string` | {% include descr_id class="LocalRequest" prefix="FIL" %} | +| isOwn | `boolean` | `true` if you sent the Request, `false` if you received it. | +| peer | `string` | The Identity that sent you the corresponding Request/that you sent the Request to. | +| createdAt | `string` | {% include descr_createdAt class="LocalRequest" %} | +| status | [`LocalRequestStatus`](#localrequeststatus) | The current status of the Request. See [below](#localrequeststatus) for a list of all possible values. | +| content | [`Request`](#request) | The actual Content object this Local Request defines the metadata for. | +| source | [`LocalRequestSource`](#localrequestsource) \| `undefined` | Information about the Transport object with which the Request came in/was sent. This property is `undefined` if the Request is not sent yet. | +| response | [`LocalResponse`](#localresponse) \| `undefined` | Metadata + Content object of the response. If there is no response yet, this property is `undefined`. | + +### LocalRequestStatus + +Depending on whether it is an incoming or an outgoing Request, there can be different statuses. The following state diagram shows which status exists in both cases and when there are transitions from one state to another: + +![State diagram for Local Request Status]( {{ '/assets/images/explore/RequestStatus%20-%20State%20Diagram.png' | relative_url }} ) + +Draft +: This status only exists for outgoing Requests. It means that the Local Request was created, but not yet sent. + +Open +: In case of an outgoing Request, `Open` means that the Request was sent. The transition to `Open` happens automatically when you send the Request with a Message. +: In case of an incoming Request, `Open` means that the Local Request was received. + +DecisionRequired +: After the prerequisites of the Request and all of its Request Items were checked, a decision can be made. At first, the [Decider Module]({% link _docs_explore/61-runtime.md %}#decider-module) tries to make an automatic decision. It therefore checks all LocalRequests in status `DecisionRequired`. + +ManualDecisionRequired +: If the Decider Module cannot make a decision, it moves the Local Request to `ManualDecisionRequired`. When the Local Request is in this status, it's the User's turn to decide whether they want to accept or reject the Request. + +Decided +: When the User or the Decider Module accepts or rejects the Request, the Response and ResponseItems are generated based on the passed parameters. This Response is saved in the `response` property of the `LocalRequest`, but not yet sent. + +Completed +: In case of an incoming Request, the Runtime Module listens to an Event saying that a Request moved to status `Decided`. It then checks on which way the Request was received (Message/RelationshipTemplate) and sends the Response on the corresponding way (by sending a message or creating a Relationship). After the Response was successfully sent, it moves the Local Request to `Completed`. +: In case of an outgoing Request, the Runtime Module listens to the `MessageReceivedEvent` and checks the content of the sent Message for a Response. If there is one, it moves the corresponding Local Request to `Completed`. + +Expired +: When the timestamp in `expiresAt` of a Request is reached, the Request automatically moves to the status `Expired`. + +### LocalRequestSource + +With the information in this type you can clearly identify the Transport object the Request was sent/received in. Currently there are only two possibilities: Message and Relationship Template. + +| Name | Type | Description | +| --------- | ----------------------------------- | ---------------------------------------------------------------- | +| type | "Message" \| "RelationshipTemplate" | The type of Transport object the Request was sent/received in. | +| reference | `string` | The ID of the Transport object the Request was sent/received in. | + +### LocalResponse + +When a Local Request is decided/received, a Local Response is generated, which contains the Response, together with some metadata. + +| Name | Type | Description | +| --------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| createdAt | `string` | {% include descr_createdAt class="LocalResponse" %} | +| content | [`Response`](#response) | The actual Content object this Local Response defines the metadata for. | +| source | [`LocalResponseSource`](#localresponsesource) \| `undefined` | Information about the Transport object with which the Response came in/was sent. This property is `undefined` if the Response is not sent/received yet. | + +### LocalResponseSource + +With the information in this type you can clearly identify the Transport object the Response was sent/received in. Currently there are only two possibilities: Message and Relationship Change. + +| Name | Type | Description | +| --------- | --------------------------------- | ----------------------------------------------------------------- | +| type | "Message" \| "RelationshipChange" | The type of Transport object the Response was sent/received in. | +| reference | `string` | The ID of the Transport object the Response was sent/received in. | + +## LocalAttribute + +A Local Attribute contains the local metadata for an [Attribute](#attributes). There are three situations a Local Attribute is created in the database: + +- The Identity maintains an Attribute about itself (e.g. sets its first name). We call such a Local Attribute "Repository Attribute". +- The Identity shares an Attribute of itself with another Identity (e.g. sends it in a Request). In that case, a _copy of the original Local Attribute_ is created, where the `shareInfo` property is set. +- The Identity receives an Attribute from another Identity (e.g. receives it in a Request). In that case a _new Local Attribute_ is created, where the `shareInfo` is set. + +| Name | Type | Description | +| ----------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | `string` | {% include descr_id class="LocalAttribute" prefix="ATT" %} | +| parentId | `string` \| `undefined` | If the Attribute referenced by this Local Attribute is a component of a composite Attribute, the `parentId` property is set to the id of the composite Attribute. Example: if a Local Attribute is created with the content `StreetAddress`, for each property of the `StreetAddress` an additional Local Attribute is created. And each of these will have `parentId` set to the `id` of the Local Attribute for the `StreetAddress`. | +| createdAt | `string` | {% include descr_createdAt class="LocalAttribute" %} | +| content | [`IdentityAttribute`](#identityattribute) \| [`RelationshipAttribute`](#relationshipattribute) | The actual Content object this Local Attribute defines the metadata for. | +| succeeds | `string` \| `undefined` | The ID of the Local Attribute that succeeds the current one. | +| succeededBy | `string` \| `undefined` | The ID of the Local Attribute that is succeeded by the current one. | +| shareInfo | [`LocalAttributeShareInfo`](#localattributeshareinfo) \| `undefined` | Information about the peer this Local Attribute was received from/shared with, as well as via which Local Request it was received/sent. If the Local Attribute refers to a Repository Attribute, this property is `undefined`. | + +### LocalAttributeShareInfo + +The Local Attribute Share Info helps to keep track of how the Local Attribute was received/sent, from whom it was received/who sent it, as well as which Local Attribute it was copied from (in case of a shared Repository Attribute). For example, this enables us to track back who we shared a certain Repository Attribute with, so we are able to notify each of them when changing the Repository Attribute. + +| Name | Type | Description | +| ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| requestReference | `string` | The ID of the Local Request the Local Attribute was received in/sent with. | +| peer | `string` | The Address of the Identity the Local Attribute was received from/shared with. | +| sourceAttribute | `string` \| `undefined` | If the Local Attribute is a copy of a Repository Attribute, then this property contains the ID of the Repository Attribute. | + +## LocalAttributeListener + +A LocalAttributeListener is created when you accept an incoming Request with a [`RegisterAttributeListenerRequestItem`]({% link _docs_operate/62-request-items.md %}#registerattributelistenerrequestitem). It is used to keep track of which Attribute Listeners currently exist and what they are listening for. + +| Name | Type | Description | +| ----- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | `string` | {% include descr_id class="LocalAttributeListener" prefix="ATL" %} | +| query | [`IdentityAttributeQuery`](#identityattributequery) \| [`ThirdPartyRelationshipAttributeQuery`](#thirdpartyrelationshipattributequery) | The query the Attribute that is listened to must match. Note that you cannot send a [`RelationshipAttributeQuery`](#relationshipattributequery) here, because it doesn't make sense: by definition, both parties know about a Relationship Attribute right from the beginning, because one party requests its creation, and the other one accepts it. | +| peer | `string` | The Address of the peer that requested the Attribute Listener. | + +# Content Types + +Content Types can be seen as a data contract between Identities. The medium through which this data is exchanged are the [Transport types](#transport-types) (e.g. Messages, Tokens, ...). This chapter shows all the Content types and describes their intended usage. + +## Request + +A Request allows you to ask another Identity to do something. What this "something" is depends on which of the so called [Request Items](#requestitem) were added to the Request (e.g. [`CreateAttributeRequestItem`]({% link _docs_operate/62-request-items.md %}#createattributerequestitem), [`ReadAttributeRequestItem`]({% link _docs_operate/62-request-items.md %}#readattributerequestitem), ...). The Request is then sent to the peer via Message or Relationship Template. The peer can then review the Request and decide whether they want to accept or reject it. And if they accept it, they can even choose which of the Items they want to accept. You can also put multiple Items into a [group](#requestitemgroup) in order to ensure that they can only be accepted/rejected as a unit. + +| Name | Type | Description | +| ----------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| id | `string` \| `undefined` | Unique identifier of this object. This property is `undefined` if the Request is inside of a Relationship Template.
        _Remark: the ID of each Request starts with the letters "REQ". This way you can tell apart a Request ID from any other ID just by looking at the prefix._
        | +| title | `string` \| `undefined` | An optional, human readable title for the Request. | +| description | `string` \| `undefined` | An optional, human readable description for the Request. | +| expiresAt | `string` \| `undefined` | {% include descr_expiresAt class="Request" %} | +| items | `(`[`RequestItemGroup`](#requestitemgroup)` | `[`RequestItem`](#requestitem)`)[]` | An array of Request Items and Groups that are part of the Request. There must be at least one Item or Group per Request. | +| metadata | `string` \| `undefined` | Optional custom metadata that can be sent together with the Request. This property is meant purely for developers who operate with Enmeshed. They can write for example some kind of key into this property, which can be used later to identify the content of this Request. | + +### RequestItem + +Request Items can be sent inside of a Request and specify what should be done when the Request is accepted. `RequestItem` itself only defines some common properties. There are multiple types that inherit from `RequestItem`, like `CreateAttributeRequestItem` or `ReadAttributeRequestItem`. + +The base properties are: + +| Name | Type | Description | +| --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| title | `string` \| `undefined` | An optional, human readable title for the Request Item. | +| description | `string` \| `undefined` | An optional, human readable description for the Request Item. | +| metadata | `object` \| `undefined` | The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by Enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. | +| mustBeAccepted | `boolean` | The mandatory mustBeAccepted property is used to differentiate between required and optional Request Items within the Request. In other words, if the peer Identity may or may not decide to ignore this specific Request Item. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective Request Items must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the Request Item is inside of a Request Item Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. | +| requireManualDecision | `boolean` | To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each Request Item may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step of for example an [AuthenticationRequestItem]({% link _docs_operate/62-request-items.md %}#authenticationrequestitem) or a [ConsentRequestItem]({% link _docs_operate/62-request-items.md %}#consentrequestitem), the requireManualDecision property can be set to true. | + +There is a [dedicated site]({% link _docs_operate/62-request-items.md %}) that lists all available kinds of Request Items. + +### RequestItemGroup + +| Name | Type | Description | +| -------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| title | `string` \| `undefined` | An optional, human readable title for the Request Item Group. | +| description | `string` \| `undefined` | An optional, human readable description for the RequestItem. | +| metadata | `object` \| `undefined` | Optional metadata that can be sent together with this RequestItem. The intended usage is the same as of the metadata property of the Request. | +| mustBeAccepted | `boolean` | If set to `true`, then this Request Item Group has to be accepted when the Request is accepted. | +| items | [`RequestItem`](#requestitem)`[]` | The items inside of this Group. There has to be at least one Request Item per Group. Note that we do not support nested Groups at the moment. If you need this feature, you can [raise a feature request](https://github.com/nmshd/feedback/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=%5BFEATURE%5D+). | + +## Response + +| Name | Type | Description | +| --------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| result | `"Accepted"` \| `"Rejected"` | Whether the Response was accepted or rejected by the recipient of the Request. | +| requestId | `string` | The `id` of the Request this Response belongs to. The Sender of the Request needs this information to map the Response to the corresponding Request. | +| items | `(`[`ResponseItemGroup`](#responseitemgroup)`\|`[`ResponseItem`](#responseitem)`)[]` | An array of Response Items and Groups that are part of the Response. For each Request Item (Group) of the Request, there must be one Response Item (Group) in the Response. Note that the indices have to be the same for matching Request and Response Items. | + +### ResponseItem + +Response Items are sent inside of a Response. They contain the response data that is sent by the recipient of the Request. There are three different kinds of Response Items: `AcceptResponseItem`, `RejectResponseItem` and `ErrorResponseItem`. Depending on the actual Request Item, there can be different derivations of these three items. For example, in case of a [`CreateAttributeRequestItem`]({% link _docs_operate/62-request-items.md %}#createattributerequestitem), there is a special [`CreateAttributeAcceptResponseItem`]({% link _docs_operate/62-request-items.md %}#createattributerequestitem-response-itemproperties), while for an [`AuthenticationRequestItem`]({% link _docs_operate/62-request-items.md %}#authenticationrequestitem), the [`AcceptResponseItem`](#acceptresponseitem) can be used, because there is no additional information necessary next to whether it was accepted or rejected. + +The [site documenting the Request Items]({% link _docs_operate/62-request-items.md %}) shows which Response Item is required for each Request Item. + +#### AcceptResponseItem + +The properties of the `AcceptResponseItem` are: + +| Name | Type | Description | +| ------ | ------------ | -------------------------------------------------------- | +| result | `"Accepted"` | The only possible value here is the string `"Accepted"`. | + +#### RejectResponseItem + +The properties of the `RejectResponseItem` are: + +| Name | Type | Description | +| -------- | ----------------------- | ------------------------------------------------------------- | +| result | `"Rejected"` | The only possible value here is the string `"Rejected"`. | +| code? | `string` \| `undefined` | A code telling the sender about the reason for the rejection. | +| message? | `string` \| `undefined` | A human readable message with details about the rejection. | + +#### ErrorResponseItem + +The `ErrorResponseItem` is only created by the Enmeshed Runtime, in case something happens which hinders you from further processing of the Request Item. It will never be created manually. The properties are: + +| Name | Type | Description | +| ------- | --------- | ----------------------------------------------------------------------- | +| result | `"Error"` | The only possible value here is the string `"Error"`. | +| code | `string` | An error code telling the sender about the kind of error that occurred. | +| message | `string` | A human readable error message with details about the error. | + +### ResponseItemGroup + +| Name | Type | Description | +| ----- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| items | [`ResponseItem`](#responseitem)`[]` | The items inside of this Group. For each Request Item of the Request Item Group, there must be one Response Item in the Response Item Group. Note that the indices have to be the same for matching Request and Response Items. | + +## ResponseWrapper + +The ResponseWrapper is a wrapper around the Response that is sent by the recipient of the Request. It contains the Response itself, but also some additional information that is required for the Request to be processed correctly. + +| Name | Type | Description | +| ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| requestId | `string` | The `id` of the Request this Response belongs to. | +| requestSourceReference | `string` | The reference to the Message or RelationshipTemplate the Request was received with. | +| requestSourceType | `"Message"` \| `"RelationshipTemplate"` | Specifies if the Request was transferred via [Message](#message) or [RelationshipTemplate](#relationshiptemplate). | +| response | [`Response`](#response) | The Response that is sent by the recipient of the Request. | + +## Attributes + +An Attribute is some piece of information about an Identity itself (e.g. its name, address, birth date, etc.) or about an Identity in the context of a Relationship (e.g. the customer id the of the user the Relationship). Since the two scenarios differ quite a lot, there are two different types for them: IdentityAttribute and RelationshipAttribute. + +### IdentityAttribute + +Identity Attributes describe an Identity itself. Their values are strongly normalized. There is a list of available values [here]({% link _docs_operate/63-attribute-values.md %}). + +| Name | Type | Description | +| --------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| owner | `string` | The Identity that owns this Attribute. Only the owner of an Attribute is allowed to change it after its creation. | +| validFrom | `string` \| `undefined` | The date from which on the Attribute is valid. Could be in the future if the Attribute is not yet valid. | +| validTo | `string` \| `undefined` | The date until this Attribute is valid. Could be in the past if the Attribute is already expired. | +| value | [`IdentityAttributeValue`]({% link _docs_operate/63-attribute-values.md %}#identity-attributes) | The Attribute's value. | +| tags | `string[]` \| `undefined` | To specify additional information. | + +### RelationshipAttribute + +Relationship Attributes describe an Identity in the context of a Relationship. While there are some types that can be used as a value for a RelationshipAttribute, these types are rather generic (e.g. `ProprietaryString`, `ProprietaryInteger`, ...). + +| Name | Type | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| owner | `string` | The Identity that owns this Attribute. Only the owner of an Attribute is allowed to change it after its creation. | +| validFrom | `string` \| `undefined` | The date from which on the Attribute is valid. Could be in the future if the Attribute is not yet valid. | +| validTo | `string` \| `undefined` | The date until this Attribute is valid. Could be in the past if the Attribute is already expired. | +| key | `string` | An arbitrary key that is set by the creator of this Attribute. It is used to identify the Attribute in a query, especially by a third party. Example: you could set something like `customerId` in case of a customer id. | +| isTechnical | `boolean` \| `undefined` | Defines whether the Relationship Attribute contains data that is actually relevant for the user (`isTechnical=false`) or whether it should be hidden in the UI (`isTechnical=true`). | +| value | [`RelationshipAttributeValue`]({% link _docs_operate/63-attribute-values.md %}#relationship-attributes) | The Attribute's value. | +| confidentiality | `"public"` \| `"protected"` \| `"private"` \| When this property is set to `"private"`, it means that third parties are not able to query this Relationship Attribute. It therefore only exists in the Relationship it was created in. If the confidentiality is `"protected"`, third parties can query the Relationship Attribute, but the App shows a warning saying that you should only share it with someone you trust. If the confidentiality is `"public"`, everybody can query the Attribute, without anything special to happen. | | + +## AttributeQueries + +One of the main features of Enmeshed is sharing Attributes. For this, an Identity either proactively sends its Attributes to a peer. Or, if let's say a company wants to know the birth date of its customer, it can ask for it. Depending on the exact use case, the latter can be achieved with one of a bunch of Request Items, like for example a [`ReadAttributeRequestItem`]({% link _docs_operate/62-request-items.md %}#readattributerequestitem), or a [`CreateAttributeListenerRequestItem`]({% link _docs_operate/62-request-items.md %}#createattributerequestitem). All of them have in common that they define a `query` property, which contains either an [`IdentityAttributeQuery`](#identityattributequery) or a [`RelationshipAttributeQuery`](#relationshipattributequery). + +### IdentityAttributeQuery + +An Identity Attribute Query is used to query for Identity Attributes. For that, it defines the following properties: + +| Name | Type | Description | +| --------- | ------------------------- | --------------------------------------------------------------------------------------------------- | +| validFrom | `string` \| `undefined` | The start date of the time frame the returned Attribute should be valid in. | +| validTo | `string` \| `undefined` | The end date of the time frame the returned Attribute should be valid in. | +| valueType | `string` | The type of value that should be queried, e.g. `"StreetAddress"`, `"BirthDate"` or `"Nationality"`. | +| tags | `string[]` \| `undefined` | To specify additional information. | + +You can only query Identity Attributes owned by the recipient of the query. + +### RelationshipAttributeQuery + +There are cases in which you want to query some data from your peer that is not an Identity Attribute. An example for this is when an electricity provider asks for the electric meter number of a new customer. Since this information is only relevant in the context of the Relationship, an Identity Attribute wouldn't make any sense here. That's why you would send a RelationshipAttributeQuery. Its properties are: + +| Name | Type | Description | +| ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| validFrom | `string` \| `undefined` | The start date of the time frame the returned Attribute should be valid in. | +| validTo | `string` \| `undefined` | The end date of the time frame the returned Attribute should be valid in. | +| key | `string` | The key of the Relationship Attribute that should be queried. | +| owner | `string` | The owner of the queried Relationship Attribute. | +| attributeCreationHints | [`RelationshipAttributeCreationHints`](#relationshipattributecreationhints) | Contains information about the value that will be created, like the value type or its confidentiality. | + +#### RelationshipAttributeCreationHints + +| Name | Type | Description | +| --------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| title | `string` | A short text describing the purpose of the Attribute that is about to be created. | +| description | `string` \| `undefined` | A long text describing the purpose of the Attribute that is about to be created. | +| valueType | `string` | The value type of the Attribute to be created (e.g. `"ProprietaryInteger"`, `"ProprietaryString"`, ...) | +| confidentiality | `"public"` \|`"protected"` \|`"private"` \| | The confidentiality of the Attribute to be created. See [`RelationshipAttribute`](#relationshipattribute) for a more detailed description of confidentialities. | +| valueHints | [`ValueHints`](#valuehints) \| `undefined` | Hints for validating the value, e.g. a regular expression or a min/max length. | + +#### ValueHints + +| Name | Type | Description | +| -------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| editHelp? | `string` | A help text you can use to describe the purpose of the Attribute. | +| min? | `number` | In case of a string: the minimum length of the string. In case of an integer: the minimum value. | +| max? | `number` | In case of a string: the maximum length of the string. In case of an integer: the maximum value. | +| pattern? | `string` | A [regular expression](https://en.wikipedia.org/wiki/Regular_expression) that is used to validate the value. Only applicable if the value is a string. | +| values? | [`ValueHintsValue`](#valuehintsvalue)`[]` | An array of allowed values. | +| defaultValue? | `string` \| `number` \| `boolean` | The default value that is used if no value is provided. | +| propertyHints? | `Record`](#valuehints) | A set of Value Hints of all properties. The key is the name of the property and the value a `ValueHints` object. Only applicable if the value is complex. | + +#### ValueHintsOverride + +Has the same properties as [`ValueHints`](#valuehints), except that all of them are optional. This type is used for some [Relationship Attribute values]({% link _docs_operate/63-attribute-values.md %}#relationship-attributes) + +#### ValueHintsValue + +| Name | Type | Description | +| ----------- | --------------------------------- | -------------------------------------------- | +| key | `string` \| `number` \| `boolean` | The actual value. | +| displayName | `string` | How the value should be displayed on the UI. | + +### ThirdPartyRelationshipAttributeQuery + +If you want to query Attributes the user has in the context of a Relationship with a third party, you can use the `ThirdPartyRelationshipAttributeQuery`. An example would be the query for the number of a bonus card managed by another company (like Payback). A ThirdPartyRelationshipAttributeQuery has the following properties: + +| Name | Type | Description | +| ---------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| validFrom | `string` \| `undefined` | The start date of the time frame the returned Attribute should be valid in. | +| validTo | `string` \| `undefined` | The end date of the time frame the returned Attribute should be valid in. | +| key | `string` | The key of the Relationship Attribute that should be queried. | +| owner | `string` | The owner of the queried Relationship Attribute. Can be an empty string (`""`), if the owner is unknown or you are querying from multiple thirdParties that could own the attribute. | +| thirdParty | `string[]` | The Address of the third parties the Relationship Attribute should be queried from. | + +## RelationshipTemplateContent + +Theoretically you can send any kind of data in a Relationship Template. However, if your peer uses the Enmeshed App, it will only be able to process Relationship Templates that contain a `RelationshipTemplateContent`, which looks like this: + +| Name | Type | Description | +| ---------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| title | `string` \| `undefined` | An optional, human readable title that should be rendered in the UI. | +| metadata | `object` \| `undefined` | Optional custom metadata that can be sent together with the Relationship Template. This property is meant purely for developers who operate with Enmeshed. They can write for example some kind of key into this property, which can be used later to identify the content of this Template. | +| onNewRelationship | [`Request`](#request) | The Request that should pop up to the user in case there is no Relationship yet. In this Request you can send Attributes of yourself the user needs to in order to know who's Template it is (e.g. company name, address, ...), as ask for Attributes of the user you need to know in the Relationship, or send some information you already know about the user, so it can be saved in its wallet (e.g. the customer id). | +| onExistingRelationship | [`Request`](#request) \| `undefined` | The Request that should pop up to the user in case a Relationship already exists. An example usage is a Request with an `AuthenticationRequestItem` for the sake of two-factor authentication. | + +## RelationshipCreationChangeRequestContent + +The naming on this one in combination with its `response` property is a bit confusing. Even though the `RelationshipCreationChangeRequestContent` contains the word "Request", it has a `response` property. +This is because in the context of Relationships, there are [Relationship Changes](#relationshipchange), which have a `request` and a `response` property. But caution: these have nothing to do with the Content-types `Request` and `Response`. + +| Name | Type | Description | +| -------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| response | [`Response`](#response) | The Response to the Request that was contained in the [RelationshipTemplateContent](#relationshiptemplatecontent) (either in the `onExistingRelationship` property or in the `onNewRelationship` property). | + +## Mail + +A Mail can be sent as the content of a [Message](#message). It is comparable with the classic email, so its properties should not contain any surprise. + +| Name | Type | Description | +| ------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- | +| to | `string[]` | The Enmeshed Addresses of the main recipients of this Mail. | +| cc | `string[]` \| `undefined` | The Enmeshed Addresses that should receive a copy of this Mail, additionally to the ones specified in `to`. | +| subject | `string` | The subject of the Mail. | +| body | `string` | The body of the Mail. | diff --git a/_docs_operate/62-request-items.md b/_docs_operate/62-request-items.md new file mode 100644 index 000000000..df898fbc3 --- /dev/null +++ b/_docs_operate/62-request-items.md @@ -0,0 +1,338 @@ +--- +title: "Request Items" +permalink: /operate/data-model-request-items +toc: true +--- + +All the RequestItems listed below inherit from the [RequestItem]({% link _docs_operate/61-data-model.md %}#requestitem) and are therefore sharing its properties. + +## AuthenticationRequestItem + +With this item the sender can request the peer for an authentication in a business context for a certain purpose. The peer can then decide to authenticate or not. This authentication is mostly short-lived and limited in time. + +### Examples {#authenticationrequestitem-examples} + +- Authentication for a login to a website +- Authentication for opening a door + +### Properties {#authenticationrequestitem-properties} + +| Name | Type | Description | +| ------- | ----------------------------- | -------------------------------------------------------------- | +| `@type` | `"AuthenticationRequestItem"` | Specifies the type of the RequestItem for internal processing. | + +### Response Parameters {#authenticationrequestitem-response} + +#### Item Properties {#authenticationrequestitem-response-itemproperties} + +- To accept this RequestItem an [AcceptResponseItem]({% link _docs_operate/61-data-model.md %}#acceptresponseitem) will be transferred. +- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. +- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. + +#### Parameters {#authenticationrequestitem-response-parameters} + +- To accept this RequestItem you can send `{ "accept": true }` as parameters. +- To reject this RequestItem you can send `{ "accept": false }` as parameters. + +## ConsentRequestItem + +With the ConsentRequestItem it is possible to request a consent of the peer to an arbitrary text and thus reach agreement on a certain non machine-processable context. + +To request an accept/reject decision from a peer to a free text, the ConsentRequestItem is used. + +Please do not use the ConsentRequestItem to submit tons of text to the peer Identity. It is meant to be a short consent or summary the user agrees to. Please move longer text to external websites. +The ConsentRequestItem is also not meant for contractual agreements. +{: .notice--info} + +### Examples {#consentrequestitem-examples} + +- "I hereby confirm that I have read the privacy terms of this cloud service and agree to them." +- "The provided EULA has been read and agreed to." +- "Yes, I have backed up all of my data of this PC and you can wipe it." +- "I opt in to the newsletter." + +### Properties {#consentrequestitem-properties} + +| Name | Type | Description | +| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"ConsentRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| `consent` | `string` | The textual consent the user needs to give. This is different to the title and description of the RequestItem, as the consent would be the actual statement the user agrees to. | +| `link` | `string` \| `undefined` | A link to a website which contains more information, like the EULA or privacy terms. | + +### Response Parameters {#consentrequestitem-response} + +#### Item Properties {#consentrequestitem-response-itemproperties} + +- To accept this RequestItem an [AcceptResponseItem]({% link _docs_operate/61-data-model.md %}#acceptresponseitem) will be transferred. +- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. +- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. + +#### Parameters {#consentrequestitem-response-parameters} + +- To accept this RequestItem you can send `{ "accept": true }` as parameters. +- To reject this RequestItem you can send `{ "accept": false }` as parameters. + +## CreateAttributeRequestItem + +If you want to create Identity- or RelationshipAttributes for the peer, the CreateAttributeRequestItem can be used. Please have a look at the ProposeAttributeRequestItem if the peer should be able to overwrite the Attribute. + +To create an Attribute with a fixed value defined by the sender, an Identity uses the CreateAttributeRequestItem. A fixed value in this case means, that the recipient is not allowed to change the value when accepting the request. + +### Examples {#createattributerequestitem-examples} + +- Share the corporate E-Mail Address of the peer to the peer +- Send a certificate of the peer to the peer, so that the peer is able to easily share it +- Create a RelationshipAttribute for the peer + +### Properties {#createattributerequestitem-properties} + +| Name | Type | Description | +| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `@type` | `"CreateAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to create for the peer within the Identity of the peer. | + +### Response {#createattributerequestitem-response} + +#### Item Properties {#createattributerequestitem-response-itemproperties} + +- To accept this RequestItem a `CreateAttributeAcceptResponseItem` will be transferred. + + | Name | Type | Description | + | ------------- | ------------------------------------- | -------------------------------- | + | `@type` | `"CreateAttributeAcceptResponseItem"` | The type of the ResponseItem. | + | `attributeId` | `string` | The id of the created Attribute. | + +- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. +- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. + +#### Parameters {#createattributerequestitem-response-parameters} + +- To accept this RequestItem you can send `{ "accept": true }` as parameters. +- To reject this RequestItem you can send `{ "accept": false }` as parameters. + +### Combinations and usage scenarios {#createattributerequestitem-combinationsandusagescenarios} + +| Attribute Type | Attribute Owner | Possible? | Automation | Examples/Reason | +| -------------- | --------------- | --------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identity | Sender | N | `N/A` | Use [ShareAttributeRequestItem](#shareattributerequestitem) instead. | +| Identity | Recipient | Y | `USER_DECISION` | University sends student his certificate (Propose would be inappropriate in this case, because the student should not be able to return his own value) | +| Identity | `` | Y | `USER_DECISION` | An empty owner defaults to an Attribute with owner=``. This is needed for Requests inside of Relationship Templates, since you don’t know the Enmeshed Address of your peer before the Relationship is established. | +| Relationship | Sender | Y | `AUTO_ACCEPT` | Company sends new customer his customer number. | +| Relationship | Recipient | Y | `USER_DECISION` | With this combination the **sender asks the recipient for the one-time permission** to write a Relationship Attribute once AND the **sender defined a value** which can either be accepted and stored, or rejected. Thus, the user cannot change the value by itself. | +| Relationship | `` | Y | `USER_DECISION` | An empty owner defaults to an Attribute with owner=``. This is needed for Requests inside of Relationship Templates, since you don’t know the Enmeshed Address of your peer before the Relationship is established. | + +## ProposeAttributeRequestItem + +The ProposeAttributeRequestItem is a combination of [ReadAttributeRequestItem](#readattributerequestitem) and [CreateAttributeRequestItem](#createattributerequestitem). The sender would like to receive a correct Attribute from the peer, thinks it has a possible value but the peer might overrule this value with an existing or new one. + +To create an Attribute with a value proposed by the sender, an Identity uses the ProposeAttributeRequestItem. A proposed value in this case means, that the recipient is allowed to change the value if accepting the request. + +### Examples {#proposeattributerequestitem-examples} + +- Onboard an existing customer to Enmeshed and propose the known private Attributes, like its name or address. +- Ask the user if a newsletter would be of interest and propose the opt-in. This could be stored as a RelationshipAttribute with owner = recipient and could then be changed by the recipient at will. + +### Properties {#proposeattributerequestitem-properties} + +| Name | Type | Description | +| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `@type` | `"ProposeAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute. | +| `query` | [`IdentityAttributeQuery`]({% link _docs_operate/61-data-model.md %}#identityattributequery) \| [`RelationshipAttributeQuery`]({% link _docs_operate/61-data-model.md %}#relationshipattributequery) \| [`ThirdPartyRelationshipAttributeQuery`]({% link _docs_operate/61-data-model.md %}#thirdpartyrelationshipattributequery) | The structured query of the Attribute the sender would like to receive. | + +### Response {#proposeattributerequestitem-response} + +#### Item Properties {#proposeattributerequestitem-response-itemproperties} + +- To accept this RequestItem a `ProposeAttributeAcceptResponseItem` will be transferred. + + | Name | Type | Description | + | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | `@type` | `"ProposeAttributeAcceptResponseItem"` | The type of the ResponseItem. | + | `attributeId` | `string` | The id of the created Attribute. | + | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute.
        The owner of the Attribute which is proposed can only be the recipient Identity. | + +- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. +- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. + +#### Parameters {#proposeattributerequestitem-response-parameters} + +- To accept this RequestItem you can send the following parameters. + + - If you want to create a new Attribute. + + | Name | Type | Description | + | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | + | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that shall be created. | + + - If you want to use the proposed Attribute. + + | Name | Type | Description | + | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | + | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that was provided in the RequestItem. | + + - If you want to use an existing Attribute. + + | Name | Type | Description | + | --------------------- | -------- | -------------------------------- | + | `existingAttributeId` | `string` | The id of the Attribute to send. | + +- To reject this RequestItem you can send `{ "accept": false }` as parameters. + +### Combinations and usage scenarios {#proposeattributerequestitem-combinationsandusagescenarios} + +| Attribute Type | Attribute Owner | Possible? | Automation | Examples/Reason | +| -------------- | --------------- | --------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identity | Sender | N | `N/A` | It makes no sense to propose own Attributes, use [ShareAttributeRequestItem](#shareattributerequestitem) instead. | +| Identity | Recipient | Y | `USER_DECISION` | Company sends name and address to new customer during its onboarding process. | +| Relationship | Sender | Y | `USER_DECISION` | With this combination the **sender gives the recipient the one-time permission** to write a Relationship Attribute once AND the **sender proposes a value** which might make sense as a default.
        Example: Electricity provider asks new customer for the electricity meter number and proposes a known number | +| Relationship | Recipient | Y | `USER_DECISION` | With this combination the **sender asks the recipient for the one-time permission** to write a Relationship Attribute once AND the **sender proposes a value** which might make sense as a default.
        Example: Asking for a newsletter subscription | + +## ReadAttributeRequestItem + +If you want to query an Identity's Attributes this is done with the ReadAttributeRequestItem. + +To query Attributes which are not known to the sender, an Identity uses the ReadAttributeRequestItem. + +### Examples {#readattributerequestitem-examples} + +- Optional query of the BirthDate, to congratulate on birthdays +- Required query of the Age, to check if alcohol may be bought +- Required query of the StreetAddress, to send an invoice to the recipient + +### Properties {#readattributerequestitem-properties} + +| Name | Type | Description | +| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| `@type` | `"ReadAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| `query` | [`IdentityAttributeQuery`]({% link _docs_operate/61-data-model.md %}#identityattributequery) \| [`RelationshipAttributeQuery`]({% link _docs_operate/61-data-model.md %}#relationshipattributequery) \| [`ThirdPartyRelationshipAttributeQuery`]({% link _docs_operate/61-data-model.md %}#thirdpartyrelationshipattributequery) | The structured query of the Attribute the sender would like to receive. | + +### Response {#readattributerequestitem-response} + +#### Item Properties {#readattributerequestitem-response-itemproperties} + +- To accept this RequestItem a `ReadAttributeAcceptResponseItem` will be transferred. + + | Name | Type | Description | + | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | + | `@type` | `"ReadAttributeAcceptResponseItem"` | The type of the ResponseItem. | + | `attributeId` | `string` | The id of the returned Attribute. | + | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that will be shared to the peer. | + +- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. +- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. + +#### Parameters {#readattributerequestitem-response-parameters} + +- To accept this RequestItem you can send the following parameters. + + - If you want to use an existing Attribute. + + | Name | Type | Description | + | --------------------- | -------- | -------------------------------- | + | `existingAttributeId` | `string` | The id of the Attribute to send. | + + - If you want to create a new Attribute. + + | Name | Type | Description | + | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | + | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that shall be created. | + +- To reject this RequestItem you can send `{ "accept": false }` as parameters. + +### Combinations and usage scenarios {#readattributerequestitem-combinationsandusagescenarios} + +| Attribute Type | Attribute Owner | Third Party | Possible? | Automation | Examples/Reason | +| -------------- | --------------- | ----------- | --------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identity | Sender | | N | `N/A` | It makes no sense to read own IdentityAttributes. | +| Identity | Recipient | | Y | `USER_DECISION` | Company asks customer for its delivery address | +| Relationship | Sender | | Y | `USER_DECISION` | With this combination the **sender gives the recipient the one-time permission** to write a Relationship Attribute once
        Example: Electricity provider asks new customers for electricity meter number | +| Relationship | Recipient | | Y | `USER_DECISION` | With this combination the **sender asks the recipient for the one-time permission** to write a Relationship Attribute
        Example: Company asks new customer to subscribe to the newsletter and proposes the subscription as default once | +| Relationship | Recipient | Third Party | Y | `USER DECISION / NOT ALLOWED` - depending on confidentiality | With this combination the **sender requests a Relationship Attribute from a Relationship between the recipient and a third party. The Attribute must be owned by the recipient**
        Example: A Social Network asks for Facebook privacy settings of a user to get senseful defaults of its own privacy settings | +| Relationship | Third Party | Third Party | Y | `USER DECISION / NOT ALLOWED` - depending on confidentiality | With this combination the **sender requests a Relationship Attribute from a Relationship between the recipient and a third party which is owned by the third party**
        Example: An online shop asks for the Payback Customer Id of a user to book the order on his account | + + + +## ShareAttributeRequestItem + +If you want to share the own DisplayName and possibly other Attributes this is done with the ShareAttributeRequestItem. + +To share own IdentityAttributes (owner = self) an Identity uses the ShareAttributeRequestItem. The Identity needs to create the IdentityAttribute separately before the Attribute can be shared. + +### Examples {#shareattributerequestitem-examples} + +- Share own DisplayName. +- Share own Address. +- Share customer number of company A with company B. + +### Properties {#shareattributerequestitem-properties} + +| Name | Type | Description | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"ShareAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | +| `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to share. This is not the LocalAttribute but the content data structure of the Attribute.
        The owner of the Attribute which should be shared can only be the sender Identity. | +| `sourceAttributeId` | `string` | The id of the LocalAttribute which is the source of the shared Attribute. This will be used later to reference the sourceAttribute from its shared copy. | + +### Response {#shareattributerequestitem-response} + +#### Item Properties {#shareattributerequestitem-response-itemproperties} + +- To accept this RequestItem a `RegisterAttributeListenerAcceptResponseItem` will be transferred. + + | Name | Type | Description | + | ------------- | ------------------------------------ | -------------------------------- | + | `@type` | `"ShareAttributeAcceptResponseItem"` | The type of the ResponseItem. | + | `attributeId` | `string` | The id of the created Attribute. | + +- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. +- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. + +#### Parameters {#shareattributerequestitem-response-parameters} + +- To accept this RequestItem you can send `{ "accept": true }` as parameters. +- To reject this RequestItem you can send `{ "accept": false }` as parameters. + +### Combinations and usage scenarios {#shareattributerequestitem-combinationsandusagescenarios} + +| Attribute Type | Attribute Owner | Possible? | Automation | Examples/Reason | +| -------------- | --------------- | --------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identity | Sender | Y | `AUTO ACCEPT` | Company sends new customer the address of the company | +| Identity | Recipient | N | `N/A` | It makes no sense to share the Attribute to the recipient, because he already owns it. | +| Identity | Third Party | N | `N/A` | You cannot share an Attribute of which you are not the owner. | +| Identity | `` | Y | `AUTO ACCEPT` | An empty owner defaults to an Attribute with owner=``. | +| Relationship | Sender | Y | `USER DECISION` / `NOT ALLOWED` (depending on confidentiality) | A user can share own RelationshipAttributes of any Relationship to any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public).
        Example: Share Customer ID from Company A with Company B (User is owner of RelationshipAttribute) | +| Relationship | Recipient | N | `N/A` | It makes no sense to share the Attribute to the recipient, because he already owns it. | +| Relationship | Third Party | Y | `USER DECISION` / `NOT ALLOWED` (depending on confidentiality) | A user can share RelationshipAttributes of any Relationship to any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public).
        Example: Share Customer ID from Company A with Company B (Company A is owner of RelationshipAttribute), e.g. Payback number | +| Relationship | `` | Y | `AUTO ACCEPT` | An empty owner defaults to an Attribute with owner=``. | diff --git a/_docs_operate/63-attribute-values.md b/_docs_operate/63-attribute-values.md new file mode 100644 index 000000000..51db8d5a8 --- /dev/null +++ b/_docs_operate/63-attribute-values.md @@ -0,0 +1,772 @@ +--- +title: "Attribute Values" +permalink: /operate/data-model-attribute-values +toc: true +--- + +Each [Attribute]({% link _docs_operate/61-data-model.md %}#attributes) contains an instance of an Attribute Value within its `value` property. There are different types of Attribute Values. The types define the value's structural definition, rendering information and validators. For example, an email address with the value `address@company.corp` is stored with the Attribute Value type [`EMailAddress`](#emailaddress), which defines + +- the data type of the actual value (a String) +- how it is validated (the pattern of an email address and a maximum length) +- information about how it can be rendered on the UI + +Enmeshed defines a standard set of possible Attribute Value types for Identities within the Enmeshed ecosystem and its meaning for the Identities. And every Identity can understand/use/fill/query these Attribute Value types of other Identities. + +Most Attribute Value types are atomic, which means that they have only one property called `value` (e.g. [`EMailAddress`](#emailaddress), [`DisplayName`](#displayname), [`PhoneNumber`](#phonenumber)). But there are also more complex Attribute Value types which consist of multiple properties with a strong correlation (e.g. [`StreetAddress`](#streetaddress), [`PersonName`](#personname)). These properties can (but don't have to) contain other Attribute Values. + +# Identity Attributes + +The Attribute Values in this chapter can only be used in an [Identity Attribute]({% link _docs_operate/61-data-model.md %}#identityattribute). + +## Affiliation + +A complex Attribute Value type which defines the affiliation of a person to an organization. Inside of the organization the person can have a role and it can be assigned to a specific unit inside of the organization. + +**Properties** + +| Name | Type | Required | Validation | +| ------------ | --------------- | :------: | --------------------------------------------------------- | +| `@type` | `"Affiliation"` | ✓ | | +| role | `string` | ✗ | see [`AffiliationRole`](#affiliationrole) | +| organization | `string` | ✓ | see [`AffiliationOrganization`](#affiliationorganization) | +| unit | `string` | ✗ | see [`AffiliationUnit`](#affiliationunit) | + +## AffiliationOrganization + +The organization the person is affiliated to. + +It is not recommended to send an AffiliationOrganization to another Identity by its own. Instead, send an [`Affiliation`](#affiliation) with the `organization` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | --------------------------- | :------: | ---------------- | +| `@type` | `"AffiliationOrganization"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +**Validation** + +## AffiliationRole + +The role the person has in the organization. + +It is not recommended to send an AffiliationRole to another Identity by its own. Instead, send an [`Affiliation`](#affiliation) with the `role` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------------- | :------: | ---------------- | +| `@type` | `"AffiliationRole"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## AffiliationUnit + +The organization unit the person is affiliated to. + +It is not recommended to send an AffiliationUnit to another Identity by its own. Instead, send an [`Affiliation`](#affiliation) with the `unit` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------------- | :------: | ---------------- | +| `@type` | `"AffiliationUnit"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## BirthCity + +The city of birth. + +It is not recommended to send a BirthCity to another Identity by its own. Instead, send a [`BirthPlace`](#birthplace) with the `city` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------- | :------: | ---------------- | +| `@type` | `"BirthCity"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## BirthCountry + +The country of birth. + +It is not recommended to send a BirthCountry to another Identity by its own. Instead, send a [`BirthPlace`](#birthplace) with the `country` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ---------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"BirthCountry"` | ✓ | | +| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | + +## BirthDate + +The birth date of a natural person. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------- | :------: | ------------------------------- | +| `@type` | `"BirthDate"` | ✓ | | +| `day` | `number` | ✓ | see [`BirthDay`](#birthday) | +| `month` | `number` | ✓ | see [`BirthMonth`](#birthmonth) | +| `year` | `number` | ✓ | see [`BirthYear`](#birthyear) | + +## BirthDay + +The day of birth. + +It is not recommended to send a BirthDay to another Identity by its own. Instead, send a [`BirthDate`](#birthdate) with the `day` property set. +{: .notice--warning} + +| Name | Type | Required | Validation | +| ------- | ------------ | :------: | --------------------------------------- | +| `@type` | `"BirthDay"` | ✓ | | +| `value` | `number` | ✓ | min: 1
        max: 31
        must be an integer | + +## BirthMonth + +The day of month. + +It is not recommended to send a BirthMonth to another Identity by its own. Instead, send a [`BirthDate`](#birthdate) with the `month` property set. +{: .notice--warning} + +| Name | Type | Required | Validation | +| ------- | -------------- | :------: | --------------------------------------- | +| `@type` | `"BirthMonth"` | ✓ | | +| `value` | `number` | ✓ | min: 1
        max: 12
        must be an integer | + +## BirthName + +The BirthName is the surname of the person at birth. Some countries allow changing the surname, thus the BirthName is also used as the identification. The BirthName is innate depending on your surname at birth. + +If this value is set, there has been a change of the surname throughout the life of the person. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------- | :------: | ---------------- | +| `@type` | `"BirthName"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## BirthPlace + +The BirthPlace consists of the BirthCity and BirthCountry and can optionally include a BirthState (e.g. if the BirthCity is ambiguous within the BirthCountry). + +**Properties** + +| Name | Type | Required | Validation | +| --------- | -------------- | :------: | ------------------------------- | +| `@type` | `"BirthPlace"` | ✓ | | +| `city` | `string` | ✓ see | [`BirthCity`](#birthcity) | +| `country` | `string` | ✓ see | [`BirthCountry`](#birthcountry) | +| `state` | `string` | ✗ see | [`BirthState`](#birthstate) | + +## BirthState + +The state of birth. + +It is not recommended to send a BirthState to another Identity by its own. Instead, send a [`BirthPlace`](#birthplace) with the `state` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | -------------- | :------: | ---------------- | +| `@type` | `"BirthState"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## BirthYear + +The year of birth in the Gregorian calendar. + +It is not recommended to send a BirthYear to another Identity by its own. Instead, send a [`BirthDate`](#birthdate) with the `year` property set. +{: .notice--warning} + +| Name | Type | Required | Validation | +| ------- | ------------- | :------: | ----------------------------------------- | +| `@type` | `"BirthYear"` | ✓ | | +| `value` | `number` | ✓ | min: 1
        max: 9999
        must be an integer | + +## Citizenship + +The Citizenship defines which country currently recognizes you as a citizen. Thus, the Citizenship usually refers to the country you have a passport from. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | --------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"Citizenship"` | ✓ | | +| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | + +## City + +The name of a city. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). + +It is not recommended to send a City to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `city` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | -------- | :------: | ---------------- | +| `@type` | `"City"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## CommunicationLanguage + +The CommunicationLanguage is an officially recognized language the person can communicate with. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------------------- | :------: | -------------------------------------------------------------------------------------- | +| `@type` | `"CommunicationLanguage"` | ✓ | | +| `value` | `string` | ✓ | only [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language codes | + +## Country + +A country code according to the standard "ISO 3166-1 alpha-2". This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). + +It is not recommended to send a Country to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `country` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ----------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"Country"` | ✓ | | +| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | + +## DeliveryBoxAddress + +A complex Attribute Value defining the components of a delivery box address. + +**Properties** + +| Name | Type | Required | Validation | +| --------------- | ---------------------- | :------: | --------------------------------- | +| `@type` | `"DeliveryBoxAddress"` | ✓ | | +| `recipient` | `string` | ✓ | max. length: 100 | +| `deliveryBoxId` | `string` | ✓ | max. length: 100 | +| `userId` | `string` | ✓ | max. length: 100 | +| `zipCode` | `string` | ✓ | see [`ZipCode`](#zipcode) | +| `city` | `string` | ✓ | see [`City`](#city) | +| `country` | `string` | ✓ | see [`Country`](#country) | +| `phoneNumber` | `string` | ✗ | see [`PhoneNumber`](#phonenumber) | +| `state` | `string` | ✗ | see [`State`](#state) | + +## DisplayName + +The Display Name is the textual representation of the natural or legal person. It is usually combined out of titles, names or legal statuses. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | --------------- | :------: | ---------------- | +| `@type` | `"DisplayName"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## EMailAddress + +The email address which can be used to reach the Identity over email systems. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ---------------- | :------: | ----------------------------------------------------------------------------------------- | +| `@type` | `"EMailAddress"` | ✓ | | +| `value` | `string` | ✓ | min. length: 3
        max. length: 100
        must match `^[A-Z0-9._%+-]+@[A-Z0-9.-]+.[A-Z]{2,}$` | + +## FaxNumber + +The telephone number which can be used to reach the Identity via fax systems. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------- | :------: | ----------------------------------------------------------------------------- | +| `@type` | `"FaxNumber"` | ✓ | | +| `value` | `string` | ✓ | min. length: 3
        max. length: 100
        must match `^[\d+\-x#*()/[\] ]{3,100}$` | + +## FileReference + +A FileReference is a link to an Enmeshed [`File`]({% link _docs_operate/61-data-model.md %}#files) and can be used to add a File as an Attribute of an Identity. One example for a use case is some kind of certificate. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ----------------- | :------: | ---------------- | +| `@type` | `"FileReference"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## GivenName + +The Given Name, also called first name or forename, is the name given to a person at birth which differentiates it from other family, tribe or community members. + +It is not recommended to send a GivenName to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `givenName` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------- | :------: | ---------------- | +| `@type` | `"GivenName"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## HonorificPrefix + +The honorific prefix of a person, e.g. 'Sir'. + +It is not recommended to send a HonorificPrefix to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `honorificPrefix` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------------- | :------: | ---------------- | +| `@type` | `"HonorificPrefix"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## HonorificSuffix + +The honorific suffix of a person, e.g. 'PhD' + +It is not recommended to send a HonorificSuffix to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `honorificSuffix` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------------- | :------: | ---------------- | +| `@type` | `"HonorificSuffix"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## HouseNumber + +A house number. This is usually used as part of a [`StreetAddress`](#streetaddress). + +It is not recommended to send a HouseNumber to another Identity by its own. Instead, send a [`StreetAddress`](#streetaddress) with the `houseNumber` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | --------------- | :------: | ---------------- | +| `@type` | `"HouseNumber"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## JobTitle + +A short phrase that describes the position an employee has within an organization. (e.g. "Senior Developer" in case of a software company). + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------ | :------: | ---------------- | +| `@type` | `"JobTitle"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## MiddleName + +In various cultures, a middle name is a portion of a personal name that is written between the person's first given name and their surname. + +It is not recommended to send a MiddleName to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `middleName` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | -------------- | :------: | ---------------- | +| `@type` | `"MiddleName"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## Nationality + +The Nationality is the citizenship of a person at birth. One cannot change the Nationality because it's innate. Thus, the Nationality refers usually to the country where you are born. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | --------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"Nationality"` | ✓ | | +| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | + +## PersonName + +The PersonName is a complex Attribute Value type consisting of the GivenName, MiddleName, Surname, HonorificSuffix and HonorificPrefix of a person. + +**Properties** + +| Name | Type | Required | Validation | +| ----------------- | -------------- | :------: | ----------------------------------------- | +| `@type` | `"PersonName"` | ✓ | | +| `givenName` | `string` | ✓ | see [`GivenName`](#givenname) | +| `middleName` | `string` | ✗ | see [`MiddleName`](#middlename) | +| `surname` | `string` | ✓ | see [`Surname`](#surname) | +| `honorificSuffix` | `string` | ✗ | see [`HonorificSuffix`](#honorificsuffix) | +| `honorificPrefix` | `string` | ✗ | see [`HonorificPrefix`](#honorificprefix) | + +## PhoneNumber + +The telephone number which can be used to reach the Identity via telephone. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | --------------- | :------: | ---------------- | +| `@type` | `"PhoneNumber"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## PostOfficeBoxAddress + +A complex Attribute Value defining the components of a post office box address. + +**Properties** + +| Name | Type | Required | Validation | +| ----------- | ------------------------ | :------: | ------------------------- | +| `@type` | `"PostOfficeBoxAddress"` | ✓ | | +| `recipient` | `string` | ✓ | max. length: 100 | +| `boxId` | `string` | ✓ | max. length: 100 | +| `zipCode` | `string` | ✓ | see [`ZipCode`](#zipcode) | +| `city` | `string` | ✓ | see [`City`](#city) | +| `country` | `string` | ✓ | see [`Country`](#country) | +| `state` | `string` | ✗ | see [`State`](#state) | + +## Pseudonym + +The officially registered pseudonym of a person. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ------------- | :------: | ---------------- | +| `@type` | `"Pseudonym"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## Sex + +The Sex is the biological, medical, or public gender of a natural person. + +Please be advised that the possible values are defined by the public laws and technical passport measures between countries.

        +We embrace the person’s own definition of its/her/his sexual and gender orientations. Therefore we have no “Gender” AttributeValueType (yet). We look forward in hearing your comments about this. +{: .notice--info} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | -------- | :------: | ------------------------------------------ | +| `@type` | `"Sex"` | ✓ | | +| `value` | `string` | ✓ | one of: `"intersex"`, `"female"`, `"male"` | + +## State + +The name of a state. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). + +It is not recommended to send a State to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `state` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | --------- | :------: | ---------------- | +| `@type` | `"State"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## Street + +A street name. This is usually used as part of a [`StreetAddress`](#streetaddress). + +It is not recommended to send a Street to another Identity by its own. Instead, send a [`StreetAddress`](#streetaddress) with the `street` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ---------- | :------: | ---------------- | +| `@type` | `"Street"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## StreetAddress + +A complex Attribute Value defining the components of a "normal" address. + +**Properties** + +| Name | Type | Required | Validation | +| ----------- | ----------------------- | :------: | --------------------------------- | +| `@type` | `"StreetAddress"` | ✓ | | +| `recipient` | `string` | ✓ | max. length: 100 | +| `street` | `string` | ✓ | see [`Street`](#street) | +| `houseNo` | `string` | ✓ | see [`HouseNumber`](#housenumber) | +| `zipCode` | `string` | ✓ | see [`ZipCode`](#zipcode) | +| `city` | `string` | ✓ | see [`City`](#city) | +| `country` | `string` | ✓ | see [`Country`](#country) | +| `state` | `string` \| `undefined` | ✓ | see [`State`](#state) | + +## Surname + +The Surname, also called family name or last name, is the portion of the personal name that indicates the family, tribe or community. + +It is not recommended to send a Surname to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `surname` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ----------- | :------: | ---------------- | +| `@type` | `"Surname"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +## Website + +The website of the person which can be used to get more information about the person. + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ----------- | :------: | ---------------------------------------------------------- | +| `@type` | `"Website"` | ✓ | | +| `value` | `string` | ✓ | min. length: 3
        max. length: 1024
        must be a valid URL | + +## ZipCode + +A zip code. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). + +It is not recommended to send a ZipCode to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `zipCode` property set. +{: .notice--warning} + +**Properties** + +| Name | Type | Required | Validation | +| ------- | ----------- | :------: | ---------------- | +| `@type` | `"ZipCode"` | ✓ | | +| `value` | `string` | ✓ | max. length: 100 | + +# Relationship Attributes + +The Attribute Values in this chapter can only be used in a [Relationship Attribute]({% link _docs_operate/61-data-model.md %}#relationshipattribute). Most of them are generic. You can recognize those by the prefix `Proprietary` (e.g. `ProprietaryInteger`, `ProprietaryString`, ...). In order to add some validation, you have the option to add [`valueHints`]({% link _docs_operate/61-data-model.md %}#valuehints). + +## Consent + +Represents the consent of a person to a specific topic. If you want to obtain a consent, you can send a [`ReadAttributeRequestItem`]({% link _docs_operate/62-request-items.md %}#readattributerequestitem) with a Consent-[RelationshipAttribute]({% link _docs_operate/61-data-model.md %}#relationshipattribute) where the owner is the peer. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ---------------------------------------------------------- | +| `@type` | `"Consent"` | ✓ | | +| `consent` | `string` | ✓ | max. length: 2000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `link` | `string` | ✗ | min. length: 3
        max. length: 1024
        must be a valid URL | + +## ProprietaryBoolean + +An arbitrary boolean value. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------- | +| `@type` | `"ProprietaryBoolean"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `boolean` | ✓ | | + +## ProprietaryCountry + +A two-letter country code according to [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | --------------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"ProprietaryCountry"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | + +## ProprietaryEMailAddress + +An email address. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------------------------------------------------------------------------------- | +| `@type` | `"ProprietaryEMailAddress"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `string` | ✓ | min. length: 3
        max. length: 100
        must match `^[A-Z0-9._%+-]+@[A-Z0-9.-]+.[A-Z]{2,}$` | + +## ProprietaryFileReference + +A FileReference is a link to an Enmeshed [`File`]({% link _docs_operate/61-data-model.md %}#files) and can be used to add a File as an Attribute of a Relationship. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------- | +| `@type` | `"ProprietaryFileReference"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `string` | ✓ | max. length: 100 | + +## ProprietaryFloat + +An arbitrary floating-point number. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------- | +| `@type` | `"ProprietaryFloat"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `number` | ✓ | | + +## ProprietaryHEXColor + +A hexadecimal color code. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ------------------------------------------------------------------------ | +| `@type` | `"ProprietaryHEXColor"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `string` | ✓ | min.length: 4
        must match `^#([0-9A-F]{3}){1,2}$`
        max. length: 100 | + +## ProprietaryInteger + +An arbitrary integer number. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ------------------ | +| `@type` | `"ProprietaryInteger"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `number` | ✓ | must be an integer | + +## ProprietaryJSON + +An arbitrary JSON value. The `value` property can contain any valid JSON structure (except `null`). + +For validation purposes, the `value` property is stringified using `JSON.stringify`. That string must not exceed the maximum length of 4096 characters. + +**Properties** + +| Name | Type | Required | Validation | +| ------------- | ------------------- | :------: | ----------------- | +| `@type` | `"ProprietaryJSON"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `value` | `unknown` | ✓ | max. length: 4096 | + +**Examples** + +```jsonc +{ + "@type": "ProprietaryJSON", + "title": "My JSON", + // length: 94 + "value": { + "foo": "bar", + "baz": 123, + "qux": true, + "quux": { + "corge": "grault" + }, + "garply": ["waldo", "fred", "plugh"] + } +} +``` + +```jsonc +{ + "@type": "ProprietaryJSON", + "title": "My JSON", + // length: 8 + "value": "a string" +} +``` + +```jsonc +{ + "@type": "ProprietaryJSON", + "title": "My JSON", + // length: 28 + "value": ["a string", 1, { "foo": "bar" }] +} +``` + +## ProprietaryLanguage + +A two-letter [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | -------------------------------------------------------------------------------------- | +| `@type` | `"ProprietaryLanguage"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `string` | ✓ | only [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language codes | + +## ProprietaryPhoneNumber + +A phone number. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------------------------------------------------------------------- | +| `@type` | `"ProprietaryPhoneNumber"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `string` | ✓ | min. length: 3
        max. length: 100
        must match `^[\d+\-x#*()/[\] ]{3,100}$` | + +## ProprietaryString + +An arbitrary string. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------- | +| `@type` | `"ProprietaryString"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `string` | ✓ | max. length: 100 | + +## ProprietaryURL + +A URL. + +**Properties** + +| Name | Type | Required | Validation | +| -------------------- | ------------------------------------------------------------------------------------ | :------: | ---------------------------------------------------------- | +| `@type` | `"ProprietaryURL"` | ✓ | | +| `title` | `string` | ✓ | max. length: 100 | +| `description` | `string` | ✗ | max. length: 1000 | +| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | +| `value` | `string` | ✓ | min. length: 3
        max. length: 1024
        must be a valid URL | diff --git a/_docs_operate/diagrams/Connector_API_!Template.pu b/_docs_operate/diagrams/Connector_API_!Template.pu new file mode 100644 index 000000000..fcf55cfbf --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_!Template.pu @@ -0,0 +1,28 @@ +@startuml Create Template +!include ../../assets/plantuml/styles.iuml + + + + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nPlatform" as backbone +participant "Enmeshed\nApp" as app +actor "User" as user + +== Prerequisites == +backbone <--> connector: Verified Enmeshed Corporate Identity +connector <--> user: Existing Enmeshed Relationship + + +== Template == + + + + + + + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_AcceptRelationshipRequest.pu b/_docs_operate/diagrams/Connector_API_AcceptRelationshipRequest.pu new file mode 100644 index 000000000..e2313329a --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_AcceptRelationshipRequest.pu @@ -0,0 +1,31 @@ +@startuml Connector_AcceptRelationshipRequest +!include ../../assets/plantuml/styles.iuml + +title Connector: Accept Relationship Request +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone + +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity + + +== Accept Relationship Request == + +-> backend ++: Start\n(with requestId,\nresponse content) +backend -> backend: Validate content +backend -> connector ++: PUT /RelationshipRequests/\n{requestId}/Accept\n- response content +connector -> connector: Validate input +connector -> connector: Encrypt response content\nwith request key +connector -> backbone ++: Create RelationshipRequestResponse\n- responseCipher +backbone -> backbone: Store request response +backbone --> connector: Returns relationshipId +backbone -> --: Forward response + +connector --> backend --: Returns relationship +<-- backend --: Stop\n(with relationship) +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_CreateRelationshipRequest.pu b/_docs_operate/diagrams/Connector_API_CreateRelationshipRequest.pu new file mode 100644 index 000000000..a7ed1e935 --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_CreateRelationshipRequest.pu @@ -0,0 +1,32 @@ +@startuml Connector_CreateRelationshipRequest +!include ../../assets/plantuml/styles.iuml + +title Connector: Create Relationship Request +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone + +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity + + +== Create Relationship Request == + +-> backend ++: Start\n(with requestContent,\ntemplateId) +backend -> backend: Validate content +backend -> connector ++: POST /RelationshipRequests\n- requestContent\n- templateId +connector -> connector: Validate input +connector -> connector: Prepare request +connector -> connector: Encrypt request content\nwith template exchange key +connector -> backbone ++: Create RelationshipRequest\n- requestCipher +backbone -> backbone: Store request +backbone --> connector: Returns requestId +backbone -> --: Communicate to\nother party +connector --> backend: Returns request +<-- backend --: Stop\n(with Request) + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_CreateTemplate.pu b/_docs_operate/diagrams/Connector_API_CreateTemplate.pu new file mode 100644 index 000000000..297ccca6d --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_CreateTemplate.pu @@ -0,0 +1,38 @@ +@startuml Connector_CreateTemplate +!include ../../assets/plantuml/styles.iuml + +title Connector: Create Template +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone + +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity + + +== Create Template == + +-> backend ++: Start\n(with User) +backend -> backend: Create template content\nfor User +backend -> connector ++: POST /RelationshipTemplates\n- content\n- expiresAt\n- maxNumberOfAllocations +connector -> connector: Validate input +connector -> connector: Encrypt template content\nwith random key +connector -> backbone ++: Create template\n- templateCipher\n- expiresAt\n- maxNumberOfAllocations +backbone -> backbone: Store template +backbone --> connector --: Returns templateId +connector --> backend --: Returns template +backend --> connector ++: POST /RelationshipTemplates/\n{templateId}/Token +connector -> connector: Create token content +connector -> connector: Encrypt token content with\nrandom key +connector -> backbone ++: Create token\n- tokenCipher\n- expiresAt +backbone -> backbone: Store token +backbone --> connector --: tokenId +connector -> connector: Create tokenReference +connector --> backend: Returns token, tokenReference +<-- backend --: Stop\n(with template & \ntoken for User) + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_GetMessage.pu b/_docs_operate/diagrams/Connector_API_GetMessage.pu new file mode 100644 index 000000000..2c24ce29b --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_GetMessage.pu @@ -0,0 +1,34 @@ +@startuml Connector_GetMessage +!include ../../assets/plantuml/styles.iuml + +title Connector: Get Message +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone +actor "Sender" as user + +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity +connector <-> user: Existing Enmeshed Relationship + +== Send Message == + +-> backend ++: Start\n(with sender id) +backend -> connector ++: GET /Messages\n- senderId + +connector -> backbone ++: Get messages +backbone -> backbone: Retrieve messages\nof sender +backbone --> connector --: Returns messages + +connector -> connector: Decrypt every message +connector -> connector: Validate every message + +connector --> backend --: Returns messages + +<-- backend --: Stop\n(with messages) + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_GetOpenRelationshipRequests.pu b/_docs_operate/diagrams/Connector_API_GetOpenRelationshipRequests.pu new file mode 100644 index 000000000..62fcfe465 --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_GetOpenRelationshipRequests.pu @@ -0,0 +1,33 @@ +@startuml Connector_GetOpenRelationshipRequests +!include ../../assets/plantuml/styles.iuml + +title Connector: Get Open Relationship Requests +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone + +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity + + +== Get Open Relationship Requests == + +-> backend ++: Start +backend -> connector ++: GET /RelationshipRequests\n/OpenIncoming + +connector -> backbone ++: Get relationship requests +backbone -> backbone: Retrieve requests +backbone --> connector --: Returns requests + +connector -> connector: Decrypt every request +connector -> connector: Validate every request + +connector --> backend --: Returns requests + +<-- backend --: Stop\n(with Requests) + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_GetTemplate.pu b/_docs_operate/diagrams/Connector_API_GetTemplate.pu new file mode 100644 index 000000000..412ac4106 --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_GetTemplate.pu @@ -0,0 +1,41 @@ +@startuml Connector_GetTemplate +!include ../../assets/plantuml/styles.iuml + +title Connector: Get Template +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone + +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity + + +== Get Template == + +-> backend ++: Start\n(with truncatedReference) +backend -> connector ++: POST /RelationshipTemplates\n- truncatedReference +connector -> connector: Validate input +connector -> connector: Extract tokenId and secretKey\nout of reference +connector -> connector: Validate tokenId and secretKey +connector -> backbone ++: Get token\n- tokenId +backbone -> backbone: Retrieve token +backbone --> connector --: Returns token + +connector -> connector: Decrypt token\nwith secretKey +connector -> connector: Validate token +connector -> connector: Extract templateId and templateKey\nout of token + +connector -> backbone ++: Get template\n- templateId +backbone -> backbone: Retrieve template +backbone --> connector --: Returns template +connector -> connector: Decrypt template\nwith templateKey +connector -> connector: Validate template + +connector --> backend: Returns template +<-- backend --: Stop\n(with Template) + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_PreRelationshipOverview.pu b/_docs_operate/diagrams/Connector_API_PreRelationshipOverview.pu new file mode 100644 index 000000000..f80d5456c --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_PreRelationshipOverview.pu @@ -0,0 +1,84 @@ +@startuml Connector_PreRelationshipOverview +!include ../../assets/plantuml/styles.iuml + + +title Connector: Pre-Relationship Overview + +footer Page %page% of %lastpage% +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Enmeshed\nApp" as app +participant "Browser" as browser +end box +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone + + + + +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity + + +== Pre-Relationship == + +-> browser++: Open Browser & Navigate +browser -> backend ++: Opens Website +backend <-> browser --: Websites & Session + +browser -> backend ++: \nLogin/Upgrade/Onboard + +backend -> backend: Create content\nfor user + +backend -> connector ++: \nCreate Template\nwith content & QR-Code + +connector -> backbone ++: Submit Template +backbone --> connector --: templateId +connector --> backend --: template, QR-Code + + +backend --> browser: Render QR-Code/Link +backend -- +-> app ++: Open App + +app -> browser: Scans QR-Code/ \nopens Link +browser --> app: Content +browser -- +app -> backbone++: \nFetch Token & Template +backbone --> app--: Returns Token & Template +app -> app: Show template with\npre-filled data + +newpage + +-> app: \nAccept template +app -> app: Bundle user content +app -> backbone ++: Submit RelationshipRequest with user content +backbone -> app : RelationshipRequest +backbone -> connector--: RelationshipRequest +connector ++ +connector -> backend++: New RelationshipRequest\ncontaining user details +connector -- +backend --> browser: Got request +backend -> backend: Validate content\n& create response +backend -> connector ++: Accept Request\nwith response +connector -> backbone ++: Accept Request\nwith response +backbone --> connector: Relationship + +connector --> backend: Relationship +connector -- +backend --> browser: Got relationship +backend -- + +backbone --> app: Relationship +backbone -- +app -- + +== Outcome == +browser <--> backend: Knowledge of\nEnmeshed Relationship +app <--> connector: Trusted, bi-directional Enmeshed relationship + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_ReceiveMessage.pu b/_docs_operate/diagrams/Connector_API_ReceiveMessage.pu new file mode 100644 index 000000000..169e27cd6 --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_ReceiveMessage.pu @@ -0,0 +1,65 @@ +@startuml Connector_ReceiveMessage +!include ../../assets/plantuml/styles.iuml + +title Connector: Receive Message +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone +actor "Sender" as user + +activate connector +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity +connector <-> user: Existing Enmeshed Relationship + + + +== Receive Message == + + +connector -> backbone ++: Regularly check for updates +backbone --> connector --: no updates + +... + +backbone <- user ++: Message to connector +backbone --> user --: Random + +... + +connector -> backbone ++: Regularly check for updates +backbone --> connector: New message +connector -> backbone: Fetch +backbone --> user: received\nby Recipient +backbone --> connector --: message + + +connector -> connector: Decrypt message + +connector -> connector: Validate message + +alt + connector <--> backend: Webhook enabled + connector -> backend ++: Forward message via webhook + backend -> backend: Process message + deactivate backend + ||| +end + +alt + connector <--> backend: Long-polling enabled + activate backend + loop + backend -> connector: POST /Synchronize + connector --> backend: Received changes + backend -> backend: Process changes + deactivate backend + ||| + end +end + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_ReceiveRelationshipRequest.pu b/_docs_operate/diagrams/Connector_API_ReceiveRelationshipRequest.pu new file mode 100644 index 000000000..58d1d2f22 --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_ReceiveRelationshipRequest.pu @@ -0,0 +1,35 @@ +@startuml Connector_ReceiveRelationshipRequest +!include ../../assets/plantuml/styles.iuml + +title Connector: Receive Relationship Request +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone + +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity + + +== Receive Relationship Request == + +backbone <- ++: Incoming request +backbone -> connector ++: Forward request +connector --> backbone: Received +backbone -> --: Request received + +connector -> connector: Decrypt request with\ntemplate key + +connector -> connector: Validate request + +connector -> backend ++: Forward request +connector-- + +backend -> backend: Validate request + +<- backend --: Forward request + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_SendMessage.pu b/_docs_operate/diagrams/Connector_API_SendMessage.pu new file mode 100644 index 000000000..a72692266 --- /dev/null +++ b/_docs_operate/diagrams/Connector_API_SendMessage.pu @@ -0,0 +1,33 @@ +@startuml Connector_SendMessage +!include ../../assets/plantuml/styles.iuml + +title Connector: Send Message +caption Copyright 2021, j&s-soft GmbH + +box "Organizations's Infrastructure" +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone +actor "Recipient" as user + +== Prerequisites == +backbone <-> connector: Verified Enmeshed Organization Identity +connector <-> user: Existing Enmeshed Relationship + +== Send Message == + +-> backend ++: Start\n(with recipients,\ncontent) +backend -> backend: Validate input +backend -> connector ++: POST /Messages\n- recipients\n- content +connector -> connector: Validate input +connector -> connector: Encrypt message for every recipient +connector -> backbone ++: Create Message\n- messageCipher +backbone -> backbone: Store message +backbone --> connector: Returns messageId, timestamp +backbone -> user--: Forward message + +connector --> backend --: Returns message +<-- backend --: Stop\n(with message) + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_Flow_CreateAuthToken.pu b/_docs_operate/diagrams/Connector_Flow_CreateAuthToken.pu new file mode 100644 index 000000000..ad62781af --- /dev/null +++ b/_docs_operate/diagrams/Connector_Flow_CreateAuthToken.pu @@ -0,0 +1,53 @@ +@startuml Core_CreateAuthToken +!include ../.plantuml/skins/sequence_diagram.iuml + +actor "User" as user +box "Consumer Landscape" + participant "Enmeshed\nApp" as app + participant "Browser" as browser +end box +participant "Enmeshed\nPlatform" as platform +box "Customer Landscape" + participant "Website" as website + participant "Enmeshed\nConnector" as connector +end box + +== Prerequisites == + +app <--> connector: Enmeshed Relationship +website <--> connector: Enmeshed Integration + +autonumber + +== Login from App == +user -> app ++: Open Customer\nWebsite +app -> platform ++: Get timestamp +platform --> app--: Returns timestamp and random id +note right +We have to ensure that +the provided signature +of the consumer was not +created in the past. + +Thus, the trusted Enmeshed +platform creates the +timestamps. +end note +app -> app: Signs random id +app -> app: Creates login token +app -> browser ++: Open Browser\nwith login token +app -- +browser -> website++: Open Website with login token +website -> connector++: Check login token +connector -> connector: Verify token\nsignature +connector -> platform++: Check random id +platform --> connector --: OK +connector -> website --: Login OK\nEnmeshed Address xyz +browser <--> website: Login Session for Enmeshed Address xyz + + + + + + +@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_Flow_UpgradeProfile.pu b/_docs_operate/diagrams/Connector_Flow_UpgradeProfile.pu new file mode 100644 index 000000000..7807680d3 --- /dev/null +++ b/_docs_operate/diagrams/Connector_Flow_UpgradeProfile.pu @@ -0,0 +1,102 @@ +@startuml Create Template +!include ../../assets/plantuml/styles.iuml + + + + +box "Organization's Infrastructure" +participant "Website" as website +participant "Business\nSystem" as backend +participant "Enmeshed\nConnector" as connector +end box +participant "Enmeshed\nBackbone" as backbone +participant "Enmeshed\nApp" as app +actor "User" as user + +== Rahmenbedinungen == +backbone <-> connector: Enmeshed Connector hat eine\ndigitale Identität der Organisation.\nEnmeshed Plattform kennt diese. +connector <-> backend: Bestehende Systeme sind\nüber Integrationsmodule\nmit Enmeshed Connector verbunden + + +== Enmeshed Onboarding == + +user -> website: Möchte Enmeshed Verknüpfung +activate website +website -> backend: Enmeshed Verknüpfung eingehen +activate backend +backend -> connector: Generiere Template für Nutzer\n(mit Nutzerdaten & Random Token) +backend -> backend: Verknüpft Random Token\nund SessionID +activate connector +connector -> connector: Template erzeugen\n& verschlüsseln +connector -> backbone: Verschlüsseltes Template\nregistrieren\n(Löschung nach x Minuten) +activate backbone +backbone --> connector: OK +deactivate backbone +connector --> backend: Template + Schlüssel\n(z.B. QR-Code/Link) +deactivate connector +backend --> website: QR-Code und Link +deactivate backend +website --> user: QR-Code und Link + + +user -> app: Installiert & startet Enmeshed App +activate app +app -> app: Erstellt Identität\n(falls keine vorhanden) +app -> backbone: Registriert Identität +activate backbone +backbone -> app: OK +deactivate backbone +app --> user: Lauffähig +user -> app: Scan QR-Code +app -> app: Lese QR-Code\n(TemplateId & Schlüssel) +app -> backbone: Lade Template +activate backbone +backbone -> app: Rückgabe Template +deactivate backbone +app -> app: Entschlüsselung\nTemplate +app --> user: Anzeige Template +user -> app: Annahme Template +app -> app: Daten aufbereiten\nEnmeshed Adresse\nevtl. Daten des Nutzers +app -> app: Beziehung vorbereiten +app -> app: Anfrage verschlüsseln +app -> backbone: Anfrage senden +activate backbone +backbone --> app: OK +app --> user: OK (müssen auf Annahme warten) +deactivate app +backbone -> connector: Anfrage senden +deactivate backbone +activate connector +connector -> connector: Anfrage entschlüsseln +connector -> connector: Anfrage prüfen +connector -> backend: Anfrage weitergeben +activate backend +backend -> backend: Mapping Enmeshed Adresse\nmit RandomToken\nmit UserID +backend -> website: Enmeshed Anfrage angekommen +website -> user: Enmeshed Anfrage angekommen +backend --> connector: OK +deactivate backend +connector -> connector: Beziehung vorbereiten +connector -> connector: Annahme verschlüsseln +connector -> backbone: Annahme versenden +activate backbone +backbone --> connector: OK +connector -> backend: Angenommen +activate backend +backend -> website: Angenommen +deactivate backend +backbone -> app: Annahme +deactivate backbone +activate app +app -> app: Annahme entschlüsseln +app -> app: Annahme prüfen +app <--> connector: Hello World + + + + + + + + +@enduml \ No newline at end of file diff --git a/_docs_operate/examples/docker-compose-with-existing-mongodb.yml b/_docs_operate/examples/docker-compose-with-existing-mongodb.yml new file mode 100644 index 000000000..94f669ead --- /dev/null +++ b/_docs_operate/examples/docker-compose-with-existing-mongodb.yml @@ -0,0 +1,14 @@ +# ATTENTION: Do NOT use this file in public or production scenarios! It may contain insecure or unstable configuration. + +services: + connector: + container_name: connector + image: ghcr.io/nmshd/connector: # specify a tag (e.g. 1.0.0) or use the latest tag + environment: + CUSTOM_CONFIG_LOCATION: "/config.json" + ports: + - :80 # define the port the connector should listen to on the host + volumes: + - /config.json:/config.json:ro + # - :/var/log/enmeshed-connector # select an existing directory of your choice where your log files should be saved + restart: on-failure diff --git a/_docs_operate/examples/docker-compose-with-ferretdb.yml b/_docs_operate/examples/docker-compose-with-ferretdb.yml new file mode 100644 index 000000000..f258100ac --- /dev/null +++ b/_docs_operate/examples/docker-compose-with-ferretdb.yml @@ -0,0 +1,39 @@ +# ATTENTION: Do NOT use this file in public or production scenarios! It may contain insecure or unstable configuration. + +services: + connector: + container_name: connector + image: ghcr.io/nmshd/connector: # specify a tag (e.g. 1.0.0) or use the 'latest' tag + environment: + CUSTOM_CONFIG_LOCATION: "/config.json" + ports: + - :80 # define the port the connector should listen to on the host + volumes: + - /config.json:/config.json:ro + # - :/var/log/enmeshed-connector # select an existing directory of your choice where your log files should be saved + depends_on: + - ferretdb + restart: on-failure + + postgres: + image: postgres + container_name: postgres + environment: + - POSTGRES_USER=user + - POSTGRES_PASSWORD=password + - POSTGRES_DB=ferretdb + restart: on-failure + + ferretdb: + image: ghcr.io/ferretdb/ferretdb:latest + container_name: ferretdb + restart: on-failure + environment: + FERRETDB_POSTGRESQL_URL: postgres://user:password@postgres:5432/ferretdb + FERRETDB_TELEMETRY: disable + FERRETDB_LOG_LEVEL: error + depends_on: + - postgres + +volumes: + mongodb_data: diff --git a/_docs_operate/examples/docker-compose-with-mongodb.yml b/_docs_operate/examples/docker-compose-with-mongodb.yml new file mode 100644 index 000000000..aa4756935 --- /dev/null +++ b/_docs_operate/examples/docker-compose-with-mongodb.yml @@ -0,0 +1,29 @@ +# ATTENTION: Do NOT use this file in public or production scenarios! It may contain insecure or unstable configuration. + +services: + connector: + container_name: connector + image: ghcr.io/nmshd/connector: # specify a tag (e.g. 1.0.0) or use the 'latest' tag + environment: + CUSTOM_CONFIG_LOCATION: "/config.json" + ports: + - :80 # define the port the connector should listen to on the host + volumes: + - /config.json:/config.json:ro + # - :/var/log/enmeshed-connector # select an existing directory of your choice where your log files should be saved + depends_on: + - mongodb + restart: on-failure + + mongodb: + container_name: mongodb + image: mongo + environment: + MONGO_INITDB_ROOT_USERNAME: + MONGO_INITDB_ROOT_PASSWORD: + volumes: + - mongodb_data:/data/db + restart: on-failure + +volumes: + mongodb_data: diff --git a/_docs_operate/examples/example.config.json b/_docs_operate/examples/example.config.json new file mode 100644 index 000000000..6fbd34aa8 --- /dev/null +++ b/_docs_operate/examples/example.config.json @@ -0,0 +1,22 @@ +{ + "transportLibrary": { + "platformClientId": " https://enmeshed.eu/operate/connector-configuration#transportlibrary>", + "platformClientSecret": " https://enmeshed.eu/operate/connector-configuration#transportlibrary>" + }, + "database": { + "connectionString": "mongodb://:@mongodb:27017/?authSource=admin&readPreference=primary&ssl=false", + "dbName": "demo" + }, + "infrastructure": { + "httpServer": { + "apiKey": " https://enmeshed.eu/operate/connector-configuration#httpserver>" + } + }, + "modules": { + "coreHttpApi": { + "docs": { + "enabled": false + } + } + } +} diff --git a/_docs_use/03-app-scenarios.md b/_docs_use/03-app-scenarios.md index aaf8a6003..e67f60604 100644 --- a/_docs_use/03-app-scenarios.md +++ b/_docs_use/03-app-scenarios.md @@ -4,6 +4,8 @@ permalink: /use/app-scenarios published: true --- + + - - - -{% assign scenarios = site.docs_scenarios | where: "type", "scenario" %} - - - - - - - - - {% for scenario in scenarios %} {% assign status = scenario.properties | map:"documentation status" %}{% if status contains "DONE" %}{% assign component = scenario.properties | map:"component" %}{% if component contains "Connector" %} - - - - - - {%- endif -%} {%- endif -%} {% endfor %} -
        Title -
        -
        Category ⌄
        -
          -
          -           		-
          -
          customer ⌄
          -
            -
            -             		-
            -
            Component ⌄
            -
              -
              -
              - {{ scenario.title }} - {{ scenario.properties | map:"category" }}{{ scenario.properties | map:"customer" }}{{ scenario.properties | map:"component" }}
              - - diff --git a/_docs_operate/31-connector-modules.md b/_docs_operate/31-connector-modules.md deleted file mode 100644 index b74411a95..000000000 --- a/_docs_operate/31-connector-modules.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Custom Connector Modules" -permalink: /operate/custom-connector-modules ---- - -> At the moment custom Connector Modules are not supported. diff --git a/_docs_operate/32-connector-events.md b/_docs_operate/32-connector-events.md deleted file mode 100644 index ab538fc7f..000000000 --- a/_docs_operate/32-connector-events.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Connector Events" -permalink: /operate/connector-events ---- - -| Event | Data | Description (This event is triggered when ...) | -| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| consumption.attributeCreated | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute was created manually or through a Request. | -| consumption.attributeDeleted | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute was deleted manually or through a Request. | -| consumption.attributeSucceded | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute was succeeded manually or through a Request. | -| consumption.attributeUpdated | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute was updated manually or through a Request. | -| consumption.incomingRequestReceived | [LocalRequest]({% link _docs_operate/61-data-model.md %}#LocalRequest) | ... an incoming Request was received either by loading a Relationship Template or by receiving a Message | -| consumption.incomingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an incoming Request has changed. | -| consumption.messageProcessed | [MessageProcessedEventData](#messageprocessedeventdata) | ... a Message was processed by Modules like the `RequestModule` or `DeciderModule`. | -| consumption.outgoingRequestCreated | [LocalRequest]({% link _docs_operate/61-data-model.md %}#LocalRequest) | ... an outgoing Request was created. | -| consumption.
              outgoingRequestFromRelationshipCreationChange
              CreatedAndCompleted | [LocalRequest]({% link _docs_operate/61-data-model.md %}#LocalRequest) | ... an outgoing Request was created and directly completed.
              This happens if the Response came in with a new Relationship. | -| consumption.outgoingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an outgoing Request has changed. | -| consumption.relationshipTemplateProcessed | [RelationshipTemplateProcessedEventData](#relationshiptemplateprocessedeventdata) | ... a RelationshipTemplate was processed by Modules like the `RequestModule` or `DeciderModule`. | -| consumption.sharedAttributeCopyCreated | [LocalAttribute]({% link _docs_operate/61-data-model.md %}#LocalAttribute) | ... an Attribute is copied for sharing with another identity. | -| transport.messageReceived | [Message]({% link _docs_operate/61-data-model.md %}#Message) | ... a Message is received during synchronization. | -| transport.messageSent | [Message]({% link _docs_operate/61-data-model.md %}#Message) | ... a Message was sent. | -| transport.peerRelationshipTemplateLoaded | [RelationshipTemplate]({% link _docs_operate/61-data-model.md %}#RelationshipTemplate) | ... a Relationship Template was loaded that belongs to another identity. | -| transport.relationshipChanged | [Relationship]({% link _docs_operate/61-data-model.md %}#Relationship) | ... a Relationship has changed. This can be due to one of the following cases:
              • you create a Relationship
              • you accept, reject or revoke a Relationship Change
              • a Relationship Change is received during synchronization | - -## Event structure - -Every event is structured as follows (TData depends on the actual event, e.g. `LocalAttribute`): - -```ts -interface Event { - namespace: string; - eventTargetAddress: string; - data: TData; -} -``` - -### RequestStatusChangedEventData - -> [LocalRequest]({% link _docs_operate/61-data-model.md %}#LocalRequest) - -```ts -export interface RequestStatusChangedEventData { - request: LocalRequest; - oldStatus: LocalRequestStatus; - newStatus: LocalRequestStatus; -} -``` - -### MessageProcessedEventData - -> [Message]({% link _docs_operate/61-data-model.md %}#Message) - -```ts -export interface MessageProcessedEventData { - message: MessageDTO; - result: "ManualRequestDecisionRequired" | "NoRequest" | "Error"; -} -``` - -### RelationshipTemplateProcessedEventData - -> [RelationshipTemplate]({% link _docs_operate/61-data-model.md %}#RelationshipTemplate) - -```ts -export interface RelationshipTemplateProcessedEventData { - template: RelationshipTemplateDTO; - result: "ManualRequestDecisionRequired" | "NonCompletedRequestExists" | "RelationshipExists" | "NoRequest" | "Error"; -} -``` diff --git a/_docs_operate/50-connector-migration-v2.md b/_docs_operate/50-connector-migration-v2.md deleted file mode 100644 index 51270c80a..000000000 --- a/_docs_operate/50-connector-migration-v2.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: "Migrate to v2" -permalink: /operate/connector-migration-v2 -toc: true ---- - -When migrating from v1 to v2, there are a few breaking changes, as well as a bunch of new features. This guide lists both of them and will help you migrate your integration coding. - -## Backwards incompatible data structure - -First and foremost, as we [already announced in our blog]({% link _posts/2022-06-27-announcing-enmeshed-v2.md %}), the underlying data structures of v2 are not compatible with the ones of v1 at all, and we are not planning to migrate any data. This means that before starting a v2 Connector, you need to make sure that the database is completely empty. You can achieve that e.g. by creating a new Docker volume for the MongoDB container or, if you host MongoDB outside of Docker, setting up a new MongoDB server. Of course, if you don't have any important data, you can also delete database. This will ensure that on startup of the Connector, a new Enmeshed Identity is created. After that, you can start to migrate your integration coding to v2. - -## Common - -There are two things that affect all HTTP routes: the route prefix and the error codes that are returned. - -### HTTP route prefix - -The prefix of each route of the Connector's HTTP API has changed from `/api/v1` to `/api/v2`. This means that you need to change all your API calls to the Connector to use the new prefix. - -### Error codes - -There are some error codes that have changed during our transition from v1 to v2. For a full list of error codes in v2, refer to [the corresponding page]({% link _docs_operate/13-connector-error-codes.md %}). - -## Attributes - -With v2 of Enmeshed, Attributes were completely revamped. We won't go into much detail here, but the following two paragraphs will give you links for further reading. - -**Data Model** - -You can find a description of Attributes in the [data model]({% link _docs_operate/61-data-model.md %}#attributes). - -**Endpoints** - -In order to manage Attributes with the Connector, the following endpoints exist (the endpoints listed below are interactive; feel free to execute them): -{% include rapidoc api_route_regex="/api/v2/Attributes" title="" %} - -Tip: go through the new [Connector tutorial]({% link _docs_operate/01-connector-tutorial.md %}) if you want an example of how to create An Attribute. -{: .notice--info} - -## Files - -There are a few minor changes to the data model and the endpoints for managing Files. - -**Data Model** - -The following properties were removed from the `File` entity: - -- `deletedAt` -- `deletedBy` -- `deletedByDevice` - -The reason for this is that these properties were added prematurely. At the moment it is not possible to delete files. This feature will be added in the future. But for now, we decided that the properties are misleading and removed them. - -There also is a new property named `truncatedReference`, which is similar to the `truncatedReference` of a Token. It is a short reference to a File containing its ID and secret key. In order to share the File with a user, you can either send the `truncatedReference` as text, or - even simpler - create a QR code for it with the new endpoint(see table below). When the user scans this QR code with the Enmeshed app, the File is automatically downloaded - No Relationship necessary. - -**Endpoints** - -The following endpoints have changed: - -| Route | Change Type | Description | -| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| POST /Files/Peer | Updated | You can now pass a `truncatedreference` of a File in the body of this endpoint. The other possibilities (id+secret key and a truncated Token reference) can still be used. | -| GET /Files/{id} | Updated | You can now pass a `truncated reference` of a File as the route parameter `id` (or `idOrReference`, as it is called now) of this endpoint. Of course, you can still pass an ID. | -| GET /Files/{id} | Updated | By setting the `Accept` HTTP header on this request to `image/png`, you can generate a QR code with the truncated File reference. | - -## Messages - -There are a few minor changes to the data model and the endpoints for managing Messages. - -**Data Model** - -The [recipient]({% link _docs_operate/61-data-model.md %}#recipient) of a `Message` now has the property `relationshipId`, which contains the ID of the Relationship the Connector has to the recipient. This is useful for example if you want to query all Messages that belong to a specific Relationship. - -**Endpoints** - -The following endpoints have changed: - -| Route | Change Type | Description | -| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| GET /Messages | Updated | As described above, there now is a `relationshipId` property on each object of the `recipients` array of a Message. You can use this property to filter for Messages of a specific Relationship by setting the query parameter `recipients.relationshipId` We further removed the query parameter `relationshipIds`, because it is not needed anymore. | - -## Relationships - -There are a few minor changes to the data model and the endpoints for managing Relationships. - -**Data Model** - -The following properties were removed from the `Relationship` entity: - -- `lastMessageReceivedAt` -- `lastMessageSentAt` - -These properties were never filled by the Runtime and were therefore removed. If you want for example the Relationships you sent a Message to in the last 24 hours, you can instead query the Messages and filter for the `createdAt` property in conjunction with createdBy set to your own Address. This gives you all the Messages you sent to in the last 24 hours. Now you just need to summarize the distinct `relationshipIds` of all these Messages. You can do similar to replace `lastMessageReceivedAt`. - -Further, we removed two Relationship status: - -- `Terminated`: Since we currently do not support termination of Relationships, we removed this status in order to reduce confusion. -- `Revoked`: With the introduction of Requests, we had to temporarily remove the possibility of revoking Relationship Creation Changes, because if the Response sent with the Relationship Creation Change was already created by the peer, this Response would have to be deleted as soon as the Relationship Creation Change was revoked - which is really hard to implement. In the future, revoking Relationship Creation Changes will probably be possible again, but at the moment this is not our top priority. - -**Endpoints** - -The following endpoints have changed: - -| Route | Change Type | Description | -| ------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| PUT /Relationships/{id}/Changes/{changeId}/Revoke | Removed | As described above, we removed the `Revoked` status of a Relationship. Therefore we also removed the endpoint that was responsible for moving a Relationship to this status. | -| GET /Relationships/{id}/Attributes | Added | This new route can be used to fetch all Attributes that exist in the context of the Relationship - so the ones you received from the peer as well as the ones you shared. | - -## Relationship Templates - -There are a few minor changes to the data model and the endpoints for managing Relationship Templates. - -**Data Model** - -The property `maxNumberOfRelationships` was removed from the `RelationshipTemplate` entity. It was replaced by the property `maxNumberOfAllocations` which offers similar functionality. The reason for this change is that with let's say a `maxNumberOfRelationships` of 5, it was possible for 10 users to download the Relationship Template and fill it out. But finally, when trying to create the Relationship, 5 of them would receive an error message, because the maximum number of Relationships is exhausted. This is why the Relationship Template now has the property `maxNumberOfAllocations`. Setting this property to e.g. 5 will ensure that the Template can only be fetched by 5 different Identities. The sixth will receive an error message when trying to fetch it, so it won't be able waste time by filling it out. - -There also is a new property named `truncatedReference`, which is similar to the `truncatedReference` of a Token. It allows you to create a reference to a Relationship Template containing its ID and secret key. With this, there is no need to create a Token for a the Relationship Template anymore. Just create a QR code for the Relationship Template directly (see the new endpoint below). When the user scans this QR code with the Enmeshed app, the Relationship Template is downloaded and displayed. - -**Endpoints** - -The following endpoints have changed: - -| Route | Change Type | Description | -| ------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| POST /RelationshipTemplates/Peer | Updated | You can now pass a `truncatedReference` of a Relationship Template in the body of this endpoint. The other possibilities (id+secret key and a truncated Token reference) can still be used. | -| GET /RelationshipTemplates/{id} | Updated | By setting the `Accept` HTTP header on this request to `image/png`, you can generate a QR code with the `truncatedReference` of the Relationship Template. | - -## Requests - -With v2 of Enmeshed, there is the new concept of "Requests", which are the new way to exchange Attributes between two Identities. And you can do a lot more with them. We won't go into much detail here, but the following two paragraphs will give you links for further reading. - -**Data Model** - -You can find a description of Requests in the [data model]({% link _docs_operate/61-data-model.md %}#request). Further, there is a [dedicated page]({% link _docs_operate/62-request-items.md %}) where you can find all existing Request Items. - -**Endpoints** - -In order to manage Requests with the Connector, the following endpoints exist: -{% include rapidoc api_route_regex="/api/v2/Requests" title="" %} - -Tip: go through the new [Connector tutorial]({% link _docs_operate/01-connector-tutorial.md %}) if you want an example of what you can do with Requests. -{: .notice--info} diff --git a/_docs_operate/62-request-items.md b/_docs_operate/62-request-items.md deleted file mode 100644 index df898fbc3..000000000 --- a/_docs_operate/62-request-items.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -title: "Request Items" -permalink: /operate/data-model-request-items -toc: true ---- - -All the RequestItems listed below inherit from the [RequestItem]({% link _docs_operate/61-data-model.md %}#requestitem) and are therefore sharing its properties. - -## AuthenticationRequestItem - -With this item the sender can request the peer for an authentication in a business context for a certain purpose. The peer can then decide to authenticate or not. This authentication is mostly short-lived and limited in time. - -### Examples {#authenticationrequestitem-examples} - -- Authentication for a login to a website -- Authentication for opening a door - -### Properties {#authenticationrequestitem-properties} - -| Name | Type | Description | -| ------- | ----------------------------- | -------------------------------------------------------------- | -| `@type` | `"AuthenticationRequestItem"` | Specifies the type of the RequestItem for internal processing. | - -### Response Parameters {#authenticationrequestitem-response} - -#### Item Properties {#authenticationrequestitem-response-itemproperties} - -- To accept this RequestItem an [AcceptResponseItem]({% link _docs_operate/61-data-model.md %}#acceptresponseitem) will be transferred. -- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. -- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. - -#### Parameters {#authenticationrequestitem-response-parameters} - -- To accept this RequestItem you can send `{ "accept": true }` as parameters. -- To reject this RequestItem you can send `{ "accept": false }` as parameters. - -## ConsentRequestItem - -With the ConsentRequestItem it is possible to request a consent of the peer to an arbitrary text and thus reach agreement on a certain non machine-processable context. - -To request an accept/reject decision from a peer to a free text, the ConsentRequestItem is used. - -Please do not use the ConsentRequestItem to submit tons of text to the peer Identity. It is meant to be a short consent or summary the user agrees to. Please move longer text to external websites. -The ConsentRequestItem is also not meant for contractual agreements. -{: .notice--info} - -### Examples {#consentrequestitem-examples} - -- "I hereby confirm that I have read the privacy terms of this cloud service and agree to them." -- "The provided EULA has been read and agreed to." -- "Yes, I have backed up all of my data of this PC and you can wipe it." -- "I opt in to the newsletter." - -### Properties {#consentrequestitem-properties} - -| Name | Type | Description | -| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"ConsentRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| `consent` | `string` | The textual consent the user needs to give. This is different to the title and description of the RequestItem, as the consent would be the actual statement the user agrees to. | -| `link` | `string` \| `undefined` | A link to a website which contains more information, like the EULA or privacy terms. | - -### Response Parameters {#consentrequestitem-response} - -#### Item Properties {#consentrequestitem-response-itemproperties} - -- To accept this RequestItem an [AcceptResponseItem]({% link _docs_operate/61-data-model.md %}#acceptresponseitem) will be transferred. -- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. -- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. - -#### Parameters {#consentrequestitem-response-parameters} - -- To accept this RequestItem you can send `{ "accept": true }` as parameters. -- To reject this RequestItem you can send `{ "accept": false }` as parameters. - -## CreateAttributeRequestItem - -If you want to create Identity- or RelationshipAttributes for the peer, the CreateAttributeRequestItem can be used. Please have a look at the ProposeAttributeRequestItem if the peer should be able to overwrite the Attribute. - -To create an Attribute with a fixed value defined by the sender, an Identity uses the CreateAttributeRequestItem. A fixed value in this case means, that the recipient is not allowed to change the value when accepting the request. - -### Examples {#createattributerequestitem-examples} - -- Share the corporate E-Mail Address of the peer to the peer -- Send a certificate of the peer to the peer, so that the peer is able to easily share it -- Create a RelationshipAttribute for the peer - -### Properties {#createattributerequestitem-properties} - -| Name | Type | Description | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -| `@type` | `"CreateAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to create for the peer within the Identity of the peer. | - -### Response {#createattributerequestitem-response} - -#### Item Properties {#createattributerequestitem-response-itemproperties} - -- To accept this RequestItem a `CreateAttributeAcceptResponseItem` will be transferred. - - | Name | Type | Description | - | ------------- | ------------------------------------- | -------------------------------- | - | `@type` | `"CreateAttributeAcceptResponseItem"` | The type of the ResponseItem. | - | `attributeId` | `string` | The id of the created Attribute. | - -- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. -- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. - -#### Parameters {#createattributerequestitem-response-parameters} - -- To accept this RequestItem you can send `{ "accept": true }` as parameters. -- To reject this RequestItem you can send `{ "accept": false }` as parameters. - -### Combinations and usage scenarios {#createattributerequestitem-combinationsandusagescenarios} - -| Attribute Type | Attribute Owner | Possible? | Automation | Examples/Reason | -| -------------- | --------------- | --------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identity | Sender | N | `N/A` | Use [ShareAttributeRequestItem](#shareattributerequestitem) instead. | -| Identity | Recipient | Y | `USER_DECISION` | University sends student his certificate (Propose would be inappropriate in this case, because the student should not be able to return his own value) | -| Identity | `` | Y | `USER_DECISION` | An empty owner defaults to an Attribute with owner=``. This is needed for Requests inside of Relationship Templates, since you don’t know the Enmeshed Address of your peer before the Relationship is established. | -| Relationship | Sender | Y | `AUTO_ACCEPT` | Company sends new customer his customer number. | -| Relationship | Recipient | Y | `USER_DECISION` | With this combination the **sender asks the recipient for the one-time permission** to write a Relationship Attribute once AND the **sender defined a value** which can either be accepted and stored, or rejected. Thus, the user cannot change the value by itself. | -| Relationship | `` | Y | `USER_DECISION` | An empty owner defaults to an Attribute with owner=``. This is needed for Requests inside of Relationship Templates, since you don’t know the Enmeshed Address of your peer before the Relationship is established. | - -## ProposeAttributeRequestItem - -The ProposeAttributeRequestItem is a combination of [ReadAttributeRequestItem](#readattributerequestitem) and [CreateAttributeRequestItem](#createattributerequestitem). The sender would like to receive a correct Attribute from the peer, thinks it has a possible value but the peer might overrule this value with an existing or new one. - -To create an Attribute with a value proposed by the sender, an Identity uses the ProposeAttributeRequestItem. A proposed value in this case means, that the recipient is allowed to change the value if accepting the request. - -### Examples {#proposeattributerequestitem-examples} - -- Onboard an existing customer to Enmeshed and propose the known private Attributes, like its name or address. -- Ask the user if a newsletter would be of interest and propose the opt-in. This could be stored as a RelationshipAttribute with owner = recipient and could then be changed by the recipient at will. - -### Properties {#proposeattributerequestitem-properties} - -| Name | Type | Description | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -| `@type` | `"ProposeAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute. | -| `query` | [`IdentityAttributeQuery`]({% link _docs_operate/61-data-model.md %}#identityattributequery) \| [`RelationshipAttributeQuery`]({% link _docs_operate/61-data-model.md %}#relationshipattributequery) \| [`ThirdPartyRelationshipAttributeQuery`]({% link _docs_operate/61-data-model.md %}#thirdpartyrelationshipattributequery) | The structured query of the Attribute the sender would like to receive. | - -### Response {#proposeattributerequestitem-response} - -#### Item Properties {#proposeattributerequestitem-response-itemproperties} - -- To accept this RequestItem a `ProposeAttributeAcceptResponseItem` will be transferred. - - | Name | Type | Description | - | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `@type` | `"ProposeAttributeAcceptResponseItem"` | The type of the ResponseItem. | - | `attributeId` | `string` | The id of the created Attribute. | - | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute.
              The owner of the Attribute which is proposed can only be the recipient Identity. | - -- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. -- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. - -#### Parameters {#proposeattributerequestitem-response-parameters} - -- To accept this RequestItem you can send the following parameters. - - - If you want to create a new Attribute. - - | Name | Type | Description | - | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | - | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that shall be created. | - - - If you want to use the proposed Attribute. - - | Name | Type | Description | - | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | - | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that was provided in the RequestItem. | - - - If you want to use an existing Attribute. - - | Name | Type | Description | - | --------------------- | -------- | -------------------------------- | - | `existingAttributeId` | `string` | The id of the Attribute to send. | - -- To reject this RequestItem you can send `{ "accept": false }` as parameters. - -### Combinations and usage scenarios {#proposeattributerequestitem-combinationsandusagescenarios} - -| Attribute Type | Attribute Owner | Possible? | Automation | Examples/Reason | -| -------------- | --------------- | --------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identity | Sender | N | `N/A` | It makes no sense to propose own Attributes, use [ShareAttributeRequestItem](#shareattributerequestitem) instead. | -| Identity | Recipient | Y | `USER_DECISION` | Company sends name and address to new customer during its onboarding process. | -| Relationship | Sender | Y | `USER_DECISION` | With this combination the **sender gives the recipient the one-time permission** to write a Relationship Attribute once AND the **sender proposes a value** which might make sense as a default.
              Example: Electricity provider asks new customer for the electricity meter number and proposes a known number | -| Relationship | Recipient | Y | `USER_DECISION` | With this combination the **sender asks the recipient for the one-time permission** to write a Relationship Attribute once AND the **sender proposes a value** which might make sense as a default.
              Example: Asking for a newsletter subscription | - -## ReadAttributeRequestItem - -If you want to query an Identity's Attributes this is done with the ReadAttributeRequestItem. - -To query Attributes which are not known to the sender, an Identity uses the ReadAttributeRequestItem. - -### Examples {#readattributerequestitem-examples} - -- Optional query of the BirthDate, to congratulate on birthdays -- Required query of the Age, to check if alcohol may be bought -- Required query of the StreetAddress, to send an invoice to the recipient - -### Properties {#readattributerequestitem-properties} - -| Name | Type | Description | -| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| `@type` | `"ReadAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| `query` | [`IdentityAttributeQuery`]({% link _docs_operate/61-data-model.md %}#identityattributequery) \| [`RelationshipAttributeQuery`]({% link _docs_operate/61-data-model.md %}#relationshipattributequery) \| [`ThirdPartyRelationshipAttributeQuery`]({% link _docs_operate/61-data-model.md %}#thirdpartyrelationshipattributequery) | The structured query of the Attribute the sender would like to receive. | - -### Response {#readattributerequestitem-response} - -#### Item Properties {#readattributerequestitem-response-itemproperties} - -- To accept this RequestItem a `ReadAttributeAcceptResponseItem` will be transferred. - - | Name | Type | Description | - | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | - | `@type` | `"ReadAttributeAcceptResponseItem"` | The type of the ResponseItem. | - | `attributeId` | `string` | The id of the returned Attribute. | - | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that will be shared to the peer. | - -- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. -- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. - -#### Parameters {#readattributerequestitem-response-parameters} - -- To accept this RequestItem you can send the following parameters. - - - If you want to use an existing Attribute. - - | Name | Type | Description | - | --------------------- | -------- | -------------------------------- | - | `existingAttributeId` | `string` | The id of the Attribute to send. | - - - If you want to create a new Attribute. - - | Name | Type | Description | - | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | - | `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute that shall be created. | - -- To reject this RequestItem you can send `{ "accept": false }` as parameters. - -### Combinations and usage scenarios {#readattributerequestitem-combinationsandusagescenarios} - -| Attribute Type | Attribute Owner | Third Party | Possible? | Automation | Examples/Reason | -| -------------- | --------------- | ----------- | --------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identity | Sender | | N | `N/A` | It makes no sense to read own IdentityAttributes. | -| Identity | Recipient | | Y | `USER_DECISION` | Company asks customer for its delivery address | -| Relationship | Sender | | Y | `USER_DECISION` | With this combination the **sender gives the recipient the one-time permission** to write a Relationship Attribute once
              Example: Electricity provider asks new customers for electricity meter number | -| Relationship | Recipient | | Y | `USER_DECISION` | With this combination the **sender asks the recipient for the one-time permission** to write a Relationship Attribute
              Example: Company asks new customer to subscribe to the newsletter and proposes the subscription as default once | -| Relationship | Recipient | Third Party | Y | `USER DECISION / NOT ALLOWED` - depending on confidentiality | With this combination the **sender requests a Relationship Attribute from a Relationship between the recipient and a third party. The Attribute must be owned by the recipient**
              Example: A Social Network asks for Facebook privacy settings of a user to get senseful defaults of its own privacy settings | -| Relationship | Third Party | Third Party | Y | `USER DECISION / NOT ALLOWED` - depending on confidentiality | With this combination the **sender requests a Relationship Attribute from a Relationship between the recipient and a third party which is owned by the third party**
              Example: An online shop asks for the Payback Customer Id of a user to book the order on his account | - - - -## ShareAttributeRequestItem - -If you want to share the own DisplayName and possibly other Attributes this is done with the ShareAttributeRequestItem. - -To share own IdentityAttributes (owner = self) an Identity uses the ShareAttributeRequestItem. The Identity needs to create the IdentityAttribute separately before the Attribute can be shared. - -### Examples {#shareattributerequestitem-examples} - -- Share own DisplayName. -- Share own Address. -- Share customer number of company A with company B. - -### Properties {#shareattributerequestitem-properties} - -| Name | Type | Description | -| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"ShareAttributeRequestItem"` | Specifies the type of the RequestItem for internal processing. | -| `attribute` | [`IdentityAttribute`]({% link _docs_operate/61-data-model.md %}#identityattribute) \| [`RelationshipAttribute`]({% link _docs_operate/61-data-model.md %}#relationshipattribute) | The IdentityAttribute or RelationshipAttribute to share. This is not the LocalAttribute but the content data structure of the Attribute.
              The owner of the Attribute which should be shared can only be the sender Identity. | -| `sourceAttributeId` | `string` | The id of the LocalAttribute which is the source of the shared Attribute. This will be used later to reference the sourceAttribute from its shared copy. | - -### Response {#shareattributerequestitem-response} - -#### Item Properties {#shareattributerequestitem-response-itemproperties} - -- To accept this RequestItem a `RegisterAttributeListenerAcceptResponseItem` will be transferred. - - | Name | Type | Description | - | ------------- | ------------------------------------ | -------------------------------- | - | `@type` | `"ShareAttributeAcceptResponseItem"` | The type of the ResponseItem. | - | `attributeId` | `string` | The id of the created Attribute. | - -- To reject this RequestItem a [RejectResponseItem]({% link _docs_operate/61-data-model.md %}#rejectresponseitem) will be transferred. -- In case of an error an [ErrorResponseItem]({% link _docs_operate/61-data-model.md %}#errorresponseitem) will be transferred. - -#### Parameters {#shareattributerequestitem-response-parameters} - -- To accept this RequestItem you can send `{ "accept": true }` as parameters. -- To reject this RequestItem you can send `{ "accept": false }` as parameters. - -### Combinations and usage scenarios {#shareattributerequestitem-combinationsandusagescenarios} - -| Attribute Type | Attribute Owner | Possible? | Automation | Examples/Reason | -| -------------- | --------------- | --------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identity | Sender | Y | `AUTO ACCEPT` | Company sends new customer the address of the company | -| Identity | Recipient | N | `N/A` | It makes no sense to share the Attribute to the recipient, because he already owns it. | -| Identity | Third Party | N | `N/A` | You cannot share an Attribute of which you are not the owner. | -| Identity | `` | Y | `AUTO ACCEPT` | An empty owner defaults to an Attribute with owner=``. | -| Relationship | Sender | Y | `USER DECISION` / `NOT ALLOWED` (depending on confidentiality) | A user can share own RelationshipAttributes of any Relationship to any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public).
              Example: Share Customer ID from Company A with Company B (User is owner of RelationshipAttribute) | -| Relationship | Recipient | N | `N/A` | It makes no sense to share the Attribute to the recipient, because he already owns it. | -| Relationship | Third Party | Y | `USER DECISION` / `NOT ALLOWED` (depending on confidentiality) | A user can share RelationshipAttributes of any Relationship to any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public).
              Example: Share Customer ID from Company A with Company B (Company A is owner of RelationshipAttribute), e.g. Payback number | -| Relationship | `` | Y | `AUTO ACCEPT` | An empty owner defaults to an Attribute with owner=``. | diff --git a/_docs_operate/63-attribute-values.md b/_docs_operate/63-attribute-values.md deleted file mode 100644 index 51db8d5a8..000000000 --- a/_docs_operate/63-attribute-values.md +++ /dev/null @@ -1,772 +0,0 @@ ---- -title: "Attribute Values" -permalink: /operate/data-model-attribute-values -toc: true ---- - -Each [Attribute]({% link _docs_operate/61-data-model.md %}#attributes) contains an instance of an Attribute Value within its `value` property. There are different types of Attribute Values. The types define the value's structural definition, rendering information and validators. For example, an email address with the value `address@company.corp` is stored with the Attribute Value type [`EMailAddress`](#emailaddress), which defines - -- the data type of the actual value (a String) -- how it is validated (the pattern of an email address and a maximum length) -- information about how it can be rendered on the UI - -Enmeshed defines a standard set of possible Attribute Value types for Identities within the Enmeshed ecosystem and its meaning for the Identities. And every Identity can understand/use/fill/query these Attribute Value types of other Identities. - -Most Attribute Value types are atomic, which means that they have only one property called `value` (e.g. [`EMailAddress`](#emailaddress), [`DisplayName`](#displayname), [`PhoneNumber`](#phonenumber)). But there are also more complex Attribute Value types which consist of multiple properties with a strong correlation (e.g. [`StreetAddress`](#streetaddress), [`PersonName`](#personname)). These properties can (but don't have to) contain other Attribute Values. - -# Identity Attributes - -The Attribute Values in this chapter can only be used in an [Identity Attribute]({% link _docs_operate/61-data-model.md %}#identityattribute). - -## Affiliation - -A complex Attribute Value type which defines the affiliation of a person to an organization. Inside of the organization the person can have a role and it can be assigned to a specific unit inside of the organization. - -**Properties** - -| Name | Type | Required | Validation | -| ------------ | --------------- | :------: | --------------------------------------------------------- | -| `@type` | `"Affiliation"` | ✓ | | -| role | `string` | ✗ | see [`AffiliationRole`](#affiliationrole) | -| organization | `string` | ✓ | see [`AffiliationOrganization`](#affiliationorganization) | -| unit | `string` | ✗ | see [`AffiliationUnit`](#affiliationunit) | - -## AffiliationOrganization - -The organization the person is affiliated to. - -It is not recommended to send an AffiliationOrganization to another Identity by its own. Instead, send an [`Affiliation`](#affiliation) with the `organization` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------------------------- | :------: | ---------------- | -| `@type` | `"AffiliationOrganization"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -**Validation** - -## AffiliationRole - -The role the person has in the organization. - -It is not recommended to send an AffiliationRole to another Identity by its own. Instead, send an [`Affiliation`](#affiliation) with the `role` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------------- | :------: | ---------------- | -| `@type` | `"AffiliationRole"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## AffiliationUnit - -The organization unit the person is affiliated to. - -It is not recommended to send an AffiliationUnit to another Identity by its own. Instead, send an [`Affiliation`](#affiliation) with the `unit` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------------- | :------: | ---------------- | -| `@type` | `"AffiliationUnit"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## BirthCity - -The city of birth. - -It is not recommended to send a BirthCity to another Identity by its own. Instead, send a [`BirthPlace`](#birthplace) with the `city` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ---------------- | -| `@type` | `"BirthCity"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## BirthCountry - -The country of birth. - -It is not recommended to send a BirthCountry to another Identity by its own. Instead, send a [`BirthPlace`](#birthplace) with the `country` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ---------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"BirthCountry"` | ✓ | | -| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | - -## BirthDate - -The birth date of a natural person. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ------------------------------- | -| `@type` | `"BirthDate"` | ✓ | | -| `day` | `number` | ✓ | see [`BirthDay`](#birthday) | -| `month` | `number` | ✓ | see [`BirthMonth`](#birthmonth) | -| `year` | `number` | ✓ | see [`BirthYear`](#birthyear) | - -## BirthDay - -The day of birth. - -It is not recommended to send a BirthDay to another Identity by its own. Instead, send a [`BirthDate`](#birthdate) with the `day` property set. -{: .notice--warning} - -| Name | Type | Required | Validation | -| ------- | ------------ | :------: | --------------------------------------- | -| `@type` | `"BirthDay"` | ✓ | | -| `value` | `number` | ✓ | min: 1
              max: 31
              must be an integer | - -## BirthMonth - -The day of month. - -It is not recommended to send a BirthMonth to another Identity by its own. Instead, send a [`BirthDate`](#birthdate) with the `month` property set. -{: .notice--warning} - -| Name | Type | Required | Validation | -| ------- | -------------- | :------: | --------------------------------------- | -| `@type` | `"BirthMonth"` | ✓ | | -| `value` | `number` | ✓ | min: 1
              max: 12
              must be an integer | - -## BirthName - -The BirthName is the surname of the person at birth. Some countries allow changing the surname, thus the BirthName is also used as the identification. The BirthName is innate depending on your surname at birth. - -If this value is set, there has been a change of the surname throughout the life of the person. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ---------------- | -| `@type` | `"BirthName"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## BirthPlace - -The BirthPlace consists of the BirthCity and BirthCountry and can optionally include a BirthState (e.g. if the BirthCity is ambiguous within the BirthCountry). - -**Properties** - -| Name | Type | Required | Validation | -| --------- | -------------- | :------: | ------------------------------- | -| `@type` | `"BirthPlace"` | ✓ | | -| `city` | `string` | ✓ see | [`BirthCity`](#birthcity) | -| `country` | `string` | ✓ see | [`BirthCountry`](#birthcountry) | -| `state` | `string` | ✗ see | [`BirthState`](#birthstate) | - -## BirthState - -The state of birth. - -It is not recommended to send a BirthState to another Identity by its own. Instead, send a [`BirthPlace`](#birthplace) with the `state` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | -------------- | :------: | ---------------- | -| `@type` | `"BirthState"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## BirthYear - -The year of birth in the Gregorian calendar. - -It is not recommended to send a BirthYear to another Identity by its own. Instead, send a [`BirthDate`](#birthdate) with the `year` property set. -{: .notice--warning} - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ----------------------------------------- | -| `@type` | `"BirthYear"` | ✓ | | -| `value` | `number` | ✓ | min: 1
              max: 9999
              must be an integer | - -## Citizenship - -The Citizenship defines which country currently recognizes you as a citizen. Thus, the Citizenship usually refers to the country you have a passport from. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"Citizenship"` | ✓ | | -| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | - -## City - -The name of a city. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). - -It is not recommended to send a City to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `city` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | -------- | :------: | ---------------- | -| `@type` | `"City"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## CommunicationLanguage - -The CommunicationLanguage is an officially recognized language the person can communicate with. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------------------- | :------: | -------------------------------------------------------------------------------------- | -| `@type` | `"CommunicationLanguage"` | ✓ | | -| `value` | `string` | ✓ | only [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language codes | - -## Country - -A country code according to the standard "ISO 3166-1 alpha-2". This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). - -It is not recommended to send a Country to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `country` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ----------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"Country"` | ✓ | | -| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | - -## DeliveryBoxAddress - -A complex Attribute Value defining the components of a delivery box address. - -**Properties** - -| Name | Type | Required | Validation | -| --------------- | ---------------------- | :------: | --------------------------------- | -| `@type` | `"DeliveryBoxAddress"` | ✓ | | -| `recipient` | `string` | ✓ | max. length: 100 | -| `deliveryBoxId` | `string` | ✓ | max. length: 100 | -| `userId` | `string` | ✓ | max. length: 100 | -| `zipCode` | `string` | ✓ | see [`ZipCode`](#zipcode) | -| `city` | `string` | ✓ | see [`City`](#city) | -| `country` | `string` | ✓ | see [`Country`](#country) | -| `phoneNumber` | `string` | ✗ | see [`PhoneNumber`](#phonenumber) | -| `state` | `string` | ✗ | see [`State`](#state) | - -## DisplayName - -The Display Name is the textual representation of the natural or legal person. It is usually combined out of titles, names or legal statuses. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------------- | :------: | ---------------- | -| `@type` | `"DisplayName"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## EMailAddress - -The email address which can be used to reach the Identity over email systems. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ---------------- | :------: | ----------------------------------------------------------------------------------------- | -| `@type` | `"EMailAddress"` | ✓ | | -| `value` | `string` | ✓ | min. length: 3
              max. length: 100
              must match `^[A-Z0-9._%+-]+@[A-Z0-9.-]+.[A-Z]{2,}$` | - -## FaxNumber - -The telephone number which can be used to reach the Identity via fax systems. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ----------------------------------------------------------------------------- | -| `@type` | `"FaxNumber"` | ✓ | | -| `value` | `string` | ✓ | min. length: 3
              max. length: 100
              must match `^[\d+\-x#*()/[\] ]{3,100}$` | - -## FileReference - -A FileReference is a link to an Enmeshed [`File`]({% link _docs_operate/61-data-model.md %}#files) and can be used to add a File as an Attribute of an Identity. One example for a use case is some kind of certificate. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ----------------- | :------: | ---------------- | -| `@type` | `"FileReference"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## GivenName - -The Given Name, also called first name or forename, is the name given to a person at birth which differentiates it from other family, tribe or community members. - -It is not recommended to send a GivenName to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `givenName` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ---------------- | -| `@type` | `"GivenName"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## HonorificPrefix - -The honorific prefix of a person, e.g. 'Sir'. - -It is not recommended to send a HonorificPrefix to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `honorificPrefix` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------------- | :------: | ---------------- | -| `@type` | `"HonorificPrefix"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## HonorificSuffix - -The honorific suffix of a person, e.g. 'PhD' - -It is not recommended to send a HonorificSuffix to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `honorificSuffix` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------------- | :------: | ---------------- | -| `@type` | `"HonorificSuffix"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## HouseNumber - -A house number. This is usually used as part of a [`StreetAddress`](#streetaddress). - -It is not recommended to send a HouseNumber to another Identity by its own. Instead, send a [`StreetAddress`](#streetaddress) with the `houseNumber` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------------- | :------: | ---------------- | -| `@type` | `"HouseNumber"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## JobTitle - -A short phrase that describes the position an employee has within an organization. (e.g. "Senior Developer" in case of a software company). - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------ | :------: | ---------------- | -| `@type` | `"JobTitle"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## MiddleName - -In various cultures, a middle name is a portion of a personal name that is written between the person's first given name and their surname. - -It is not recommended to send a MiddleName to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `middleName` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | -------------- | :------: | ---------------- | -| `@type` | `"MiddleName"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## Nationality - -The Nationality is the citizenship of a person at birth. One cannot change the Nationality because it's innate. Thus, the Nationality refers usually to the country where you are born. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"Nationality"` | ✓ | | -| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | - -## PersonName - -The PersonName is a complex Attribute Value type consisting of the GivenName, MiddleName, Surname, HonorificSuffix and HonorificPrefix of a person. - -**Properties** - -| Name | Type | Required | Validation | -| ----------------- | -------------- | :------: | ----------------------------------------- | -| `@type` | `"PersonName"` | ✓ | | -| `givenName` | `string` | ✓ | see [`GivenName`](#givenname) | -| `middleName` | `string` | ✗ | see [`MiddleName`](#middlename) | -| `surname` | `string` | ✓ | see [`Surname`](#surname) | -| `honorificSuffix` | `string` | ✗ | see [`HonorificSuffix`](#honorificsuffix) | -| `honorificPrefix` | `string` | ✗ | see [`HonorificPrefix`](#honorificprefix) | - -## PhoneNumber - -The telephone number which can be used to reach the Identity via telephone. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------------- | :------: | ---------------- | -| `@type` | `"PhoneNumber"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## PostOfficeBoxAddress - -A complex Attribute Value defining the components of a post office box address. - -**Properties** - -| Name | Type | Required | Validation | -| ----------- | ------------------------ | :------: | ------------------------- | -| `@type` | `"PostOfficeBoxAddress"` | ✓ | | -| `recipient` | `string` | ✓ | max. length: 100 | -| `boxId` | `string` | ✓ | max. length: 100 | -| `zipCode` | `string` | ✓ | see [`ZipCode`](#zipcode) | -| `city` | `string` | ✓ | see [`City`](#city) | -| `country` | `string` | ✓ | see [`Country`](#country) | -| `state` | `string` | ✗ | see [`State`](#state) | - -## Pseudonym - -The officially registered pseudonym of a person. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ------------- | :------: | ---------------- | -| `@type` | `"Pseudonym"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## Sex - -The Sex is the biological, medical, or public gender of a natural person. - -Please be advised that the possible values are defined by the public laws and technical passport measures between countries.

              -We embrace the person’s own definition of its/her/his sexual and gender orientations. Therefore we have no “Gender” AttributeValueType (yet). We look forward in hearing your comments about this. -{: .notice--info} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | -------- | :------: | ------------------------------------------ | -| `@type` | `"Sex"` | ✓ | | -| `value` | `string` | ✓ | one of: `"intersex"`, `"female"`, `"male"` | - -## State - -The name of a state. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). - -It is not recommended to send a State to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `state` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | --------- | :------: | ---------------- | -| `@type` | `"State"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## Street - -A street name. This is usually used as part of a [`StreetAddress`](#streetaddress). - -It is not recommended to send a Street to another Identity by its own. Instead, send a [`StreetAddress`](#streetaddress) with the `street` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ---------- | :------: | ---------------- | -| `@type` | `"Street"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## StreetAddress - -A complex Attribute Value defining the components of a "normal" address. - -**Properties** - -| Name | Type | Required | Validation | -| ----------- | ----------------------- | :------: | --------------------------------- | -| `@type` | `"StreetAddress"` | ✓ | | -| `recipient` | `string` | ✓ | max. length: 100 | -| `street` | `string` | ✓ | see [`Street`](#street) | -| `houseNo` | `string` | ✓ | see [`HouseNumber`](#housenumber) | -| `zipCode` | `string` | ✓ | see [`ZipCode`](#zipcode) | -| `city` | `string` | ✓ | see [`City`](#city) | -| `country` | `string` | ✓ | see [`Country`](#country) | -| `state` | `string` \| `undefined` | ✓ | see [`State`](#state) | - -## Surname - -The Surname, also called family name or last name, is the portion of the personal name that indicates the family, tribe or community. - -It is not recommended to send a Surname to another Identity by its own. Instead, send a [`PersonName`](#personname) with the `surname` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ----------- | :------: | ---------------- | -| `@type` | `"Surname"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -## Website - -The website of the person which can be used to get more information about the person. - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ----------- | :------: | ---------------------------------------------------------- | -| `@type` | `"Website"` | ✓ | | -| `value` | `string` | ✓ | min. length: 3
              max. length: 1024
              must be a valid URL | - -## ZipCode - -A zip code. This is usually used as part of a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress). - -It is not recommended to send a ZipCode to another Identity by its own. Instead, send a [`DeliveryBoxAddress`](#deliveryboxaddress), [`PostOfficeBoxAddress`](#postofficeboxaddress) or [`StreetAddress`](#streetaddress) with the `zipCode` property set. -{: .notice--warning} - -**Properties** - -| Name | Type | Required | Validation | -| ------- | ----------- | :------: | ---------------- | -| `@type` | `"ZipCode"` | ✓ | | -| `value` | `string` | ✓ | max. length: 100 | - -# Relationship Attributes - -The Attribute Values in this chapter can only be used in a [Relationship Attribute]({% link _docs_operate/61-data-model.md %}#relationshipattribute). Most of them are generic. You can recognize those by the prefix `Proprietary` (e.g. `ProprietaryInteger`, `ProprietaryString`, ...). In order to add some validation, you have the option to add [`valueHints`]({% link _docs_operate/61-data-model.md %}#valuehints). - -## Consent - -Represents the consent of a person to a specific topic. If you want to obtain a consent, you can send a [`ReadAttributeRequestItem`]({% link _docs_operate/62-request-items.md %}#readattributerequestitem) with a Consent-[RelationshipAttribute]({% link _docs_operate/61-data-model.md %}#relationshipattribute) where the owner is the peer. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ---------------------------------------------------------- | -| `@type` | `"Consent"` | ✓ | | -| `consent` | `string` | ✓ | max. length: 2000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `link` | `string` | ✗ | min. length: 3
              max. length: 1024
              must be a valid URL | - -## ProprietaryBoolean - -An arbitrary boolean value. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------- | -| `@type` | `"ProprietaryBoolean"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `boolean` | ✓ | | - -## ProprietaryCountry - -A two-letter country code according to [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | --------------------------------------------------------------------------------------------------------------------------- | -| `@type` | `"ProprietaryCountry"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `string` | ✓ | only [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country codes | - -## ProprietaryEMailAddress - -An email address. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------------------------------------------------------------------------------- | -| `@type` | `"ProprietaryEMailAddress"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `string` | ✓ | min. length: 3
              max. length: 100
              must match `^[A-Z0-9._%+-]+@[A-Z0-9.-]+.[A-Z]{2,}$` | - -## ProprietaryFileReference - -A FileReference is a link to an Enmeshed [`File`]({% link _docs_operate/61-data-model.md %}#files) and can be used to add a File as an Attribute of a Relationship. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------- | -| `@type` | `"ProprietaryFileReference"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `string` | ✓ | max. length: 100 | - -## ProprietaryFloat - -An arbitrary floating-point number. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------- | -| `@type` | `"ProprietaryFloat"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `number` | ✓ | | - -## ProprietaryHEXColor - -A hexadecimal color code. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ------------------------------------------------------------------------ | -| `@type` | `"ProprietaryHEXColor"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `string` | ✓ | min.length: 4
              must match `^#([0-9A-F]{3}){1,2}$`
              max. length: 100 | - -## ProprietaryInteger - -An arbitrary integer number. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ------------------ | -| `@type` | `"ProprietaryInteger"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `number` | ✓ | must be an integer | - -## ProprietaryJSON - -An arbitrary JSON value. The `value` property can contain any valid JSON structure (except `null`). - -For validation purposes, the `value` property is stringified using `JSON.stringify`. That string must not exceed the maximum length of 4096 characters. - -**Properties** - -| Name | Type | Required | Validation | -| ------------- | ------------------- | :------: | ----------------- | -| `@type` | `"ProprietaryJSON"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `value` | `unknown` | ✓ | max. length: 4096 | - -**Examples** - -```jsonc -{ - "@type": "ProprietaryJSON", - "title": "My JSON", - // length: 94 - "value": { - "foo": "bar", - "baz": 123, - "qux": true, - "quux": { - "corge": "grault" - }, - "garply": ["waldo", "fred", "plugh"] - } -} -``` - -```jsonc -{ - "@type": "ProprietaryJSON", - "title": "My JSON", - // length: 8 - "value": "a string" -} -``` - -```jsonc -{ - "@type": "ProprietaryJSON", - "title": "My JSON", - // length: 28 - "value": ["a string", 1, { "foo": "bar" }] -} -``` - -## ProprietaryLanguage - -A two-letter [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | -------------------------------------------------------------------------------------- | -| `@type` | `"ProprietaryLanguage"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `string` | ✓ | only [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language codes | - -## ProprietaryPhoneNumber - -A phone number. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------------------------------------------------------------------- | -| `@type` | `"ProprietaryPhoneNumber"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `string` | ✓ | min. length: 3
              max. length: 100
              must match `^[\d+\-x#*()/[\] ]{3,100}$` | - -## ProprietaryString - -An arbitrary string. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------- | -| `@type` | `"ProprietaryString"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `string` | ✓ | max. length: 100 | - -## ProprietaryURL - -A URL. - -**Properties** - -| Name | Type | Required | Validation | -| -------------------- | ------------------------------------------------------------------------------------ | :------: | ---------------------------------------------------------- | -| `@type` | `"ProprietaryURL"` | ✓ | | -| `title` | `string` | ✓ | max. length: 100 | -| `description` | `string` | ✗ | max. length: 1000 | -| `valueHintsOverride` | [`ValueHintsOverride`]({% link _docs_operate/61-data-model.md %}#valuehintsoverride) | ✗ | | -| `value` | `string` | ✓ | min. length: 3
              max. length: 1024
              must be a valid URL | diff --git a/_docs_operate/diagrams/Connector_API_!Template.pu b/_docs_operate/diagrams/Connector_API_!Template.pu deleted file mode 100644 index fcf55cfbf..000000000 --- a/_docs_operate/diagrams/Connector_API_!Template.pu +++ /dev/null @@ -1,28 +0,0 @@ -@startuml Create Template -!include ../../assets/plantuml/styles.iuml - - - - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nPlatform" as backbone -participant "Enmeshed\nApp" as app -actor "User" as user - -== Prerequisites == -backbone <--> connector: Verified Enmeshed Corporate Identity -connector <--> user: Existing Enmeshed Relationship - - -== Template == - - - - - - - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_AcceptRelationshipRequest.pu b/_docs_operate/diagrams/Connector_API_AcceptRelationshipRequest.pu deleted file mode 100644 index e2313329a..000000000 --- a/_docs_operate/diagrams/Connector_API_AcceptRelationshipRequest.pu +++ /dev/null @@ -1,31 +0,0 @@ -@startuml Connector_AcceptRelationshipRequest -!include ../../assets/plantuml/styles.iuml - -title Connector: Accept Relationship Request -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone - -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity - - -== Accept Relationship Request == - --> backend ++: Start\n(with requestId,\nresponse content) -backend -> backend: Validate content -backend -> connector ++: PUT /RelationshipRequests/\n{requestId}/Accept\n- response content -connector -> connector: Validate input -connector -> connector: Encrypt response content\nwith request key -connector -> backbone ++: Create RelationshipRequestResponse\n- responseCipher -backbone -> backbone: Store request response -backbone --> connector: Returns relationshipId -backbone -> --: Forward response - -connector --> backend --: Returns relationship -<-- backend --: Stop\n(with relationship) -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_CreateRelationshipRequest.pu b/_docs_operate/diagrams/Connector_API_CreateRelationshipRequest.pu deleted file mode 100644 index a7ed1e935..000000000 --- a/_docs_operate/diagrams/Connector_API_CreateRelationshipRequest.pu +++ /dev/null @@ -1,32 +0,0 @@ -@startuml Connector_CreateRelationshipRequest -!include ../../assets/plantuml/styles.iuml - -title Connector: Create Relationship Request -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone - -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity - - -== Create Relationship Request == - --> backend ++: Start\n(with requestContent,\ntemplateId) -backend -> backend: Validate content -backend -> connector ++: POST /RelationshipRequests\n- requestContent\n- templateId -connector -> connector: Validate input -connector -> connector: Prepare request -connector -> connector: Encrypt request content\nwith template exchange key -connector -> backbone ++: Create RelationshipRequest\n- requestCipher -backbone -> backbone: Store request -backbone --> connector: Returns requestId -backbone -> --: Communicate to\nother party -connector --> backend: Returns request -<-- backend --: Stop\n(with Request) - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_CreateTemplate.pu b/_docs_operate/diagrams/Connector_API_CreateTemplate.pu deleted file mode 100644 index 297ccca6d..000000000 --- a/_docs_operate/diagrams/Connector_API_CreateTemplate.pu +++ /dev/null @@ -1,38 +0,0 @@ -@startuml Connector_CreateTemplate -!include ../../assets/plantuml/styles.iuml - -title Connector: Create Template -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone - -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity - - -== Create Template == - --> backend ++: Start\n(with User) -backend -> backend: Create template content\nfor User -backend -> connector ++: POST /RelationshipTemplates\n- content\n- expiresAt\n- maxNumberOfAllocations -connector -> connector: Validate input -connector -> connector: Encrypt template content\nwith random key -connector -> backbone ++: Create template\n- templateCipher\n- expiresAt\n- maxNumberOfAllocations -backbone -> backbone: Store template -backbone --> connector --: Returns templateId -connector --> backend --: Returns template -backend --> connector ++: POST /RelationshipTemplates/\n{templateId}/Token -connector -> connector: Create token content -connector -> connector: Encrypt token content with\nrandom key -connector -> backbone ++: Create token\n- tokenCipher\n- expiresAt -backbone -> backbone: Store token -backbone --> connector --: tokenId -connector -> connector: Create tokenReference -connector --> backend: Returns token, tokenReference -<-- backend --: Stop\n(with template & \ntoken for User) - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_GetMessage.pu b/_docs_operate/diagrams/Connector_API_GetMessage.pu deleted file mode 100644 index 2c24ce29b..000000000 --- a/_docs_operate/diagrams/Connector_API_GetMessage.pu +++ /dev/null @@ -1,34 +0,0 @@ -@startuml Connector_GetMessage -!include ../../assets/plantuml/styles.iuml - -title Connector: Get Message -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone -actor "Sender" as user - -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity -connector <-> user: Existing Enmeshed Relationship - -== Send Message == - --> backend ++: Start\n(with sender id) -backend -> connector ++: GET /Messages\n- senderId - -connector -> backbone ++: Get messages -backbone -> backbone: Retrieve messages\nof sender -backbone --> connector --: Returns messages - -connector -> connector: Decrypt every message -connector -> connector: Validate every message - -connector --> backend --: Returns messages - -<-- backend --: Stop\n(with messages) - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_GetOpenRelationshipRequests.pu b/_docs_operate/diagrams/Connector_API_GetOpenRelationshipRequests.pu deleted file mode 100644 index 62fcfe465..000000000 --- a/_docs_operate/diagrams/Connector_API_GetOpenRelationshipRequests.pu +++ /dev/null @@ -1,33 +0,0 @@ -@startuml Connector_GetOpenRelationshipRequests -!include ../../assets/plantuml/styles.iuml - -title Connector: Get Open Relationship Requests -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone - -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity - - -== Get Open Relationship Requests == - --> backend ++: Start -backend -> connector ++: GET /RelationshipRequests\n/OpenIncoming - -connector -> backbone ++: Get relationship requests -backbone -> backbone: Retrieve requests -backbone --> connector --: Returns requests - -connector -> connector: Decrypt every request -connector -> connector: Validate every request - -connector --> backend --: Returns requests - -<-- backend --: Stop\n(with Requests) - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_GetTemplate.pu b/_docs_operate/diagrams/Connector_API_GetTemplate.pu deleted file mode 100644 index 412ac4106..000000000 --- a/_docs_operate/diagrams/Connector_API_GetTemplate.pu +++ /dev/null @@ -1,41 +0,0 @@ -@startuml Connector_GetTemplate -!include ../../assets/plantuml/styles.iuml - -title Connector: Get Template -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone - -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity - - -== Get Template == - --> backend ++: Start\n(with truncatedReference) -backend -> connector ++: POST /RelationshipTemplates\n- truncatedReference -connector -> connector: Validate input -connector -> connector: Extract tokenId and secretKey\nout of reference -connector -> connector: Validate tokenId and secretKey -connector -> backbone ++: Get token\n- tokenId -backbone -> backbone: Retrieve token -backbone --> connector --: Returns token - -connector -> connector: Decrypt token\nwith secretKey -connector -> connector: Validate token -connector -> connector: Extract templateId and templateKey\nout of token - -connector -> backbone ++: Get template\n- templateId -backbone -> backbone: Retrieve template -backbone --> connector --: Returns template -connector -> connector: Decrypt template\nwith templateKey -connector -> connector: Validate template - -connector --> backend: Returns template -<-- backend --: Stop\n(with Template) - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_PreRelationshipOverview.pu b/_docs_operate/diagrams/Connector_API_PreRelationshipOverview.pu deleted file mode 100644 index f80d5456c..000000000 --- a/_docs_operate/diagrams/Connector_API_PreRelationshipOverview.pu +++ /dev/null @@ -1,84 +0,0 @@ -@startuml Connector_PreRelationshipOverview -!include ../../assets/plantuml/styles.iuml - - -title Connector: Pre-Relationship Overview - -footer Page %page% of %lastpage% -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Enmeshed\nApp" as app -participant "Browser" as browser -end box -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone - - - - -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity - - -== Pre-Relationship == - --> browser++: Open Browser & Navigate -browser -> backend ++: Opens Website -backend <-> browser --: Websites & Session - -browser -> backend ++: \nLogin/Upgrade/Onboard - -backend -> backend: Create content\nfor user - -backend -> connector ++: \nCreate Template\nwith content & QR-Code - -connector -> backbone ++: Submit Template -backbone --> connector --: templateId -connector --> backend --: template, QR-Code - - -backend --> browser: Render QR-Code/Link -backend -- --> app ++: Open App - -app -> browser: Scans QR-Code/ \nopens Link -browser --> app: Content -browser -- -app -> backbone++: \nFetch Token & Template -backbone --> app--: Returns Token & Template -app -> app: Show template with\npre-filled data - -newpage - --> app: \nAccept template -app -> app: Bundle user content -app -> backbone ++: Submit RelationshipRequest with user content -backbone -> app : RelationshipRequest -backbone -> connector--: RelationshipRequest -connector ++ -connector -> backend++: New RelationshipRequest\ncontaining user details -connector -- -backend --> browser: Got request -backend -> backend: Validate content\n& create response -backend -> connector ++: Accept Request\nwith response -connector -> backbone ++: Accept Request\nwith response -backbone --> connector: Relationship - -connector --> backend: Relationship -connector -- -backend --> browser: Got relationship -backend -- - -backbone --> app: Relationship -backbone -- -app -- - -== Outcome == -browser <--> backend: Knowledge of\nEnmeshed Relationship -app <--> connector: Trusted, bi-directional Enmeshed relationship - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_ReceiveMessage.pu b/_docs_operate/diagrams/Connector_API_ReceiveMessage.pu deleted file mode 100644 index 169e27cd6..000000000 --- a/_docs_operate/diagrams/Connector_API_ReceiveMessage.pu +++ /dev/null @@ -1,65 +0,0 @@ -@startuml Connector_ReceiveMessage -!include ../../assets/plantuml/styles.iuml - -title Connector: Receive Message -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone -actor "Sender" as user - -activate connector -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity -connector <-> user: Existing Enmeshed Relationship - - - -== Receive Message == - - -connector -> backbone ++: Regularly check for updates -backbone --> connector --: no updates - -... - -backbone <- user ++: Message to connector -backbone --> user --: Random - -... - -connector -> backbone ++: Regularly check for updates -backbone --> connector: New message -connector -> backbone: Fetch -backbone --> user: received\nby Recipient -backbone --> connector --: message - - -connector -> connector: Decrypt message - -connector -> connector: Validate message - -alt - connector <--> backend: Webhook enabled - connector -> backend ++: Forward message via webhook - backend -> backend: Process message - deactivate backend - ||| -end - -alt - connector <--> backend: Long-polling enabled - activate backend - loop - backend -> connector: POST /Synchronize - connector --> backend: Received changes - backend -> backend: Process changes - deactivate backend - ||| - end -end - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_ReceiveRelationshipRequest.pu b/_docs_operate/diagrams/Connector_API_ReceiveRelationshipRequest.pu deleted file mode 100644 index 58d1d2f22..000000000 --- a/_docs_operate/diagrams/Connector_API_ReceiveRelationshipRequest.pu +++ /dev/null @@ -1,35 +0,0 @@ -@startuml Connector_ReceiveRelationshipRequest -!include ../../assets/plantuml/styles.iuml - -title Connector: Receive Relationship Request -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone - -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity - - -== Receive Relationship Request == - -backbone <- ++: Incoming request -backbone -> connector ++: Forward request -connector --> backbone: Received -backbone -> --: Request received - -connector -> connector: Decrypt request with\ntemplate key - -connector -> connector: Validate request - -connector -> backend ++: Forward request -connector-- - -backend -> backend: Validate request - -<- backend --: Forward request - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_API_SendMessage.pu b/_docs_operate/diagrams/Connector_API_SendMessage.pu deleted file mode 100644 index a72692266..000000000 --- a/_docs_operate/diagrams/Connector_API_SendMessage.pu +++ /dev/null @@ -1,33 +0,0 @@ -@startuml Connector_SendMessage -!include ../../assets/plantuml/styles.iuml - -title Connector: Send Message -caption Copyright 2021, j&s-soft GmbH - -box "Organizations's Infrastructure" -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone -actor "Recipient" as user - -== Prerequisites == -backbone <-> connector: Verified Enmeshed Organization Identity -connector <-> user: Existing Enmeshed Relationship - -== Send Message == - --> backend ++: Start\n(with recipients,\ncontent) -backend -> backend: Validate input -backend -> connector ++: POST /Messages\n- recipients\n- content -connector -> connector: Validate input -connector -> connector: Encrypt message for every recipient -connector -> backbone ++: Create Message\n- messageCipher -backbone -> backbone: Store message -backbone --> connector: Returns messageId, timestamp -backbone -> user--: Forward message - -connector --> backend --: Returns message -<-- backend --: Stop\n(with message) - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_Flow_CreateAuthToken.pu b/_docs_operate/diagrams/Connector_Flow_CreateAuthToken.pu deleted file mode 100644 index ad62781af..000000000 --- a/_docs_operate/diagrams/Connector_Flow_CreateAuthToken.pu +++ /dev/null @@ -1,53 +0,0 @@ -@startuml Core_CreateAuthToken -!include ../.plantuml/skins/sequence_diagram.iuml - -actor "User" as user -box "Consumer Landscape" - participant "Enmeshed\nApp" as app - participant "Browser" as browser -end box -participant "Enmeshed\nPlatform" as platform -box "Customer Landscape" - participant "Website" as website - participant "Enmeshed\nConnector" as connector -end box - -== Prerequisites == - -app <--> connector: Enmeshed Relationship -website <--> connector: Enmeshed Integration - -autonumber - -== Login from App == -user -> app ++: Open Customer\nWebsite -app -> platform ++: Get timestamp -platform --> app--: Returns timestamp and random id -note right -We have to ensure that -the provided signature -of the consumer was not -created in the past. - -Thus, the trusted Enmeshed -platform creates the -timestamps. -end note -app -> app: Signs random id -app -> app: Creates login token -app -> browser ++: Open Browser\nwith login token -app -- -browser -> website++: Open Website with login token -website -> connector++: Check login token -connector -> connector: Verify token\nsignature -connector -> platform++: Check random id -platform --> connector --: OK -connector -> website --: Login OK\nEnmeshed Address xyz -browser <--> website: Login Session for Enmeshed Address xyz - - - - - - -@enduml \ No newline at end of file diff --git a/_docs_operate/diagrams/Connector_Flow_UpgradeProfile.pu b/_docs_operate/diagrams/Connector_Flow_UpgradeProfile.pu deleted file mode 100644 index 7807680d3..000000000 --- a/_docs_operate/diagrams/Connector_Flow_UpgradeProfile.pu +++ /dev/null @@ -1,102 +0,0 @@ -@startuml Create Template -!include ../../assets/plantuml/styles.iuml - - - - -box "Organization's Infrastructure" -participant "Website" as website -participant "Business\nSystem" as backend -participant "Enmeshed\nConnector" as connector -end box -participant "Enmeshed\nBackbone" as backbone -participant "Enmeshed\nApp" as app -actor "User" as user - -== Rahmenbedinungen == -backbone <-> connector: Enmeshed Connector hat eine\ndigitale Identität der Organisation.\nEnmeshed Plattform kennt diese. -connector <-> backend: Bestehende Systeme sind\nüber Integrationsmodule\nmit Enmeshed Connector verbunden - - -== Enmeshed Onboarding == - -user -> website: Möchte Enmeshed Verknüpfung -activate website -website -> backend: Enmeshed Verknüpfung eingehen -activate backend -backend -> connector: Generiere Template für Nutzer\n(mit Nutzerdaten & Random Token) -backend -> backend: Verknüpft Random Token\nund SessionID -activate connector -connector -> connector: Template erzeugen\n& verschlüsseln -connector -> backbone: Verschlüsseltes Template\nregistrieren\n(Löschung nach x Minuten) -activate backbone -backbone --> connector: OK -deactivate backbone -connector --> backend: Template + Schlüssel\n(z.B. QR-Code/Link) -deactivate connector -backend --> website: QR-Code und Link -deactivate backend -website --> user: QR-Code und Link - - -user -> app: Installiert & startet Enmeshed App -activate app -app -> app: Erstellt Identität\n(falls keine vorhanden) -app -> backbone: Registriert Identität -activate backbone -backbone -> app: OK -deactivate backbone -app --> user: Lauffähig -user -> app: Scan QR-Code -app -> app: Lese QR-Code\n(TemplateId & Schlüssel) -app -> backbone: Lade Template -activate backbone -backbone -> app: Rückgabe Template -deactivate backbone -app -> app: Entschlüsselung\nTemplate -app --> user: Anzeige Template -user -> app: Annahme Template -app -> app: Daten aufbereiten\nEnmeshed Adresse\nevtl. Daten des Nutzers -app -> app: Beziehung vorbereiten -app -> app: Anfrage verschlüsseln -app -> backbone: Anfrage senden -activate backbone -backbone --> app: OK -app --> user: OK (müssen auf Annahme warten) -deactivate app -backbone -> connector: Anfrage senden -deactivate backbone -activate connector -connector -> connector: Anfrage entschlüsseln -connector -> connector: Anfrage prüfen -connector -> backend: Anfrage weitergeben -activate backend -backend -> backend: Mapping Enmeshed Adresse\nmit RandomToken\nmit UserID -backend -> website: Enmeshed Anfrage angekommen -website -> user: Enmeshed Anfrage angekommen -backend --> connector: OK -deactivate backend -connector -> connector: Beziehung vorbereiten -connector -> connector: Annahme verschlüsseln -connector -> backbone: Annahme versenden -activate backbone -backbone --> connector: OK -connector -> backend: Angenommen -activate backend -backend -> website: Angenommen -deactivate backend -backbone -> app: Annahme -deactivate backbone -activate app -app -> app: Annahme entschlüsseln -app -> app: Annahme prüfen -app <--> connector: Hello World - - - - - - - - -@enduml \ No newline at end of file diff --git a/_docs_operate/examples/docker-compose-with-existing-mongodb.yml b/_docs_operate/examples/docker-compose-with-existing-mongodb.yml deleted file mode 100644 index 94f669ead..000000000 --- a/_docs_operate/examples/docker-compose-with-existing-mongodb.yml +++ /dev/null @@ -1,14 +0,0 @@ -# ATTENTION: Do NOT use this file in public or production scenarios! It may contain insecure or unstable configuration. - -services: - connector: - container_name: connector - image: ghcr.io/nmshd/connector: # specify a tag (e.g. 1.0.0) or use the latest tag - environment: - CUSTOM_CONFIG_LOCATION: "/config.json" - ports: - - :80 # define the port the connector should listen to on the host - volumes: - - /config.json:/config.json:ro - # - :/var/log/enmeshed-connector # select an existing directory of your choice where your log files should be saved - restart: on-failure diff --git a/_docs_operate/examples/docker-compose-with-ferretdb.yml b/_docs_operate/examples/docker-compose-with-ferretdb.yml deleted file mode 100644 index f258100ac..000000000 --- a/_docs_operate/examples/docker-compose-with-ferretdb.yml +++ /dev/null @@ -1,39 +0,0 @@ -# ATTENTION: Do NOT use this file in public or production scenarios! It may contain insecure or unstable configuration. - -services: - connector: - container_name: connector - image: ghcr.io/nmshd/connector: # specify a tag (e.g. 1.0.0) or use the 'latest' tag - environment: - CUSTOM_CONFIG_LOCATION: "/config.json" - ports: - - :80 # define the port the connector should listen to on the host - volumes: - - /config.json:/config.json:ro - # - :/var/log/enmeshed-connector # select an existing directory of your choice where your log files should be saved - depends_on: - - ferretdb - restart: on-failure - - postgres: - image: postgres - container_name: postgres - environment: - - POSTGRES_USER=user - - POSTGRES_PASSWORD=password - - POSTGRES_DB=ferretdb - restart: on-failure - - ferretdb: - image: ghcr.io/ferretdb/ferretdb:latest - container_name: ferretdb - restart: on-failure - environment: - FERRETDB_POSTGRESQL_URL: postgres://user:password@postgres:5432/ferretdb - FERRETDB_TELEMETRY: disable - FERRETDB_LOG_LEVEL: error - depends_on: - - postgres - -volumes: - mongodb_data: diff --git a/_docs_operate/examples/docker-compose-with-mongodb.yml b/_docs_operate/examples/docker-compose-with-mongodb.yml deleted file mode 100644 index aa4756935..000000000 --- a/_docs_operate/examples/docker-compose-with-mongodb.yml +++ /dev/null @@ -1,29 +0,0 @@ -# ATTENTION: Do NOT use this file in public or production scenarios! It may contain insecure or unstable configuration. - -services: - connector: - container_name: connector - image: ghcr.io/nmshd/connector: # specify a tag (e.g. 1.0.0) or use the 'latest' tag - environment: - CUSTOM_CONFIG_LOCATION: "/config.json" - ports: - - :80 # define the port the connector should listen to on the host - volumes: - - /config.json:/config.json:ro - # - :/var/log/enmeshed-connector # select an existing directory of your choice where your log files should be saved - depends_on: - - mongodb - restart: on-failure - - mongodb: - container_name: mongodb - image: mongo - environment: - MONGO_INITDB_ROOT_USERNAME: - MONGO_INITDB_ROOT_PASSWORD: - volumes: - - mongodb_data:/data/db - restart: on-failure - -volumes: - mongodb_data: diff --git a/_docs_operate/examples/example.config.json b/_docs_operate/examples/example.config.json deleted file mode 100644 index 6fbd34aa8..000000000 --- a/_docs_operate/examples/example.config.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "transportLibrary": { - "platformClientId": " https://enmeshed.eu/operate/connector-configuration#transportlibrary>", - "platformClientSecret": " https://enmeshed.eu/operate/connector-configuration#transportlibrary>" - }, - "database": { - "connectionString": "mongodb://:@mongodb:27017/?authSource=admin&readPreference=primary&ssl=false", - "dbName": "demo" - }, - "infrastructure": { - "httpServer": { - "apiKey": " https://enmeshed.eu/operate/connector-configuration#httpserver>" - } - }, - "modules": { - "coreHttpApi": { - "docs": { - "enabled": false - } - } - } -} diff --git a/_docs_scenarios/scenario-.md b/_docs_scenarios/scenario-.md new file mode 100644 index 000000000..18543eee6 --- /dev/null +++ b/_docs_scenarios/scenario-.md @@ -0,0 +1,22 @@ +--- +permalink: /scenario- +published: false +title: "" +type: scenario +toc: true +properties: + - id: + - category: + - description: + - customer: + - component: + - level: + - implementation status: + - documentation status: + - published: + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-.md %} diff --git a/_docs_scenarios/scenario-sc1.md b/_docs_scenarios/scenario-sc1.md index cc774e704..c20a6d2ef 100644 --- a/_docs_scenarios/scenario-sc1.md +++ b/_docs_scenarios/scenario-sc1.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc1 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Create an Identity" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc10.md b/_docs_scenarios/scenario-sc10.md index 654fe6fef..6b02a4a6a 100644 --- a/_docs_scenarios/scenario-sc10.md +++ b/_docs_scenarios/scenario-sc10.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc10 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Remove an onboarded Device from the Identity" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc11.md b/_docs_scenarios/scenario-sc11.md index 4f7dbf18c..c4a3199d1 100644 --- a/_docs_scenarios/scenario-sc11.md +++ b/_docs_scenarios/scenario-sc11.md @@ -1,7 +1,10 @@ --- permalink: /scenario-sc11 published: false -title: "Fill Attributes of your Identity" +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Manually fill Attributes of your Identity" type: scenario toc: true properties: diff --git a/_docs_scenarios/scenario-sc12.md b/_docs_scenarios/scenario-sc12.md index 1f257a747..179b98d39 100644 --- a/_docs_scenarios/scenario-sc12.md +++ b/_docs_scenarios/scenario-sc12.md @@ -1,7 +1,10 @@ --- permalink: /scenario-sc12 published: false -title: "Overview of your shared data" +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Get overview of your data" type: scenario toc: true properties: diff --git a/_docs_scenarios/scenario-sc13.md b/_docs_scenarios/scenario-sc13.md index 383a62615..21ef2996e 100644 --- a/_docs_scenarios/scenario-sc13.md +++ b/_docs_scenarios/scenario-sc13.md @@ -1,7 +1,10 @@ --- permalink: /scenario-sc13 published: false -title: "Share data to contacts" +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Manually share data to contact" type: scenario toc: true properties: diff --git a/_docs_scenarios/scenario-sc14.md b/_docs_scenarios/scenario-sc14.md index 555ab350f..80ce6b6dd 100644 --- a/_docs_scenarios/scenario-sc14.md +++ b/_docs_scenarios/scenario-sc14.md @@ -1,7 +1,10 @@ --- permalink: /scenario-sc14 published: false -title: "Upgrade existing online accounts to enmeshed" +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Upgrade existing online account to enmeshed" type: scenario toc: true properties: @@ -11,7 +14,7 @@ properties: - customer: All - component: App - level: Beginner - - implementation status: DONE + - implementation status: DOCS ONLY - documentation status: OPEN - published: - link to lucid: diff --git a/_docs_scenarios/scenario-sc15.md b/_docs_scenarios/scenario-sc15.md index 317279054..8f0efc6e7 100644 --- a/_docs_scenarios/scenario-sc15.md +++ b/_docs_scenarios/scenario-sc15.md @@ -1,7 +1,10 @@ --- permalink: /scenario-sc15 published: false -title: "Register new online accounts with enmeshed" +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Register new online account with enmeshed" type: scenario toc: true properties: @@ -11,7 +14,7 @@ properties: - customer: All - component: App - level: Beginner - - implementation status: DONE + - implementation status: DOCS ONLY - documentation status: OPEN - published: - link to lucid: diff --git a/_docs_scenarios/scenario-sc16.md b/_docs_scenarios/scenario-sc16.md index 28ab98bbe..8e9657674 100644 --- a/_docs_scenarios/scenario-sc16.md +++ b/_docs_scenarios/scenario-sc16.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc16 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Scan QR Codes to set up digital communication by printouts" type: scenario toc: true @@ -11,7 +14,7 @@ properties: - customer: All - component: App - level: Beginner - - implementation status: DONE + - implementation status: DOCS ONLY - documentation status: OPEN - published: - link to lucid: diff --git a/_docs_scenarios/scenario-sc17.md b/_docs_scenarios/scenario-sc17.md index 393dc3254..4bd81d60c 100644 --- a/_docs_scenarios/scenario-sc17.md +++ b/_docs_scenarios/scenario-sc17.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc17 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Use nmshd// links to trigger enmeshed on the same device" type: scenario toc: true @@ -11,7 +14,7 @@ properties: - customer: All - component: App - level: Beginner - - implementation status: DONE + - implementation status: DOCS ONLY - documentation status: OPEN - published: - link to lucid: diff --git a/_docs_scenarios/scenario-sc18.md b/_docs_scenarios/scenario-sc18.md index 737d440da..30655c728 100644 --- a/_docs_scenarios/scenario-sc18.md +++ b/_docs_scenarios/scenario-sc18.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc18 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Create own enmeshed codes to share with your peers" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc19.md b/_docs_scenarios/scenario-sc19.md index e03be224f..91f225b92 100644 --- a/_docs_scenarios/scenario-sc19.md +++ b/_docs_scenarios/scenario-sc19.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc19 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Distinguish personalized and non-personalized codes" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc2.md b/_docs_scenarios/scenario-sc2.md index 4dfa1aa31..b41648ba1 100644 --- a/_docs_scenarios/scenario-sc2.md +++ b/_docs_scenarios/scenario-sc2.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc2 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Set-up and use Profile authentication" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc20.md b/_docs_scenarios/scenario-sc20.md index c88fe5a50..df935fe6a 100644 --- a/_docs_scenarios/scenario-sc20.md +++ b/_docs_scenarios/scenario-sc20.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc20 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Rename Contacts to your needs" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc21.md b/_docs_scenarios/scenario-sc21.md index 80bb13e38..78ebb8d02 100644 --- a/_docs_scenarios/scenario-sc21.md +++ b/_docs_scenarios/scenario-sc21.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc21 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Cluster Contacts into your phase of live or categories" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc22.md b/_docs_scenarios/scenario-sc22.md index 49cefd992..c05264344 100644 --- a/_docs_scenarios/scenario-sc22.md +++ b/_docs_scenarios/scenario-sc22.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc22 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Pin Contacts to have the most prominent Contacts at hand" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc23.md b/_docs_scenarios/scenario-sc23.md index e6c7f0a5e..74b4500e8 100644 --- a/_docs_scenarios/scenario-sc23.md +++ b/_docs_scenarios/scenario-sc23.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc23 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Archive stale Contacts" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc24.md b/_docs_scenarios/scenario-sc24.md index 8fa27dcdf..0d6f2d2af 100644 --- a/_docs_scenarios/scenario-sc24.md +++ b/_docs_scenarios/scenario-sc24.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc24 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Overview of consent possibilities" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Requesting consent of users - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DOCS ONLY - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc25.md b/_docs_scenarios/scenario-sc25.md index dc3445f4d..c86867338 100644 --- a/_docs_scenarios/scenario-sc25.md +++ b/_docs_scenarios/scenario-sc25.md @@ -1,6 +1,10 @@ --- permalink: /scenario-sc25 -published: false +redirect_from: +published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Requesting one-time consents " type: scenario toc: true @@ -9,11 +13,11 @@ properties: - category: Requesting consent of users - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DONE - documentation status: DONE - - published: + - published: true - link to lucid: require: - /scenario-sc59 diff --git a/_docs_scenarios/scenario-sc27.md b/_docs_scenarios/scenario-sc27.md index 83a9c9d4e..b418a539a 100644 --- a/_docs_scenarios/scenario-sc27.md +++ b/_docs_scenarios/scenario-sc27.md @@ -1,15 +1,18 @@ --- permalink: /scenario-sc27 published: false -title: "Requesting persistent consents " +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Request persistent consent of peer" type: scenario toc: true properties: - id: SC27 - - category: Requesting consent of users + - category: Manage attributes of others - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc29.md b/_docs_scenarios/scenario-sc29.md index 9efdf533c..233831c68 100644 --- a/_docs_scenarios/scenario-sc29.md +++ b/_docs_scenarios/scenario-sc29.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc29 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Get users who did not consent to latest version" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Requesting consent of users - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc3.md b/_docs_scenarios/scenario-sc3.md index 6386ca80c..f6c82dcc8 100644 --- a/_docs_scenarios/scenario-sc3.md +++ b/_docs_scenarios/scenario-sc3.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc3 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Check Device configuration" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc30.md b/_docs_scenarios/scenario-sc30.md index d185eb00f..e38c51f4b 100644 --- a/_docs_scenarios/scenario-sc30.md +++ b/_docs_scenarios/scenario-sc30.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc30 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Updating consents" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Requesting consent of users - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: OPEN - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc31.md b/_docs_scenarios/scenario-sc31.md index df0c105fc..b3b80f625 100644 --- a/_docs_scenarios/scenario-sc31.md +++ b/_docs_scenarios/scenario-sc31.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc31 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Automated consent management with external system" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Requesting consent of users - description: - customer: All - - component: Connector + - component: Runtime - level: Expert - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc32.md b/_docs_scenarios/scenario-sc32.md index 29ddd02bc..358b52e0f 100644 --- a/_docs_scenarios/scenario-sc32.md +++ b/_docs_scenarios/scenario-sc32.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc32 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Requesting authentication " type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Requesting authentication - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc34.md b/_docs_scenarios/scenario-sc34.md index 8cc75d288..4530a4644 100644 --- a/_docs_scenarios/scenario-sc34.md +++ b/_docs_scenarios/scenario-sc34.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc34 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Requesting authentication by multiple parties" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Requesting authentication - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc35.md b/_docs_scenarios/scenario-sc35.md index be77859ba..400043cd0 100644 --- a/_docs_scenarios/scenario-sc35.md +++ b/_docs_scenarios/scenario-sc35.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc35 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Automated authentication management with external system" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Requesting authentication - description: - customer: All - - component: Connector + - component: Runtime - level: Expert - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc36.md b/_docs_scenarios/scenario-sc36.md index 036188aed..d4b84d547 100644 --- a/_docs_scenarios/scenario-sc36.md +++ b/_docs_scenarios/scenario-sc36.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc36 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Request and response introduction" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Working with requests - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DOCS ONLY - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc37.md b/_docs_scenarios/scenario-sc37.md index 96f124ce8..35d9117c7 100644 --- a/_docs_scenarios/scenario-sc37.md +++ b/_docs_scenarios/scenario-sc37.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc37 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Request statuses" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Working with requests - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: DOCS ONLY - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc38.md b/_docs_scenarios/scenario-sc38.md index b3c921194..839622164 100644 --- a/_docs_scenarios/scenario-sc38.md +++ b/_docs_scenarios/scenario-sc38.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc38 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Overview of request items" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Working with requests - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DOCS ONLY - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc39.md b/_docs_scenarios/scenario-sc39.md index 2ee396010..1a589555f 100644 --- a/_docs_scenarios/scenario-sc39.md +++ b/_docs_scenarios/scenario-sc39.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc39 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Creating complex requests" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Working with requests - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc4.md b/_docs_scenarios/scenario-sc4.md index a73d72358..1aab31fc9 100644 --- a/_docs_scenarios/scenario-sc4.md +++ b/_docs_scenarios/scenario-sc4.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc4 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Create Recovery Data for the Identity" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc40.md b/_docs_scenarios/scenario-sc40.md index 5aa0fff3f..0e880e17c 100644 --- a/_docs_scenarios/scenario-sc40.md +++ b/_docs_scenarios/scenario-sc40.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc40 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Process responses to outgoing requests" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Working with requests - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc41.md b/_docs_scenarios/scenario-sc41.md index 924ce12ad..e52f2f239 100644 --- a/_docs_scenarios/scenario-sc41.md +++ b/_docs_scenarios/scenario-sc41.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc41 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Respond to incoming requests" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Working with requests - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc42.md b/_docs_scenarios/scenario-sc42.md index 312653cce..cca51e665 100644 --- a/_docs_scenarios/scenario-sc42.md +++ b/_docs_scenarios/scenario-sc42.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc42 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Automate request handling" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Working with requests - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: OPEN - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc43.md b/_docs_scenarios/scenario-sc43.md index 8d64612c7..1edd3cde5 100644 --- a/_docs_scenarios/scenario-sc43.md +++ b/_docs_scenarios/scenario-sc43.md @@ -1,19 +1,23 @@ --- permalink: /scenario-sc43 -published: false -title: "Connector event introduction" +redirect_from: /integrate/connector-events +published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Event introduction" type: scenario toc: true properties: - id: SC43 - category: Handling events - - description: + - description: https//enmeshed.eu/integrate/connector-events - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: DOCS ONLY - documentation status: OPEN - - published: + - published: true - link to lucid: require: required_by: diff --git a/_docs_scenarios/scenario-sc44.md b/_docs_scenarios/scenario-sc44.md index 91143f500..bec362715 100644 --- a/_docs_scenarios/scenario-sc44.md +++ b/_docs_scenarios/scenario-sc44.md @@ -1,7 +1,10 @@ --- permalink: /scenario-sc44 published: false -title: "Handling events by webhooks" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Notify service of enmeshed event" type: scenario toc: true properties: @@ -9,7 +12,7 @@ properties: - category: Handling events - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc45.md b/_docs_scenarios/scenario-sc45.md index 8471c4d9a..3fafb25b7 100644 --- a/_docs_scenarios/scenario-sc45.md +++ b/_docs_scenarios/scenario-sc45.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc45 published: false +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" title: "Handling events by AMQP" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc46.md b/_docs_scenarios/scenario-sc46.md index e1e85e7ac..2c49a9f23 100644 --- a/_docs_scenarios/scenario-sc46.md +++ b/_docs_scenarios/scenario-sc46.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc46 published: false +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" title: "Writing your own Connector module" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc47.md b/_docs_scenarios/scenario-sc47.md index 59dc57a28..78b5eee9d 100644 --- a/_docs_scenarios/scenario-sc47.md +++ b/_docs_scenarios/scenario-sc47.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc47 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "IdentityAttribute introduction" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Manage attributes of yourself - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DOCS ONLY - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc48.md b/_docs_scenarios/scenario-sc48.md index f589c9bc6..44e5a4d20 100644 --- a/_docs_scenarios/scenario-sc48.md +++ b/_docs_scenarios/scenario-sc48.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc48 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Overview of Attribute Values" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Manage attributes of yourself - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DOCS ONLY - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc49.md b/_docs_scenarios/scenario-sc49.md index b55d775ba..2c02ef8c7 100644 --- a/_docs_scenarios/scenario-sc49.md +++ b/_docs_scenarios/scenario-sc49.md @@ -1,7 +1,10 @@ --- permalink: /scenario-sc49 published: false -title: "Create own IdentityAttributes" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Create own IdentityAttribute" type: scenario toc: true properties: @@ -9,7 +12,7 @@ properties: - category: Manage attributes of yourself - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc5.md b/_docs_scenarios/scenario-sc5.md index e414762d7..f2833df15 100644 --- a/_docs_scenarios/scenario-sc5.md +++ b/_docs_scenarios/scenario-sc5.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc5 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Delete Identity from Enmeshed" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc50.md b/_docs_scenarios/scenario-sc50.md index 10c7af7a9..0dcf033aa 100644 --- a/_docs_scenarios/scenario-sc50.md +++ b/_docs_scenarios/scenario-sc50.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc50 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Request and process attributes by code/link of new contacts" type: scenario toc: true @@ -9,9 +12,9 @@ properties: - category: Manage attributes of others - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - - implementation status: DONE + - implementation status: DOCS ONLY - documentation status: OPEN - published: - link to lucid: diff --git a/_docs_scenarios/scenario-sc51.md b/_docs_scenarios/scenario-sc51.md index 0c11ddf89..1856ddd6f 100644 --- a/_docs_scenarios/scenario-sc51.md +++ b/_docs_scenarios/scenario-sc51.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc51 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Request and process attributes by code/link of existing contacts" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Manage attributes of others - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DONE - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc52.md b/_docs_scenarios/scenario-sc52.md index 976310dca..658728864 100644 --- a/_docs_scenarios/scenario-sc52.md +++ b/_docs_scenarios/scenario-sc52.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc52 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Request and process attributes by messages" type: scenario toc: true @@ -9,9 +12,9 @@ properties: - category: Manage attributes of others - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - - implementation status: DONE + - implementation status: DOCS ONLY - documentation status: OPEN - published: - link to lucid: diff --git a/_docs_scenarios/scenario-sc53.md b/_docs_scenarios/scenario-sc53.md index a7f55ed56..ddb3ca651 100644 --- a/_docs_scenarios/scenario-sc53.md +++ b/_docs_scenarios/scenario-sc53.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc53 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Updating IdentityAttributes of yourself" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Manage attributes of yourself - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: OPEN - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc54.md b/_docs_scenarios/scenario-sc54.md index 2932769ea..4413f03ab 100644 --- a/_docs_scenarios/scenario-sc54.md +++ b/_docs_scenarios/scenario-sc54.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc54 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Respond to incoming IdentityAttribute update requests" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Manage attributes of others - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: OPEN - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc55.md b/_docs_scenarios/scenario-sc55.md index f935d36ad..8ead22f63 100644 --- a/_docs_scenarios/scenario-sc55.md +++ b/_docs_scenarios/scenario-sc55.md @@ -1,7 +1,10 @@ --- permalink: /scenario-sc55 published: false -title: "Process incoming IdentityAttribute deletion requests" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Process incoming Attribute deletion requests" type: scenario toc: true properties: @@ -9,7 +12,7 @@ properties: - category: Handling data deletion - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: OPEN - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc56.md b/_docs_scenarios/scenario-sc56.md index 510b5c0cf..c42afb910 100644 --- a/_docs_scenarios/scenario-sc56.md +++ b/_docs_scenarios/scenario-sc56.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc56 published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Process incoming Relationship deletion requests" type: scenario toc: true @@ -9,7 +12,7 @@ properties: - category: Handling data deletion - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - implementation status: OPEN - documentation status: OPEN diff --git a/_docs_scenarios/scenario-sc57.md b/_docs_scenarios/scenario-sc57.md index 3b86edebd..5be113bc2 100644 --- a/_docs_scenarios/scenario-sc57.md +++ b/_docs_scenarios/scenario-sc57.md @@ -1,7 +1,10 @@ --- permalink: /scenario-sc57 published: false -title: "x" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Working with unstructed data / files" type: scenario toc: true properties: @@ -9,9 +12,9 @@ properties: - category: Manage attributes of others - description: - customer: All - - component: Connector + - component: Runtime - level: Advanced - - implementation status: OPEN + - implementation status: DOCS ONLY - documentation status: OPEN - published: - link to lucid: diff --git a/_docs_scenarios/scenario-sc58.md b/_docs_scenarios/scenario-sc58.md index 026901a9c..670bb54dc 100644 --- a/_docs_scenarios/scenario-sc58.md +++ b/_docs_scenarios/scenario-sc58.md @@ -2,6 +2,9 @@ permalink: /scenario-sc58 redirect_from: /integrate/connector-flows-messages published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Sending Messages" type: scenario toc: true @@ -10,7 +13,7 @@ properties: - category: Messages - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DONE - documentation status: DONE diff --git a/_docs_scenarios/scenario-sc59.md b/_docs_scenarios/scenario-sc59.md index e62d0b69c..85239dbbf 100644 --- a/_docs_scenarios/scenario-sc59.md +++ b/_docs_scenarios/scenario-sc59.md @@ -2,18 +2,21 @@ permalink: /scenario-sc59 redirect_from: /integrate/requests-over-templates published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Requests over Templates" type: scenario toc: true properties: - id: SC59 - - category: Requests + - category: Manage Requests - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DONE - - documentation status: DONE + - documentation status: DOCS ONLY - published: true - link to lucid: require: diff --git a/_docs_scenarios/scenario-sc6.md b/_docs_scenarios/scenario-sc6.md index 64e62a7e5..afe38e883 100644 --- a/_docs_scenarios/scenario-sc6.md +++ b/_docs_scenarios/scenario-sc6.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc6 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Recover an existing Identity" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc60.md b/_docs_scenarios/scenario-sc60.md index ec8b96a34..ffa49d596 100644 --- a/_docs_scenarios/scenario-sc60.md +++ b/_docs_scenarios/scenario-sc60.md @@ -2,18 +2,21 @@ permalink: /scenario-sc60 redirect_from: /integrate/requests-over-messages published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" title: "Requests over Messages" type: scenario toc: true properties: - id: SC60 - - category: Requests + - category: Manage Requests - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - implementation status: DONE - - documentation status: DONE + - documentation status: DOCS ONLY - published: true - link to lucid: require: diff --git a/_docs_scenarios/scenario-sc61.md b/_docs_scenarios/scenario-sc61.md index 6cd9850c2..4e743311a 100644 --- a/_docs_scenarios/scenario-sc61.md +++ b/_docs_scenarios/scenario-sc61.md @@ -1,17 +1,20 @@ --- permalink: /scenario-sc61 published: false -title: "Uplaod File" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Delete Identity from Enmeshed" type: scenario toc: true properties: - id: SC61 - - category: File handling + - category: Identity Basics - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - - implementation status: DONE + - implementation status: OPEN - documentation status: OPEN - published: - link to lucid: diff --git a/_docs_scenarios/scenario-sc62.md b/_docs_scenarios/scenario-sc62.md index 78671cecc..3809b54be 100644 --- a/_docs_scenarios/scenario-sc62.md +++ b/_docs_scenarios/scenario-sc62.md @@ -1,17 +1,20 @@ --- permalink: /scenario-sc62 published: false -title: "Download File" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Succeed attribute of peer" type: scenario toc: true properties: - id: SC62 - - category: File handling + - category: Manage attributes of others - description: - customer: All - - component: Connector + - component: Runtime - level: Beginner - - implementation status: DONE + - implementation status: OPEN - documentation status: OPEN - published: - link to lucid: diff --git a/_docs_scenarios/scenario-sc63.md b/_docs_scenarios/scenario-sc63.md index f03786ef5..8527902ab 100644 --- a/_docs_scenarios/scenario-sc63.md +++ b/_docs_scenarios/scenario-sc63.md @@ -1,13 +1,16 @@ --- permalink: /scenario-sc63 published: false -title: "share File" +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Set-up Connector for productive use" type: scenario toc: true properties: - id: SC63 - - category: File handling - - description: + - category: Operations + - description: #1 https//enmeshed.eu/integrate/connector-installation - customer: All - component: Connector - level: Beginner diff --git a/_docs_scenarios/scenario-sc64.md b/_docs_scenarios/scenario-sc64.md index 7657bb985..c73394819 100644 --- a/_docs_scenarios/scenario-sc64.md +++ b/_docs_scenarios/scenario-sc64.md @@ -1,23 +1,25 @@ --- permalink: /scenario-sc64 published: false -title: "" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Process received enmeshed onboarding package and create relationship" type: scenario toc: true properties: - id: SC64 - - category: + - category: Get in touch with other Identities - description: - - customer: - - component: - - level: - - implementation status: - - documentation status: + - customer: All + - component: Runtime + - level: Advanced + - implementation status: DONE + - documentation status: OPEN - published: - link to lucid: require: required_by: - - /scenario-sc58 --- {% include scenarios/scenario-sc64.md %} diff --git a/_docs_scenarios/scenario-sc65.md b/_docs_scenarios/scenario-sc65.md index d5ef2e78a..701dba39e 100644 --- a/_docs_scenarios/scenario-sc65.md +++ b/_docs_scenarios/scenario-sc65.md @@ -1,23 +1,25 @@ --- permalink: /scenario-sc65 published: false -title: "" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Read attribute from peer" type: scenario toc: true properties: - id: SC65 - - category: + - category: Manage attributes of others - description: - - customer: - - component: - - level: - - implementation status: - - documentation status: + - customer: All + - component: Runtime + - level: Beginner + - implementation status: CHANGES REQUIRED + - documentation status: OPEN - published: - link to lucid: require: required_by: - - /scenario-sc58 --- {% include scenarios/scenario-sc65.md %} diff --git a/_docs_scenarios/scenario-sc66.md b/_docs_scenarios/scenario-sc66.md index bbfdd1903..36fb60bd4 100644 --- a/_docs_scenarios/scenario-sc66.md +++ b/_docs_scenarios/scenario-sc66.md @@ -1,23 +1,25 @@ --- permalink: /scenario-sc66 published: false -title: "" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Propose attribute to peer" type: scenario toc: true properties: - id: SC66 - - category: + - category: Manage attributes of others - description: - - customer: - - component: - - level: - - implementation status: - - documentation status: + - customer: All + - component: Runtime + - level: Beginner + - implementation status: CHANGES REQUIRED + - documentation status: OPEN - published: - link to lucid: require: required_by: - - /scenario-sc58 --- {% include scenarios/scenario-sc66.md %} diff --git a/_docs_scenarios/scenario-sc67.md b/_docs_scenarios/scenario-sc67.md index 5033eef9c..d5611b674 100644 --- a/_docs_scenarios/scenario-sc67.md +++ b/_docs_scenarios/scenario-sc67.md @@ -1,23 +1,25 @@ --- permalink: /scenario-sc67 published: false -title: "" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Create attribute for peer" type: scenario toc: true properties: - id: SC67 - - category: + - category: Manage attributes of others - description: - - customer: - - component: - - level: - - implementation status: - - documentation status: + - customer: All + - component: Runtime + - level: Beginner + - implementation status: CHANGES REQUIRED + - documentation status: OPEN - published: - link to lucid: require: required_by: - - /scenario-sc58 --- {% include scenarios/scenario-sc67.md %} diff --git a/_docs_scenarios/scenario-sc68.md b/_docs_scenarios/scenario-sc68.md index f07471f32..882f4165d 100644 --- a/_docs_scenarios/scenario-sc68.md +++ b/_docs_scenarios/scenario-sc68.md @@ -1,23 +1,25 @@ --- permalink: /scenario-sc68 published: false -title: "" +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Share own attribute to peer" type: scenario toc: true properties: - id: SC68 - - category: + - category: Manage attributes of yourself - description: - - customer: - - component: - - level: - - implementation status: - - documentation status: + - customer: All + - component: Runtime + - level: Beginner + - implementation status: DONE + - documentation status: OPEN - published: - link to lucid: require: required_by: - - /scenario-sc58 --- {% include scenarios/scenario-sc68.md %} diff --git a/_docs_scenarios/scenario-sc69.md b/_docs_scenarios/scenario-sc69.md index f6c1292ad..7c5cb918b 100644 --- a/_docs_scenarios/scenario-sc69.md +++ b/_docs_scenarios/scenario-sc69.md @@ -1,23 +1,25 @@ --- permalink: /scenario-sc69 published: false -title: "" +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Check health of Connector" type: scenario toc: true properties: - id: SC69 - - category: + - category: Identity Basics - description: - - customer: - - component: - - level: - - implementation status: - - documentation status: + - customer: All + - component: Connector + - level: Beginner + - implementation status: DONE + - documentation status: OPEN - published: - link to lucid: require: required_by: - - /scenario-sc58 --- {% include scenarios/scenario-sc69.md %} diff --git a/_docs_scenarios/scenario-sc7.md b/_docs_scenarios/scenario-sc7.md index 1526e7c87..d7ab0fa9c 100644 --- a/_docs_scenarios/scenario-sc7.md +++ b/_docs_scenarios/scenario-sc7.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc7 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Rename Profile to distinguish multiple Profiles" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc71.md b/_docs_scenarios/scenario-sc71.md new file mode 100644 index 000000000..128f51d3c --- /dev/null +++ b/_docs_scenarios/scenario-sc71.md @@ -0,0 +1,25 @@ +--- +permalink: /scenario-sc71 +published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Process received enmeshed onboarding package and create relationship" +type: scenario +toc: true +properties: + - id: SC71 + - category: Get in touch with other Identities + - description: + - customer: All + - component: App + - level: Beginner + - implementation status: DONE + - documentation status: OPEN + - published: + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc71.md %} diff --git a/_docs_scenarios/scenario-sc72.md b/_docs_scenarios/scenario-sc72.md new file mode 100644 index 000000000..d7e8885a7 --- /dev/null +++ b/_docs_scenarios/scenario-sc72.md @@ -0,0 +1,25 @@ +--- +permalink: /scenario-sc72 +published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Process requests of contact" +type: scenario +toc: true +properties: + - id: SC72 + - category: Manage Requests + - description: + - customer: All + - component: App + - level: Beginner + - implementation status: DONE + - documentation status: OPEN + - published: + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc72.md %} diff --git a/_docs_scenarios/scenario-sc73.md b/_docs_scenarios/scenario-sc73.md new file mode 100644 index 000000000..0d0a48821 --- /dev/null +++ b/_docs_scenarios/scenario-sc73.md @@ -0,0 +1,25 @@ +--- +permalink: /scenario-sc73 +published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Send prefabricated request to contact" +type: scenario +toc: true +properties: + - id: SC73 + - category: Manage Requests + - description: + - customer: All + - component: App + - level: Beginner + - implementation status: OPEN + - documentation status: OPEN + - published: + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc73.md %} diff --git a/_docs_scenarios/scenario-sc74.md b/_docs_scenarios/scenario-sc74.md new file mode 100644 index 000000000..14d091643 --- /dev/null +++ b/_docs_scenarios/scenario-sc74.md @@ -0,0 +1,25 @@ +--- +permalink: /scenario-sc74 +published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Prepare enmeshed onboarding package" +type: scenario +toc: true +properties: + - id: SC74 + - category: Get in touch with other Identities + - description: + - customer: All + - component: Runtime + - level: Beginner + - implementation status: DONE + - documentation status: OPEN + - published: + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc74.md %} diff --git a/_docs_scenarios/scenario-sc75.md b/_docs_scenarios/scenario-sc75.md new file mode 100644 index 000000000..fc3ef89e0 --- /dev/null +++ b/_docs_scenarios/scenario-sc75.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc75 +redirect_from: /integrate/connector-tutorial +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Get in touch with Connector REST API" +type: scenario +toc: true +properties: + - id: SC75 + - category: Getting Started + - description: https//enmeshed.eu/integrate/connector-api + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc75.md %} diff --git a/_docs_scenarios/scenario-sc76.md b/_docs_scenarios/scenario-sc76.md new file mode 100644 index 000000000..9a3627d64 --- /dev/null +++ b/_docs_scenarios/scenario-sc76.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc76 +redirect_from: /integrate/basics +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Get an overview of Connector" +type: scenario +toc: true +properties: + - id: SC76 + - category: Getting Started + - description: https//enmeshed.eu/integrate/basics + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc76.md %} diff --git a/_docs_scenarios/scenario-sc77.md b/_docs_scenarios/scenario-sc77.md new file mode 100644 index 000000000..0c7a1382a --- /dev/null +++ b/_docs_scenarios/scenario-sc77.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc77 +redirect_from: /integrate/connector-installation +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Set-up Connector for development use (with Docker compose)" +type: scenario +toc: true +properties: + - id: SC77 + - category: Getting Started + - description: #2 https//enmeshed.eu/integrate/connector-installation + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc77.md %} diff --git a/_docs_scenarios/scenario-sc78.md b/_docs_scenarios/scenario-sc78.md new file mode 100644 index 000000000..5a175e3e8 --- /dev/null +++ b/_docs_scenarios/scenario-sc78.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc78 +redirect_from: /integrate/data-model-overview +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Get in touch with enmeshed data concepts" +type: scenario +toc: true +properties: + - id: SC78 + - category: Getting Started + - description: https//enmeshed.eu/integrate/data-model-overview + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc78.md %} diff --git a/_docs_scenarios/scenario-sc79.md b/_docs_scenarios/scenario-sc79.md new file mode 100644 index 000000000..8715b74ef --- /dev/null +++ b/_docs_scenarios/scenario-sc79.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc79 +redirect_from: /integrate/connector-configuration +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Customizing Connector by config" +type: scenario +toc: true +properties: + - id: SC79 + - category: Operations + - description: https//enmeshed.eu/integrate/connector-configuration + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc79.md %} diff --git a/_docs_scenarios/scenario-sc8.md b/_docs_scenarios/scenario-sc8.md index 695914a06..e2396b650 100644 --- a/_docs_scenarios/scenario-sc8.md +++ b/_docs_scenarios/scenario-sc8.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc8 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Delete Profile from the App" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc80.md b/_docs_scenarios/scenario-sc80.md new file mode 100644 index 000000000..de1bc2d59 --- /dev/null +++ b/_docs_scenarios/scenario-sc80.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc80 +redirect_from: /integrate/connector-modules +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Extending Connector with Connector modules" +type: scenario +toc: true +properties: + - id: SC80 + - category: Operations + - description: https//enmeshed.eu/integrate/connector-modules + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc80.md %} diff --git a/_docs_scenarios/scenario-sc81.md b/_docs_scenarios/scenario-sc81.md new file mode 100644 index 000000000..828aae0fb --- /dev/null +++ b/_docs_scenarios/scenario-sc81.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc81 +redirect_from: /integrate/connector-setup-troubleshooting +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Troubleshooting the Connector" +type: scenario +toc: true +properties: + - id: SC81 + - category: Operations + - description: https//enmeshed.eu/integrate/connector-setup-troubleshooting + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc81.md %} diff --git a/_docs_scenarios/scenario-sc82.md b/_docs_scenarios/scenario-sc82.md new file mode 100644 index 000000000..b084e71ed --- /dev/null +++ b/_docs_scenarios/scenario-sc82.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc82 +redirect_from: /integrate/helm-chart +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Setting up the Connector with Helm Charts" +type: scenario +toc: true +properties: + - id: SC82 + - category: Operations + - description: https//enmeshed.eu/integrate/helm-chart + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc82.md %} diff --git a/_docs_scenarios/scenario-sc83.md b/_docs_scenarios/scenario-sc83.md new file mode 100644 index 000000000..7790d24b4 --- /dev/null +++ b/_docs_scenarios/scenario-sc83.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc83 +redirect_from: /integrate/connector-operations +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Overview of Connector operations" +type: scenario +toc: true +properties: + - id: SC83 + - category: Operations + - description: https//enmeshed.eu/integrate/connector-operations + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc83.md %} diff --git a/_docs_scenarios/scenario-sc84.md b/_docs_scenarios/scenario-sc84.md new file mode 100644 index 000000000..bf9140b98 --- /dev/null +++ b/_docs_scenarios/scenario-sc84.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc84 +redirect_from: /integrate/connector-security +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Security Considerations" +type: scenario +toc: true +properties: + - id: SC84 + - category: Operations + - description: https//enmeshed.eu/integrate/connector-security + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc84.md %} diff --git a/_docs_scenarios/scenario-sc85.md b/_docs_scenarios/scenario-sc85.md new file mode 100644 index 000000000..e4bf68bf6 --- /dev/null +++ b/_docs_scenarios/scenario-sc85.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc85 +redirect_from: /integrate/connector-privacy +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Privacy Considerations" +type: scenario +toc: true +properties: + - id: SC85 + - category: Operations + - description: https//enmeshed.eu/integrate/connector-privacy + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc85.md %} diff --git a/_docs_scenarios/scenario-sc86.md b/_docs_scenarios/scenario-sc86.md new file mode 100644 index 000000000..947966eb8 --- /dev/null +++ b/_docs_scenarios/scenario-sc86.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc86 +redirect_from: /integrate/connector-performance +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Performance Considerations" +type: scenario +toc: true +properties: + - id: SC86 + - category: Operations + - description: https//enmeshed.eu/integrate/connector-performance + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc86.md %} diff --git a/_docs_scenarios/scenario-sc87.md b/_docs_scenarios/scenario-sc87.md new file mode 100644 index 000000000..37e792e0f --- /dev/null +++ b/_docs_scenarios/scenario-sc87.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc87 +redirect_from: /integrate/connector-sdks +published: true +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Working with the Connector SDKs" +type: scenario +toc: true +properties: + - id: SC87 + - category: Programming + - description: https//enmeshed.eu/integrate/connector-sdks + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc87.md %} diff --git a/_docs_scenarios/scenario-sc88.md b/_docs_scenarios/scenario-sc88.md new file mode 100644 index 000000000..a5fcec011 --- /dev/null +++ b/_docs_scenarios/scenario-sc88.md @@ -0,0 +1,25 @@ +--- +permalink: /scenario-sc88 +published: false +sidebar: + - title: "Operate Enmeshed" + nav: "docs_operate" +title: "Working with the Connector Runtime" +type: scenario +toc: true +properties: + - id: SC88 + - category: Programming + - description: + - customer: + - component: Connector + - level: + - implementation status: DOCS ONLY + - documentation status: + - published: + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc88.md %} diff --git a/_docs_scenarios/scenario-sc89.md b/_docs_scenarios/scenario-sc89.md new file mode 100644 index 000000000..b9968e3e5 --- /dev/null +++ b/_docs_scenarios/scenario-sc89.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc89 +redirect_from: /integrate/error-codes +published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Error Codes" +type: scenario +toc: true +properties: + - id: SC89 + - category: Data Model + - description: https//enmeshed.eu/integrate/error-codes + - customer: + - component: Runtime + - level: + - implementation status: + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc89.md %} diff --git a/_docs_scenarios/scenario-sc9.md b/_docs_scenarios/scenario-sc9.md index 09e0ebabc..2a0f287e6 100644 --- a/_docs_scenarios/scenario-sc9.md +++ b/_docs_scenarios/scenario-sc9.md @@ -1,6 +1,9 @@ --- permalink: /scenario-sc9 published: false +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" title: "Set-up an additional Device for the Identity" type: scenario toc: true diff --git a/_docs_scenarios/scenario-sc90.md b/_docs_scenarios/scenario-sc90.md new file mode 100644 index 000000000..4931228c9 --- /dev/null +++ b/_docs_scenarios/scenario-sc90.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc90 +redirect_from: /integrate/data-model-overview +published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Introducing the enmeshed Data Model" +type: scenario +toc: true +properties: + - id: SC90 + - category: Data Model + - description: https//enmeshed.eu/integrate/data-model-overview + - customer: + - component: Runtime + - level: + - implementation status: + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc90.md %} diff --git a/_docs_scenarios/scenario-sc91.md b/_docs_scenarios/scenario-sc91.md new file mode 100644 index 000000000..7aaa589d6 --- /dev/null +++ b/_docs_scenarios/scenario-sc91.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc91 +redirect_from: /integrate/data-model-request-items +published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Overview of Requests and RequestItems" +type: scenario +toc: true +properties: + - id: SC91 + - category: Data Model + - description: https//enmeshed.eu/integrate/data-model-request-items + - customer: + - component: Runtime + - level: + - implementation status: + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc91.md %} diff --git a/_docs_scenarios/scenario-sc92.md b/_docs_scenarios/scenario-sc92.md new file mode 100644 index 000000000..f8c52f720 --- /dev/null +++ b/_docs_scenarios/scenario-sc92.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc92 +redirect_from: /integrate/data-model-attribute-values +published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Overview of Attribute Values" +type: scenario +toc: true +properties: + - id: SC92 + - category: Data Model + - description: https//enmeshed.eu/integrate/data-model-attribute-values + - customer: + - component: Runtime + - level: + - implementation status: + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc92.md %} diff --git a/_docs_scenarios/scenario-sc93.md b/_docs_scenarios/scenario-sc93.md new file mode 100644 index 000000000..368ac533c --- /dev/null +++ b/_docs_scenarios/scenario-sc93.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc93 +redirect_from: /use/basics +published: true +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Install the App" +type: scenario +toc: true +properties: + - id: SC93 + - category: Getting Started + - description: https//enmeshed.eu/use/basics + - customer: + - component: App + - level: Beginner + - implementation status: + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc93.md %} diff --git a/_docs_scenarios/scenario-sc94.md b/_docs_scenarios/scenario-sc94.md new file mode 100644 index 000000000..fd5469a25 --- /dev/null +++ b/_docs_scenarios/scenario-sc94.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc94 +redirect_from: /use/security-recommendations +published: true +sidebar: + - title: "Use Enmeshed" + nav: "docs_use" +title: "Securely use the app" +type: scenario +toc: true +properties: + - id: SC94 + - category: Getting Started + - description: https//enmeshed.eu/use/security-recommendations + - customer: + - component: App + - level: Beginner + - implementation status: + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc94.md %} diff --git a/_docs_scenarios/scenario-sc95.md b/_docs_scenarios/scenario-sc95.md new file mode 100644 index 000000000..eb93cffba --- /dev/null +++ b/_docs_scenarios/scenario-sc95.md @@ -0,0 +1,26 @@ +--- +permalink: /scenario-sc95 +redirect_from: /integrate/connector-tutorial +published: true +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Tutorial???" +type: scenario +toc: true +properties: + - id: SC95 + - category: Getting Started + - description: https//enmeshed.eu/integrate/connector-tutorial + - customer: + - component: Runtime + - level: + - implementation status: + - documentation status: + - published: true + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc95.md %} diff --git a/_docs_scenarios/scenario-sc96.md b/_docs_scenarios/scenario-sc96.md new file mode 100644 index 000000000..312dfd26f --- /dev/null +++ b/_docs_scenarios/scenario-sc96.md @@ -0,0 +1,25 @@ +--- +permalink: /scenario-sc96 +published: false +sidebar: + - title: "Integrate Enmeshed" + nav: "docs_integrate" +title: "Introduction" +type: scenario +toc: true +properties: + - id: SC96 + - category: Getting Started + - description: + - customer: + - component: Runtime + - level: + - implementation status: + - documentation status: + - published: + - link to lucid: +require: +required_by: +--- + +{% include scenarios/scenario-sc96.md %} diff --git a/_includes/scenarios/scenario-sc43.md b/_includes/scenarios/scenario-sc43.md index 27c2aef9d..c6cdac8b7 100644 --- a/_includes/scenarios/scenario-sc43.md +++ b/_includes/scenarios/scenario-sc43.md @@ -1,21 +1,64 @@ - +| Event | Data | Description (This event is triggered when ...) | +| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| consumption.attributeCreated | [LocalAttribute]({% link _docs_scenarios/scenario-sc90.md %}#LocalAttribute) | ... an Attribute was created manually or through a Request. | +| consumption.attributeDeleted | [LocalAttribute]({% link _docs_scenarios/scenario-sc90.md %}#LocalAttribute) | ... an Attribute was deleted manually or through a Request. | +| consumption.attributeSucceded | [LocalAttribute]({% link _docs_scenarios/scenario-sc90.md %}#LocalAttribute) | ... an Attribute was succeeded manually or through a Request. | +| consumption.attributeUpdated | [LocalAttribute]({% link _docs_scenarios/scenario-sc90.md %}#LocalAttribute) | ... an Attribute was updated manually or through a Request. | +| consumption.incomingRequestReceived | [LocalRequest]({% link _docs_scenarios/scenario-sc90.md %}#LocalRequest) | ... an incoming Request was received either by loading a Relationship Template or by receiving a Message | +| consumption.incomingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an incoming Request has changed. | +| consumption.messageProcessed | [MessageProcessedEventData](#messageprocessedeventdata) | ... a Message was processed by Modules like the `RequestModule` or `DeciderModule`. | +| consumption.outgoingRequestCreated | [LocalRequest]({% link _docs_scenarios/scenario-sc90.md %}#LocalRequest) | ... an outgoing Request was created. | +| consumption.
              outgoingRequestFromRelationshipCreationChange
              CreatedAndCompleted | [LocalRequest]({% link _docs_scenarios/scenario-sc90.md %}#LocalRequest) | ... an outgoing Request was created and directly completed.
              This happens if the Response came in with a new Relationship. | +| consumption.outgoingRequestStatusChanged | [RequestStatusChangedEventData](#requeststatuschangedeventdata) | ... the status of an outgoing Request has changed. | +| consumption.relationshipTemplateProcessed | [RelationshipTemplateProcessedEventData](#relationshiptemplateprocessedeventdata) | ... a RelationshipTemplate was processed by Modules like the `RequestModule` or `DeciderModule`. | +| consumption.sharedAttributeCopyCreated | [LocalAttribute]({% link _docs_scenarios/scenario-sc90.md %}#LocalAttribute) | ... an Attribute is copied for sharing with another identity. | +| transport.messageReceived | [Message]({% link _docs_scenarios/scenario-sc90.md %}#Message) | ... a Message is received during synchronization. | +| transport.messageSent | [Message]({% link _docs_scenarios/scenario-sc90.md %}#Message) | ... a Message was sent. | +| transport.peerRelationshipTemplateLoaded | [RelationshipTemplate]({% link _docs_scenarios/scenario-sc90.md %}#RelationshipTemplate) | ... a Relationship Template was loaded that belongs to another identity. | +| transport.relationshipChanged | [Relationship]({% link _docs_scenarios/scenario-sc90.md %}#Relationship) | ... a Relationship has changed. This can be due to one of the following cases:
              • you create a Relationship
              • you accept, reject or revoke a Relationship Change
              • a Relationship Change is received during synchronization | -Lorem ipsum dolor sit amet consectetur adipisicing elit. Perferendis voluptas deserunt alias accusantium rem? Quaerat, temporibus alias fuga rerum unde dolor blanditiis quia incidunt modi rem, sequi, esse aut accusamus. +## Event structure - +Every event is structured as follows (TData depends on the actual event, e.g. `LocalAttribute`): -{% include properties_list.html %} +```ts +interface Event { + namespace: string; + eventTargetAddress: string; + data: TData; +} +``` - +### RequestStatusChangedEventData -Lorem ipsum dolor sit amet consectetur adipisicing elit. Unde nihil sequi ipsam blanditiis optio nulla quidem tempore sapiente nam, molestiae et voluptas ab harum quo incidunt reiciendis dolorum sed eligendi quos in itaque vel facilis. Rerum quia asperiores porro, odit laborum error voluptates repellat repellendus doloribus minima voluptate debitis libero nemo sit, dolorem consequatur expedita architecto! Molestiae, quae maxime ut iste ratione veniam velit asperiores. Earum corrupti architecto molestiae necessitatibus ullam modi beatae optio distinctio et labore, consectetur, repudiandae alias recusandae quas delectus placeat error laudantium quos, autem non nemo cum. Obcaecati iure maiores quas temporibus assumenda, qui veritatis necessitatibus. +> [LocalRequest]({% link _docs_scenarios/scenario-sc90.md %}#LocalRequest) - +```ts +export interface RequestStatusChangedEventData { + request: LocalRequest; + oldStatus: LocalRequestStatus; + newStatus: LocalRequestStatus; +} +``` -# Developer Corner +### MessageProcessedEventData - -
              - Flowchart -
              {% include diagrams/Enmeshed_Scenarios.svg %}
              -
              +> [Message]({% link _docs_scenarios/scenario-sc90.md %}#Message) + +```ts +export interface MessageProcessedEventData { + message: MessageDTO; + result: "ManualRequestDecisionRequired" | "NoRequest" | "Error"; +} +``` + +### RelationshipTemplateProcessedEventData + +> [RelationshipTemplate]({% link _docs_scenarios/scenario-sc90.md %}#RelationshipTemplate) + +```ts +export interface RelationshipTemplateProcessedEventData { + template: RelationshipTemplateDTO; + result: "ManualRequestDecisionRequired" | "NonCompletedRequestExists" | "RelationshipExists" | "NoRequest" | "Error"; +} +``` diff --git a/_includes/scenarios/scenario-sc59.md b/_includes/scenarios/scenario-sc59.md index 6ed7fc24e..df690c88b 100644 --- a/_includes/scenarios/scenario-sc59.md +++ b/_includes/scenarios/scenario-sc59.md @@ -1,8 +1,8 @@ -This guide will explain the end to end flow of sharing and answering a [Request]({% link _docs_integrate/61-data-model.md %}#request) over a Template. This flow usually happens between the App and a Connector, but for simplicity and more transparency we will use two Connectors. Therefore you have to start two Connectors that don't have a Relationship yet. +This guide will explain the end to end flow of sharing and answering a [Request]({% link _docs_scenarios/scenario-sc90.md %}#request) over a Template. This flow usually happens between the App and a Connector, but for simplicity and more transparency we will use two Connectors. Therefore you have to start two Connectors that don't have a Relationship yet. -You can use the [Connector Installation Guide]({% link _docs_integrate/10-connector-installation.md %}) if you need help for the setup the Connectors. +You can use the [Connector Installation Guide]({% link _docs_scenarios/scenario-sc77.md %}) if you need help for the setup the Connectors. @@ -13,7 +13,7 @@ On the first Connector you will create a Template. This Connector will be called ## Check your Request's validity At first you should check if your Request is valid. You can do this by calling the `POST /api/v2/Requests/Outgoing/Validate` route on the Templator Connector with the following body. -For simplicity the Request inside the Template only contains an AuthenticationRequestItem, but you can use any [RequestItems]({% link _docs_integrate/62-request-items.md %}) you want. +For simplicity the Request inside the Template only contains an AuthenticationRequestItem, but you can use any [RequestItems]({% link _docs_scenarios/scenario-sc91.md %}) you want. ```json { @@ -76,7 +76,7 @@ If no Relationship exists, this will trigger a process in the Enmeshed Runtime. The long polling is done by calling the `GET /api/v2/Requests/Incoming` route. You can use the query params `source.reference=` and `status=ManualDecisionRequired` to filter for Requests that belong to the Template you are currently working on. -For more information about the events you can head over to the [Connector Modules site]({% link _docs_integrate/03-connector-modules.md %}) and read about the [AMQP Publisher module]({% link _docs_integrate/03-connector-modules.md %}#amqppublisher) and the [WebhooksV2 module]({% link _docs_integrate/03-connector-modules.md %}#webhooksv2) that are propagating events. +For more information about the events you can head over to the [Connector Modules site]({% link _docs_scenarios/scenario-sc80.md %}) and read about the [AMQP Publisher module]({% link _docs_scenarios/scenario-sc80.md %}#amqppublisher) and the [WebhooksV2 module]({% link _docs_scenarios/scenario-sc80.md %}#webhooksv2) that are propagating events. {% include copy-notice description="After you received the Request, save its `id` for the next step." %} diff --git a/_includes/scenarios/scenario-sc60.md b/_includes/scenarios/scenario-sc60.md index 0688af303..c0ae7edf9 100644 --- a/_includes/scenarios/scenario-sc60.md +++ b/_includes/scenarios/scenario-sc60.md @@ -6,7 +6,7 @@ This guide explains how to send and receive a Request over Enmeshed Messages usi {% include properties_list.html %} -This guide assumes that you already have an active Relationship between two Connectors. If you don't, you should follow the [Requests over Templates]({% link _docs_scenarios/scenario-sc59.md %}) guide first. If you created a Relationship during the [Connector Tutorial]({% link _docs_integrate/01-connector-tutorial.md %}) this will also work. +This guide assumes that you already have an active Relationship between two Connectors. If you don't, you should follow the [Requests over Templates]({% link _docs_scenarios/scenario-sc59.md %}) guide first. If you created a Relationship during the [Connector Tutorial]({% link _docs_scenarios/scenario-sc95.md %}) this will also work. In this guide, the first Connector will be called Sender and the second Connector will be called Recipient. The Sender will send a Request to the Recipient. For the next steps you will need the Enmeshed Address of the Recipient. You can find it out by calling the `GET /api/v2/Relationships` route on the Sender Connector. @@ -27,7 +27,7 @@ In this guide, the first Connector will be called Sender and the second Connecto ## Check your Requests validity At first you should check if your Request is valid. You can do this by calling the `POST /api/v2/Requests/Outgoing/Validate` route on the Sender Connector with the following body. -For simplicity the Request inside the Template only contains an AuthenticationRequestItem, but you can use any [RequestItems]({% link _docs_integrate/62-request-items.md %}) you want. +For simplicity the Request inside the Template only contains an AuthenticationRequestItem, but you can use any [RequestItems]({% link _docs_scenarios/scenario-sc91.md %}) you want. Even though the `peer` property is optional, it is recommended to specify it whenever possible. This allows additional validation rules to execute. When you are sending a Request over Messages you always know your peer. @@ -107,7 +107,7 @@ The Enmeshed Runtime will read the Message and create a new incoming Request. Yo The long polling is done by calling the `GET /api/v2/Requests/Incoming` route. You can use the query params `source.reference=` and `status=ManualDecisionRequired` to filter for Requests that belong to the Message that contained the Request. -For more information about the events you can head over to the [Connector Modules site]({% link _docs_integrate/03-connector-modules.md %}) and read about the [AMQP Publisher module]({% link _docs_integrate/03-connector-modules.md %}#amqppublisher) and the [WebhooksV2 module]({% link _docs_integrate/03-connector-modules.md %}#webhooksv2) that are propagating events. +For more information about the events you can head over to the [Connector Modules site]({% link _docs_scenarios/scenario-sc80.md %}) and read about the [AMQP Publisher module]({% link _docs_scenarios/scenario-sc80.md %}#amqppublisher) and the [WebhooksV2 module]({% link _docs_scenarios/scenario-sc80.md %}#webhooksv2) that are propagating events. {% include copy-notice description="After you received the Request, save its `id` for the next step." %} diff --git a/_includes/scenarios/scenario-sc63.md b/_includes/scenarios/scenario-sc63.md index 27c2aef9d..b043b7d09 100644 --- a/_includes/scenarios/scenario-sc63.md +++ b/_includes/scenarios/scenario-sc63.md @@ -1,21 +1,104 @@ - +## Prerequisites -Lorem ipsum dolor sit amet consectetur adipisicing elit. Perferendis voluptas deserunt alias accusantium rem? Quaerat, temporibus alias fuga rerum unde dolor blanditiis quia incidunt modi rem, sequi, esse aut accusamus. +### MongoDB - +The Connector requires a MongoDB database as its data storage. MongoDB is a document-oriented database. For compatibility and security reasons, the most up-to-date version of MongoDB should be used. +For more information, please see . -{% include properties_list.html %} +### Container Runtime - +The Connector requires a Container Runtime like Docker or Kubernetes: Docker is a virtualization technology which introduces highly portable software containers. The Connector is shipped and updated as such a Docker container - the Docker Runtime is the runtime environment which can execute the Docker containers. For compatibility and security reasons, the most up-to-date version of the Docker Runtime should be used. +For more information, please see . -Lorem ipsum dolor sit amet consectetur adipisicing elit. Unde nihil sequi ipsam blanditiis optio nulla quidem tempore sapiente nam, molestiae et voluptas ab harum quo incidunt reiciendis dolorum sed eligendi quos in itaque vel facilis. Rerum quia asperiores porro, odit laborum error voluptates repellat repellendus doloribus minima voluptate debitis libero nemo sit, dolorem consequatur expedita architecto! Molestiae, quae maxime ut iste ratione veniam velit asperiores. Earum corrupti architecto molestiae necessitatibus ullam modi beatae optio distinctio et labore, consectetur, repudiandae alias recusandae quas delectus placeat error laudantium quos, autem non nemo cum. Obcaecati iure maiores quas temporibus assumenda, qui veritatis necessitatibus. +Visit [the official docker docs](https://docs.docker.com/get-docker/) for installation guides. - +### Hardware Requirements -# Developer Corner +No special hardware requirements have been identified so far and as always, hardware requirements strongly correlate with the envisoned usage scenario. - -
              - Flowchart -
              {% include diagrams/Enmeshed_Scenarios.svg %}
              -
              +A good starting point for hosting the Docker image of the Connector would be the following: + +- 1 CPU +- 512MB RAM +- 1GB HDD + +Depending on the usage scenario, higher hardware requirements might be necessary. + +### Internet Connectivity + +A reliable and fast internet connection is mandatory for running the Connector. However, the Connector is only communicating with the Backbone so the corresponding domain (e.g. `https://prod.enmeshed.eu`) can be whitelisted and the associated certificate can be additionally pinned. + +### List docker image tags + +Read more about listing available docker image tags [here]({% link _docs_explore/52-connector.md %}#connector-docker-image). + +### Familiarize with our policies + +Before setting up Enmeshed, you should familiarize yourself with our [Security Considerations]({% link _docs_scenarios/scenario-sc84.md %}) and [Privacy Considerations]({% link _docs_scenarios/scenario-sc85.md %}). + +## Installation with Docker + +Make sure that you have installed docker compose. Visit [the official installation guide](https://docs.docker.com/compose/install/) for more information. + +**ATTENTION:** The Docker compose files we provide in this tutorial are not recommended to use in production scenarios. Please read [Use Compose in production](https://docs.docker.com/compose/production/) for more information on how to write a production-grade compose file and our [Security Considerations]({% link _docs_scenarios/scenario-sc84.md %}#docker-compose-file-security-considerations). +{: .notice--warning} + +### Option 1: docker compose including MongoDB + +Go through the following steps to start the Connector: + +1. place the file [examples/docker-compose-with-mongodb.yml](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/docker-compose-with-mongodb.yml) as `docker-compose.yml` in a folder of your choice +2. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_scenarios/scenario-sc79.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/example.config.json). If you used the yml-file from the first step, the connection string looks as follows: + ```text + mongodb://:@mongodb:27017 + ``` +3. replace all `` in the compose file with the corresponding values +4. (optional) follow the steps under [log file mounting](#log-file-mounting) if you want to persist and access the log files on the host system +5. execute `docker compose up -d` in the shell + +### Option 2: docker compose with existing MongoDB + +Visit the official [MongoDB website](https://www.mongodb.com/) for installation without docker or cloud usage or the [docker hub page](https://hub.docker.com/_/mongo) for information about the installation with docker. + +Go through the following steps to start the Connector: + +1. make your existing MongoDB available for the connector +2. place the file [examples/docker-compose-with-existing-mongodb.yml](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/docker-compose-with-existing-mongodb.yml) as `docker-compose.yml` in a folder of your choice +3. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_scenarios/scenario-sc79.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/example.config.json) +4. replace all `` in the compose file with the corresponding values +5. (optional) follow the steps under [log file mounting](#log-file-mounting) if you want to persist and access the log files on the host system +6. execute `docker compose up -d` in the shell + +### Option 3: docker compose with FerretDB + +Go through the following steps to start the Connector: + +1. place the file [examples/docker-compose-with-ferretdb.yml](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/docker-compose-with-ferretdb.yml) as `docker-compose.yml` in a folder of your choice +2. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_scenarios/scenario-sc79.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/example.config.json). If you used the yml-file from the first step, the connection string looks as follows: `mongodb://ferretdb:27017` +3. replace all `` in the compose file with the corresponding values +4. (optional) follow the steps under [log file mounting](#log-file-mounting) if you want to persist and access the log files on the host system +5. execute `docker compose up -d` in the shell + +## Installation with Kubernetes and Helm + +Make sure that you have a running Kubernetes cluster and that you have installed [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) and [Helm](https://helm.sh/docs/intro/install/). + +You have to provide your own MongoDB instance. Visit the [MongoDB website](https://www.mongodb.com/) for installation without docker or cloud usage or the [docker hub page](https://hub.docker.com/_/mongo) for information about the installation with docker or install it [in kubernetes via Helm](https://artifacthub.io/packages/helm/bitnami/mongodb). + +For the installation and configuration head over to the dedicated [Connector Helm chart site]({% link _docs_scenarios/scenario-sc82.md %}). + +## Validate the Connector installation + +You can validate the Connector installation by checking its health route. Simply access `/health` in your browser or using curl. + +If the swagger documentation is enabled you can also access it under `/docs` + +## Log file mounting + +1. Uncomment the volume mapping in the created `docker-compose.yml` file +2. Create a folder where the log files shall be placed. Make sure that the process in the container has write access to the folder e.g. by executing `chmod 777 ` on your created folder. +3. replace `` with the path to your created folder + +## Troubleshooting + +If you encounter any problems while setting up the Connector, head over to the [Troubleshooting]({% link _docs_scenarios/scenario-sc81.md %}) site. diff --git a/_docs_operate/20-connector-api.md b/_includes/scenarios/scenario-sc75.md similarity index 95% rename from _docs_operate/20-connector-api.md rename to _includes/scenarios/scenario-sc75.md index 9c5977a96..9c7e6adb0 100644 --- a/_docs_operate/20-connector-api.md +++ b/_includes/scenarios/scenario-sc75.md @@ -1,8 +1,3 @@ ---- -title: "Connector API" -permalink: /operate/connector-api ---- - The primary integration capability of the Connector is the REST API. In order to use it, you should have received an API-Key for the respective Connector. An API-Key so far has all authorizations for accessing the API. ## Interactive Documentation diff --git a/_docs_integrate/00-basics.md b/_includes/scenarios/scenario-sc76.md similarity index 98% rename from _docs_integrate/00-basics.md rename to _includes/scenarios/scenario-sc76.md index 277cb3a95..73de9140b 100644 --- a/_docs_integrate/00-basics.md +++ b/_includes/scenarios/scenario-sc76.md @@ -1,8 +1,3 @@ ---- -title: "Basics" -permalink: /integrate/basics ---- - You want to seamlessly use Enmeshed with your processes, solutions and software components? No worries, you are good to go! We've built the Enmeshed Connector exactly for this scenario: to integrate existing systems with the Enmeshed approach with as little effort as possible. diff --git a/_docs_integrate/10-connector-installation.md b/_includes/scenarios/scenario-sc77.md similarity index 83% rename from _docs_integrate/10-connector-installation.md rename to _includes/scenarios/scenario-sc77.md index 637cc5548..b043b7d09 100644 --- a/_docs_integrate/10-connector-installation.md +++ b/_includes/scenarios/scenario-sc77.md @@ -1,9 +1,3 @@ ---- -title: "Connector Installation" -permalink: /integrate/connector-installation -toc: true ---- - ## Prerequisites ### MongoDB @@ -40,13 +34,13 @@ Read more about listing available docker image tags [here]({% link _docs_explore ### Familiarize with our policies -Before setting up Enmeshed, you should familiarize yourself with our [Security Considerations]({% link _docs_integrate/42-connector-security.md %}) and [Privacy Considerations]({% link _docs_integrate/43-connector-privacy.md %}). +Before setting up Enmeshed, you should familiarize yourself with our [Security Considerations]({% link _docs_scenarios/scenario-sc84.md %}) and [Privacy Considerations]({% link _docs_scenarios/scenario-sc85.md %}). ## Installation with Docker Make sure that you have installed docker compose. Visit [the official installation guide](https://docs.docker.com/compose/install/) for more information. -**ATTENTION:** The Docker compose files we provide in this tutorial are not recommended to use in production scenarios. Please read [Use Compose in production](https://docs.docker.com/compose/production/) for more information on how to write a production-grade compose file and our [Security Considerations]({% link _docs_integrate/42-connector-security.md %}#docker-compose-file-security-considerations). +**ATTENTION:** The Docker compose files we provide in this tutorial are not recommended to use in production scenarios. Please read [Use Compose in production](https://docs.docker.com/compose/production/) for more information on how to write a production-grade compose file and our [Security Considerations]({% link _docs_scenarios/scenario-sc84.md %}#docker-compose-file-security-considerations). {: .notice--warning} ### Option 1: docker compose including MongoDB @@ -54,7 +48,7 @@ Make sure that you have installed docker compose. Visit [the official installati Go through the following steps to start the Connector: 1. place the file [examples/docker-compose-with-mongodb.yml](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/docker-compose-with-mongodb.yml) as `docker-compose.yml` in a folder of your choice -2. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_integrate/11-connector-configuration.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/example.config.json). If you used the yml-file from the first step, the connection string looks as follows: +2. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_scenarios/scenario-sc79.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/example.config.json). If you used the yml-file from the first step, the connection string looks as follows: ```text mongodb://:@mongodb:27017 ``` @@ -70,7 +64,7 @@ Go through the following steps to start the Connector: 1. make your existing MongoDB available for the connector 2. place the file [examples/docker-compose-with-existing-mongodb.yml](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/docker-compose-with-existing-mongodb.yml) as `docker-compose.yml` in a folder of your choice -3. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_integrate/11-connector-configuration.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/example.config.json) +3. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_scenarios/scenario-sc79.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/example.config.json) 4. replace all `` in the compose file with the corresponding values 5. (optional) follow the steps under [log file mounting](#log-file-mounting) if you want to persist and access the log files on the host system 6. execute `docker compose up -d` in the shell @@ -80,7 +74,7 @@ Go through the following steps to start the Connector: Go through the following steps to start the Connector: 1. place the file [examples/docker-compose-with-ferretdb.yml](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/docker-compose-with-ferretdb.yml) as `docker-compose.yml` in a folder of your choice -2. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_integrate/11-connector-configuration.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/example.config.json). If you used the yml-file from the first step, the connection string looks as follows: `mongodb://ferretdb:27017` +2. create a config file that can be mounted inside the Connector. Fill the config file using the [configuration docs]({% link _docs_scenarios/scenario-sc79.md %}) and the [example config file](https://raw.githubusercontent.com/nmshd/documentation/main/_docs_integrate/examples/example.config.json). If you used the yml-file from the first step, the connection string looks as follows: `mongodb://ferretdb:27017` 3. replace all `` in the compose file with the corresponding values 4. (optional) follow the steps under [log file mounting](#log-file-mounting) if you want to persist and access the log files on the host system 5. execute `docker compose up -d` in the shell @@ -91,7 +85,7 @@ Make sure that you have a running Kubernetes cluster and that you have installed You have to provide your own MongoDB instance. Visit the [MongoDB website](https://www.mongodb.com/) for installation without docker or cloud usage or the [docker hub page](https://hub.docker.com/_/mongo) for information about the installation with docker or install it [in kubernetes via Helm](https://artifacthub.io/packages/helm/bitnami/mongodb). -For the installation and configuration head over to the dedicated [Connector Helm chart site]({% link _docs_integrate/14-connector-helm-chart.md %}). +For the installation and configuration head over to the dedicated [Connector Helm chart site]({% link _docs_scenarios/scenario-sc82.md %}). ## Validate the Connector installation @@ -107,4 +101,4 @@ If the swagger documentation is enabled you can also access it under `