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

# Tutorial: Build your first workflow

> Connect FlowX to an external REST API, build an integration workflow around it, and call that workflow from a BPMN process.

In this tutorial you build your first **integration workflow**: a small flow that calls an external REST API, shapes the response with a script, and returns the result to a Business Process Model and Notation (BPMN) process.

Along the way you work with the three pieces every real integration uses:

1. A **data source**: the reusable connection to the external system.
2. A **workflow**: the integration logic, built visually in the Integration Designer.
3. A **process action**: how a BPMN process starts the workflow and receives its output.

<Info>
  **Prerequisites**: a project in your workspace and access to FlowX.AI Designer. If you haven't built a process yet, start with [Build your first process](./building-your-first-proc) - this tutorial picks up where it leaves off conceptually.
</Info>

<Tip>
  Remember the distinction: a **process** is a BPMN flow with user and service tasks; a **workflow** is integration logic built in the Integration Designer. Processes delegate data fetching and transformations to workflows. See the [Glossary](./glossary) if any term here is new.
</Tip>

***

## What you'll build

A currency-lookup workflow: given a base currency, it calls an exchange-rates API, extracts the rate you care about, and hands the result back to the process that asked for it. The API is a stand-in - swap in any REST API you have access to and the steps stay the same.

***

## Step 1: Create the data source

A data source is a collection of endpoints, authentication, and variables that workflows can reuse.

<Steps>
  <Step title="Open Data Sources">
    In FlowX.AI Designer, go to **Workspaces** → your workspace → **Projects** → your project → **Integrations** → **Data Sources**.
  </Step>

  <Step title="Create a RESTful System">
    Click **New Data Source** and pick the **RESTful System** tile. Fill in:

    * **Name**: `Exchange Rates`
    * **Code**: `exchange_rates`
    * **Base URL**: `https://api.exchange.example.com/v1` (use your real API's base URL)
    * **Description**: what this system is for

    <Tip>
      Base URLs usually differ per environment. You can write them as `https://api.${environment}.example.com/v1` and resolve the variable through [configuration parameters overrides](/5.9/docs/projects/runtime/configuration-parameters-overrides).
    </Tip>
  </Step>

  <Step title="Set the authorization">
    Under authorization, pick what your API needs: **Service Token**, **Bearer Token**, or **No Auth**. Token values are best defined at system level and overridden per environment.
  </Step>

  <Step title="Add an endpoint">
    In the **Endpoints** section, add the endpoint the workflow will call:

    * **Method**: `GET`
    * **Path**: `/rates`
    * **Parameters**: a query parameter named `base`

    Endpoints defined here are reusable across every workflow in the project.
  </Step>
</Steps>

<Check>
  You can save a data source even if some fields (credentials, endpoints) aren't final - it can be referenced in workflows immediately and becomes operational once the required fields are filled in.
</Check>

***

## Step 2: Build the workflow

<Steps>
  <Step title="Create the workflow">
    Go to **Projects** → your project → **Integrations** → **Workflows** and create a new workflow named `Get exchange rate`.
  </Step>

  <Step title="Define the input on the Start node">
    Every workflow begins with a **Start node**: it defines the input data passed to all subsequent nodes. Give it the input your callers will send:

    ```json theme={"system"}
    {
      "baseCurrency": "EUR"
    }
    ```
  </Step>

  <Step title="Add the REST endpoint node">
    Add a **REST endpoint node** and select your `Exchange Rates` endpoint from the dropdown (endpoints are grouped by system). Map the `base` query parameter to the `baseCurrency` input. The node's input is auto-populated from the previous node; its output shows the API response.

    <Tip>
      Test the REST endpoint node on its own before wiring the rest of the workflow - it's the fastest way to validate the connection and see the real response shape.
    </Tip>
  </Step>

  <Step title="Shape the result with a Script node">
    Add a **Script node** (JavaScript or Python) after the REST call to keep only what the process needs - for example, picking one rate out of the full response and returning `{ "rate": <value>, "currency": "USD" }`.
  </Step>

  <Step title="Capture the output on the End node">
    Connect an **End node** and map the script's result to it. Whatever reaches the End node is the workflow's output - this is what the calling process receives.
  </Step>

  <Step title="Run a test">
    Run the workflow from the Designer with a sample input and confirm the output contains your shaped result.
  </Step>
</Steps>

<Info>
  For structured, typed inputs and outputs, define a [workflow data model](/5.9/docs/platform-deep-dive/integrations/workflow-data-models) - input parameters then pre-fill the Start node automatically. For a first workflow, plain JSON on the Start node is fine.
</Info>

***

## Step 3: Call the workflow from a process

<Steps>
  <Step title="Add the action">
    In your BPMN process, add a **Send Message Task** node and configure a **Start Integration Workflow** action on it. The action is also available on **Task** and **User Task** nodes.
  </Step>

  <Step title="Select the workflow and map the input">
    Pick `Get exchange rate` from the **Select Workflows** dropdown, then map process data to the workflow input:

    ```json theme={"system"}
    {
      "baseCurrency": "${processInstanceData.selectedCurrency}"
    }
    ```
  </Step>

  <Step title="Set the result key">
    Configure the **result key** - for example `exchangeResult`. The workflow's output lands at this key in the process instance data.
  </Step>

  <Step title="Receive the output">
    Add a **Receive Message Task** node after the Send Message Task. The process waits for the workflow to complete, the output is mapped to your result key, and every node after that can read `exchangeResult`.
  </Step>
</Steps>

***

## Step 4: Run it end to end

Start the process, let it reach the Send Message Task, and inspect the process instance data: the workflow's shaped output should sit under `exchangeResult`. That round trip - process → workflow → external API → back to the process - is the pattern behind most FlowX integrations.

<Check>
  You built a reusable data source, an integration workflow with REST + script + output nodes, and a process that delegates to it and reads the result.
</Check>

***

## Where to go next

<CardGroup cols={2}>
  <Card title="Integration Designer" icon="plug" href="/5.9/docs/platform-deep-dive/integrations/integration-designer">
    The full reference: endpoint parameters, authorization, caching, file handling, and every workflow node.
  </Card>

  <Card title="Workflow data models" icon="table" href="/5.9/docs/platform-deep-dive/integrations/workflow-data-models">
    Typed inputs and outputs for workflows, with automatic Start-node pre-fill.
  </Card>

  <Card title="Start integration workflow action" icon="bolt" href="/5.9/docs/building-blocks/actions/start-integration-workflow">
    Everything about calling workflows from processes, including when to use subprocesses instead.
  </Card>

  <Card title="Cookbooks" icon="utensils" href="/5.9/cookbooks/overview">
    Tutorials, guides, and patterns to build on what you just learned.
  </Card>
</CardGroup>