Execution Spec

Updated: Jan 13, 2020

The execution_spec of a rule determines the action that applies to all objects that pass evaluation. Schedule and Trigger Based Rules support different actions. Actions are listed under execution_type.

Execution Type	Description
NOTIFICATION	Sends a jeweled notification to this rule's creator, or the list of users specified in user_ids, if this option is provided. Supported Evaluation Types: SCHEDULE, TRIGGER
PAUSE	Pauses the objects. Supported Evaluation Types: SCHEDULE, TRIGGER
UNPAUSE	Unpauses the objects. Supported Evaluation Types: SCHEDULE, TRIGGER
CHANGE_BUDGET	Changes the budgets based on a defined change_spec. This applies to ad sets only. Supported Evaluation Types: SCHEDULE
CHANGE_CAMPAIGN_BUDGET	Changes the budgets based on a defined change_spec. This applies to ad campaigns only. Supported Evaluation Types: SCHEDULE
CHANGE_BID	Changes the bids based on a defined change_spec. This applies to ad sets only. Supported Evaluation Types: SCHEDULE
ROTATE	Pauses the currently active ad, and activates the next ad by ID in the ad set. Requires an id filter of ad sets, and an entity_type filter of an ad. Supported Evaluation Types: SCHEDULE
REBALANCE_BUDGET	Pauses the objects that match the evaluation criteria, and rebalances their budgets towards the rest based on a defined rebalance_spec. This applies to ad sets only. Supported Evaluation Types: SCHEDULE
PING_ENDPOINT	Sends a ping to the application's subscription via Webhooks. See Trigger Based Rules for more details on setup. Supported Evaluation Types: TRIGGER

execution_options

You may need to provide additional information to perform some of these actions. The execution_spec provides an optional execution_options array to specify these additional parameters. The array contains a list of execution_option objects, which are dictionaries with keys of field, value, and operator just like Evaluation Spec's filter objects.

Trigger Based Rules do not require any execution options.

Below, see supported execution options, which execution_type values they support, and how to structure them. Currently, the only supported operator for all options is EQUAL.

Execution Option Field	Description
user_ids*	Jeweled notification recipients for NOTIFICATION, or recipients for Schedule Based Rules summary emails for each execution_type. Supported Execution Types: ALL execution_type supported by Schedule Based Rules Value (Example): array ([123, 456])
change_spec	Specifies amount, limit, unit, and target_field. Required as a dictionary for the supported types. If target_field exists, the bid or budget scales based on the difference between the current value of the target_field and the target value specified in amount. The target_field must be a valid Insights filter. Supported Execution Types: CHANGE_BUDGET, CHANGE_BID Value (Example): Ad Rules Change Spec Examples
rebalance_spec	Supports different options that determine how budgets are rebalanced. See example for more details. Supported Execution Types: REBALANCE_BUDGET Value (Example): Rebalance Budget Ad Rules
execution_count_limit	Specifies the maximum number of times a budget/bid change action is taken for each individual ad object for the rule. If not specified, it defaults to no limit. Supported Execution Types: CHANGE_BUDGET, CHANGE_BID Value (Example): int (123)
action_frequency	Specifies the minimum amount of minutes until the same action can be taken on an object by a rule. For example, if value is 10080 for a CHANGE_BUDGET rule, and budget was just increased by that rule for object A. That rule does not increase the budget for object A for at least a week, even if object A passes the rule evaluation during that week. Supported Execution Types: CHANGE_BUDGET, CHANGE_BID Value (Example): int (123)

user_ids

If user_ids are provided for Schedule Based Rules:

• A daily email is generated to summarize actions performed by your rule within the last 24 hours
• The information is sent to the list of users specified under user_ids
• the email is sent at 12:30AM, using the ad account's time zone

This summary email aggregates notifications for all rules to which each user is subscribed. If no actions are performed by any of the subscribed rules, the user does not get an email for that day.