Setting up triggers in Master Data v2

A Master Data trigger is an action executed after the insert or update of a given document. Actions can be of three types:

  • Send an HTTP request.
  • Send an email.
  • Send email using Message Center template.
  • Save data to another data entity.

In this guide, you will learn how to set up Master Data v2 triggers and see some code examples of different use cases.

πŸ“˜

Note that:

  • This article is about Master Data v2 triggers. If you want to use Master Data v1, check out the steps described in How to create a trigger in Master Data v1.
  • You may use Master Data triggers to create add hooks to VTEX first party apps. To do that, Create a new JSON schema for the data entity used by the app and then follow the instructions below.

Creating triggers

Each trigger is described as an item of the array v-triggers of a JSON schema. If you want to create a trigger for a data entity with no associated schema, you may create a new schema with the trigger settings according to what is described below. To create a new trigger in an existing schema, follow these steps:

  1. Get the schema to which you wish to add a trigger.
  2. Copy the JSON schema from the response and create a new item in the v-triggers array, configuring the properties according to your desired behavior. See the properties and example below.
  3. Send your edited schema as the body in the Save schema by name endpoint.

πŸ“˜

Edit triggers

To edit Master Data v2 triggers, follow the same steps described above, just editing the properties you wish instead of creating a new array item.

JSON Properties:

PropertyDescription
nametrigger name
activeboolean to enable or disable the trigger
conditionrule that validates the document before execution
runAtschedule the action to some time in the future
weightpercentage value used for A/B test
retrycustomize the retry policy
actionthe action that will be executed

name

It is the trigger name and must be a string value with limit of 100 characters.

active

Boolean value that indicates if the trigger is either enabled or disabled.

condition

The rule is the same for the search route. Example: status=ready-for-handling
To get futher information, check the developer docs for Master Data search route.

runAt

In case of scheduling an action in the future you can use the runAt property. See the examples below:

  • Schedule the execution 10 minutes after.
    {
        "dateTime": "now",
        "increment": {
            "addMinutes": 10
        }
    }
  • Schedule the execution six months after the field value createdIn.
    {
        "dateTime": "{!createdIn}",
        "increment": {
            "addMonths": 6
        }
    }

weight

An integer field used to distribute actions. See more information in the article Setting up an A/B test with Master Data trigger.

retry

By default, VTEX Master Data makes 3 attempts in an interval of 10 minutes. Use this property to override such behavior. See the example below.

Attempt five times in an interval of 30 minutes.

    {
        "times": 5,
        "delay": {
            "addMinutes": 30
        }
    }

action

There are 3 types of actions: Call an HTTP Request, send an email and save in other data entity. See the examples below.

  • Setting up an HTTP Request action.
    {
        "type": "http",
        "uri": "http://mydomain.com/api/test",
        "method": "POST",
        "headers": {
            "content-type": "application/json"
        },
        "body": {
            "id": "{!id}",
            "test": "TestValue",
            "count": 25
        }
    }
  • Setting up an email action.
    {
        "type": "email",
        "provider": "default",
        "subject": "My email with VTEX Master Data",
        "to": [
            "{!email}",
            "[email protected]"
        ],
        "bcc": [
            "[email protected]"
        ],
        "replyTo": "[email protected]",
        "body": "My email with document {!id}."
    }
    {
        "type": "t-email",
        "template": "template-name",
        "provider": "default",
        "subject": "My template email with VTEX Master Data",
        "to": [
            "{!email}",
            "[email protected]"
        ],
        "bcc": [
            "[email protected]"
        ],
        "replyTo": "[email protected]",
         "body": {
                        "firstName": "{firstName}",
                        "email": "{email}",
                        "id": "{!id}",
                        "clientName": "{!clientProfileData.firstName} {!clientProfileData.lastName}",
                        "ownerListName": "{!customData.customApps[0].fields.ownerListName}",
                        "ownerListEmail": "{!customData.customApps[0].fields.ownerListEmail}",
                        "items": "{!items}",
                        "openTextField": "{!openTextField.value}"
                    }
    }
  • Setting up an action saving a document to another data entity.
    {
        "type": "save",
        "dataEntity": "copy",
        "json": {
            "id": "{!id}",
            "message": "{!message}",
            "custom": "created/updated by VTEX Master Data triggers"
        }
    }

Complete example

    {
        "properties": {},
        "v-triggers": [
            {
                "name": "copy-document",
                "active": true,
                "condition": "status=window-to-cancel",
                "action": {
                    "type": "save",
                    "dataEntity": "copy",
                    "json": {
                        "id": "{!id}",
                        "message": "{!message}",
                        "custom": "created/updated by VTEX triggers"
                    }
                },
                "retry": {
                    "times": 5,
                    "delay": {
                        "addMinutes": 30
                    }
                }
            }
        ]
    }