Automation JSON import format

This is the canonical version 1 interchange format for exporting and importing Crewvana Automations. It is intentionally explicit enough for an AI agent to author a workflow without reading application source. Imports create safe drafts; they never publish or execute a workflow.

Envelope and schema version

Every file is one bundle. A single-Automation export still uses the automations array with one item.

• format must be exactly crewvana.automation.
• schema_version must be the integer 1.
• automations must contain 1 to 100 Automation objects.
• Unknown envelope fields and unsupported versions are rejected.
• Encode the file as UTF-8 JSON and use a .json filename.

{
    "format": "crewvana.automation",
    "schema_version": 1,
    "automations": [
        {
            "key": "example_automation",
            "name": "Example Automation",
            "settings": {
                "delay_seconds": 0,
                "folder": null
            },
            "nodes": [
                {
                    "key": "trigger_contact",
                    "type": "trigger",
                    "name": "lead_created",
                    "parameters": {}
                }
            ],
            "connections": [
                {
                    "from": null,
                    "to": "trigger_contact",
                    "branch": "trigger",
                    "order": 1
                }
            ]
        }
    ]
}

Automation object

Each Automation has these fields:

The importer keeps a requested name when it is unused, using a case-insensitive collision check. On a collision it tries <name> (Imported), then <name> (Imported 2), increasing the suffix until the name is unused. References using automation_key bind by document key before this rename occurs.

Nodes and parameters

A node contains key, type, name, optional display_name, and parameters. The key is local to its Automation. type is trigger or action. name is the stable identifier from the node catalog. parameters is always an object, including for nodes with no parameters.

• A draft may contain zero or one registered trigger. Add one documented trigger before publishing a workflow; multiple triggers are rejected.
• Use only registered node identifiers. Class names and translated labels are not identifiers.
• Unknown parameters and unknown node-specific settings are rejected.
• display_name is an optional editor label. It does not alter runtime behavior.
• Database IDs, runtime logs, enrollments, waits, history, publication state, and tenant IDs do not belong in this format.

The current catalog contains 38 registered nodes. Compatibility-only nodes remain importable for round trips but are hidden from the new-node selector.

Connections, ordering, and branches

Each connection has from, to, branch, and order:

• Every root node uses from: null. A root trigger uses branch: "trigger"; every root action uses branch: "actions".
• A branch child uses the branching action key in from and its exact branch token in branch.
• order is 1-based and contiguous within a path. The root trigger and root actions are separate paths because they use the distinct trigger and actions branch tokens.
• Each node must appear as to exactly once. A node cannot have multiple parents.
• Branch parents must be registered branching actions, and branch tokens are case-sensitive.
• When present, the single trigger must be a root at order 1 and cannot be the source of child connections.
• A branching action must be the final action in its path. Put later work inside one of its branches.
• A wait timeout connection is valid only when that wait node has timeout_enabled set to true.
• The graph is an ordered tree of paths, not a general DAG: no cycles, joins, convergence, dangling endpoints, or cross-Automation node edges.
• No node may be deeper than 25 nodes from its root.
• A branch path may be empty. Execution ends when the selected empty branch is reached.

The importer derives database parent IDs and sort orders from these records. Never include database node IDs.

Dependency references

Named tenant references resolve only inside the importing tenant. Unless create_if_missing is explicitly allowed, resolution must find exactly one eligible record; zero matches and ambiguous matches are errors. Matching never falls back to a numeric database ID. A Facebook form uses its external form id rather than a tenant database ID; that id must be present in exactly one active Facebook integration for the target tenant.

An Automation reference using automation_key targets another Automation in the same file. An Automation reference using name targets one existing tenant Automation. Prefer automation_key whenever the target is in the bundle.

create_if_missing is explicit. It is supported only where the node reference documents it; omission means false. The importer never silently creates other dependencies.

Conditions

A conditions value is a non-empty array of at most 50 objects. Every condition in the array uses AND semantics.

