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

# Set up the PI extractor

> Install and configure the Cognite PI extractor on Windows to stream time series data from OSISoft PI to Cognite Data Fusion (CDF).

The Cognite PI extractor is distributed as a Windows installer (.msi file). When you run the .msi file, a setup wizard guides you through the installation process. The installer creates a Windows service and installs the binary files needed to run the extractor.

## Before you start

* Check the [server requirements](/cdf/integration/guides/extraction/pi/pi_server_requirements) for the extractor.

* Assign [access capabilities](/cdf/access/guides/capabilities#pi-extractor) in a CDF project.

<Tip>
  You can use OpenID Connect and your existing identity provider (IdP) framework to manage access to CDF data securely. [Read more](/cdf/integration/guides/extraction/admin_oidc).
</Tip>

* Set up a Windows Update schedule. Note that the update may reboot the machine, causing extractor downtime.

* Download and run the installation files for the extractor from CDF.

<Info>
  Set Modify permission under **Properties** in the installation folder to avoid permission issues.
</Info>

* Create a configuration file according to the [configuration settings](/cdf/integration/guides/extraction/configuration/pi). The file must be in YAML format.

## Run as a Windows service

<Steps>
  <Step title="Start the PI extractor service">
    Start the PI extractor service using the Windows service or with a command line:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    net start PiExtractor
    ```

    The Windows service is named **Cognite Pi Extractor 4.3.0**, and the command line for the `net start` and `net stop` commands is named **PiExtractor**.
  </Step>

  <Step title="Verify service is running">
    Verify that the service is running.

    <Frame>
      <img src="https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/integrations/extraction/pi/running_windows_service.png" alt="Running the Windows service" />
    </Frame>
  </Step>

  <Step title="Configure startup type">
    Open the **Properties** for the service and set the **Startup type** to **Automatic (Delayed Start)**:

    <Frame>
      <img src="https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/integrations/extraction/pi/setting_up_windows_service.png" alt="Setting up the Windows service" />
    </Frame>
  </Step>

  <Step title="Verify extractor is running">
    If you've configured the extractor to log messages to a file, you'll find the log files in the configured path, for instance, `logs/log.txt`. These should contain progress messages similar to the example below:

    <Frame>
      <img src="https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/integrations/extraction/pi/verify_extractor_run.png" alt="Verify that the extractor is running" />
    </Frame>

    <Tip>
      If you've configured the extractor to push metrics, you can inspect the extractor operation and health in real-time using a Grafana board.
    </Tip>
  </Step>
</Steps>

## Run the extractor behind a proxy

<Steps>
  <Step title="Edit configuration file">
    Open and edit the `PiExtractor.exe.config` file from the installation directory.
  </Step>

  <Step title="Add system.net section">
    Add the `system.net` section under `configuration` with this content:

    ```xml theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    <system.net>
        <defaultProxy>
            <proxy  proxyaddress=""
                    bypassonlocal="True"
            />
            <bypasslist>
                <add address="[a-z]+\.contoso\.com$" />
            </bypasslist>
        </defaultProxy>
    </system.net>
    ```
  </Step>

  <Step title="Configure proxy settings">
    Configure the proxy address and bypass rules according to the proxy server you want to use.
  </Step>

  <Step title="Restart the service">
    Restart the extractor service. Read more about the [default-proxy-element](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/network/defaultproxy-element-network-settings).
  </Step>
</Steps>

## Upgrade the extractor

To upgrade the current extractor version, download and run the .msi file for the new version. The installer detects the current installation directory, updates the software, and keeps the configuration as-is. The sample configuration file is a part of the software package and is overwritten during an extractor upgrade.

<Steps>
  <Step title="Download installer">
    Download the PI extractor .msi file from CDF.
  </Step>

  <Step title="Note current settings">
    Take note of the currently **installed version** in case of a rollback and of the **service properties** in the Properties dialog.

    <Warning>
      During the upgrade, the installer resets all custom service properties to their default values, such as the service recovery settings.
    </Warning>
  </Step>

  <Step title="Run the installer">
    Run the installer.
  </Step>

  <Step title="Update service properties">
    Update the custom service properties you noted in step 2.
  </Step>

  <Step title="Verify extractor version">
    Verify that the extractor is running and that the version displayed in the `Starting PI Extractor` logline matches the upgraded version.
  </Step>

  <Step title="Check metrics">
    Check the metrics and verify that the extractor resumes operation.
  </Step>
</Steps>

If you've configured additional services to extract from multiple sources, the installer won't change the settings for these services during upgrades. If you've created multiple services, the following dialog appears during the upgrade:

<Frame>
  <img src="https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/integrations/extraction/pi/upgrade_extractor.png" alt="Upgrade extractor with multiple services" />
</Frame>

The installer uses the default options, stops the services, and restarts the services after the upgrade. Otherwise, a server reboot is required to complete the upgrade process.

## Uninstall the extractor

<Steps>
  <Step title="Open uninstaller">
    Run the installer and select **Remove the extractor** or open **Add or remove programs** from the control panel.
  </Step>

  <Step title="Remove extractor">
    Remove **Cognite PI extractor**.
  </Step>

  <Step title="Optional. Clean up files">
    Optionally, remove the installation directory with the configuration file and logs.
  </Step>

  <Step title="Optional. Delete the installer">
    Optionally, delete the .msi file.
  </Step>
</Steps>