The Project Plan API facilitates system integration, providing a mechanism to get versioned data from DrillPlan.

The collection of APIs is used to list the available projects on a data-partition, the plans within a given project, the artifacts within a given plan and finally a specific artifact.

As the data models change over time, new versions may be introduced, hence some artifacts will be available in multiple versions. It is recommended to use the latest version of each artifact type, and to adopt the latest version when this becomes available. Superseded versions are only guaranteed support for 6 months, although we often maintain support for longer.

It is recommended that the users of this API have some familiarity with the DrillPlan Application. A useful resource would be the DrillPlan Help Documentation. The following items are summarized below:

• Data-partition: A data-partition is layer for data separation. There can be multiple data-partitions within a DELFI Account and Contract.

• Project: Within a data-partition there are multiple projects. A project is used to manage the planning of a particular well and contains:

  • Well header information such as Name, UWI (unique well identifier), Operator, Country, Elevation, CRS, Corporate Profile (rule-sets used for governance), unit system selection etc.
  • Tasks and project management
  • Team management: A list of users known as team members who have access to the project
  • Reports
  • Plans

• Plan: A project can contain multiple plans. One plan is always designated as the "master" plan and other plans can be used to evaluate competing design concepts, contingencies etc. A plan is a fundamental layer in the DrillPlan collaboration model and contains all the elements of the well design e.g. Surface Locations, Wellbores, Trajectories, Target, Formation Tops, Temperature Curves, Pressure Windows, Wellbore Geometries, Sections, Drilling Fluid Programs, Drilling Runs and Activities, Risks, BHAs, Operating Parameters, Cement Programs, Detailed Casing/Liner/Tieback string design, AFE (Costs) etc.

1. Find the DrillPlan project

   Caller can query DrillPlan projects using one of the following APIs:

   1. Query all DrillPlan projects:

   By calling the GET /projects/pages API,​ the paginated project list will be returned according to the following schema. This API is accessible with either user identity or service identity. However, please note that a user is only allowed to fetch data from projects they have joined.

   Example response body(click to open)

   
   

   {
     "projects": [
       {
         "project_id": "string",
         "project_name": "string",
         "well_name": "string",
         "country": "string",
         "created_by": "string",
         "create_date": "string",
         "is_invitation_only": true,
         "joined": true
       }
     ],
     "page_index": 1,
     "total_pages": 1,
     "total_items": 1
   }

   2. Get user joined project list:

   Users can also retrieve all project that they have joined in DrillPlan. To do this, call the GET /projects/joined API,​ the user joined project list will be returned according to the following schema. This API is only accessible by user identity and will return empty list when called by a service identity.

   Example response body(click to open)

   
   

   [
     {
       "project_id": "string",
       "project_name": "string",
       "well_name": "string",
       "country": "string",
       "created_by": "string",
       "create_date": "string",
     }
   ]

2. Get plan list by Project Id:

The list of plans within a specific project can be retrieved using the **GET /plans/by-project/{projectId}**​ endpoint. It will return a plan list according to the following schema.

[
  {
    "id": "string",
    "name": "string",
    "isMaster": true,
    "status": 0,
    "shareTime": "2022-09-06T01:41:50.717Z",
    "shareBy": "string"
  }
]

User can find the master plan by filtering on the isMaster boolean property.

3. Get artifact index for a given plan:

Call GET /plans/{planId}/artifact-index​ to get the plan data structure (well, wellbores, sections, runs) and available artifact list. The corresponding artifact links can then be used to fetch the corresponding data.

[
  {
    "planName": "string",
    "planStatus": 0,
    "dataPartitionId": "string",
    "lastUpdateTime": "2022-09-06T03:19:45.828Z",
    "well": {
      "name": "string",
      "id": "string"
    },
    "wellbores": [
      {
        "name": "string",
        "id": "string",
        "parentWellbore": "string"
      }
    ],
    "sections": [
      {
        "name": "string",
        "id": "string",
        "wellboreId": "string"
      }
    ],
    "runs": [
      {
        "displayName": "string",
        "id": "string",
        "type": "string",
        "sectionId": "string"
      }
    ],
    "artifacts": [
      {
        "wellboreId": "string",
        "sectionId": "string",
        "runId": "string",
        "artifactType": "string",
        "artifactLink": "string"
      }
    ]
  }
]

4. Get a specific artifact file:

Use the artifact link returned by the artifact-index API to get specific artifact file. The artifact file can be in WISTML, Json or other format. The artifact link follows the pattern of GET /plans/{planId}/artifacts/{id}/{artifactType} Note: For examples of artifacts, please refer to the end of the document.

5. Get DrillPlan editor links:

Call GET /plans/{planId}/application-links to get direct links of DrillPlan editors (object). This can be useful to edit most of the artifacts details by directly accessing the relevant editor.

[
  {
    "node_id": "string",
    "name": "string",
    "wellbore_id": "string",
    "section_id": "string",
    "run_id": "string",
    "node_type": "string",
    "editor_link": "string"
  }
]

6. Call GET /plans/{planId}/application-review-states to know the DrillPlan object's state during the course of planning. This object state (or application review state) can be used to determine its current status, such as "in progress," "in review," "in approval," "rejected," or "completed."

[
  {
    "node_id": "string",
    "node_type": "string",
    "name": "string",
    "review_state": "InProgress"
  }
]

The following table includes some example artifacts that can be retrieved using the API. The list of artifacts will increase over time, so it is recommended to use the Project Plan API to retrieve the latest list.

The download link below provides an example extract using Project Plan API from a demo project created using a public data set. This can be used to give an indication of kind of values that are included in the above artifacts, but will not be comprehensive, since the output will depend on the data that resides inside the project being queried.

📥 Download Example Artifacts