Set up a GAP connector

The Cognite GAP connector is distributed as a Windows service. Follow the steps below to set up the connector.

Beta

The features described in this section are currently in beta testing and are subject to change.

Before you start

• Check the server requirements for the connector.

• Make sure the connector has access capabilities in a Cognite Data Fusion (CDF) project.

• Create a configuration file according to the configuration settings in the working directory of the folder where the connector is installed. The file must be in YAML format.

Connect to the GAP simulator

The GAP connector connects to the PETEX OpenServer protocol via COM, which connects with the GAP simulator.

For any connection errors, you can define retry parameters in the configuration file:

 automation:
     simulator-retries:
         max-tries: 12
         max-delay: "60s"

This configuration enables retry attempts to the simulator for up to 5 minutes before failing. The retries follow an exponential backoff strategy, starting with shorter delays and gradually increasing to a maximum interval of one minute.

Retry attempt	Delay duration before attempt
1	░░ (0.5s)
2	░░░░ (1s)
3	▓▓▓▓▓ (2s)
4	██████ (4s)
5	██████████ (8s)
6	██████████████ (16s)
7	██████████████████ (32s)
8	████████████████████████ (60s limit)
9	████████████████████████ (60s limit)
10	████████████████████████ (60s limit)

GAP connector modes

The GAP connector supports two modes:

• Single bundle mode (.gar files): A simple approach with all components packaged in a single archive file.

• External dependencies mode (.zip files): For advanced users to manage network models and dependencies separately for greater flexibility and control.

Single bundle mode (.gar files)

Manage simulation models via a single bundle mode using .gar files. These files are PETEX's standard for a GAP archive file. A .gar file is a self-contained archive that includes the GAP surface network model along with all associated IPM files, such as well models, tanks, and other components required for simulation.

Prerequisites

• The .gar file must contain a valid production network model as the primary entry point.

• All network models (production and injection) referenced in the system must be present.

• All dependent files (wells, pipes, tanks) referenced by any network must be included in the .gar file.

• Missing dependencies will invalidate the model and prevent simulation execution.

Connector workflow

1. Downloads and extracts the .gar file

   The connector downloads and extracts the contents of the .gar file into a temporary directory.

2. Validates the production network model

   The connector searches for a production network model, which is indexed as MOD[0] or identified by the {PROD} literal constant. This serves as the primary entry point. This network model is mandatory and must be present in the .gar file.

3. Resolves network dependencies

   From the production network, the connector identifies any dependent networks such as Water Injection (WINJ), Gas Injection (GINJ), or GasLift Injection (GLINJ) networks that are referenced in the model.

4. Validates component dependencies

   For each identified network (production and injection):

   • The connector locates all dependent files for wells, pipes, and tanks referenced by that network.

   • All dependent files must be present within the .gar archive.

   • If any required dependent file is missing, the model is considered invalid and can't be used for simulations.

5. Resolves file paths

   When all dependencies are validated, the connector updates file paths for all components to reference their new locations within the extracted directory.

External dependencies mode (.zip files)

Manage simulation models via an external dependencies mode (.zip files). Use this mode when you need to frequently update individual components, such as individual well models, VLP tables, or other components without repackaging the entire model. This mode reduces storage since it avoids duplicating unchanged files across model revisions and enables different team members to work on different components independently.

Prerequisites

• Upload a .zip file that only contains GAP network files (production and injection networks).

• Map individual node dependencies (.OUT, .VLP, .MBAL files) as separate CDF files

• Map external dependencies with the correct file IDs and argument paths.

• Make sure all referenced external dependency files exist in CDF.

• Specify the GAP model path for each dependency in the arguments field.

Connector workflow

1. Downloads the .zip file with GAP networks

   The connector downloads and extracts the .zip file containing only the GAP network files (production and injection networks).

2. Processes external dependencies mapping

   The connector reads the external dependencies list provided with the model revision, which maps node dependencies to individual CDF files.

3. Downloads individual dependency files

   Based on the mapping, the connector downloads each external dependency file (.OUT, .VLP, .MBAL) from CDF separately.

4. Resolves file paths with arguments

   The connector uses the arguments field in the external dependencies to resolve file paths. For example:

   • "GAP.MOD[{PROD}].WELL[{A1}].File" maps to the PROSPER file for well A1
   • "GAP.MOD[{PROD}].WELL[{A1}].VLPFile" maps to the VLP file for well A1

5. Assembles the complete model

   The connector combines the GAP network files with all external dependencies to create a complete simulation model ready for execution.

Example: External dependencies structure

When you create a model revision with external dependencies, provide a list of dependencies with this structure:

{
  "externalDependencies": [
    {
      "file": {"id": 1231231231},
      "arguments": {
        "address": "GAP.MOD[{PROD}].WELL[{A1}].File"
      }
    },
    {
      "file": {"id": 1333123123},
      "arguments": {
        "address": "GAP.MOD[{PROD}].WELL[{A1}].VLPFile"
      }
    }
  ]
}

• The first dependency maps a PROSPER .OUT file for well A1
• The second dependency maps a PROSPER .VLP file for the same well
• The address field uses GAP's path notation to specify where each file should be linked in the model

Run as a Windows service

1. Download the gap-setup-{VERSION}.exe file via the download links available from Data management > Integrate > Extractors in CDF.

2. Run the installer on a Windows operating system. A wizard guides you through the installation process.

3. Select the destination folder where the connector will be installed. By default, this is C:\Cognite\. Inside this folder, the GapConnector working directory is created. The connector expects a config.yml file as the configuration in the same directory.

   提示

   You'll find templates for the configuration file in the config folder.

4. Open the Services app in Windows and find the Cognite GAP Connector service.

5. Right-click the service and select Start.

Uninstall and update the connector

Run the same MSI installer to uninstall the connector. The installer deletes installed binaries, removes the service, and cleans the application registry. The installation is not deleted and still contains the configuration file, logs, and application data generated by the connector. If the connector is re-installed, it resumes the operation using the saved state.

When a new version of the GAP connector is available, run the MSI installer for the new version to upgrade the connector to the new version. After the upgrade, you must manually restart the service.