DrillPlan AEA Extensibility Tutorial

• DrillPlan AEA Extensibility Tutorial
• DrillPlan AEA Summary
• External Engine Registrations
  • Add a new external engine
  • Engine metadata
  • Audit Log
  • Transport Layer Security validation
• DrillPlan AEA Agent API
  • Metadata
  • Agent Metadata Contents
  • Supported input types
    • Agent dependencies
    • Example agent dependency registration
    • Agent Registration Sequence Diagram
  • Validations
    • Validation include three types of results
    • Preview result types
    • Unit conversion
    • Results
    • Agent Validation Sequence Diagram

The DrillPlan AEA (Automated Engineering Analysis) framework is used to provide engineering validations to the end user, shown in the form of "AEA cards" in the front end. Each AEA card is initially shown as a traffic light

• green checkmark = successful validation (info)
• yellow exclamation = warning (warning)
• red cross = failed validation (error)
• grey question mark = missing data or input (unknown)

together with a preview message or value. Further details can then be visualized by opening the card to reveal

• messages
• text based results (e.g. key value pairs)
• links
• graphical charts
• suggestions

The 'DrillPlan Collaboration Model' allows user's to create multiple plans within a project. Any user working within the project has the ability to edit a plan by creating a "draft" (e.g. a draft might contain several edited objects like a an updated trajectory or wellbore geometry). This action automatically triggers all the engineering validations, whose input has been updated to re-calculate, providing the relevant information to the user. Once they have reviewed the results of all the validations, they can decide to share their draft changes, overwriting and automatically incrementing the latest team plan version. This in turn will also automatically re-run all the engineering validations.

DrillPlan's 'AEA Extensibility' allows additional external services, hosted anywhere on the web, to be self-registered in the corporate settings. Once successfully registered, they will automatically be called each time their inputs or dependencies are updated, providing a very flexible and powerful way to supplement the default DrillPlan experience. While initially intended to perform supplementary or IP controlled simulations, the infrastructure could and indeed has, been used in a number of creative ways including:

• to perform cross-system lookups checking that designs are synchronized in multiple applications
• to perform inventory checks of selected components
• to use other web services to provide additional information about an geographic location or field
• to broadcast update events to external systems
• to generate reports and pre-filled permits
• to provide graphics and tables to DrillPlan's reporting infrastructure (all AEA cards and their contents are automatically mapped into this application)

This tutorial aims to provide instructions on how to register a new external engine, to offer some guidance and examples of the API responses needed by the external service and to describe the available data you can extract from the system.

To register an external engine, enter DrillPlan Corporate Settings.

All external engines can be created, edited and deleted under 'External Engines' (located today in the Default Corporate Profile)

To add a new external engine, select the

To view the engine's information, select The metadata contains name and version of the engine.

Engine output shows under which AEA Panel tab it will be placed and what the validation card is called.

Engine input allows you to see required DrillPlan input types.

Agent Dependencies shows which DrillPlan internal engines results are required for the external engine.

"Download Recent Events" gives you the latest events from the engine as a .csv file. Its main purpose is to help while troubleshooting.

All service registration actions will be recorded. We provide this log for download by selecting the icon. This will download the entire audit log as a .csv file.

Only valid TLS certificates are allowed, and supported TLS protocols are 1.2 and 1.3.

The DrillPlan AEA External Engine API OpenAPI specification details the required endpoints for the external service.

All DrillPlan AEA Agents must declare through its metadata endpoint what they require to complete their validation.

NOTE: DrillPlan will rely on the metadata both for registering engines to be part of the AEA infrastructure and as a health check.

• Input Types (Required)
  • An array of at least one of the supported input types
  • In cases where you want a collection, you can declare this by appending "[]" at the end of the declaration, e.g. "run-v1[]". Note that collections are only available if you declare your scope on a level higher than the required input type.
• Agent Dependencies (Optional)
  • An array of DrillPlan AEA agent dependency registrations
• Validation Result Placeholder
  • A description of where to place, how to group and a title of the validation result
• Scope
  • The validation scope.

If your external engine requires the results of a DrillPlan AEA internal engine, you can register this dependency in the metadata. The available agent dependecies are listed below:

{
    "agent": {
        "name": "External Engine Test",
        "version": "11"
    },
    "input_metadata": [
        {
            "type_id": "run-v1[]"
        },         
        {
            "type_id": "wbg-v4"
        }
    ],
    "agent_dependencies": [
        {
            "name": "CasingDesign.CasingIntegrity.AeaAgent",
            "version": "0.9.1"
        }
    ],
    "result_placeholders": [
        {
            "id": "external-engine-validation-id",
            "name": "External Engine Validation",
            "category": "External Engine"
        },
        {
            "id": "external-engine-validation-parameterized-id",
            "name": "Parameterized results",
            "category": "External Engine"
        }
    ],
    "visualizations": {
        "NTZ-compatibility-result_1": {
            "type": "log",
            "tracks": [
                {
                    "fill": [
                        {
                            "key": "planned_wob_1",
                            "label": "L1",
                            "from": "planned_min_wob_1",
                            "to": "planned_max_wob_1",
                            "style": {
                                "color": "#75CDFF",
                                "opacity": 0.5,
                                "pattern": "solid"
                            }
                        },
                        {
                            "key": "rotating_wob_1",
                            "label": "L2",
                            "from": "rotating-tension-wob_1",
                            "to": "rotating_compression_wob_1",
                            "style": {
                                "color": "#EB8180",
                                "opacity": 0.5,
                                "pattern": "solid"
                            }
                        }
                    ],
                    "fillsOverlap": [
                        {
                            "fillsKeys": [
                                "planned_wob_1",
                                "rotating_wob_1"
                            ],
                            "label": "L3"
                        }
                    ]
                }
            ]
        }
    },
    "scope": "Wellbore",
    "package_version": "1.0.0"
}

In this example, the engine provides two validation results, "External Engine Validation" and "Parameterized results". To rely on the built-in charting for an AEA card, you must declare visualization by providing a configuration for your chart declared in the validation results. In this example, it is NTZ-compatibility-result_1".

The scope tells DrillPlan AEA where to place the engine in the DrillPlan project. Currently there are 4 levels available: Well, Wellbore, Section and Run.

The following sequence diagram details the actions and API calls involved in registering a new agent (aka engine or external service) and the follow up requests to check for health and updates to the metadata.

Note that the values shown in blue are all entered in the corporate settings during registration.

When an object is saved as draft or shared to the team plan, the AEA infrastructure will trigger a request for validation. The infrastructure will respond with cached results in the event of requesting validations on previously ran validations.

A validation request will only be made if any of the engine's required input objects are part of the change set.

When a validation is requested, a POST request is made to the AEA Agent API. This request will provide all inputs data and dependency agents results required by the engine along with a validation id. DrillPlan will rely on this validation id when polling for engine results or in an event of a cancellation.

• Single result
  • Required in payload
    • "$type" : "SingleResult"
• Parameterized result
  • Required in payload
    • "$type":"ParameterizedResult"
  • Templatized string that support token replacement, with unit conversion support.
• Data series result
  • Required in payload
    • "$type": "DataSeriesResult"
  • All visualizations will be defined here. This includes index and different curves, in addition how each curve is displayed. There is a developer portal in DrillPlan that let you test out supported charts. This can be found under https://<your drillplan host>/webdrillplan/developer-portal. It may be that this is not enabled for your tenant. If so, contact your DrillPlan representative.

• Preview Text Result
  • Required in payload
    • "$type": "PreviewTextResult"
• Preview Value Result
  • Required in Payload
    • "$type": "PreviewValueResult"

Results will be expected by DrillPlan to be in SI. To be unit converted, the "measurement" property must be applied and must be SI compliant, i.e. "Torque", "Depth", "Pressure", "Volume" etc.

Example validation input:

{

    "validation_id": "d527cf7b-ea17-4f0a-b16d-d4fdba518134",
    "input": {
        "effective_operation_parameters-v1": {
        *Data removed for clarity. Refer to schema for possible values.*
        },
    "run-v1": {
        *Data removed for clarity. Refer to schema for possible values.*
        }
    }
}

When the validation is complete, either successfully or with a failure, the result is transferred to the DrillPlan AEA infrastructure.

The results will then be presented on the AEA Panel.

Example results

{

    "id": "3351a72f-a017-46e2-809e-2b2bd5dcd843",
    "completion_percent": 1.0,
    "status": "Completed",
    "validation_results": [

        {
            "placeholder_id": **"external-engine-validation-id",**

            "messages": [
                {
                    "severity": "Info",
                    "template": "Test engine message",
                    "parameters": **null**
                }
            ],
            "preview_result": {
                "$type": "PreviewValueResult",
                "value": 19.0,
                "url" : "https://nam.drillplan.delfi.slb.com/",
                "measurement": **null**

            },
            "results": [

                {
                    "key": "NTZ-compatibility-result_1",
                    "name": "Neutral Transion Zone Results",
                    "$type": "DataSeriesResult",
                    "index": {
                        "name": "Depth",
                        "measurement": "StandardDepthIndex",
                        "values": []

                    },
                    "series": [

                        {
                            "name": "WOB",
                            "series_group": "rotating-tension-wob_1",
                            "measurement": "HighForce",
                            "values": [],
                            "parameters": **null**
                        },
                        {
                            "name": "WOB",
                            "series_group": "rotating_compression_wob_1",
                            "measurement": "HighForce",
                            "values": [],
                            "parameters": **null**
                        },
                        {
                            "name": "WOB",
                            "series_group": "sliding_tension_wob_1",
                            "measurement": "HighForce",
                            "values": [],
                            "parameters": **null**
                        },
                        {
                            "name": "WOB",
                            "series_group": "sliding_compression_wob_1",
                            "measurement": "HighForce",
                            "values": [],
                            "parameters": **null**
                        },
                        {
                            "name": "Planned Min WOB",
                            "series_group": "planned_min_wob_1",
                            "measurement": "HighForce",
                            "values": [],
                            "parameters": **null**
                        },
                        {
                            "name": "Planned Max WOB",
                            "series_group": "planned_max_wob_1",
                            "measurement": "HighForce",
                            "values": [],
                            "parameters": **null**
                        }
                    ]
                }
            ]
        },
        {
            "placeholder_id": **"external-engine-validation-parameterized-id",**
            "messages": [
                {
                    "severity": "Info",
                    "template": "Test engine message with parameterized result",
                    "parameters": **null**
                }
            ],
            "preview_result": {
                "$type": "PreviewTextResult",
                "text": "Status"
            },
            "results": [
                {
                    "name": "Status",
                    "$type": "ParameterizedResult",
                    "template": "Hookload {hookload-key}",
                    "parameters": [
                        {
                            "key": "hookload-key",
                            "value": 30.725,
                            "measurement": "HighForce",
                            "display_decimal_place": 3
                        }
                    ]
                }
            ]
        }
    ]
}

The following sequence diagram details the actions and API calls involved in creating a new validation, the checking the results and finally the delete.

Note that the values shown in blue are all entered in the corporate settings during registration.