docs(ic): added new feature Notifications API as well as guidance and potential benefits of Digital Twins to Industry Core KIT #1158
Conversation
…Twins and Asset Administration Shell
… greater than symbols)
…e correctly linked via API-Hub
There was a problem hiding this comment.
Only different minor suggestions and comments. Overall, the most important points are:
- Please check that the year and company names in the license headers are up to date.
- I personally would change all "data exchange" to "data sharing"
- Please only use relative links
- Please try to avoid duplicates
docs-kits/kits/Industry Core Kit/Software Development View/page_notifications.mdx
Outdated
Show resolved
Hide resolved
docs-kits/kits/Industry Core Kit/Software Development View/page_notifications.mdx
Outdated
Show resolved
Hide resolved
docs-kits/kits/Industry Core Kit/Software Development View/page_notifications.mdx
Outdated
Show resolved
Hide resolved
| - The property `header` must be compliant to the aspect model [MessageHeaderAspect](#31-aspect-model-messageheaderaspect). | ||
| - The `messageId` of a notification must uniquely identify a single message, therefore it must not be reused. No two notifications must share the same `messageId`. Only if a notification could not be sent because of data transfer errors, it MAY be re-sent with the same `messageId`. | ||
| - It is recommended to use the following format (defined in the MessageHeaderAspect aspect model) for property `context`: `<domain>-<subdomain>-<object>:<[major] version>` | ||
| - `<domain>` should be the name of the use case that defines the notification, e.g., `IndustryCore`. | ||
| - `<subdomain>` should be the name of the notification API, e.g., `DigitalTwinEventAPI`. | ||
| - `<object>` should be the name of the operation for which the notification is used, e.g., `ConnectToParent`. | ||
| - Versioning only refers to major versions in both default and fallback cases. | ||
| - This is recommended as it allows the notification receiver to freely choose what technology to use for the backend service. If this information is not encoded into the notifcation's `context` propoerty, a backend service like a message-queue technology will not know which notification operation was invoked by the sender as the endpoint information is not available in this case (compared to a REST API backend service). |
There was a problem hiding this comment.
In this text, only some of the keys of the JSON data format are explained, but not all of them. Please explain all the keys/values. For example, what is the value inside version? The version of the aspect model? The version of the notification?
There was a problem hiding this comment.
I don't think that this is the correct way. There is already a aspect model documentation where all properties are explained. I don't want to replicate that. Only differences should be documented here. Otherwise, the aspect model documentation would be redundant.
|
|
||
| #### Preconditions and Dependencies | ||
|
|
||
| - The use case must standardize the notification API's name. The name of the notification API (used in property `http://purl.org/dc/terms/type`) must be defined in the Catena-X taxonomy published under https://w3id.org/catenax/taxonomy. |
There was a problem hiding this comment.
If I want to add a new name to the taxonomy, how can I do it? I would suggest to add a hint about this, here.
There was a problem hiding this comment.
Create a PR for that file. I would rather link to a documentation for that taxonomy that explain it myself, but there is none as far as I know. But I am not the owner of this, so I would not like to add that here.
|  | ||
|
|
||
| ### Notifications | ||
|
|
||
| With notifications, the Industry Core defines a message-based data exchange within Catena-X. The message is sent from one Catena-X partner - called sender - to another Catena-X partner - called receiver - using simple messages in JSON format via Catena-X connector, as shown in the following figure: |
There was a problem hiding this comment.
Duplicate content should be avoided. This is already mentioned:
https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/pull/1158/files#diff-041c26ae00b923db3704e965461d104073b021ea2e2ed3d8df81f712c31c5236R32
There was a problem hiding this comment.
Well, this is the architecture view which comes first. So, I would rather remove it from the Development View then. But I think this bit of redundancy is ok, otherwise the text would be to fragmented and hard to read.
There was a problem hiding this comment.
Thank you for keepting the IC Kit up to date. Next to the comments from @mhellmeier I also have some minor findings and suggestions. See comments below.
docs-kits/kits/Industry Core Kit/Software Development View/page_notifications.mdx
Outdated
Show resolved
Hide resolved
docs-kits/kits/Industry Core Kit/Software Development View/page_notifications.mdx
Show resolved
Hide resolved
docs-kits/kits/Industry Core Kit/Software Development View/page_notifications.mdx
Show resolved
Hide resolved
docs-kits/kits/Industry Core Kit/Software Development View/page_notifications.mdx
Show resolved
Hide resolved
…e_notifications.mdx Co-authored-by: Malte Hellmeier <[email protected]>
Accepted several proposed changes by reviews Co-authored-by: Johann Schütz <[email protected]> Co-authored-by: Malte Hellmeier <[email protected]>
|
@mhellmeier @jSchuetz88 I fixed all issues from the reviews above or gave feedback in the comments above why I don't think it's correct to change something. |
Description
This PR implements Implements a subset of eclipse-tractusx/sig-release#986
Pre-review checks
Please ensure to do as many of the following checks as possible, before asking for committer review: