Skip Execution Mapper

Overview

The skip execution mapper is an optional function you can add to event triggers and webhook triggers. It determines whether a workflow should run or be skipped based on conditions you define. 

In this article, we'll be covering how to configure skip execution mappers, what happens when they run, and examples for common use cases.

Configuring a skip execution mapper

You can add a skip execution mapper to any event trigger or webhook trigger in the workflow builder.

1. Open your workflow in the builder
2. Click on your event trigger or webhook trigger node
3. Locate the Skip execution mapper field
   
4. Click to open the code editor
5. Write a function that returns true to skip execution or false to proceed

When a workflow execution is skipped, it will not appear in your workflow execution history.

Understanding how skip execution mappers work

When a trigger event occurs or a webhook is called, the skip execution mapper runs first—before the workflow execution is created. Based on what the function returns, gaiia either creates the execution or skips it entirely.

For event triggers

The function must return a boolean value:

• true — skip the workflow execution
• false — create and run the workflow execution

If the function throws an error or returns an unexpected value, the workflow execution will not be created.

For webhook triggers

The function can return:

• false — create the workflow execution (caller receives 200 with the workflow execution ID)
• true — skip the workflow execution (caller receives 204)
• { statusCode } — skip execution and return a custom HTTP status code
• { statusCode, body } — skip execution and return a custom status code with a response body

When an input schema is defined on the webhook trigger, the request body is validated against it before the skip execution mapper runs. If validation fails, the mapper is not invoked and the caller receives a 400 response.

Accessing trigger data in your function

The skip execution mapper receives a state object containing contextual data about the trigger.

Event trigger state

For event triggers, the following fields are available:

• state.input — the event payload
• state.eventName — the name of the event that fired
• state.objectId — the entity's global ID
• state.objectUuid — the entity's UUID

Webhook trigger state

For webhook triggers, the following fields are available:

• state.input — the parsed request body
• state.trigger.headers — HTTP request headers
• state.trigger.queryParameters — URL query string parameters
• state.trigger.pathParameters — path segments after the webhook URL

Using skip execution mappers for common scenarios

Run only when a work order is completed

If you want a workflow to run only when a work order reaches a specific status, check the status field in the skip execution mapper:

  return state.input?.workOrder?.status !== 'COMPLETED';

This returns true (skip) for any status except COMPLETED, so the workflow only runs when the work order is completed.

Run only when a ticket reopens

If you're listening to the ticket.status_updated event and want to act only when a closed ticket reopens, check the previous status:

  return state.input?.previousStatus !== 'CLOSED';

This skips execution unless the ticket was previously closed, ensuring the workflow runs only when a ticket moves from CLOSED to an active state like OPEN or IN_PROGRESS.

Filter webhook requests by authentication

For webhook triggers, you can check headers to validate requests before creating an execution:

  const authHeader = state.trigger.headers['Authorization'];
if (authHeader !== 'Bearer YOUR_SECRET_TOKEN') {
return { statusCode: 401, body: { message: 'Unauthorized' } };
}
return false;

Unauthorized requests receive a 401 response and no workflow execution is created.

Use optional chaining (?.) when accessing nested fields like state.input?.workOrder?.status to avoid errors if the field is missing or undefined.