Build a Workflow v2

Build a Workflow that finds the name of the driver who came first in the first race of a year you choose. The Workflow returns the driver's family name, such as Verstappen for 2024.

This article explains how to build a Workflow by hand. You can also build using AI - either by using the built-in AI assistant or by connecting Flowgear Builder MCP Server to your own agent.

You will use two OpenAPI REST Request Steps: one to get the season schedule and one to fetch the first race's results. Along the way, you will configure a Connection, drag Flow Connectors to map data, use FIRST to select values, inspect real responses, and save a revision.

Before you start

You need access to a Site and permission to create Connections and design Workflows. This example uses the public Jolpica F1 API. The schedule and results requests used here are free and work without an account, API key, or authentication.

Use the Site's Test Environment. The Save action is available in the first-ranked Test Environment, where the latest design is maintained. The reference example uses OpenAPI REST Request version 0.0.0.18.

Create the Jolpica Connection

A Connection stores the settings a Node uses to access another system. An OpenAPI definition describes the API's operations and data shapes so the designer can offer them as Templates.

  1. Open Connections from the main navigation and click New v2 Connection.
  2. Enter Jolpica F1 in Connection name.
  3. Select the OpenAPI REST Request Node in the Node field.
  4. Select the Test Environment and keep the Cluster set to Cloud Cluster.
  5. Enter https://api.jolpi.ca in Url.
  6. Enter https://api.jolpi.ca/docs/schema in OpenApiUrl.
  7. Keep Authorization set to None and leave CustomHeaders empty.
  8. Click Acquire Metadata to load the API definition, then click Save changes.

Only the base URL and OpenAPI URL need to be supplied for this example. Acquiring metadata makes the API operations available when you add a Step.

Create a Workflow

  1. Open Workflows from the main navigation.
  2. Open the folder where you want to create the Workflow. Stay at the root if you do not need a folder.
  3. Click New Workflow.
  4. Click the generated Workflow name in the top bar.
  5. Enter Grand Prix podium finder, then click ✓.

Renaming changes the current design. It is recorded when you save the Workflow.

Add the Year Parameter

A Workflow Parameter lets you change the year without editing the Steps that use it.

  1. Open the ... menu on the Workflow Parameters card and select Edit Properties.
  2. Click the + control labelled Add Property. Rename the new Property to Year and set its type to number.
  3. Click Apply to finish editing the Properties.
  4. Select Year and enter 2024 as its Value.

This is the default year for the example. Property names are case-sensitive.

Get the season schedule

The results API identifies each race by an internal round ID. Start with the season schedule so you can select the first race's ID.

  1. Click the + control on the canvas to open Add step.
  2. Search for and select OpenAPI REST Request, then select the Query Method.
  3. Select your Jolpica F1 Connection.
  4. Select the Alpha - Get Detailed F1 Season Schedule Template.
  5. Open the new Step's ... menu, select Rename Step, and name it getSchedule.
  6. Expand getSchedule.Options, then drag a Flow Connector from Parameters.Year to getSchedule.Options.year.

To create the Flow Connector, press and hold the connector point on the edge of the Parameters.Year row. Drag it to getSchedule.Options.year, then release. The designer draws the Flow Connector and creates the mapping.

  1. Confirm that the Test Environment and Cloud are selected, then click Run.
  2. Wait for the run to complete and select the getSchedule entry in Logs.
  3. Expand its Response Return, then inspect data → events → round. Inspect the first event. For 2024, its round name is Bahrain Grand Prix; check that it also has an id.

The Template already exposes events, round, name, and id, so you can use them in the next mapping without inferring a schema.

Get the race results

  1. Click the + control after getSchedule.
  2. Select OpenAPI REST Request → Query and your Jolpica F1 Connection.
  3. Select the Alpha - Get results for a round Template.
  4. Check that its Options contain round_id and session_filter. Jolpica also has a laps operation with the same Template name; if you see full_session_code, remove that Step and select the other matching Template.
  5. Rename the Step to getResults.
  6. Drag a Flow Connector from getSchedule.Response to getResults.Options.
  7. Expand Options, select round_id, switch to Expression, and enter:
FIRST({getSchedule.Response.data.events.round.id})

Click ✓ to apply the Expression. The Flow Connector to getResults.Options makes the fields inside it use the current schedule response. FIRST then selects the first event's round ID, so the next request retrieves the opening race of the selected season.

  1. Select session_filter and enter R as its Value to request the race results.
  2. Click Run, wait for completion, and open the getResults log entry.
  3. Expand Response → data. Inspect season, round, circuit, and results.

Response is an array containing the API's response object. Inside that object, data.results is another array containing the drivers' results. Keep this distinction when you build the Workflow Returns.

If the request fails after changing Year, inspect the schedule first. Choose a year whose opening race has finished and has results. If the Workflow does not start, open Problems, resolve the error at the reported path, and run again.

Inspect the response shape with Infer Schema

The results Template already exposes results.driver.family_name, so you can map the driver's family name without inferring a schema. After running, you can also use inference to inspect the shape of the data that actually passed through the Step.

  1. Return to Canvas after the run and log loading have completed.
  2. Open the getResults Step's ... menu and select Infer from run data.
  3. Expand the proposed Response Return. Review the fields, types, and samples under data → results → driver.
  4. Select the top-level Response Return and click Apply if you want to include its inferred subtree, or click Cancel to keep the existing schema.

Inference uses recorded run data; it does not call the API again. Some fields can be present in the response without being expanded in the Template. For example, the Bahrain response contains starting-grid and fastest-lap details inside results.components. Infer and apply the schema before mapping those extra fields.