Allowed field tokens are: email, phone, first_name, last_name, full_name, source, city, state, pipeline, pipeline_id, pipeline_status, pipeline_status_id, tenant.activated, tenant.activation_step, tenant.plan_id, tenant.plan_name, tenant.plan_free_trial_days, tenant.subscription_status, tenant.subscription_billing_cycle, tenant.subscription_amount, tenant.subscription_trial_days_left, tenant.subscription_trial_end_date, tenant.subscription_has_card_on_file, tenant.subscription_card_brand, tenant.subscription_card_last_four, and tenant.subscription_next_billing_at.

For pipeline, pipeline_id, pipeline_status, and pipeline_status_id, value is still the exact human-readable Pipeline or Pipeline Status name in the target tenant—not a numeric ID. The name must resolve uniquely.

Examples:

[
    {
        "operator": "has_tag",
        "value": "VIP"
    },
    {
        "operator": "not_empty",
        "field": "email"
    },
    {
        "operator": "equals",
        "field": "state",
        "value": "CO"
    }
]

Variables, JSON, and escaping

Templated setting strings and webhook payload string values can use double-brace placeholders such as {{contact.first_name}}. Keep the braces inside the JSON string. Escape JSON quotes and backslashes normally.

• Common groups are contact, service_job, team, user, form, facebook_form, date, search, and platform-only tenant values.
• Incoming webhook payload fields use dotted paths such as {{webhook.customer.email}}.
• Variables are replaced at runtime, so the required runtime context still has to exist.
• References are resolved during import and cannot contain variables.
• A send_webhook payload is a JSON object, not text containing encoded JSON.
• Null, booleans, numbers, arrays, and objects should remain typed JSON values unless a node article explicitly calls for a string.
• Integer-valued JSON numbers must stay in the lossless range −9007199254740991 through 9007199254740991. Use a documented string field when a larger identifier is required.

Import safety and naming

The complete bundle is validated before persistence and created transactionally. Every imported Automation receives fresh database IDs and starts inactive and unpublished with no copied runtime records. Review it in the editor and publish it explicitly before it can run.

Imports do not copy executions, enrollments, logs, waits, history, published snapshots, owners, tenant IDs, webhook history samples, or audit timestamps. A failed import leaves the database unchanged.

Validation errors and limits

Validation errors identify a JSON path, for example $.automations[0].nodes[2].parameters.pipeline.name. Fix every reported path and submit the complete file again.

The published JSON Schema enforces the closed envelope, all 38 registered type/name pairs, exact parameter and settings keys, value types, enums, reference shapes, and condition object variants. The importer then performs semantic checks that JSON Schema cannot fully express, including graph topology and ordering, branch-parent compatibility, dependency resolution, cross-Automation references, and tenant-specific runtime constraints.

• A bundle supports at most 100 Automations, 500 nodes per Automation, 500 connections per Automation, 5000 total nodes, and 5000 total connections.
• Duplicate Automation keys, duplicate node keys, missing endpoints, duplicate path orders, cycles, excessive depth, invalid branches, and branching actions followed by siblings are rejected.
• Multiple triggers, mismatched node type/name pairs, non-importable nodes, invalid parameter types, and unknown fields are rejected.
• Missing or ambiguous tenant dependencies are rejected instead of being guessed.
• The HTTP upload limit is 2 MiB. JSON parser depth and validation-error limits also apply before persistence.

Forward compatibility

Authors must emit only schema version 1. Importers reject versions they do not understand rather than guessing. Do not add extension fields: version 1 objects use closed property sets. Re-export an Automation after a future schema migration to obtain that version’s canonical representation.

Complete examples

These examples use the same envelope accepted by import. They intentionally avoid tenant dependencies, so their JSON contracts validate in any tenant; replace the example webhook destinations before using them.

Basic workflow

A new-contact trigger posts typed contact data to an external webhook.

