Overview
Use this page when calling the Management API or reading campaign configuration. It describes how configuration is structured: a campaign is a tree of components plugged into typed sockets. Each of these concepts has a runtime meaning and a configuration meaning. At runtime, a campaign is the thing that accepted an event, a reward is one a person earned, and a journey is the path that person took. The Integration APIs work with that meaning, and Key Concepts explains it. In configuration, a campaign is a tree of components, a reward is a reward component with its rules and supplier, and a journey is a component that groups business events. The Management API and My Extole work with that meaning. This page explains it.Components
A component is the unit of configuration. Everything you set up in a campaign is one: a role, a journey, a business event, a reward, an experience, a rule. A component has a name, one or more types, settings, and child components. Together, the components of a campaign form a tree whose root is the campaign. List components returns the components of an account. Get a built component returns one with every setting evaluated.Types
A component’s type decides which settings it carries and which child components it can hold. Type names carry a generation suffix, such asbusiness-event-v10.0. The pages on this site drop the suffix when they name a type in prose.
A type can specialize another. reward-email-v10.0 is a kind of reward-send-action-v10.0, which is a kind of action-v10.0. A socket that accepts the general type accepts each specialized one.
Sockets
A socket is a typed slot for child components — a setting that holds one component or many. ASOCKET holds one. A MULTI_SOCKET holds many. Each socket declares the types it accepts, so a businessEvents socket on a journey holds business events and nothing else.
You add to a campaign by copying a component into a socket. The API lists those sources as duplicatable components — templates you can install. Pass a target component and setting to see only the ones that fit that socket. Duplicate a component installs the copy. The sources are the components Extole maintains and the ones your account already has.
For example, to add a reward, list duplicatable components for the campaign’s rewards socket, then duplicate one into that socket. The copy keeps the source defaults until you change its variables.
Variables
A variable is a setting with a value. Each has a type, such asSTRING, COLOR, BOOLEAN, REWARD_SUPPLIER_ID or TRIGGER_CONFIGURATION, and a map of values that can differ by locale. List component settings returns the variables and sockets of a component.
A duplicated component keeps the values of its source until you set your own. Values are evaluated when the campaign is built, which is why Get a built component and the component as configured can differ.
Some variable types reference configuration that lives outside any campaign. REWARD_SUPPLIER_ID names a reward supplier, AUDIENCE_ID an audience, WEBHOOK_ID a webhook. The campaign refers to them; the Management API’s Reward Suppliers, Audiences and Webhooks groups manage them.
The Four Kinds of Campaign
An account’s campaign list holds four kinds. The Management API carries the kind ascampaign_type.
Create a campaign takes the kind. List campaigns returns all four.
A Marketing Campaign as a Tree
The socket names below are the ones the API returns, and the type names drop their suffix. Each line issocketName: component-type — children listed under a socket are the types that socket accepts.
- content is a creative, a page or an experience. It holds content blocks in layout sockets, nested experiences, and the trigger events that show it.
- action is what a business event does: send an email, publish an event, send a reward. It holds data and a person identification that says which person the action is about.
- rule is a condition. A group rule holds rules. A targetable event listener is a rule that listens for a journey step — the named milestone recorded after a business event matches.
- business-event declares the event a campaign listens for. Once a campaign accepts an event that matches one, the person’s journey records a step with that name.
- reward holds the rules that decide whether one is owed and the issuer that sends and fulfills it.
- data declares the fields a component captures or carries.
Extensions and Integrations as Trees
integrationEvents are the events an outside system can send to the account. A marketing campaign’s business event is triggered by one of them, which is what Triggered By selects in Flow Builder. How to Set Up Triggered By covers that choice.
Programs, Labels, Versions and State
In product language, a program is the use case — audience plus outcome. In the Management API, that grouping is represented as aPROGRAM label: every campaign carries one, and the campaigns that share a label are one program. A campaign can also carry CAMPAIGN and JOURNEY labels. An integration’s events name the program label they are for, and that label is what targets them at the campaign. Programs vs. Campaigns explains when to make a new one of each.
A campaign has versions. Editing creates a draft, and publishing makes the draft the published version. Building evaluates every variable of a version into the built campaign the runtime uses.
A campaign has a state: NOT_LAUNCHED, LIVE, PAUSED, ENDED, STOPPED or ARCHIVED. The state decides whether the runtime considers the campaign for an event. Pausing, Ending, and Scheduling Campaigns covers the transitions in My Extole.
