Using project event triggers

Last updated: November 9, 2026

Overview

Project event triggers start a workflow when something happens to a project: it is created, its status changes, or one of its steps opens or is completed. Use them to notify a team, update another system, or start the next piece of work automatically.

In this article, we'll be covering the four project events, what each one includes, how to set up a project event trigger, and common automation patterns.

Understanding project events

gaiia publishes four project events that can be used as event triggers:

  • project.created: Fires when a project is created.

  • project.status_updated: Fires when a project's status changes, whether the change is made in gaiia or through the API.

  • project.step_opened: Fires when a step of a project opens and its tickets are requested.

  • project.step_completed: Fires when every ticket of a project step is closed.

The project.status_updated event only fires when the status actually changes. Saving a project with the same status, or changing only its other details, does not trigger the event. The step events only fire for projects whose type groups its tickets into steps. See About Projects.

Event payloads

Every project event includes a project object with the project's details:

  • id (its Global ID), readableId, customProjectId, title and description

  • startDate, targetDate, createdAt and updatedAt

  • customStatus: the project's current status, with its id, name, type ("UNSTARTED", "STARTED" or "CLOSED"), default and archived

  • template: the project type's id and name, when the project has a type

  • linkedEntity: the id and type of the linked account, business account, property or network site, when the project has one

  • assignees and formValues

The project.created event contains only the project object. The other events add their own fields:

project.status_updated

Adds previousStatus and newStatus, each with the same fields as customStatus.

project.step_opened

Adds a step object with the step's id, name, position (the first step is 0) and totalSteps, the number of steps in the project.

project.step_completed

Adds the same step object, plus isLastStep, which is true when the completed step was the project's last one.

Setting up a project event trigger

  1. Create a new workflow and select Event as the trigger type.

  2. Select the project event you want to respond to from the list of events. Project event names start with project..

  3. Configure your workflow logic to respond to the event.

  4. Access the event data using state.input in your workflow nodes.

Common use cases

Notifying a team when a project changes status

  • Trigger: project.status_updated

  • Format a message with the project's title, its previous status and its new status

  • Send it to the team responsible for the project's type

Acting when a project is closed

  • Trigger: project.status_updated

  • Check that newStatus.type is "CLOSED" with a Condition node

  • Update the linked account, or send a communication to the customer

Following a project's steps

  • Trigger: project.step_completed

  • When isLastStep is true, move the project to a closed status or notify the project's assignees

  • Otherwise, post the progress, for example "Step 2 of 4 completed"

Filtering project events

Use the skip execution mapper on your trigger to filter which project events actually run your workflow. The skip execution mapper receives the event payload in state.input and returns true to skip the execution or false to proceed.

Examples:

  • Only run for one project type: return state.input.project.template?.name !== 'Fiber installation';

  • Only run when a project is closed: return state.input.newStatus.type !== 'CLOSED';

  • Only run when the last step is completed: return !state.input.step.isLastStep;

Accessing project details

Project events include the project's Global ID in project.id, and the linked record's Global ID in project.linkedEntity.id. To get more details, such as the linked account's name or address, use these IDs with the gaiia GraphQL API node.

Permissions

  • View: Users need the Workflows > View permission to see workflows that use these events.

  • Create: Users need the Workflows > Edit permission to create workflows that respond to project events.