{
    "format": "crewvana.automation",
    "schema_version": 1,
    "automations": [
        {
            "key": "new_contact_webhook",
            "name": "New Contact Webhook",
            "settings": {
                "delay_seconds": 0,
                "folder": "Imported Examples"
            },
            "nodes": [
                {
                    "key": "trigger_contact",
                    "type": "trigger",
                    "name": "lead_created",
                    "parameters": {}
                },
                {
                    "key": "post_contact",
                    "type": "action",
                    "name": "send_webhook",
                    "parameters": {
                        "url": "https://example.com/hooks/new-contact",
                        "payload": {
                            "event": "contact_created",
                            "contact_id": "{{contact.id}}",
                            "source": "{{contact.source}}"
                        }
                    }
                }
            ],
            "connections": [
                {
                    "from": null,
                    "to": "trigger_contact",
                    "branch": "trigger",
                    "order": 1
                },
                {
                    "from": null,
                    "to": "post_contact",
                    "branch": "actions",
                    "order": 1
                }
            ]
        }
    ]
}

If / Else workflow

The condition action posts to different webhook destinations based on the contact source.

{
    "format": "crewvana.automation",
    "schema_version": 1,
    "automations": [
        {
            "key": "contact_source_routing",
            "name": "Contact Source Routing",
            "settings": {
                "delay_seconds": 0,
                "folder": "Imported Examples"
            },
            "nodes": [
                {
                    "key": "trigger_contact",
                    "type": "trigger",
                    "name": "lead_created",
                    "parameters": {}
                },
                {
                    "key": "check_source",
                    "type": "action",
                    "name": "if_else",
                    "parameters": {
                        "settings": {
                            "conditions": [
                                {
                                    "operator": "equals",
                                    "field": "source",
                                    "value": "Website"
                                }
                            ]
                        }
                    }
                },
                {
                    "key": "website_webhook",
                    "type": "action",
                    "name": "send_webhook",
                    "parameters": {
                        "url": "https://example.com/hooks/website-contact",
                        "payload": {
                            "route": "website",
                            "contact_id": "{{contact.id}}"
                        }
                    }
                },
                {
                    "key": "other_source_webhook",
                    "type": "action",
                    "name": "send_webhook",
                    "parameters": {
                        "url": "https://example.com/hooks/other-contact",
                        "payload": {
                            "route": "other",
                            "contact_id": "{{contact.id}}"
                        }
                    }
                }
            ],
            "connections": [
                {
                    "from": null,
                    "to": "trigger_contact",
                    "branch": "trigger",
                    "order": 1
                },
                {
                    "from": null,
                    "to": "check_source",
                    "branch": "actions",
                    "order": 1
                },
                {
                    "from": "check_source",
                    "to": "website_webhook",
                    "branch": "if",
                    "order": 1
                },
                {
                    "from": "check_source",
                    "to": "other_source_webhook",
                    "branch": "else",
                    "order": 1
                }
            ]
        }
    ]
}

Wait workflow

The wait pauses for an SMS reply, then follows either the continued or timeout branch.

{
    "format": "crewvana.automation",
    "schema_version": 1,
    "automations": [
        {
            "key": "reply_follow_up",
            "name": "Reply Follow-up",
            "settings": {
                "delay_seconds": 0,
                "folder": "Imported Examples"
            },
            "nodes": [
                {
                    "key": "trigger_contact",
                    "type": "trigger",
                    "name": "lead_created",
                    "parameters": {}
                },
                {
                    "key": "wait_for_reply",
                    "type": "action",
                    "name": "wait",
                    "parameters": {
                        "settings": {
                            "wait_mode": "reply",
                            "reply_channel": "sms",
                            "wait_until_business_hours": true,
                            "resume_timezone_mode": "recipient",
                            "resume_day_mon": true,
                            "resume_day_tue": true,
                            "resume_day_wed": true,
                            "resume_day_thu": true,
                            "resume_day_fri": true,
                            "resume_start_time": "09:00",
                            "resume_end_time": "17:00",
                            "timeout_enabled": true,
                            "timeout_number": 2,
                            "timeout_unit": "days"
                        }
                    }
                },
                {
                    "key": "reply_received",
                    "type": "action",
                    "name": "send_webhook",
                    "parameters": {
                        "url": "https://example.com/hooks/reply-received",
                        "payload": {
                            "outcome": "continued",
                            "contact_id": "{{contact.id}}"
                        }
                    }
                },
                {
                    "key": "reply_timeout",
                    "type": "action",
                    "name": "send_webhook",
                    "parameters": {
                        "url": "https://example.com/hooks/reply-timeout",
                        "payload": {
                            "outcome": "timeout",
                            "contact_id": "{{contact.id}}"
                        }
                    }
                }
            ],
            "connections": [
                {
                    "from": null,
                    "to": "trigger_contact",
                    "branch": "trigger",
                    "order": 1
                },
                {
                    "from": null,
                    "to": "wait_for_reply",
                    "branch": "actions",
                    "order": 1
                },
                {
                    "from": "wait_for_reply",
                    "to": "reply_received",
                    "branch": "continued",
                    "order": 1
                },
                {
                    "from": "wait_for_reply",
                    "to": "reply_timeout",
                    "branch": "timeout",
                    "order": 1
                }
            ]
        }
    ]
}

