Create Automation

Before You Begin

Use the GraphQL Playground.
Authenticate with a Service Account token.

Prerequisites

You must have access to the repos involved:
- For most automations: admin permission on both the event repo and the action repo.
- For scheduler automations: permission requirements differ; generally you must be able to manage the action repo.

Create an Automation

AI action example (generate_with_ai using field internal_id)

Inputs

name: Display name of the automation.
action_id: Must be generate_with_ai for AI generation.
event_id: Set to card_created to trigger on new cards.
event_repo_id and action_repo_id: Pipe IDs where the trigger runs and where the action writes. See "Get Resource IDs" → Pipe ID and UUID.
action_params.aiParams.value: Prompt text. Reference source fields from the card with %{INTERNAL_ID} (e.g., %{132}).
action_params.aiParams.fieldIds: Destination field internal IDs for the AI output (e.g., 133). See "Get Resource IDs" → Field internal_id for Start Form and Phase Fields.
condition: Optional filter tree to control when the automation runs. Contains:
- expressions: Array of condition expressions. Each expression has:
  - structure_id: Unique identifier for this expression within the condition (use incremental numbers: 0, 1, 2, etc.).
  - field_address: The field's internal ID to evaluate (leave empty "" for placeholder conditions).
  - operation: Comparison operation. Valid options: equals, not_equals, present, blank, string_contains, string_not_contains, number_greater_than, number_less_than, date_is_today, date_is_yesterday, date_in_current_week, date_in_last_week, date_in_current_month, date_in_last_month, date_in_current_year, date_in_last_year, date_is, date_is_after, date_is_before.
  - value: The value to compare against (leave empty "" for placeholder conditions).
- expressions_structure: Defines how expressions are combined using logical operators. Use nested arrays where each sub-array represents a group of expressions connected by AND logic, and different sub-arrays are connected by OR logic.

mutation {
  createAutomation(
    input: {
  name: "Teste",
  action_id: "generate_with_ai",
  event_id: "card_created",
  event_repo_id: "22",
  action_repo_id: "22",
  action_params: {
    aiParams: {
      value: "Translate accurately, maintaining the original meaning, context, and tone of the following inputs: %{132}\nOutput language: English",
      fieldIds: [
        133
      ]
    }
  },
  condition: {
    expressions: [
      {
        structure_id: 0,
        field_address: "",
        operation: "",
        value: ""
      }
    ],
    expressions_structure: [
      [
        0
      ]
    ]
  }
}
  ) {
    automation {
      id
      name
      action_id
      event_id
      action_repo_v2 { ... on Pipe { id } ... on Table { id } }
      event_repo { id }
      active
    }
    error_details {
      object_name
      object_key
      messages
    }
  }
}

Response:

{
  "data": {
    "createAutomation": {
      "automation": {
        "id": "20",
        "name": "Teste",
        "action_id": "generate_with_ai",
        "event_id": "card_created",
        "action_repo_v2": {
          "id": "22"
        },
        "event_repo": {
          "id": "22"
        },
        "active": true
      },
      "error_details": null
    }
  }
}

Response explained

automation.id: Created automation identifier.
automation.name/action_id/event_id: Echoes the input for verification.
action_repo_v2.id / event_repo.id: Repo/Pipe IDs used.
active: Whether the automation is enabled.
error_details: Null when creation succeeds; otherwise includes validation errors.

Notes:

Repo IDs are the same as Pipe IDs. Get them in “Get Resource IDs” → Pipe ID and UUID.
Use field internal_id values:
- In the prompt: %{INTERNAL_ID} (e.g., %{132}).
- For outputs: list destination internal_id(s) in aiParams.fieldIds (e.g., 133).
To fetch internal_id values, use “Get Resource IDs” → Field internal_id for Start Form and Phase Fields:
- pipe(id: <PIPE_ID>) { start_form_fields { label internal_id } phases { fields { label internal_id } } }.

Update a field when a card is moved to a phase

Inputs

name: Display name of the automation.
action_id: update_card_field to update field values on a card.
event_id: card_moved to trigger on phase transitions.
event_repo_id / action_repo_id: Pipe IDs for trigger and action. See "Get Resource IDs" → Pipe ID and UUID.
event_params: Configuration for the triggering event. Contains:
- to_phase_id: Destination phase ID to match the move. Automation only triggers when cards move to this specific phase. See "Get Resource IDs" → Phase ID.
action_params: Configuration for the field update action. Contains:
- field_map: Array of field mappings. Each mapping has:
  - fieldId: Destination field internal ID where the value will be written.
  - inputMode: How to populate the field. Use copy_from to copy from another field, static for fixed values, or dynamic for calculated values.
  - value: Source value or field placeholder. Use %{INTERNAL_ID} to reference source fields (e.g., %{134}) or provide static text.
