Using custom objects in triggers

There are two types of triggers that support custom objects: ticket triggers and object triggers. Ticket triggers run any time a ticket is created or updated, while object triggers run any time the object's records are created or updated.

Using custom objects in ticket triggers

Custom objects are useful in their own right because they enable you to capture and reference your unique data within Zendesk. However, you can go further and integrate your custom objects and data into your ticket triggers. Within the ticket trigger, any custom objects that are related to tickets through a lookup relationship ticket field can be referenced in your conditions. Similarly, you can add actions that notify users related to a custom object record.

The following example continues the IT asset management scenario described in Creating custom objects. Now that you've created the custom objects, your admin wants you to create a trigger that assigns tickets to the IT group when any Software requested value is present in a ticket.

Let's assume the following exist in your account:

• A custom object named Software
• A ticket lookup relationship field named Requested software, that points to the Software object. The field's id is 17531702893847. In trigger conditions, custom ticket fields are specified by id rather than key: custom_field_{id}.
• A group named IT, with an id of 15609689242263.
• A trigger category named Assignment, with an id of 15590471937303.

Then you can use the POST /api/v2/triggers endpoint to create the requested trigger. Refer to the API Conditions reference and API Actions reference for more details about the request body. For example:

curl https://{subdomain}.zendesk.com/api/v2/triggers.json \
  -H "Content-Type: application/json" -X POST \
  -u {email}/token:{api_token} \
  -d '{
  "trigger": {
    "title": "Triage Software Requests",
    "category_id": "15590471937303",
    "actions": [
        {
            "field": "group_id",
            "value": "15609689242263"
        }
    ],
    "conditions": {
        "all": [
            {
                "field": "custom_fields_17531702893847",
                "operator": "present",
                "value": null
            }
        ],
        "any": []
    }
  }
}'

In response, you'll get details about the trigger similar to this:

// Status 201 Created

{
    "url": "https://{subdomain}.zendesk.com/api/v2/triggers/17532274678039.json",
    "id": 17532274678039,
    "title": "Triage Software Requests",
    "active": true,
    "updated_at": "2023-09-14T18:32:50Z",
    "created_at": "2023-09-14T18:32:50Z",
    "default": false,
    "actions": [
        {
            "field": "group_id",
            "value": "15609689242263"
        }
    ],
    "conditions": {
        "all": [
            {
                "field": "custom_fields_17531702893847",
                "operator": "present",
                "value": null
            }
        ],
        "any": []
    },
    "description": null,
    "position": 1,
    "raw_title": "Triage Software Requests",
    "category_id": "15590471937303"
}

Now let's say your admin wants a second trigger that sends an email notification when a license is assigned to a user. To do this, you define the following:

• A new lookup field named Assigned to with the key assigned_to on the License object that points to Users.
• A ticket lookup relationship field that points to the License object. The field name is License assigned to and the id is 17680080658199.

Now you can create a trigger that sends an email to the user specified in the ticket's License assigned to field. In the email notification you send to the user, you can reference custom object fields and values in placeholders. For example:

curl https://{subdomain}.zendesk.com/api/v2/triggers.json \
  -H "Content-Type: application/json" -X POST \
  -u {email}/token:{api_token} \
  -d '{
  "trigger": {
    "title": "Triage Software Requests",
    "category_id": "15590471937303",
    "actions": [
        {
            "field": "notification_user",
            "value": [
                "lookup:ticket.ticket_field_17680080658199.custom_fields.assigned_to",
                "License for requested software",
                "You've been assigned the following license for {{ticket.ticket_field_17531702893847}}:\n\n{{custom_object.license.custom_fields.name}}"
            ]
        },
        {
            "field": "custom_status_id",
            "value": "15590402606999"
        }
    ],
    "conditions": {
        "all": [
            {
                "field": "custom_fields_17680080658199",
                "operator": "present",
                "value": null
            }
        ],
        "any": []
    }
  }
}'

In response, you'll get details about the trigger similar to this:

{
  // Status 201 Created

    "url": "https://{subdomain}.zendesk.com/api/v2/triggers/17532274678039.json",
    "id": 17532274678039,
    "title": "Notify of license assignment",
    "active": true,
    "updated_at": "2023-09-20T14:21:48Z",
    "created_at": "2023-09-20T14:21:48Z",
    "default": false,
    "actions": [
        {
            "field": "notification_user",
            "value": [
                "lookup:ticket.ticket_field_17680080658199.custom_fields.assigned_to",
                "License for requested software",
                "You've been assigned the following license for {{ticket.ticket_field_17531702893847}}:\n\n{{custom_object.license.custom_fields.name}}"
            ]
        },
        {
            "field": "custom_status_id",
            "value": "15590402606999"
        }
    ],
    "conditions": {
        "all": [
            {
                "field": "custom_fields_17680080658199",
                "operator": "present",
                "value": null
            }
        ],
        "any": []
    },
    "description": null,
    "position": 1,
    "raw_title": "Notify of license assignment",
    "category_id": "15590471937303"
}

Using custom objects in object triggers

In addition to using custom objects related to tickets in ticket triggers, object triggers provide a way for admins to create triggers oriented around custom object record creation and updates. The conditions and actions available depend on the fields defined for the custom object itself.

The following example continues the IT asset management scenario described in Creating custom objects. Your admin wants you to create an object trigger that sets the Software object's needs_approval checkbox field to true when the object is created or updated and has a status field equal to "Pending" or "Not Approved".

Let's assume the following exist in your account:

• A custom object named Software
• The Software object has a checkbox field with the key needs_approval
• The Software object has a drop-down field with the key approval_statusand three values: approved (id 28555656458509), not approved (id 28555656458637), and pending (id: 28555656458765)

Then you can use the POST /api/v2/custom_objects/software/triggers endpoint to create the requested trigger. Refer to the API Conditions reference and API Actions reference for more details about the request body. For example:

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/software/triggers.json \
  -H "Content-Type: application/json" -X POST \
  -u {email}/token:{api_token} \
  -d '{
    "trigger": {
        "actions": [
            {
                "field": "custom_object.software.custom_fields.needs_approval",
                "operator": "",
                "value": "true"
            }
        ],
        "active": true,
        "title": "Set software approval",
        "description": "",
        "conditions": {
            "all": [],
            "any": [
                {
                    "field": "custom_object.software.custom_fields.approval_status",
                    "operator": "is_not",
                    "value": "28555656458509"
                }
            ]
        }
    }
}'

In response, you'll get details about the object trigger similar to this:

{
    // Status 201 Created

    "url": "https://{subdomain}/api/v2/custom_objects/software/triggers/28555854729613.json",
    "id": 28555854729613,
    "title": "Set software approval",
    "active": true,
    "updated_at": "2024-07-19T15:05:40Z",
    "created_at": "2024-07-19T15:05:40Z",
    "default": false,
    "actions": [
        {
            "field": "custom_object.software.custom_fields.needs_approval",
            "value": "true"
        }
    ],
    "conditions": {
        "all": [],
        "any": [
            {
                "field": "custom_object.software.custom_fields.approval_status",
                "operator": "is_not",
                "value": "28555656458509"
            }
        ]
    },
    "description": "",
    "position": 1,
    "raw_title": "Set software approval"
    
}

For more information, see Understanding object triggers and Creating object triggers to update records and send notifications.