If a field you need is missing from the canvas, first check that it appears in the log, then infer the schema and apply the Response Return before continuing. A field absent from that run cannot be discovered. See Infer a Schema for more about reviewing inferred Properties.

Return the winning driver's family name

A Workflow Return makes the result available to a caller as well as in the logs. This Workflow has one Return, FamilyName, with type string.

  1. Open the ... menu on the Workflow Returns card and select Edit Properties.
  2. Add a Property named FamilyName with type string, then click Apply.
  3. Expand getResults.Response.data.results.driver, then drag a Flow Connector from getResults.Response.data.results.driver.family_name to Returns.FamilyName.
  4. Select FamilyName, open its Expression, and replace the generated mapping with:
FIRST(FIRST({getResults.Response.data.results.driver.family_name}))

Click ✓ to apply the Expression. Response and results are both arrays, so this uses FIRST twice: once to select the response's list of family names, then to select the first driver's family name. The first result is the race winner; you can check its position is 1 in the getResults log.

Run and check the winner

  1. Click Run and wait for the Workflow to complete.
  2. Inspect the Workflow Returns in Logs.
  3. Check the value of FamilyName.

For 2024, the first race is the Bahrain Grand Prix. Max Verstappen came first, so the Workflow returns:

FamilyName: Verstappen

Change Year to another year whose opening race has finished, then run again. The Workflow retrieves that year's first race and returns its winner's family name. Restore Year to 2024 if you want to keep the original default.

Save the first revision

  1. Click Save in the top bar.
  2. In the Manage revisions view, enter First working version as the optional commit message.
  3. Click ✓ or press Enter.

When validation and compilation succeed, saving records a revision when the design has changed and publishes the latest design to the Test Environment. A new Workflow is also enabled automatically in that Environment.

If the design can be saved but cannot be published, the Console warns you and reports the compilation problem under Problems. Correct the problem, then save again.

The status switch in the top-right corner should now show Enabled. Workflow status is Environment-specific. Changing this switch controls whether the Runtime can start the Workflow through published interfaces in the selected Environment; it does not replace saving the design.

What you learned

You have used the main authoring loop:

  • Create a Connection and load an OpenAPI definition.
  • Add API operations as Workflow Steps from Templates.
  • Supply inputs through Workflow Parameters.
  • Use FIRST to select the first race and its winning driver.
  • Drag Flow Connectors to map fields visually.
  • Inspect real responses and infer missing fields before mapping them.
  • Expose a single value through a Workflow Return, test different inputs, and save a revision.

Continue with Workflow YAML, Data Mapping, or the Workflow designer reference.

Complete reference YAML

This complete example finds the driver who came first in the first race of the selected year and returns their family name. It defaults Year to 2024 and includes only the response fields needed by the mappings. Use Infer from run data to add other fields before mapping them.

Connection keys belong to your Site, so the two Connection Values are deliberately left unset. Create the Jolpica F1 Connection and acquire its metadata as described above, then select it on both Steps after pasting.

  1. Open Workflows and click New Workflow to start with a blank design.
  2. Select Code in the bottom-right view selector.
  3. Select all of the existing YAML and replace it with the complete block below, without the surrounding Markdown code fences.
  4. Switch back to Canvas to see the Year Parameter, two Steps, Flow Connectors, and FamilyName Return.
  5. Select the Connection Parameter on each Step and choose your Jolpica F1 Connection.
  6. Confirm that the Test Environment and Cloud are selected, then click Run.
  7. Inspect the results and save the revision. Use Infer from run data before extending the mappings to fields missing from the included schemas.

The Expression entries that contain only a field reference are how YAML stores visual Flow Connectors. When following the canvas walkthrough, create those connections by dragging. Edit Expressions when you need a function to transform or select data.

Name: Grand Prix podium finder
Parameters:
  Year:
    Type: number
    Value: 2024
Steps:
- Name: getSchedule
  Node: v2.OpenApiRestRequest@0.0.0.18
  Method: Query
  TemplateKey: 2f6de8fa-7157-566d-1cf6-65d64ec33acb
  Parameters:
    Connection:
      Type: connectionKey
    OperationId:
      Type: string
      Value: 2f6de8fa-7157-566d-1cf6-65d64ec33acb
    Options:
      Type: object
      Properties:
        year:
          Type: string
          Expression: '{.Year}'
  Returns:
    Response:
      Type: array
      Properties:
        data:
          Type: object
          Properties:
            events:
              Type: array
              Properties:
                round:
                  Type: object
                  Properties:
                    id:
                      Type: string
- Name: getResults
  Node: v2.OpenApiRestRequest@0.0.0.18
  Method: Query
  TemplateKey: 554db1e4-b388-ba71-f35d-fd57fa46b5c8
  Parameters:
    Connection:
      Type: connectionKey
    OperationId:
      Type: string
      Value: 554db1e4-b388-ba71-f35d-fd57fa46b5c8
    Options:
      Type: object
      Expression: '{getSchedule.Response}'
      Properties:
        round_id:
          Type: string
          Expression: FIRST({getSchedule.Response.data.events.round.id})
        session_filter:
          Type: string
          Value: R
  Returns:
    Response:
      Type: array
      Properties:
        data:
          Type: object
          Properties:
            results:
              Type: array
              Properties:
                driver:
                  Type: object
                  Properties:
                    family_name:
                      Type: string
Returns:
  FamilyName:
    Type: string
    Expression: FIRST(FIRST({getResults.Response.data.results.driver.family_name}))