Building your first workflow: Weather Greeting

Overview

Building your first workflow can feel complex, especially when you are starting from a blank canvas. This article walks through how to build a simple workflow from start to finish so you can get familiar with how the Workflow Builder works and how data moves through a workflow.

Below, you will create a basic workflow, retrieve and reuse account data, call an external API, shape that data for later steps, and use the result to take action inside gaiia.

So buckle up, and lets build a workflow together. 

Creating your workflow

We will start by creating a new workflow. At this stage, the goal is simply to define the workflow container and save it so we can begin adding steps.

1. Navigate to Workflows.
2. Click Create Workflow.
3. Set the workflow name to Weather Greeting.
4. Add a short description explaining what the workflow does (for example, Fetch weather and leave Activity Log comment).
5. Click Save.

Configuring a manual trigger

Every workflow begins with a trigger. For this workflow, we will use a manual trigger so it only runs when you explicitly launch it from an account.

1. Select the trigger node at the top of the canvas.
2. Set the Trigger Type to Manual.
3. Set the Object Type to Account.
4. Click Save.

Manual triggers automatically receive the selected object’s ID as input when the workflow runs. In this case, the account ID is passed into the workflow and can be reused by every step that follows.

Retrieving account data

Next, we need to retrieve information about the account the workflow is running on. This allows us to reuse details such as the account’s city and primary contact name later in the workflow.

1. Click the + icon beneath the trigger.
2. Select Accounts: Get Account from the gaiia API node list.
3. In the accountId input:
   • Select the state selector icon.
   • Choose State as the input source.
   • Select the objectId value provided by the trigger.
     
4. Click Save, then click Test.

Each step adds data to the workflow state. Once data is in state, it can be reused by every step that comes after it.

Calling an external API

Workflows are not limited to data inside gaiia. HTTP nodes allow workflows to request data from external systems and use that data as part of the workflow logic.

What is an API?
An API (Application Programming Interface) lets your workflow request data or trigger actions in another system. You send a request, that system processes it, and sends back a response. In this example, we will request current weather data from an external weather service.

In this workflow, we will call a weather API and pass the account’s city so we can retrieve the current temperature for that location.

1. Click the + icon beneath the Get Account node.
2. Navigate to the HTTP section of the node library.
3. Select HTTP REST Request.
4. Set the node name to Get Weather.

Next, we will configure the API request itself.

You will need an OpenWeatherMap API key for this step. You can generate a free key from your OpenWeatherMap account.

• Method: GET
• URL: This value will be generated using TypeScript.

1. In the url field, open the input type dropdown.
2. Select TypeScript.
3. Remove the placeholder // TODO comment.

4. Paste the following code into the editor:

   return `https://api.openweathermap.org/data/2.5/weather?q=${state.steps['get-account'].output.data.account.physicalAddress.locality}&units=imperial&appid=YOUR_API_KEY`;

5. Replace YOUR_API_KEY with your OpenWeatherMap API key.
6. Click Save, then click Test.

When the test runs successfully, the node output will include the full weather response for the account’s city.

What is happening in this request?
The URL is being built dynamically using data from the previous step. The workflow pulls the city value from the Get Account node and inserts it into the API request so the weather service knows which location to return data for.

API keys should never be exposed in real production workflows. As a next step, you can store your API key using Workflow Secrets and then you can update the node to replace your visible API key in the url input with a reference to the secret, like &appid=${secrets.OPEN_WEATHER_KEY}

Extracting the temperature

The weather API returns a large response, but we only need a small portion of it. In this step, we will use an output mapper to extract just the temperature and city name from the API response.

Add an output mapper to the weather node

1. Open the Get Weather node.
2. Locate the Output Mapper section.
3. Add the following TypeScript function:

return {
  temperature: Math.round(output.data.main.temp),
  city: output.data.name
};

4. Click Save, then click Test.

When the test runs successfully, the node output will now contain only the extracted temperature and city name.

What this does
This output mapper takes the full API response, extracts the temperature and city, rounds the temperature to the nearest whole number, and returns a clean object with only the values needed for later steps.

Why this matters
Reducing the response at this stage keeps downstream steps simpler, clearly documents which data you care about, and makes debugging much easier.

// Basic output mapper pattern
return {
  // Values this step should output
};

// Access data from a previous step
const firstName =
  state.steps['get-account'].output.data.account.primaryContact.firstName;

// Round a number
Math.round(42.7); // Returns 43

// Format a string with variables
`Hello, ${firstName}!`; // Returns "Hello, Sarah!"

// Get the current date and time
const dayjs = utils.packages.dayjs_v1;
return dayjs().toISOString(); // Returns an ISO timestamp

