DrillPlan's Notification API allows external applications to subscribe to key events within the system. Following the event, DrillPlan will send a POST request to a provided callback_uri, together with some context, allowing the external application to trigger further action and business logic e.g.
- Extract some data from DrillPlan's Project Plan API and publish it to another application or database.
- Extract a report from DrillPlan's Reporting API.
- Update an external system with a new state.
- etc.
To make a new subscription, the subscribing application should issue a POST request to the following endpoint {baseURL}/v1/notifications/subscriptions/types/{subscriptionType}:
Example cURL POST Request (click to open)
curl -L -X POST '{baseURL}/notifications/v1/notifications/subscriptions/types/{subscriptionType}' \
-H 'accept: application/json' \
-H 'slb-partition-id: {SlbPartitionId}' \
-H 'appkey: {appKey}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {token}' \
--data-raw '{
"subscriber": "DemoApp",
"callback_uri": "{callback_uri}",
"callback_headers": {
"Authorization": "Bearer {token}",
"CustomHeader1": "Personal Header Value 1"
},
"drill_plan_object_types": [
"reporting",
"/geomechanics/api/temperatures",
"/geology/api/formation-tops"
],
"contact_email": "TMurray2@slb.com"
}'Where:
baseURL= API URL corresponding to your DrillPlan sitesubscriptionType= Any of:ReviewStateChanged: Raised when an object specified in thedrill_plan_object_typesarray, has been reviewed, approved, completed or rejected in DrillPlan.This was selected in the example above.
PublishData: Raised when a user selects the "Publish Data" button in the connection portal.If this subscription type is selected then a
data_sourcemust also be provided in the request body, with a matching value used in the Consumption Hub APIPlanShared: Raised when an object specified in thedrill_plan_object_typesarray has been shared to the plan in DrillPlan.ProjectCreated: Raised when a new Project is created in DrillPlan.MasterPlanChanged: Raised when master plan is changed in DrillPlan.
Following the event in DrillPlan, a callback will be made to the callback_uri provided in the subscription, as a POST request. The body of the request will vary depending on the nature of the subscription. Some examples are provided below:
Example Body Received for PlanShared Notification (click to open)
{
"slb_partition_id": "publicdemo01-osdu-slb",
"site_url": "https://eur.drillplan.delfi.slb.com/",
"drill_plan_plan_id": "3d697b991e084c99a2b786e72d0fc86e",
"drill_plan_project_id": "f267fb27acca41e4857237aff9c91339",
"notification_type": "PlanShared",
"drill_plan_object_types": [
"/Traj/api/trajectories",
"/Traj/api/trajectories",
"/location/api/targets",
"/well/api/wbgs"
],
"content": {
"changes_summaries": [
{
"node_id": "a6cfc8dde4dc58d6877a9704acbf0784",
"change_type": "Modify",
"object_type": "/Traj/api/trajectories",
"wellbore_id": "f32eb82917544f4b9b92dbc9072bbb4d"
},
{
"node_id": "354364f2fe3d583cb8f8eed76260b0f8",
"change_type": "Modify",
"object_type": "/Traj/api/trajectories",
"wellbore_id": "a2a0555f8b0144f4881de92a21893db3"
},
{
"node_id": "5f8622cc23d941c79bf2da76251d3bc8",
"change_type": "Add",
"object_type": "/location/api/targets",
"wellbore_id": "f32eb82917544f4b9b92dbc9072bbb4d"
},
{
"node_id": "71f377a61f095246a2616e493325a172",
"change_type": "Add",
"object_type": "/well/api/wbgs",
"wellbore_id": "ef3b15a9ea4d4bf69317631a39e972ef"
}
]
}
}
Example Body Received for ReviewStateChange Notification (click to open)
{
"slb_partition_id": "publicdemo01-osdu-slb",
"site_url": "https://eur.drillplan.delfi.slb.com/",
"drill_plan_plan_id": "9168ec42639b4049b163ee8690882a6d",
"drill_plan_project_id": "65496022660a467f93c524ecf365dbf2",
"notification_type": "ReviewStateChanged",
"drill_plan_object_types": [
"/geomechanics/api/temperatures"
],
"content": {
"status": "Completed",
"wellbore_id": "00b8079c73e14686a446399d3ef83060",
"section_id": "ef10024ad11545978c6411e10b9ede39",
"artifact_type": "/geomechanics/api/temperatures",
"artifact_link": "/geomechanics/api/temperatures/16e95464f1244cf0b261ead9d0aa3ca1/versions/4",
"node_id": "1c54e86cc75959dc828de8ecf960d897"
}
}Example Body Received for ProjectCreated Notification (click to open)
{
"slb_partition_id": "publicdemo01-osdu-slb",
"site_url": "https://eur.drillplan.delfi.slb.com/",
"drill_plan_project_id": "65496022660a467f93c524ecf365dbf2",
"notification_type": "ProjectCreated",
}Example Body Received for MasterPlanChanged Notification (click to open)
{
"slb_partition_id": "publicdemo01-osdu-slb",
"site_url": "https://eur.drillplan.delfi.slb.com/",
"drill_plan_plan_id": "9168ec42639b4049b163ee8690882a6d",
"drill_plan_project_id": "65496022660a467f93c524ecf365dbf2",
"notification_type": "MasterPlanChanged",
"content": {
"previous_master_plan_id": "abcdec8a34564049b163aa8698436ddd",
}
}The 'Notification API' is designed to adapt to various authentication systems, enabling subscribers to seamlessly incorporate it into their current authentication processes. Subscribers have the ability to modify their subscription and associated headers as often as needed, which facilitates the use of diverse authentication techniques, such as:
- Authorization: Basic {base64encodedstring}
- Authorization: Bearer {token}
- X-API-Key: {apiKey}
- and more.
While the specific architecture may vary, one example is provided below where a service periodically generates a token from an Authorization Server, updates the subscription using the DrillPlan 'Notification API' and validates the inbound calls received by checking the Bearer token contained in the Authorization header. This could be validated by using an Introspection Request to the Authorization server or using a public key and token signature.
