The Conductrics Agent Management API can be used to create and manage Conductrics agents, which you can use to create new A/B tests or other agents programmatically instead of using the Conductrics Admin. You can also do things like change their status from "stopped" to "running" and so on.

Typically the Agent Management API is used to create "API Agents", meaning Conductrics agents that you intend to use via our REST API or Local JS API in the browser, or via our Mobile Support.

However, you can also use the Agent Management API to create or update "Express" agents, meaning Conductrics agents that should run as if you set them up using the Custom JS or WYSIWYG paths through the "Create" process in the Conductrics Admin.

Creating or Updating a "Custom JS" Agent

Here is the general form of a simple Express agent, which you could create (or update) by issuing a PUT to your Conductrics account, using an endpoint similar to the following:

https://api-v3.conductrics.com/admin/acc-xxxxxx/agents/agent/a-xxxxxxxxxx

See the Agent Management API doc page for details about how to get the exact endpoint to use for your account (which may be hosted on a dedicated Conductrics environment) and how to provide an API Key for authentication purposes.

{
    "code": " a-xxxxxxxxxx", // starts with "a-" if created via admin
    "name": "My Express JS A/B Test",
    "status": "running", // "running", "stopped", "paused"

    // the agent's variations (add a third one for an A/B/C Test, etc)
    // (each code should have a corresponding key in "actions" portion of diagram)
    "choices": [
    {
        "code": "A",
        "name": "Default"
    },
    {
        "code": "B",
        "name": "B Variation"
    }],
    "tags": [
      "c-wa", // important - this tags the agent as an "Express" agent 
      "c-qa"  // optional - this puts the agent in "QA-Only Mode" 
    ],

    // "Visitor Eligibility Conditions" 
    // (separate from URL Conditions, provided at wa-decision level within "diagram")
    "conds": [],
  
    // "diagram" section (see next section in this doc page)
    "diagram": { ... } // will contain your Custom JS, "Wait For" selectors, etc
}

The main items of interest to note for our purposes here are:

• The c-wa tag, which must be provided to let Conductrics know that the agent should be run as an "Express" agent (as opposed to an agent that would be invoked from code on "your side" via our Runtime API). We do not support converting an existing agent from Express mode to API mode, or vice-versa (so please don't attempt to add or remove the c-wa tag from an existing agent).
• The c-qa tag, which puts the agent in "QA-Only Mode", which is generally recommended for new Express agents (especially if you create them with status running, because a running agent without the c-qa flag would deploy and start running for public visitors immediately). Later, you can turn off the QA-Only Mode via the admin, or by updating the agent via another PUT with the c-qa flag removed.
• The conds portion, which is where you can define any "Visitor Eligibility" conditions that you want to define for the agent. See the "Providing Conditions" section later in this doc page for details.
• The diagram portion, which is where the actual "Custom JS" and corresponding options are provided for each variation (discussed shortly).

See the Agent Management API page for details about the other agent-level attributes such as code, name, status, and choices, and where to get the API endpoint and API Key to use.

Understanding the "Diagram" Structure

The diagram portion is where the "Express content" for your agent is stored, and should look something like this:

"diagram":
{
    "module": "root",
    "items": [
    {
        "module": "entry",
        "entry": "wax",
        "items": [
        {
            "module": "wa-start",
            "items": [
            {
                // Represents a "Change Set" as shown in the Admin
             		// Typically there is just one wa-decision, but multiple are supported
                "module": "wa-decision",
                "agent": "a-xxxxxxxxxx", // the agent in question
                "name": "Change Set 1", // friendly name for the Change Set (matters only if multiple)

              	// The "actions" to take for each variation
                // ...in this case, Custom JS is being provided for each variation)
                "actions":
                {
                    "A": [
                    {
                        "module": "wa-script",
                        "js": "document.querySelector('h2').innerText = 'Hello World A';",
                    }],
                    "B": [
                    {
                        "module": "wa-script",
                        "js": "document.querySelector('h2').innerText = 'Hello World B';",
                    }]
                },
              
                // The "URL Conditions" that say which URLs the agent activates on (for this change set)
                // Not to be confused with "Visitor Conditions", which are at the agent level (see prior section)
              	"conds": [
                    ["${v.loc.qx}", "is", "https://pretend-company.com/landing-page/"]
                ],
              
              	// The "view-states" that the agent should activate at (if needed))
                "vstates": [], // leave empty to activate when the Conductrics script first runs

                // Optional - these appear under the "Eligibility" tab in the Code window in the admin
                "selector": "h2", // if provided, proceed if/when this selector appears in DOM
                "js": "if (something) { return true; }", // if provided, proceed only if this code returns true

              	// The URL to use by default for previews and WYSIWYG editing
                "_ipe_url": "https://pretend-company.com/landing-page/"
            }]
        }]
    }]
},

As shown above, the diagram is made up of a "tree" of instructions that will be used to "run" your Express agent when it activates on your pages.

A few general words about the diagram structure:

• We call each item in the diagram tree a "node".
• Each node has a "module" property (such as wa-decision or wa-script) which we call the "node type", plus various additional attributes that are specific to the node type (such as js or selector).
• When the Conductrics script actually runs on your pages, its runtime logic "walks" through the diagram tree, executing an internal handler function specific to each node type.

For the type of diagram we're considering here (execution of Custom JS for an A/B Test), the main portion of interest is the wa-decision node and its actions.

• The actions structure should contain a key/value pair for each of the agent's variations, where the key is the variation code (such as A or B), and the value is an array of "actions" to take if the visitor is selected for that variation.
• Within the array for each variation, you may place ONE wa-script node with the JavaScript code that you want to execute on the page (assuming that the visitor is eligible and is selected for that variation). See the next section for notes about some additional attributes that are supported on thewa-script node.
• Do not include more than one wa-script node per variation, mainly because that is not supported by the Admin UI. If you need to provide different JS to execute on different pages, add another "Change Set" by adding another wa-decision node to the items array of the wa-start node).
• There are other node types that can appear in the variation-specific action arrays (that is, at the same level as the wa-script nodes shown above). These would most likely be actions such as wa-show, wa-hide, wa-insert, 'wa-set-style`, which are normally created by our WYSIWYG editing workflow and are not discussed in detail here. Contact Conductrics if you have questions about them.