- fields_map_order: Array of field internal IDs defining the order in which fields are updated.
- card_id: Target card identifier. Use "%{id}" to reference the card that triggered the event.
condition: Optional filter tree to control when the automation runs. Same structure as described in the AI example above.

mutation {
  createAutomation(input: 
  {
  name: "Update the field when card is moved to Doing",
  action_id: "update_card_field",
  event_id: "card_moved",
  event_repo_id: "23",
  action_repo_id: "23",
  action_params: {
    field_map: [
      {
        fieldId: "135",
        inputMode: "copy_from",
        value: "%{134}"
      }
    ],
    fields_map_order: [
      135
    ],
    card_id: "%{id}"
  },
  condition: {
    expressions: [
      {
        structure_id: 0,
        field_address: "",
        operation: "",
        value: ""
      }
    ],
    expressions_structure: [
      [
        0
      ]
    ]
  },
  event_params: {
    to_phase_id: "328"
  }
}) {
    automation {
      id
      action_params {
        authenticationAddTo
        authenticationKey
        authenticationType
        body
        card_id
        email_template_id
        hasAuthenticationValue
        headers
        httpMethod
        strategy
        to_phase_id
        url
      }
    }
  }
}

Response:

{
  "data": {
    "createAutomation": {
      "automation": {
        "id": "22",
        "action_params": {
          "authenticationAddTo": null,
          "authenticationKey": null,
          "authenticationType": null,
          "body": null,
          "card_id": "%{id}",
          "email_template_id": null,
          "hasAuthenticationValue": false,
          "headers": null,
          "httpMethod": null,
          "strategy": null,
          "to_phase_id": null,
          "url": null
        }
      }
    }
  }
}

Response explained

automation.id: Created automation identifier.
action_params.card_id: Confirms it targets the moved card via %{id} from the event.
Other fields shown as null are not used by this action type and remain unset.
If validation fails, error_details would be provided (omitted here because success).

Understanding Condition Expressions

Condition expressions are powerful filters that control when automations execute. They evaluate field values against specified criteria and determine whether the automation should run. Here's a comprehensive guide:

What Are Condition Expressions?

Each condition expression is a database record that:

Belongs to a specific condition (linked via condition_id)
References a field in your pipe (via field_address and field_id)
Defines a comparison operation and value
Has a unique structure_id within its condition for logical grouping

Field Address: The Key Concept

The field_address is the field's internal ID that you want to evaluate. This is crucial:

{
  "structure_id": 0,
  "field_address": "132",  // This is the field's internal_id
  "operation": "equals",
  "value": "High Priority"
}

How to get field addresses:

Use Get Resource IDs → Field internal_id for Start Form and Phase Fields
Query: pipe(id: "PIPE_ID") { start_form_fields { label internal_id } phases { fields { label internal_id } } }
The internal_id from the response becomes your field_address

Structure ID: Unique Identifiers

Each expression within a condition must have a unique structure_id:

Start from 0 and increment: 0, 1, 2, 3...
Used to reference expressions in expressions_structure
Database enforces uniqueness within each condition

Available Operations by Field Type

Text/String Fields

equals - Exact match
not_equals - Not equal to
present - Field has any value
blank - Field is empty
string_contains - Contains substring
string_not_contains - Doesn't contain substring

Number Fields

equals - Exact numeric match
not_equals - Not equal to number
number_greater_than - Greater than value
number_less_than - Less than value
present - Field has any value
blank - Field is empty

Date Fields

date_is_today - Today's date
date_is_yesterday - Yesterday's date
date_in_current_week - This week
date_in_last_week - Last week
date_in_current_month - This month
date_in_last_month - Last month
date_in_current_year - This year
date_in_last_year - Last year
date_is - Specific date (value: "YYYY-MM-DD")
date_is_after - After specific date
date_is_before - Before specific date

Expression Structure: Logical Combinations

The expressions_structure defines how expressions are combined using AND/OR logic:

"expressions_structure": [
  [0, 1],  // Expression 0 AND Expression 1
  [2]      // OR Expression 2
]

