> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Learn how to set up and configure the GAP connector Windows service, including connection modes and model management.

<Warning>
  The features described in this section are in [public preview](/cdf/product_feature_status#public-preview) and may change.
</Warning>

## Before you start

* Check the [server requirements](/cdf/integration/guides/simulators/connectors/gap/gap_server_requirements) for the connector.

* Make sure the connector has [access capabilities](/cdf/access/guides/capabilities#simulator-connectors) in a Cognite Data Fusion (CDF) project.

* Create a configuration file according to the [configuration settings](/cdf/integration/guides/simulators/connectors/gap/gap_configuration) 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:

```yaml theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
 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.

<Tabs>
  <Tab title="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

    <Steps>
      <Step title="Downloads and extracts the .gar file">
        The connector downloads and extracts the contents of the `.gar` file into a temporary directory.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="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

    <Steps>
      <Step title="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).
      </Step>

      <Step title="Processes external dependencies mapping">
        The connector reads the external dependencies list provided with the model revision, which maps node dependencies to individual CDF files.
      </Step>

      <Step title="Downloads individual dependency files">
        Based on the mapping, the connector downloads each external dependency file (`.OUT`, `.VLP`, `.MBAL`) from CDF separately.
      </Step>

      <Step title="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
      </Step>

      <Step title="Assembles the complete model">
        The connector combines the GAP network files with all external dependencies to create a complete simulation model ready for execution.
      </Step>
    </Steps>

    #### Example: External dependencies structure

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

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "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
  </Tab>
</Tabs>

## Run as a Windows service

<Steps>
  <Step title="Download the installer">
    Download the *gap-setup-\{VERSION}.exe* file via the download links available from <span class="ui-element">Data fusion</span> > <span class="ui-element">Integrate</span> > **Extractors** in CDF.
  </Step>

  <Step title="Run the installer">
    Run the installer on a Windows operating system. A wizard guides you through the installation process.
  </Step>

  <Step title="Select installation folder">
    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.

    <Tip>
      You'll find templates for the configuration file in the `config` folder.
    </Tip>
  </Step>

  <Step title="Open Windows Services">
    Open the **Services** app in Windows and find the **Cognite GAP Connector** service.
  </Step>

  <Step title="Start the service">
    Right-click the service and select **Start**.
  </Step>
</Steps>

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