Set up a GAP connector

Beta

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

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

Before you start

1. Check the server requirements for the connector.

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

3. 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 GAP simulator

The connector uses COM to connect to the PETEX OpenServer protocol, which establishes the connection with the GAP simulator.

1. The connector connects to PETEX OpenServer via COM. In case of connection errors, it can retry. The retry parameters can be defined 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 file support

The GAP Connector only supports .gar files, which 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.

How the GAP connector works

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 (indexed as MOD[0] or identified by the {PROD} literal constant) which 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

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

Key requirements

• 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.

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.