Automation — Scripted Automation

Introduction

Scripted automation is an advanced tool which allows programmatic creation of automation rules. Using this tool, a combination of SQL and JavaScript can be employed to create powerful and complex automation rules.

Developing Document: This is a dynamic document that will be updated as Search Ads Maven adjusts to changes and updates that arise though the Beta process.

Requirements

• Basic knowledge of SQL
• Basic knowledge of JavaScript

Scripted automation rules are created using a series of triggers (SQL) and actions (JavaScript). Triggers define the conditions which must be met in order for resulting actions to take place. A typical scripted rule consists of a single trigger and action. More complex rules may contain multiple triggers and actions. When a scripted rule runs, each trigger and action is executed sequentially (from top to bottom). Execution of triggers and actions continues until one of the following takes place:

1. A trigger produces 0 results.
2. The last (bottom) action or trigger completes execution.
3. The StopRule() function is called within an action.

---

Conceptual

Before diving into scripted rule creation, it is important to understand how a rule is created from a conceptual standpoint. This means understanding how to properly break up your desired automation scenario into triggers and actions. Trigger — Defines what set of conditions must take place in order for this rule to continue execution. Action — Defines what actions to take on each of the results returned by trigger.

---

First we will cover a simple automation scenario. In this scenario, we want to pause campaigns with a CPA greater than $5.

The first step is splitting this scenario into a trigger and action. The trigger defines the condition that must be met, which in this case is identifying any campaigns with a CPA greater than $5. The action defines what to do with these campaigns, which in this case is pausing each of the resulting campaigns.

Next we will cover a slightly more complex scenario where we want to reduce keyword spend by 25% but only for adgroups with less than 20 installs and only for keywords within those adgroups with bids greater than $3 and which contain the phrase “chocolate”.

In this case the trigger is a combination of adgroups with less than 20 installs, keywords with bids greater than $3 and keywords containing “chocolate”.

As you can see, understanding how to split an automation scenario into triggers and actions is an important concept which is fundamental to leveraging the scripted automation tool. Once you master this you will be able to automate virtually any scenario.

Now that you have a fundamental understanding of what a trigger and action is, read on to learn how to create each of these.

---

Triggers

Triggers represent the set of conditions which must be met in order for the rule to execute further. Triggers are defined using SQL. Click the Add Trigger button to add a trigger to your rule.

The contents of a trigger can be thought of as the WHERE clause of an SQL query run against the current snapshot of your ASA data existing as campaign, adgroup and keyword tables. All columns within these tables are available to you as first-class variables in the right pane of the view during trigger construction and can be referenced using the syntax {table}.{column}.

When a trigger runs and the SQL query is performed, tables are joined and all campaign, adgroup and keyword entities are recursively returned so that actions may be performed on those results. For example, if a single campaign is returned then all of its child adgroups and all of its child keywords are returned as well. As another example, if a single keyword is returned, its parent adgroup and parent campaign are returned as well.

NOTE: Tables are sandboxed and query capability is limited to read-only basic SQL syntax.

Example — Return all entities where campaign CPA > $10

This will return:

• Campaigns: Those with a CPA > 10
• Adgroups: Child adgroups of the returned campaigns
• Keywords: Child keywords of the returned adgroups

---

Example — Return all entities where keyword bids > $1.25

This will return:

• Keywords: Those with a bid > 1.25
• Adgroups: Parent adgroups of the returned keywords
• Campaigns: Parent campaigns of the returned adgroups

---

Example — Return all entities where campaign CPA > $10 and which have keywords bids > $1.25

This will return:

• Campaigns: Those with a CPA > 10 and which also have keywords with bids > 1.25
• Adgroups: Child adgroups of the returned campaigns
• Keywords: Those with a bid > 1.25 and which also belong to campaigns with a CPA > 10

---

Once the trigger SQL query is performed, actions may then be instrumented to act on each of the campaigns, adgroups and keywords returned.

Development Notes

• A scripted automation rule must contain at least one trigger and action.
• If no entities are returned by a trigger, execution of the rule stops and no further actions or triggers are evaluated.