Logic patterns:

[[0]] - Only expression 0 must be true
[[0, 1]] - Expression 0 AND 1 must both be true
[[0], [1]] - Expression 0 OR 1 must be true
[[0, 1], [2]] - (Expression 0 AND 1) OR Expression 2
[[0], [1, 2]] - Expression 0 OR (Expression 1 AND 2)

Retrieving Existing Conditions

To see how existing automations use conditions, query with the condition field:

{
  automations(repoId: "123", organizationId: "321") {
    edges {
      node {
        id
        name
        condition {
          expressions {
            structure_id
            field_address
            operation
            value
          }
          expressions_structure
        }
      }
    }
  }
}

Practical Examples

Example 1: Single Condition (Priority equals "High")

"condition": {
  "expressions": [
    {
      "structure_id": 0,
      "field_address": "132",
      "operation": "equals",
      "value": "High"
    }
  ],
  "expressions_structure": [[0]]
}

Example 2: Multiple AND Conditions (Priority = "High" AND Status = "Open")

"condition": {
  "expressions": [
    {
      "structure_id": 0,
      "field_address": "132",
      "operation": "equals",
      "value": "High"
    },
    {
      "structure_id": 1,
      "field_address": "145",
      "operation": "equals",
      "value": "Open"
    }
  ],
  "expressions_structure": [[0, 1]]
}

Example 3: OR Logic (Priority = "High" OR "Critical")

"condition": {
  "expressions": [
    {
      "structure_id": 0,
      "field_address": "132",
      "operation": "equals",
      "value": "High"
    },
    {
      "structure_id": 1,
      "field_address": "132",
      "operation": "equals",
      "value": "Critical"
    }
  ],
  "expressions_structure": [[0], [1]]
}

Example 4: Complex Logic ((Priority = "High" AND Status = "Open") OR Due Date is Today)

"condition": {
  "expressions": [
    {
      "structure_id": 0,
      "field_address": "132",
      "operation": "equals",
      "value": "High"
    },
    {
      "structure_id": 1,
      "field_address": "145",
      "operation": "equals",
      "value": "Open"
    },
    {
      "structure_id": 2,
      "field_address": "156",
      "operation": "date_is_today",
      "value": ""
    }
  ],
  "expressions_structure": [[0, 1], [2]]
}

Empty/Placeholder Conditions

When you don't want any filtering, use placeholder values:

"condition": {
  "expressions": [
    {
      "structure_id": 0,
      "field_address": "",
      "operation": "",
      "value": ""
    }
  ],
  "expressions_structure": [[0]]
}

Important Notes

Field Address Validation: The system validates that field_address corresponds to an existing field in your pipe
Operation Compatibility: Ensure the operation matches the field type (don't use number_greater_than on text fields)
Value Format:
- Text: Plain string values
- Numbers: Numeric strings ("123", "45.67")
- Dates: ISO format ("2024-01-15") for specific date operations
Connected Fields: For connector fields, the value should be the connected card's ID
Structure ID Uniqueness: Each expression in a condition must have a unique structure_id

Tips:

Use "Get Resource IDs" → Pipe ID and UUID to fetch event_repo_id/action_repo_id (Pipe ID).
Use "Get Resource IDs" → Phase ID to fetch to_phase_id for the target phase.
Use "Get Resource IDs" → Field internal_id for Start Form and Phase Fields to fetch:
- Source field internal_id used in value as %{INTERNAL_ID} (e.g., %{134}).
- Destination field internal_id in field_map.fieldId and fields_map_order (e.g., 135).

Before You Begin

Prerequisites

Create an Automation

AI action example (generate_with_ai using field internal_id)

Inputs

Response explained

Update a field when a card is moved to a phase

Inputs

Response explained

Understanding Condition Expressions

What Are Condition Expressions?

Field Address: The Key Concept

Structure ID: Unique Identifiers

Available Operations by Field Type

Text/String Fields

Number Fields

Date Fields

Expression Structure: Logical Combinations

Retrieving Existing Conditions

Practical Examples

Example 1: Single Condition (Priority equals "High")

Example 2: Multiple AND Conditions (Priority = "High" AND Status = "Open")

Example 3: OR Logic (Priority = "High" OR "Critical")

Example 4: Complex Logic ((Priority = "High" AND Status = "Open") OR Due Date is Today)

Empty/Placeholder Conditions

Important Notes

See also