AI author checklist

Before returning a generated file:

1. Emit one envelope with the exact format and schema_version values.
2. Give every Automation and node a unique, readable document key; never invent database IDs.
3. Select one registered trigger for an executable workflow and only documented actions. A deliberately incomplete draft may omit the trigger.
4. Build every parameters object from that node’s article and remove unknown keys.
5. Use portable dependency references and verify that names/emails/endpoints will resolve uniquely in the target tenant.
6. Add exactly one incoming connection per node with contiguous 1-based order; root triggers use branch trigger and root actions use branch actions.
7. Make every branching action the last node in its path and use only its documented branch tokens.
8. Check for cycles, joins, dangling keys, accidental self-enrollment, and unreachable actions.
9. Keep webhook payloads as objects and preserve JSON value types.
10. Expect an inactive, unpublished draft; never claim that import publishes or executes it.

Node catalog

• Contact created — trigger:lead_created (selectable)
• Contact added to pipeline status — trigger:pipeline_status_added (selectable)
• Contact added to pipeline — trigger:contact_pipeline_updated (selectable)
• Tag added to contact — trigger:contact_tag_added (selectable)
• Tag removed from contact — trigger:contact_tag_removed (selectable)
• Facebook form submission — trigger:facebook_lead_received (selectable)
• Form submission — trigger:form_submission (selectable)
• Visit created — trigger:service_job_created (selectable)
• Visit updated — trigger:service_job_updated (selectable)
• Repeat every X — trigger:repeat_every (selectable)
• User created — trigger:user_created (selectable)
• User added to team — trigger:user_assigned_team (selectable)
• Webhook trigger — trigger:webhook (selectable)
• Move contact to pipeline status — action:move_to_pipeline_status (selectable)
• Find open opportunity — action:opportunity:find (selectable)
• Create opportunity — action:opportunity:create (selectable)
• Create or update contact — action:contact:upsert (selectable)
• Create contact — action:contact:create (compatibility-only)
• Update contact — action:contact:update (compatibility-only)
• Add tag to contact — action:contact_tag:add (selectable)
• Add tag by name to contact — action:contact_tag:add_custom (compatibility-only)
• Remove tag from contact — action:contact_tag:remove (selectable)
• Find contact by phone number — action:contact:search_by_phone (selectable)
• Find contacts by tag — action:contact:search_by_tag (selectable)
• Add contact to automation — action:workflow:enroll_contact (selectable)
• Remove contact from automation — action:workflow:remove_contact (selectable)
• Create task — action:task:create (selectable)
• Create job — action:service_job:create (selectable)
• Find job — action:service_job:find (selectable)
• Update job — action:service_job:update (selectable)
• Delete job — action:service_job:delete (selectable)
• Webhook — action:send_webhook (selectable)
• If / Else — action:if_else (selectable)
• Wait — action:wait (selectable)
• Call Connect — action:call_connect (selectable)
• Send notification — action:send_notification (selectable)
• Send email — action:send_email_template (selectable)
• Send SMS — action:send_sms_template (selectable)