---

Actions

Actions are broken up by type (campaign, adgroup, keyword and one-time) and represent what actions to take on each of the resulting campaigns, adgroups or keywords of the previous trigger. Click the Add Action button of the desired type to add an action to your rule following a trigger.

Actions are defined using JavaScript. A typical action script block consists of calling one or more functions to accomplish a task but may also contain logical operations, variable assignments, cache storage and any other basic JavaScript syntax necessary for your rule.

A single action script block applies to each of the entity results of the previous trigger and can be thought of as a for-each iteration over the entity results of that type. For example, let’s look at a scenario where a trigger returns five campaigns, three adgroups, and ten keywords. In this scenario, a campaign action block would run five times (once for each campaign returned), an adgroup action block would run three times, and a keyword action block would run ten times.

When an action block runs, it is scoped to each individual entity from the trigger result. The properties of the current entity are visible in the right pane under the Variables tab and can be referenced using the syntax {property}. Functions can also be called within the action block using these properties and are also available in the right pane under the Functions tab.

It is important to understand how to reference the entity variables within the action, as they are necessary for most functions and logical operations.

Example — Pause Each Campaign

In this campaign action we reference the {id} property of the current campaign and pass that into the PauseCampaign() function as the id parameter. This will result in PauseCampaign() being called for each campaign returned.

---

Example — Reduce each keyword bid by 25%

In this keyword action we multiply the {bid} property of the current keyword by .75 (which results in a 25% reduction) and pass that result to the AdjustBid() function along with the {id} property of the current keyword. This will result in AdjustBid() being called for each keyword returned.

---

Example — Reduce each keyword bid by 25% but only for those named “horse”

In this keyword action we perform the same action as the previous example but only if the {name} property of the current keyword is “horse”. Keywords not named “horse” are not adjusted.

---

You may create multiple actions for a single trigger. For example you may wish to take action on both campaigns and keywords within those campaigns for single action, in which case you would simply create a campaign action and keyword action following the trigger.

You may also create additional triggers following actions if desired (more complex rules might require this). Keep in mind that actions only apply to the previous trigger.

---

Persisting Values

At times you may wish to persist values across multiple actions. This can be accomplished using the SetCachedValue() and GetCachedValue() functions.

The caching functions allow you to read and write to a global key value store for the duration of the rule. The key value store is not persisted between separate instances of the same rule. SetCachedValue() allows you to write a cached value to a key name of your choosing, while GetCachedValue() allows you to read the value from the provided key. Other caching functions, such as SumCachedValue() exist as a convenience and are not required but make operations on cached values easier.

Example — Store campaign spend from the current campaign action under a key named “mySpend”

Example — Read the stored spend from the previous action

Example — Sum campaign spend from the current campaign with previous campaign spend

---

One-Time Actions

These are lesser-used actions which do not execute within the scope of any individual entity but rather execute one time following a trigger. They are often used to perform a single piece of logic following multiple actions or multiple results from a trigger.

---

Testing a Rule

---

Disabling a Rule

Scripted rules continue to run at the desired frequency until disabled. You must determine when a rule should no longer run by calling the DisableRule() function within an action block.

If you desire a rule to run only once when successful, a one-time action should be added to the end of your rule which calls DisableRule().

If you desire that a rule be disabled only under certain conditions, create an appropriate action which calls DisableRule() gated behind the required conditions. In this case the rule will continue to run until the conditions are met.

---

Rule Scheduling

A variety of additional settings exist below the action and trigger blocks which allow you to specify how often and when the rule runs.

Significant consideration should be given to the frequency at which scripted rules are scheduled, as they will continue to run at the desired schedule until stopped manually or disabled within an action block. A rule that reduces keyword bids, for example, could continue to reduce the keyword bid each time it runs. Give plenty of thought to how often a scripted rule should run and be sure to consider when and if the DisableRule() function is called.

Once your rule is behaving as expected and additional settings have been provided, click the Save (or update) button to finalize and save the rule. Keep in mind that you can return and edit the rule any time.