📘

There are other node types that can appear in the variation-specific action arrays (that is, at the same level as the wa-script nodes shown above). These would most likely be actions such as wa-show, wa-hide, wa-insert, 'wa-set-style`, which are normally created by our WYSIWYG editing workflow and are not discussed in detail here. Contact Conductrics if you have questions about them.

📘

If you're wondering what the wa- prefix is about, it stands for "Web Actions", which is an earlier name for what we now call "Conductrics Express".

🚧

Please consider the root, entry, and wa-start nodes as shown in the example above to be the required "boilerplate" for an Express agent to run properly. Conductrics does not necessarily support a diagram that is missing these items.

Providing the wa-script for Each Variation

As you can see in the diagram shown in the section above, the wa-script node is what holds the JavaScript code that should execute per variation (assuming eligibility requirements have been met and the visitor is selected for the variation, of course).

There are some additional options that you can provide for each wa-script node, which correspond to the options for each variation's "tab" when providing Custom JS in the Conductrics Admin:

{
    "module": "wa-script",

    // required - the actual JS to execute for this variation 
    "js": "document.querySelector('h2').innerText = 'Hello World B';",
  
    // "Wait For Selector" options (all optional)
    "selector": "h2", // a selector that your JS code "depends upon"
    "watch": false, // corresponds to "Watch & Reapply" option in admin
    "watch_sel": "h2 .icon", // Custom selector for "Watch & Reapply"
    "prehide": false, // corresponds to "Prehide" option in admin
  
    // other options
    "confirm": false, // corresponds to "Confirm variation selection via JS" option in admin
    "ext": false, // corresponds to "Load JS separately in browser" option in admin
    "ctx": , // corresponds to "Pass Custom Visitor Traits to JS" option in admin
}

📘

To provide the Eligibility Selector or Eligibility JS as shown under the Eligibility tab when providing Custom JS in the Admin UI, use the selector or js properties of the wa-decision object, respectively (see prior section).

Providing Conditions

There are two main places to provide "conditions" in the overall structure of an Express agent:

1. The conds array at the "Change Set" level, represented in the wa-decision part of the diagram structure (discussed above). This corresponds to the conditions you provide via the URL Conditions button in the Conductrics Admin. These conditions execute FIRST, to determine whether the agent is potentially relevant to the current page. This conds array should only contain URL-related conditions, as other data may not yet be initialized/populated. It should NOT contain conditions about the visitor (such as visitor traits, etc).
2. The conds array at the agent level (see above section), which you get to via the Visitor Conditions button on an agent's main page when using the Conductrics Admin. These Conditions execute SECOND, if and when the URL Conditions have passed (and after the Eligibility Selector has matched and/or the Eligibility JS test has passed, if you are using either in the wa-decision portion of your diagram). This conds array may contain conditions about the visitor.

There are a lot of values and comparison operators available for conditions, not documented here at this time. If you want to populate either of the conds arrays, we suggest that you create the conditions you want in the Conductrics Admin, then use the "Copy to Clipboard" function (in the window where you provide the conditions) to get the corresponding conditions structure (as an array).

You can then make any modifications you need, and use that for the conds that you PUT to the Agent Management API as discussed on this doc page. Alternatively, you or another user could add the conditions interactively via the Conductrics Admin after the agent is created. Feel free to reach out to Conductrics if you have questions.