Skip to content
Snippets Groups Projects
Commit ffb52fae authored by Anfal Fadhil's avatar Anfal Fadhil
Browse files

new documentation added in a separate section

parent 51b65226
No related branches found
No related tags found
1 merge request!331Collaboration Support documentation update
Pipeline #161608 failed
Stage: review
Hide whitespace changes
Inline Side-by-side
docs/tutorial/DataNotification.md
+ 127
− 124
View file @ ffb52fae
......@@ -13,6 +13,7 @@
* [Update secret for a Subscription](#update-subscription)
* [Version info endpoint](#version-info-endpoint)
* [Current Limitations](#limitation)
* [Support for Collaboration Context](#collaboration-support)
## Introduction <a name="introduction"></a>
The OSDU notification system allows for interested consumers to subscribe to data and metadata changes using a publish/subscriber pattern.
......@@ -33,12 +34,10 @@ The topics below describe these steps/APIs in detail that allow consumers to cre
### Get topics available to subscribe<a name="list-topics"></a>
Consumer uses Data notification "topics" API to view the list of supported notification topics and corresponding sample messages.
Notice that now register is collaboration aware, which means when the consumer provides the "x-collaboration" header the list of topics returned will have a new topic "recordstopic-v2" which will receive notifications when "x-collaboration" header is provided.
```
GET api/register/v1/topics
```
<details><summary>curl for a general request</summary>
<details><summary>curl</summary>
```
curl --request GET \
......@@ -49,8 +48,7 @@ curl --request GET \
```
</details>
A sample output is shown below when the collaboration context header is not provided. Please note the "name" of the topic. This is required to create a Subscription for a topic you are interested in.
A sample output is shown below. Please note the "name" of the topic. This is required to create a Subscription for a topic you are interested in.
<details><summary>Sample response</summary>
```
......@@ -136,125 +134,6 @@ A sample output is shown below when the collaboration context header is not prov
</details>
<details><summary>curl for a collaboration context header provided request</summary>
```
curl --request GET \
--url 'https://register-svc.osdu.com/api/register/v1/topics' \
--header 'Authorization: Bearer <JWT>' \
--header 'Content-Type: application/json' \
--header 'data-partition-id: common' \
--header 'x-collaboration: id=<collaboration id>,application=<application name>' \
```
</details>
A sample output is shown below when the collaboration context header is provided.
<details><summary>Sample response</summary>
```
[
{
"name": "recordstopic",
"description": "This notification is sent whenever a new record or record version is created, updated or deleted in storage. 'previousVersionKind' is noted upon 'kind' update. Record deletion is noted as a soft 'deletionType'. Record purge is noted as a hard 'deletionType'.",
"state": "ACTIVE",
"example": [
{
"id": "osdu:abc:123",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.0",
"op": "create"
},
{
"id": "osdu:abc:345",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.1",
"op": "update",
"previousVersionKind": "osdu:petrel:regularheightfieldsurface:1.0.0"
},
{
"id": "osdu:abc:567",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.0",
"op": "delete",
"deletionType": "soft"
},
{
"id": "osdu:abc:789",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.0",
"op": "delete",
"deletionType": "hard"
}
]
},
{
"name": "schemachangedtopic",
"description": "This notification is sent whenever a new schema is created or updated via schema-service.",
"state": "ACTIVE",
"example": [
{
"kind": "osdu:wks:wellbore:1.0.0",
"op": "update"
},
{
"kind": "osdu:wks:wellbore:2.0.0",
"op": "create"
}
]
},
{
"name": "statuschangedtopic",
"description": "Every Service/Stage would publish their respective status changed information in this topic.",
"state": "ACTIVE",
"example": [
{
"kind": "status",
"properties": {
"correlationId": "12345",
"recordId": "osdu:file:3479d828-a47d-4e13-a1f8-9791a19e1a7e",
"recordIdVersion": "1610537924768407",
"stage": "STORAGE_SYNC",
"status": "FAILED",
"message": "acl is not valid",
"errorCode ": 400.0,
"timestamp ": 1.622118996E12
}
},
{
"kind": "dataSetDetails",
"properties": {
"correlationId": "12345",
"dataSetId": "12345",
"dataSetIdVersion": "1",
"dataSetType": "FILE",
"recordCount": 10.0,
"timestamp ": 1.622118996E12
}
}
]
},
{
"name": "recordstopic-v2",
"description": "This notification is sent whenever a new record or record version is created, updated or deleted in storage for all collaboration and non-collaboration context changes. The collaboration context will be provided as part of the message properties if exist. 'previousVersionKind' is noted upon 'kind' update. Record deletion is noted as a soft 'deletionType'. Record purge is noted as a hard 'deletionType'.",
"state": "ACTIVE",
"example": {
"message": {
"data": [
{
"id": "osdu:abc:123",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.0",
"op": "create"
}
],
"account-id": "opendes",
"data-partition-id": "opendes",
"correlation-id": "4f1982a2-cbdf-438a-b5a1-e0c6239d46fc",
"x-collaboration": "id=1e1c4e74-3b9b-4b17-a0d5-67766558ec65,application=Test App"
}
}
}
]
```
</details>
[Back to Table of Contents](#TOC)
## Subscribing to a topic <a name="create-subscription"></a>
......@@ -824,3 +703,127 @@ properties:
- There is no filtering applied on messages (such as based on the kind etc.) at the moment in OSDU. All the messages will be pushed to consumers.
[Back to Table of Contents](#TOC)
## Support for Collaboration Context <a name="collaboration-support"></a>
Register service and Notification service are collaboration aware. For now, to enable collaboration context support you have to enable collaboration feature flag in the services. Refer to this [Wiki](https://community.opengroup.org/groups/osdu/platform/system/-/wikis/Feature-Flag) for more details on how to do that.
That means when the consumer provides the "x-collaboration" header the list of topics returned will have a new topic "recordstopic-v2" which will receive notifications when "x-collaboration" header is provided.
<details><summary>curl for a collaboration context header provided request</summary>
```
curl --request GET \
--url 'https://register-svc.osdu.com/api/register/v1/topics' \
--header 'Authorization: Bearer <JWT>' \
--header 'Content-Type: application/json' \
--header 'data-partition-id: common' \
--header 'x-collaboration: id=<collaboration id>,application=<application name>' \
```
</details>
A sample output is shown below when the collaboration context header is provided.
<details><summary>Sample response</summary>
```
[
{
"name": "recordstopic",
"description": "This notification is sent whenever a new record or record version is created, updated or deleted in storage. 'previousVersionKind' is noted upon 'kind' update. Record deletion is noted as a soft 'deletionType'. Record purge is noted as a hard 'deletionType'.",
"state": "ACTIVE",
"example": [
{
"id": "osdu:abc:123",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.0",
"op": "create"
},
{
"id": "osdu:abc:345",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.1",
"op": "update",
"previousVersionKind": "osdu:petrel:regularheightfieldsurface:1.0.0"
},
{
"id": "osdu:abc:567",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.0",
"op": "delete",
"deletionType": "soft"
},
{
"id": "osdu:abc:789",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.0",
"op": "delete",
"deletionType": "hard"
}
]
},
{
"name": "schemachangedtopic",
"description": "This notification is sent whenever a new schema is created or updated via schema-service.",
"state": "ACTIVE",
"example": [
{
"kind": "osdu:wks:wellbore:1.0.0",
"op": "update"
},
{
"kind": "osdu:wks:wellbore:2.0.0",
"op": "create"
}
]
},
{
"name": "statuschangedtopic",
"description": "Every Service/Stage would publish their respective status changed information in this topic.",
"state": "ACTIVE",
"example": [
{
"kind": "status",
"properties": {
"correlationId": "12345",
"recordId": "osdu:file:3479d828-a47d-4e13-a1f8-9791a19e1a7e",
"recordIdVersion": "1610537924768407",
"stage": "STORAGE_SYNC",
"status": "FAILED",
"message": "acl is not valid",
"errorCode ": 400.0,
"timestamp ": 1.622118996E12
}
},
{
"kind": "dataSetDetails",
"properties": {
"correlationId": "12345",
"dataSetId": "12345",
"dataSetIdVersion": "1",
"dataSetType": "FILE",
"recordCount": 10.0,
"timestamp ": 1.622118996E12
}
}
]
},
{
"name": "recordstopic-v2",
"description": "This notification is sent whenever a new record or record version is created, updated or deleted in storage for all collaboration and non-collaboration context changes. The collaboration context will be provided as part of the message properties if exist. 'previousVersionKind' is noted upon 'kind' update. Record deletion is noted as a soft 'deletionType'. Record purge is noted as a hard 'deletionType'.",
"state": "ACTIVE",
"example": {
"message": {
"data": [
{
"id": "osdu:abc:123",
"kind": "osdu:petrel:regularheightfieldsurface:1.0.0",
"op": "create"
}
],
"account-id": "opendes",
"data-partition-id": "opendes",
"correlation-id": "4f1982a2-cbdf-438a-b5a1-e0c6239d46fc",
"x-collaboration": "id=1e1c4e74-3b9b-4b17-a0d5-67766558ec65,application=Test App"
}
}
}
]
```
</details>
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment