Create Automation Rule

POST https://{server}/api/v2.1/workspace/{workspace_id}/dtable/{base_name}/automation-rules/

You can set the automation rule to trigger by condition, or periodically. The following instruction shows you how to send the request body. Consult the example request for demonstration.

After successful creation, an id is returned, this is the ID of the automation rule you just created, and is to be distinguished from the action's _id like explained below in the actions section.

First, define the running condition

For the run_condition parameter, use

• per_update for conditional trigger, if the rule should be triggered when a certain condition is met when the table has been updated;
• per_day, per_week, or per_month for periodical trigger, if the rule should be triggered periodically.
  

Then, define the trigger condition

In the trigger object, all the following params are required:

• rule_name is the name of this rule;
• table_id is the ID of the table;
• view_id is the ID of the view;
• condition is how you'd like the rule to trigger. Use filters_satisfy for conditional trigger or run_periodically for periodical trigger.
  

Determine the trigger scenario if run_condition is per_update

In the automation rule's trigger conditions, you can watch some or all of the columns for changes, and eventually set filter conditions to narrow down the watching. So that means there are three typical scenarios:

• Watch all the columns without filters

  This is the simplest scenario: whenever a record has been changed, this rule will trigger. To do this, just define watch_all_columns as true and you are good to go:
  

    "trigger": {
        "rule_name": "Watch all",
        "table_id": "0000",
        "view_id": "0000",
        "condition": "filters_satisfy",
        "watch_all_columns": true
    }

• Watch one or more columns without filters

  In the column_keys array, list the keys of columns you'd like to watch. Remember to set watch_all_columns to false (if you leave it as true, all the columns will be watched):
  

    "trigger": {
        "rule_name": "Watch Name and Select",
        "table_id": "0000",
        "view_id": "0000",
        "condition": "filters_satisfy",
        "column_keys": ["0000", "72IC"]
    }

• To apply filters to the above scenarios

  You'll need two further params, if you'd like to filter the watched columns:
• filters as an object. For details, refer to the SeaTable API Parameter Reference under "filters".
• filter_conjunction: Use And or Or for the filter conjunction logic.
  

Here's an example:

    "trigger": {
        "rule_name": "test-auto",
        "table_id": "0000",
        "view_id": "0000",
        "condition": "filters_satisfy",
        "filters": [{
            "column_key": "0000",
            "filter_predicate": "contains",
            "filter_term": "yes"
        }, {
            "column_key": "_creator",
            "filter_predicate": "contains",
            "filter_term": ["[email protected]"]
        }],
        "filter_conjunction": "And"
    }

Determine the trigger scenario if run_condition is per_day, per_week, or per_month

One or more further params are required:

• If the run_condition is per_day, define notify_hour here. Use 0 to 23 for the time of day you'd like the rule to trigger.
• If the run_condition is per_week, define these two params:
  • notify_week_day: Use an integer from 1 to 7 for Monday to Sunday, and
  • notify_week_hour: Use 0 to 23 for the time of day you'd like the rule to trigger.
• If the run_condition is per_month, define these two params:
  • notify_month_day: Use an integer from 1 to 31 for the day of month. Attention: If it's set to 31 but a month doesn't have a 31st day, this rule won't be triggered. It'll only be triggered when the current day is a 31st.
  • notify_month_hour: Use 0 to 23 for the time of day you'd like the rule to trigger.

See the example request for demonstration.

Last but not least: The action

Different than the trigger object, the actions is a list of objects. This enables you to trigger multiple actions all at once.

In each action object, the _id is the first parameter. It's an ID of the action. If you have multiple actions in one rule, they should carry different IDs. You can decide which ID an action should carry.

To notify one or more users:

• type should be notify;
• users is a list of user's IDs, it's optional if the users_column_key is defined;
• users_column_key is a list of keys of columns that are the types of collaborator, creator or modifier;
• default_msg: is the content of the message. You can use {column name} in the message to quote the content of a certain cell.
  

Example:

    "actions": [
        {
            "type": "notify",
            "users": [],
            "default_msg": "look at {Name}.",
            "_id": "740077",
            "users_column_key": "iXRK"
        }
    ]

To modify the record:

• type should be update_record;
• updates is an object including the column key and desired content of each field that you would like to modify.
  

Example:

    "actions": [
        {
            "type": "update_record",
            "updates": {
                "0000": "abc",
                "6NKm": 123
            },
            "_id": "54696"
        }
    ]

To lock the record:

• type should be lock_record;
• is_locked set to true and the record that triggered the action will be locked.
  

Example:

    "actions": [
        {
            "type": "lock_record",
            "is_locked": true,
            "_id": "872510"
        }
    ]

To add a new record:

• type should be add_record;
• row is an object including the column key and desired content of each field that you would like to add in the new record.
  

Example:

    "actions": [
        {
            "type": "add_record",
            "row": {
                "0000": "abc"
            },
            "_id": "410993"
        }
    ]

To send an email:

• type should be send_email;
• account_id is the ID of the third party account you added in this base. Refer to Third Party Email Accounts for details;
• send_to is the receiver's email address. If you would like to send to multiple receivers, separate their email addresses with comma (,) inside of the quotation mark.
• copy_to is the CC receiver's email address. For multiple addresses see above.
• subject is the subject of your email.
• default_msg is the content of the message.
  

Example:

    "actions": [
        {
            "type": "send_email",
            "default_msg": "Content example.",
            "account_id": 17,
            "subject": "Subject sample",
            "send_to": "[email protected], [email protected]",
            "copy_to": "[email protected], [email protected]",
            "_id": "838356"
        }
    ]
}