Skip to content

API Basics

The FieldTwin API allows you to quickly build integrations on your own where you can connect FieldTwin with you own software applications and/or backend systems. This allows you integrate with e.g. Enterprise Document Systems, Simulation Software, or Engineering calculations software. But first lets cover some of the basic principles of what the FieldTwin platform offers.

  • Enabled with a FieldTwin Partner or Advanced License
  • Web-based REST API, industry standard technology
  • No lock-in
  • Public documentation and examples
  • You can collaborate with others and others can collaborate with you
  • Secured by a private token
  • Provides read/write access to (almost) all your data in FieldTwin
  • Provides remote management capabilities

Data Exchange

The FieldTwin Platform allows you to easily import various data sources to help build out your Energy field layout. Examples of this would typically be:

  • Bathymetry, reservoir, 2D and 3D surfaces from files
  • Connections from file, Web Feature Service (WFS) or ArcGIS
  • Layers from file, Web Map Service (WMS) or ArcGIS
  • Wells (and trajectories) from file
  • Images

Read more here FieldTwin Import Menu

You can also Export data directly from FieldTwin. Examples of this would be:

  • Project connections to XYZ, Shapefile or GeoJSON files
  • Project wells to XYZ, Shapefile or GeoJSON files
  • Project assets to Shapefile, GeoJSON, GLTF or Excel files
  • Project shapes to Shapefile, GeoJSON or GLTF files
  • Bathymetry contours as Shapefile
  • Whole field as Shapefile, GeoJSON, GLTF, or image files

Read more here FieldTwin Export Menu

See the illustration below for an overview:

Overview

You can also use the built in Rules Engine. This allows you to define your own logical rules to import layers, connections, assets, wells and their associated metadata direct from ArcGIS Servers or Excel files.

See the illustration below for an overview:

Overview

See the following example video explaining this powerful functionality:

You can also go straigth to the tutorial section

Almost anything in FieldTwin then can be accessed through the FieldTwin API

Data Objects

FieldTwin supports a range of different data objects and data types you can utilize when you are building your integrations.

Overview

Examples are:

  • Metadata
  • Asset and project costs (per item), connection costs (per meter)
  • Custom connection types
  • Connection segment types
  • Layer types
  • Well types, well bore types, well bore segment types,
  • Shape types
  • Virtual assets

All definitions are accessible and changeable through the FieldTwin API. See FieldTwin Admin Docs

Metadata

Vital for many integrations, and supports your workflows, processes, standards, and compliance needs.

  • Capture data to send to other systems
  • Import data from other systems
  • Unambiguous links using FieldTwin’s ID or your own Vendor ID.

Overview

Read more here FieldTwin Admin Docs

API

In this section we will cover the various functionality that the FieldTwin API offers!

API - Data Access

What does it do?

  • Create, read, update and delete…
  • Project assets, wells and bores, connections, shapes, layers
    • Metadata
    • Attach custom values and pipeline visualization data
    • Upload/download linked files or documents
  • Attach custom values to account, project, subproject
  • Perform height/depth sampling
  • Generate connection profiles along seabed / terrain
  • Detect connection crossings
  • Generate layout schematics as a SVG file

API - Project Information

The API allows you to obtain or update the following project information:

  • List projects
  • Update project settings
  • Create read-only sharing link
  • List tags in use
  • Get project activity

API - Remote Configuration

The API provides CRUD operations (Create, read, update and delete) on:

  • Metadata definitions, groups and associations
  • Connection definitions
  • Connection design and segment types
  • Layer types
  • Shape types
  • Well types
  • Well bore and segment types
  • Virtual assets

API - Remote Administration

  • List users, register users
  • Create user roles, assign user permissions
  • Activity reporting
  • Audit trail / changes reporting
  • Install or remove an integration

API - What does it not do?

  • Clone subprojects, branch and merge subprojects (in FieldTwin 8.x)
  • Shapes are read-only
  • Connection segments are read-only
  • Well bore segments are read-only
  • Workflow tasks and management (coming in 8.x in 2024)

Do contact us if you have a use-case that the API does not cover. We are typically very responsive and FieldTwin is SaaS, so we can quickly roll out enhancements.

API - Security

Use of the API requires an access token:

API User Role

Option 1: API Token

  • Created in FieldTwin Admin - Account Settings
  • Default permission means full access to everything in one account
  • Optionally assign a user role (new with FieldTwin 7.2 or greater)
  • Never expires, must be kept secret

Use for:

  • Non-interactive or background integrations - without a logged in user

  • Without a role (unrestricted)

    • Handling situations where the user does not have permission
    • Administration and management tasks

  • Assign a role

    • Read-only dashboards and reporting tools

Option 2: JSON Web Token (JWT)

  • Provided by FieldTwin once logged in
  • Represents the current user and the current project
  • Restricts access to the user’s normal permissions
  • Expires after 1 hour (FieldTwin sends a replacement)

Use for:

  • Interactive integrations (working as a logged in user)
  • Integrations hosted inside FieldTwin
  • Working with a project or subproject
  • Use in preference to an API Token