# Getting Started

This tutorial will walk you through building and deploying a flow, as well as best practices for testing and debugging flows. While this tutorial uses a prepackaged example flow, these same steps should be used for developing flows specific to your business needs.

After completing this tutorial, you will:

- Have a local environment with the `flows-sdk` library installed
- Package an example “IDP Starter” flow into an artifact
- Import that artifact into the Hyperscience Platform
- Be able to test and debug your flow

The provided [IDP Starter Example](https://flows-sdk.hyperscience.ai/pages/examples.html) is a basic approach to extracting text from documents. It’s a good starting point for adding process logic, data validation, data formatting, etc. specific to your business’s document extraction process.

## Prerequisites

The prerequisites depend on what application version you’re developing for.

- Hyperscience v41+: Python 3.12
- Hyperscience v39.1-v41: Python 3.11

Legacy versions:

- Hyperscience v36-v39: Python 3.9
- Hyperscience <=v35: Python 3.7

> The example below assumes that you are using **bash** or **zsh** for Unix and **cmd** or **PowerShell** for Windows. For other terminals, check out [the official venv documentation](https://docs.python.org/3/library/venv.html).

## Building & Deploying

_The examples below assume you are developing for Hyperscience v36. If you are developing for earlier versions, change the version number in `idp_starter_flow_v36.py` to match your Hyperscience application version (e.g., `idp_starter_flow_v35.py`)._

1. Create a virtual environment and source it.

```
   python3 -m venv venv
   source venv/bin/activate
   ```

**For Windows**
   
   **cmd.exe**
   
   ```
   python -m venv venv
   venv\Scripts\activate.bat
   ```
   
   **PowerShell**
   
   ```
   python -m venv venv
   venv\Scripts\Activate.ps1
   ```

2. Install the `flows_sdk` Python package. Contact your CX representative to receive the `.whl` package. The command below should reflect the local path of your package.

**Example:**
   
   ```
   pip install "~/Downloads/flows_sdk-1.6.2-py3-none-any.whl"
   ```
   
   **For Windows**
   
   ```
   pip install "C:\Downloads\flows_sdk-1.6.2-py3-none-any.whl"
   ```

3. Download the [IDP Starter Example](https://flows-sdk.hyperscience.ai/pages/examples.html) package, which includes:

- `idp_starter_flow_v36.py` file. This is the Python file, built using the Flows SDK, that defines all of the logic for IDP Starter Example flow
   - `release.zip`, which includes a layout for processing W-9 forms. Because W-9s are a structured document it is not necessary to train any models. To learn more about releases, visit our [application documentation](https://help.hyperscience.ai/latest/docs/releases)
   - `form-w9-blank.pdf`, a blank Form W-9 used to build the layout
   - `form-w9-sample.png`, a W-9 form filled out with handwriting. This image can be submitted to test your flow.

4. Package `idp_starter_flow_v36.py` - the Hyperscience Platform accepts `.json` and `.zip` files:

**Export to a `.json` file:**
   
   ```
   python idp_starter_flow_v36.py > idp_starter_flow.json
   ```
   
   **Alternatively bundle into a `.zip` file (via `hs-flows`):**
   
   ```
   hs-flows bundle idp_starter_flow_v36.py -o idp_starter_flow.zip
   ```

5. Upload the produced `idp_starter_flow.json` to a Hyperscience instance by going to `https://{hyperscience-url}/flows` and clicking **Import Flow**.

6. If everything went as expected, you should be redirected to the Flow Studio - you’ve successfully uploaded your first flow to the Hyperscience Platform!

## Testing & Debugging

The Hyperscience Platform includes tools to help you test and debug your flows. Continuing with the above example, we’ll show you how to submit documents to your new IDP Starter Flow by using the additional materials provided in the package.

1. Flows need an associated “Release” to process documents. Go to `https://{hyperscience-url}/layouts/releases` and click **Add Release**. Select **Upload Existing** and choose the `release.zip` included in the IDP Starter Example package. After a moment you should see the release uploaded to the Hyperscience Platform.

2. Navigate back to the flow that was uploaded in the previous section by going to `https://{hyperscience-url}/flows` and selecting it.

3. The newly uploaded release should be selectable under `Layout Release` in the **Flow Settings** panel on the left-hand side of the page.

4. Set your flow’s status to “Live.” Documents can only be submitted to “Live” flows.

5. Go to `https://{hyperscience-url}/submissions` and click **Create Submission**. Upload the `form-w9-sample.png` sample document. Finally, select **IDP Starter Flow** as the flow to submit to. You should see that the submission was created - it may take a few minutes to process.

6. Now we can use our testing and debugging tools to better understand how your flow processed those documents. Click on the completed submission’s ID, then click **Actions** and select **View Flow Run**. If you used the provided IDP Starter Flow and sample document, you should see that the document processed without error.

## Troubleshooting flow runs

If errors occur in the flow, you can use the information on the Flow Run page to troubleshoot them. To learn more about the Flow Run page, see [Testing and Debugging Flows](https://help.hyperscience.ai/latest/docs/testing-and-debugging-flows) in our application documentation.