Handling errors early

Before calling an external API, it is important to confirm that the required data exists. In this workflow, the weather request depends on the account having a city set on its physical address.

Check whether a city is available

We will add error handling to the Get Account node so the workflow fails early if the city value is missing.

1. Open the Get Account node.
2. Locate the Output Mapper section.
3. Add the following TypeScript function:

const inputFunction: NodeStateFunction = ({ output, secrets, state, utils, variables }) = {
  if (!output.account.physicalAddress.locality) {
    return utils.fail(
      'MISSING_CITY',
      'Account does not have a city in physical address'
    );
  }

  return output;
};

4. Click Save, then click Test.
5. Run the workflow against an account with a blank city value to confirm the failure behaviour.

What this does
This logic checks whether the account has a city set. If the city is missing, the workflow fails with a clear error code and message. If the city exists, the workflow continues to the next step.

Why this matters
Failing early prevents unnecessary API calls, reduces noise in execution logs, and makes it immediately clear why a workflow stopped.

Leaving a comment in the Activity Log

With all data collected and prepared, the final step is to leave a message on the account that includes the current weather information.

Add a Create Activity Log Comment node

1. Click the + icon beneath the Get Weather node.
2. Navigate to the Utilities section of the node library.
3. Select Create Activity Log Comment.

Next, we will configure the message that appears in the Activity Log.

1. Locate the message input in the node configuration panel.
2. Change the input type to TypeScript.
3. Remove the placeholder comment.
4. Paste the following code into the editor:

const firstName =
  state.steps['get-account'].output.data.account.primaryContact.firstName;

const weather = state.steps['get-weather'].output;

return `Hello, ${firstName}! The temperature in ${weather.city} is ${weather.temperature}°F.`;

5. Click Save, then click Test.

After the workflow completes, you can confirm the message was written successfully by checking the Activity Log.

• The Workflow Execution’s Activity Log section
  
• The Account’s Workflows section, under the execution details for this workflow
  

What this does
This step pulls the account’s first name from the Get Account step, retrieves the weather data from the Get Weather step, and builds a personalized message that is visible to anyone reviewing the workflow execution.

// Basic template literal
`Hello, ${firstName}!`

`Hello, ${firstName}
The temperature in ${city} is ${temperature}°F.
Have a great day!`

`$${price.toFixed(2)}`  // Returns "$42.99"
`${percentage}%`      // Returns "15%"

Adding workflow-level output

Workflow-level output determines what data the workflow returns once it has completed. This output is useful for reviewing execution results, debugging, and sharing data with other workflows.

Configure workflow output

1. Scroll to the bottom of the workflow graph.
2. Select the End node.
3. In the Output Mapper section, click Add Function.
4. Select your preferred output type.
5. Paste the following TypeScript function:

const account = state.steps['get-account'].output.account;
const weather = state.steps['get-weather'].output;

return {
  accountId: account.id,
  firstName: account.primaryContact.firstName,
  city: weather.city,
  temperature: weather.temperature,
  message: `${state.steps['create-activity-log-comment'].output.message}`
};

6. Click Save.
7. Click Test and run the workflow against an account.

Workflow-level output makes it easy to see the result of the workflow without reviewing each individual step.

Understanding what you built

And just like that, you have built your first workflow. Before moving on, let’s quickly review what you created and how each part works together.

The workflow starts with a manual trigger, which waits for you to explicitly run it on an account. When you do, gaiia automatically passes the account’s unique ID into the workflow so it can be used by the steps that follow.

Using that ID, the workflow retrieves account data from gaiia, including details like the account’s first name and city. That data becomes part of the workflow state and can be reused anywhere downstream.

Next, the workflow calls an external weather API. It uses the city from the account data to request current weather information, then extracts only the temperature and city name so later steps stay simple and predictable. If the required city data is missing, the workflow fails early with a clear error.

With the data prepared, the workflow writes a personalized message to the account’s Activity Log. This message combines information from multiple steps and provides visibility into what the workflow did during its execution.

Finally, the workflow returns a small summary of the execution using workflow-level output, making it easy to confirm the result without reviewing each step individually.

Looking to take this a few steps further?

If you are feeling comfortable with this workflow, try challenging yourself to build on it.

You could include additional weather data, such as humidity or “feels like” temperature, and incorporate that into the Activity Log message. You might also experiment with adding more error handling or formatting the output differently based on conditions.

Once you are ready, consider changing the trigger type or replacing the Activity Log step with another action, such as creating a note or an internal ticket. The same patterns you used here apply to all of those scenarios.