Define bot responses

Use our Bot Manager subprovider to identify, track, and respond to bot activity on your domain or in your app.

📘

For information about adding analytics cookies to your integration, contact your account team.

Before you begin

• Understand the basics of Terraform.
• Complete the steps in Get started.
• Subscribe to Bot Manager.
• Use ≥v2.3.1 of our Terraform provider.
• Be familiar with Bot Manager terms and concepts.

Using JSON to specify argument values

Bot Manager doesn’t use a lot of separate arguments. For example, suppose an item has three settings: setting_1, setting_2, and setting_3. In many subproviders, these settings and their values, are expressed as separate arguments:

setting_1 = 100
setting_2 = 200
setting_3 = 300

With Bot Manager, these settings are usually configured as a JSON array, and that array is then used as the value for a single argument (e.g., item_argument). That’s why the examples used in this documentation often include code that looks like this:

  item_argument = <<-EOF
{
     "setting_1": 100,
     "setting_2": 200,
     "setting_3": 300
}
EOF

This code snippet has a single argument: item_argument. In addition, the value of that argument is a JSON array containing the three settings and their values:

{
     "setting_1": 100,
     "setting_2": 200,
     "setting_3": 300
}

The EOF delimiter tells Terraform that the subsequent lines of code contain the value to be assigned to item_argument. As a result, Terraform reads in each line, not stopping until it see the EOF delimiter, which tells Terraform that the input is complete. In our simple example, Terraform reads in the following lines of code and then assigns that input to item_argument:

{
     "setting_1": 100,
     "setting_2": 200,
     "setting_3": 300
}

Instead of hard-coding these values and settings in your Terraform configuration, you can:

1. Save the JSON array to a separate file. For example, you might save your custom category settings to a file named custom-category.json.

2. Use syntax similar to the following to read the JSON file and assign the contents of that file to the custom_bot_category argument:
   `custom_bot_category = file("${path.module}/custom-category.json")``

In the preceding example, the syntax ${path.module} is a shorthand way to indicate that the JSON file is stored in the same folder as the Terraform executable. Note that you don't have to store your JSON files in the same folder as the Terraform executable: store the file wherever you want. Just remember that, if you use a different folder, you need to specify the full path to that file in your code. Otherwise, Terraform won't be able to find it.

Workflow

Bot Manager has a number capabilities, and some of those capabilities depend on whether you’re running the standard version of Bot Manager or the Premier version of Bot Manager. Because Bot Manager can do so many things, there’s no way to walk you through an exhaustive set of Bot Manager workflows. However, we can walk you through a typical workflow, one in which you:

1. Create a custom bot category.
2. Modify the action assigned to that custom category.
3. Create a custom bot and assigning that bot to the new category.
4. Move an Akamai-defined bot from its Akamai-defined category to the custom category.

Create a custom category

Custom categories serve at least two purposes in Bot Manager. First, custom-defined bots you create need to be placed in a custom category. You can’t add bots to an Akamai-defined category. Before you can create a custom-defined bot you need to create a custom category you can assign that bot to.

In addition to that, you can move an Akamai-defined bot out of its Akamai-defined category, but only if you move that bot to a customer category. An Akamai-defined bot can’t be moved into a different Akamai-defined category.

To create a custom category, use a Terraform configuration similar to this:

data "akamai_appsec_configuration" "configuration" {
  name = "Documentation"
}

resource "akamai_botman_custom_bot_category" "custom_bot_category" {
  config_id           = data.akamai_appsec_configuration.configuration.config_id
  custom_bot_category = file("${path.module}/custom_category.json")
}

Although that configuration might look a bit intimidating, its bark is actually far worse than its bite. For example, take the first block of code:

terraform {
  required_providers {
    akamai = {
      source = "akamai/akamai"
    }
  }
}

That’s boilerplate code for loading the Akamai Terraform provider. This code can be used exactly as-is in all your Terraform configurations.

That’s also true of the second block of code, which loads the edgerc file.

provider "akamai" {
  edgerc = "~/.edgerc"
}

Finally, this block of code returns the ID of your security configuration:

data "akamai_appsec_configuration" "configuration" {
  name = "Documentation"
}

And what if you don’t have a security configuration named Documentation? That’s fine: just replace Documentation with the name of that configuration. For example:

data "akamai_appsec_configuration" "configuration" {
  name = "NorthAmerica"
}

Incidentally, this block is optional: if you prefer, you can specify the ID of your security configuration (e.g., 76982) when you create your custom category. The advantage of including the preceding block of code is that you only have to remember the security configuration's name, something that’s often easier to recall than the configuration ID.

That brings us to our final block of code, which uses the akamai_botman_custom_bot_category resource to create a custom bot category named Vendor bots:

resource "akamai_botman_custom_bot_category" "custom_bot_category" {
  config_id           = data.akamai_appsec_configuration.configuration.config_id
  custom_bot_category = file("${path.module}/custom_category.json")
}

That code block requires the two arguments shown below:

Modify the action assigned to a custom category

When you create a custom bot category, you don’t specify the action taken when the category is triggered. Instead, Bot Manager automatically sets the category action. If you want to assign a different action to the category, use the akamai_botman_custom_bot_category_action resource and a Terraform configuration similar to this:

data "akamai_appsec_configuration" "configuration" {
  name = "Documentation"
}

resource "akamai_botman_custom_bot_category_action" "custom_category_action" {
  config_id                  = data.akamai_appsec_configuration.configuration.config_id
  security_policy_id         = "gms1_134637"
  category_id                = "2c8add8e-a23c-4c3e-a5c9-8a3dc0d4c0b8"
  custom_bot_category_action = file("${path.module}/action.json")
}

The first three blocks of code you should already be familiar with. The first block loads the Akamai Terraform provider and the second block points to the edgerc file, the file containing your authentication credentials. Meanwhile, the third block connects you to the Documentation security configuration and, not coincidentally, returns the ID of that configuration. Again, that step is entirely optional. If you prefer, leave it out and simply specify the ID of the security configuration in the code that modifies the category action.

The code that modifies the category action uses the following arguments:

Create a custom bot

Although Bot Manager currently recognizes some 1,400 bots, that’s clearly not all the bots ever created. For example, you, one of your partners, or one of your vendors might have internal bots employed to help maintain your site. It’s unlikely that Akamai would know about, let alone have provided definitions for, bots like these. That’s one reason why you might need to create custom-defined bots.

To create a custom-defined bot, you need to specify the conditions that enable Bot Manager to identity the bot. For detailed information on how to configure these conditions, see Update a custom-defined bot.

Note that, when you create a custom bot, that bot must be assigned to a custom bot category. That simply means that, if you haven’t already done so, you need to create a custom category before you create a custom bot.

The following Terraform configuration uses the akamai_botman_custom_defined_bot resource to create a custom bot named vendor-bot:

Here's the Terraform code:

data "akamai_appsec_configuration" "configuration" {
  name = "Documentation"
}

resource "akamai_botman_custom_defined_bot" "custom_defined_bot" {
  config_id          = data.akamai_appsec_configuration.configuration.config_id
  custom_defined_bot = file("${path.module}/custom_bot.json")
}

Like our previous examples, this configuration starts off by:

1. Loading the Akamai Terraform provider.
2. Retrieving authentication credentials from the edgerc file.
3. Connecting to the Documentation security configuration.

Following those three steps (and those three blocks of code), the configuration calls the akamai_botman_custom_defined_bot resource and creates the new bot. The code for doing that includes these two arguments:

Recategorize an existing bot

When you subscribe to Bot Manager, you gain access to a large number of Akamai-defined bots, with each bot assigned to an Akamai-defined category. In most cases, those Akamai-defined categories will suit your needs just fine. However, you might have certain bots that you’d prefer to associate with a different category.

In a case like that, you need to “recategorize” the bot, which means that you need to move the bot to the custom category of your choice. To recategorize a bot, use the akamai_botman_recategorized_akamai_defined_bot resource and a Terraform configuration similar to the following:

data "akamai_appsec_configuration" "configuration" {
  name = "Documentation"
}

resource "akamai_botman_recategorized_akamai_defined_bot" "recategorized_bot" {
  config_id   = data.akamai_appsec_configuration.configuration.config_id
  bot_id      = "cc9c3f89-e179-4892-89cf-d5e623ba9dc7"
  category_id = "2c8add8e-a23c-4c3e-a5c9-8a3dc0d4c0b8"
}

As usual, most of this configuration is boilerplate. The first two blocks load the Akamai provider and specify your authentication credentials, and the third block connects you to a security configuration named Documentation. After that, you use the following three arguments to specify the bot you want to move and where you want to move it to: