Campaigns

Campaigns or Events are rules and associated actions configured on data streams to detect in realtime. This consist of selecting an audience of an event, configurating the certain transaction or activity to be performed by users and configurating the actions to be performed upon event detection. This section will explain how to preconfigure different templates for audience, triggers, offer actions and e2e campaign templates so that campaign creation by marketing user will be performed easily from UI.

Below are the concepts used in the campaign or event configuration process.

Enums Type Definitions

Enums are custom types, used for enabling dropdowns in audience, triggers and action offers templates. Enum types are of two types i.e., Enum and TreeEnums. Enums are configured in file etc/model/campaigns/enum_type_definitions.json.

Enum

This Enum Types are simple one item selection type Enums.

Lets take example of an enum and how its configuration looks like:

                            "enums":[......{"enumName":"SubscriberCategoryType","placeholder":"Select subscriber category","possibleValues":[{"displayOrder":0,"displayValue":"Regular","intEnumValue":0},{"displayOrder":1,"displayValue":"Silver","intEnumValue":1},{"displayOrder":2,"displayValue":"Gold","intEnumValue":2}],"uelType":"Int32"},......]}
                        

Above Enum is a configuration of Subscriber Category, there are 4 possible values for this Enum i.e., Regular, Silver and Gold. In the streaming data/Real data these different values are represented as ID field and value 0 denotes Regular, 1 denotes Silver and 2 denotes Gold. But on UI users will descriptive values like Gold, Regular.

enums is the type of enum being configured.
enumName is not name of enum to be used in various condition templates.
placeholder is the text to be show inplace where selection is required on UI.
possibleValues are list of possible values for this enum.
displayOrder is order of this value in the dropdown.
displayValue is value to be show in the drop-down item.
intEnumValue or stringEnumValue or booleanEnumValue are the actual data value being selected.
uelType is the type of values.

When we use this enum type in a template condition then UI will look like below:

Enum used in a template.

TreeEnums

TreeEnums are hierarchical enums and allows multi select in the drop-down. Once we select from a TreeEnum a list of values are selected. If you select a leaf node of the tree then only single value will be selected, but if you select any other node except leaf node, then all leaf node under that will be selected.

lets take example of DeviceType Enum as configured below:

                            ....{"enumName":"Devices","placeholder":"Select device","possibleValues":[{"children":[{"children":[{"displayOrder":0,"displayValue":"Samsung Galaxy S5","enumValue":"GALAXY_S5"},{"displayOrder":1,"displayValue":"Samsung Galaxy S6","enumValue":"GALAXY_S6"},{"displayOrder":2,"displayValue":"Samsung Galaxy S7","enumValue":"GALAXY_S7"}],"displayOrder":0,"displayValue":"Samsung Galaxy","enumValue":"ALL_GALAXY_S"}],"displayOrder":0,"displayValue":"Samsung","enumValue":"ALL_SAMSUNG"},{"children":[{"children":[{"displayOrder":0,"displayValue":"iPhone 4","enumValue":"IPHONE4"},{"displayOrder":1,"displayValue":"iPhone 5","enumValue":"IPHONE5"},{"displayOrder":2,"displayValue":"iPhone 6","enumValue":"IPHONE6"}],"displayOrder":0,"displayValue":"iPhone","enumValue":"ALL_APPLE_IPHONE"}],"displayOrder":1,"displayValue":"Apple","enumValue":"ALL_APPLE"},{"displayOrder":2,"displayValue":"Google","enumValue":"ALL_GOOGLE"}]}....
                        

When we use this enum type in a template condition then UI will look like below:

TreeEnum used in a template.

Note: Enum type definitions are loaded in-memory every-time we restart the tomcat backend.

Audience Condition Templates

Audience Condition Templates are template condition for filtering the master profile of Detect. This selects a list of users which satisfies an audience condition.

audience conditions are configured in etc/model/campaigns/audience_condition_categories.json file.

Audience templates are grouped into named categories based on their business logics as shown below:

                        {"categories":[{"icon":"fa-sliders","name":"Demographic","templates":[{...},{...}]},{"icon":"fa-user","name":"Transaction Based","templates":[{...},{...}]}}
                    

categories are shown below:

Audience categories.

Once we select an audience category, all audience templetes under that audience category will shown as below:

List of Audience templates.

Elements inside the templates are differnt audience template condition, we will try learn how to configure audience condition templates by examples.

Simple Audience Templates

Below is an example audience template, which filters users who have not changes device since some configurable datetime:

                            {"analyticsBased":false,"caption":"Subscribers who have not changed their device since ${deviceChangeDateTime}","conditionTemplateId":"deviceChangeDateTime","domainMapping":{"expressionTemplate":"profile.deviceChangeTime < ${deviceChangeDateTime}"},"name":"Device change time","profile":"Customer","segments":[{"segmentId":"deviceChangeDateTime","segmentKind":"Complex","segmentType":"DateTime","segmentValue":{"dateTimeValue":"2000-11-11T12:00:00"}}]},
                        

Lets look how it looks in the UI if we select this audience template in the use case:

Simple Audience condition.

caption is the caption text which will appear in the UI. It can optionally cantain one or more segmentIds inorder to make caption customizable. In this example deviceChangeDateTime is a segmentId and definition of this segmentId is done in the segments section. Segments are used to get inputs from users while they are configuring an audience condition.
conditionTemplateId is an unique id given to used by Detect.
domainMapping.expressionTemplate is the UEL expression that always evalues to either true or false. A Subscriber will be part of this audience only if this UEL expression evaluates to true based on their profile attributes. In order to access a profile attribute, profile. is suffixed in the name of attribute. In this example profile.deviceChangeTime will access deviceChangeTime attribute of master profile of any given subscriber.
name is the name of the audience condition under a given audience category.
profile should alway be master profile name.
segments the list of segment definitions used in the caption.
segmentId is id of segment used in the caption.
segmentKind is the data type of segment. This can be Primitive type like String, Integer, Double or Boolean. or Complex type like Time, POIs, Geofences, Duration, DateTime, AggregationDuration, MonetaryValue. or Enum or TreeEnum.
segmentValue is the value which will be shown as default value in the UI which user can update while configuring the audience.

Audience Template With Modifiers

An audience template can have one or more optional additional condition along with primary domainMapping condition expression. These are called modifiers.

Let look at below example:

                            {"analyticsBased":false,"caption":"Subscribers whose monthly average amount in the last ${recentObservationWindowLength}months has ${increasedDecreasedIndicator}by ${changePercentage}% compared to the average recharge value in the last ${historicalObservationWindowLength}months","conditionTemplateId":"averageRechargeAmount","domainMapping":{......}},"modifiers":[{"caption":"${hasRoaming}roaming enabled","domainMapping":{"expressionTemplate":"profile.roamingEnabled == ${hasRoaming}"},"modifierId":"roamingEnabled","name":"Roaming...","segments":[{"captions":["Does not have","Has"],"segmentId":"hasRoaming","segmentKind":"Enum","segmentType":"Boolean","segmentValue":{"booleanValue":false}}]},{"caption":"Main balance is greater than ${mainBalanceAmount}","domainMapping":{"expressionTemplate":"profile.mainBalanceAmount >= ${mainBalanceAmount}"},......}],"name":"Average recharge amount","profile":"Customer","segments":[..]}
                        

In above example we have 2 additional modifiers condition along with primary domainMapping condition. If selected a modifier in the UI, modifier's domainMapping is added as an and condition logic to primary domainMapping condition.

Lets look how the list of modifiers looks in the UI :

Modifiers list in the Audience condition.

If we select a modifer the UI refect it by expanding the caption and allowing users to exit default segment values.

Modifiers selected in the Audience condition.

Modifier follows the same structure as explained in simple audience template, expect it has unique modifierId insead offer conditionTemplateId

hasRoaming is a segment of type Enum. Its Enum type is Boolean and selected segment value is false

below is an example of a condition using TreeEnum:

                            {"analyticsBased":false,"caption":"Subscribers who have installed appllications from categories ${appCategories}","conditionTemplateId":"treeSelectAppCategories","domainMapping":{"expressionTemplate":"profile.installedAppCategories in ${appCategories}"},"name":"App categories","profile":"Customer","segments":[{"segmentId":"appCategories","segmentKind":"TreeEnum","segmentType":"AppCategories","segmentValue":{"stringListValue":{"values":["BOOKS_AND_REFERENCE","GAME_ACTION"]}}}]}
                        

TreeEnum selection retruns are list, that is why the segmentValue is stringListValue type.

Audience template With Segment Switch

If we want to have different expressions to be used in a domainMapping based on the value of user selected segmentId, then we could use segmentSwitch in the domainMapping

example as below:

                            {"analyticsBased":false,"caption":"Subscribers who ${belong}to the ${staticSegment}static segment","conditionTemplateId":"staticSegment","domainMapping":{"segmentSwitch":{"cases":[{"expressionTemplate":"${staticSegment}not in profile.segments","segmentValue":"false"},{"expressionTemplate":"${staticSegment}in profile.segments","segmentValue":"true"}],"segmentId":"belong"}},"name":"Static Segment","profile":"Customer","segments":[{"captions":["do not belong","belong"],"segmentId":"belong","segmentKind":"Enum","segmentType":"Boolean","segmentValue":{"booleanValue":true}},{"segmentId":"staticSegment","segmentKind":"DynamicEnum","segmentType":"StaticSegment"}]}
                        

In above example we can see that we have a segmentIdbelong whose value will decide which expressionTemplate will be used in the domain mapping.
We can also override the display value of a Enum by addition captions in the segment definition.
DynamicEnum is a builtin enum for StaticSegment selection.

Audience template with Aggregate condition

Audience condition can make use of aggregates being maintain by Detect. The condition can combine any combination of profile attribute based condition and aggregate based condition.

details of aggregates based UEL expression can be found in Miscellaneous - UEL section.

An example of aggregate based profile condition is as below:

                            {"analyticsBased":false,"caption":"Subscribers who calls back after ${callBackDuration}","conditionTemplateId":"callBack","domainMapping":{"expressionTemplate":"aggregate(numOutgoingCallsBySubscriber[profile.MSISDN], Last, ${callBackDuration.amount}, #{callBackDuration.windowLengthUnit}) == 5"},"name":"Call back duration","profile":"Customer","segments":[{"segmentId":"callBackDuration","segmentKind":"Complex","segmentOption":{"aggregationDurationOption":{"durationStepSizeInMinutes":10}},"segmentType":"AggregationDuration","segmentValue":{"aggregationDurationValue":{"amount":1,"unit":"Months"}}}]},
                        

Below is the UI for the same:

Aggregate based Audience condition.

The segment callBackDuration is of kind Complex, of type AggregationDuration.
callBackDuration.amount will give Window Unit Length for the aggregate query.
callBackDuration.windowLengthUnit will give aggregate window unit i.e., Month, Year, Hour, Minute, or Day.
aggregate(numOutgoingCallsBySubscriber[profile.MSISDN], Last, ${callBackDuration.amount}, #{callBackDuration.windowLengthUnit}), here numOutgoingCallsBySubscriber is name of aggregate, profile.MSISDN is group by attribute, Last is the period.

Metrics

To better breakdown and understand the audience of an event, charts based on different metrics can be added. These chart show histograms on various metrics and these metrices are configured in the metric_categories.json file.

Trigger templates are grouped into named categories based on their business logics as shown below:

                        {"categories":[{"icon":"fa-phone","name":"Voice call metrics","metrics":[{...},{...}]},{"icon":"fa-money","name":"Recharge metrics","metrics":[{...},{...}]}}
                    

Elements inside the metrics are differnt metric , we will try learn how to configure metrices by examples.

metrices categories are configured in etc/model/campaigns/metric_categories.json file.

Profile Attributes Sourced Metric

The Metric charts prepared from Profile Attributes Sourced metrics gets data from profiles and histograms are produced from profile values of each subscriber.

Example Configuration:

                            {"dataType":"String","metricId":"gender","minimumBucketSize":50,"name":"Gender","profileAttributeSource":{"name":"gender"}}
                        

profileAttributeSource selects a profile attribute on which histograms needs to be produced.
name is name of metric.
dataType is data type of X-Axis.
metricId is unique name of metric.
minimumBucketSize is the minimumBucketSize of histograms.

Aggregate Sourced Metrics

The Metric charts prepared from Aggregate Sourced metrics gets data from aggregate and histograms are produced from aggregate values buckets of each subscriber.

Example Configuration:

                            {"icon":"fa-money","metrics":[{"aggregateSource":{"groupByAttributes":[{"name":"MSISDN"}],"name":"topupAmountBySubscriber"},"dataType":"Currency","metricId":"topupAmount","minimumBucketSize":300,"name":"Topup Amount"}],"name":"Recharge metrics"},
                        

aggregateSource as this metric get data from an aggregate.
aggregateSource.groupByAttributes the group by attribute to be passed.
aggregateSource.name is the name of aggregate.

Trigger Event Categories

Campaign trigger profile categories is a list of categories used for defining the templates used to create trigger conditions. Each category has a name and list of templates, each template has defines a list of segments. A segment is a customizable part of the audience condition like segments in audience templates which can be used when forming the template's caption. Each trigger template also defines a domain mapping, the domain mapping may contains a switch/case statement on the segment values, and translates the condition into a UEL expression using profile attributes and aggregates, very similar to audience selection profile categories discussed earlier The former can reference profile attributes, where the latter can reference both the profile attributes and the feed attributes aka tuple's attributes.

Trigger templates are grouped into named categories based on their business logics as shown below:

                        {"categories":[{"icon":"fa-user","name":"Usage-Based Trigger Conditions","templates":[{...},{...}]},{"icon":"fa-crosshairs","name":"Usage threshold Based","templates":[{...},{...}]}}
                    

categories are shown below:

Trigger categories.

Once we select an trigger category, all trigger templetes under that trigger category will shown as below:

List of Trigger templates.

Elements inside the templates are differnt trigger template condition, we will try learn how to configure trigger condition templates by examples.

trigger conditions are configured in etc/model/campaigns/trigger_event_categories.json file.

As trigger templates are very similar to audience template, below section will only discuss about the difference between them.

Simple Trigger Templates

Example:

                            {"analyticsBased":false,"caption":"When the subscriber's current call duration is greater than ${callDuration}","conditionTemplateId":"callDuration","domainMapping":{"expressionTemplate":"duration > ${callDuration}"},"feedsSelector":{"byNames":["Ericsson Usage"]},"name":"Call duration","segments":[{"segmentId":"callDuration","segmentKind":"Primitive","segmentType":"Double","segmentValue":{"doubleValue":1.0}}]},
                        

Here domainMapping.expressionTemplate uses attribute duration, this is an attribute in the realtime feed Ericsson Usage.
feedsSelector select a feed on which domainMapping expression will be evaluated. Feeds can be selected by byNames i.e., a list of feed application names or by byModelNames i.e. a list of feed data models.

Trigger Templates With Aggregate

Example:

                            {"analyticsBased":false,"caption":"When the subscriber's current call duration is greater than ${averageCallDurationPercent}% to his average call duration in the last ${windowLength}hours","conditionTemplateId":"averageCallDuration","domainMapping":{"expressionTemplate":"((duration / aggregate(avgCallDuration[MSISDN], Last, ${windowLength}, Day)) * 100 ) > ${averageCallDurationPercent}"},"feedsSelector":{"byNames":["Ericsson Usage"]},"name":"Average call duration","segments":[{"segmentId":"averageCallDurationPercent","segmentKind":"Primitive","segmentType":"Double","segmentValue":{"doubleValue":2.0}},{"segmentId":"windowLength","segmentKind":"Primitive","segmentType":"Integer","segmentValue":{"integerValue":1}}]},
                        

Trigger Templates With Modifiers

Example:

                            {"analyticsBased":false,"caption":"When a voice transaction using the ${walletName}wallet takes place for a subscriber","conditionTemplateId":"transactionUsingAWallet","domainMapping":{"expressionTemplate":"currentWalletName == ${walletName}"},"feedsSelector":{"byNames":["Voice"]},"modifiers":[{"caption":"and wallet is expiring within ${daysToExpire}day(s)","domainMapping":{"expressionTemplate":"currentWalletDaysToExpire == ${daysToExpire}"},"modifierId":"daysUntilExpirationForWallet","name":"Days until expiration for wallet","segments":[{"segmentId":"daysToExpire","segmentKind":"Primitive","segmentType":"Integer","segmentValue":{"integerValue":2}}]}],"name":"Transaction using the wallet","segments":[{"segmentId":"walletName","segmentKind":"Primitive","segmentType":"String","segmentValue":{"stringValue":"Data200"}}]}
                        

Offer Action Categories

Offer action categories are configured to enable action based offers. These actions are of two types.

offer action categories are configured in etc/model/campaigns/offer_action_categories.json file.

Offer Action templates are grouped into named categories based on their business logics as shown below:

                        {"categories":[{"icon":"fa-sliders","name":"Recharge-Based Actions","templates":[{...},{...}]},}
                    

Action offers are shown below:

Offer actions.

Non-Cummulative Actions

Non-Cummulative Actions are a single action to be performed by subscriber on a real time feed. Detect will track this event in realtime.

Example:

                            {"analyticsBased":false,"caption":"Perform a one-time recharge greater than the target recharge amount","conditionTemplateId":"subscriberRechargeAmount","feedsSelector":{"byNames":["Topup Demo"]},"name":"One-time recharge","targetMetricSegment":{"actionType":"NonCumulative","domainMapping":{"expressionTemplate":"sellAmount"},"name":"Recharge Amount","type":"Double","unit":"#{currencySymbol}","value":{"doubleValue":100}}},
                        

caption is description text to be appreared in the dowpdown list.
conditionTemplateId is a unique name for a offer action template.
feedsSelector select feeds where this action is expected.
name is the name of offer action as it will appear in the dropdown list.
targetMetricSegment contains the action definition.
targetMetricSegment.actionType is type of action, this is an example for NonCumulative action hence only single action needed.
targetMetricSegment.domainMapping is expression for the attribute or a formula, this will be compared with configured threshold value.
targetMetricSegment.name is the of the attribute for UI.
targetMetricSegment.type is the data type of attribute value.
targetMetricSegment.value is the threshold value.

Cummulative Actions

This allows actions to be tracked over multiple transactions done by users, the values are accumulated and thresholds are compared with this cummulative value.

Example:

                            {"analyticsBased":false,"caption":"Perform a cumulative recharge greater than the target recharge amount","conditionTemplateId":"cumulativeSubscriberRechargeAmount","feedsSelector":{"byNames":["Topup Demo"]},"modifiers":[{"caption":"${hasRoaming}roaming enabled","domainMapping":{"expressionTemplate":"profile.roamingEnabled == ${hasRoaming}"},"modifierId":"roamingEnabled","name":"Roaming...","segments":[{"captions":["Does not have","Has"],"segmentId":"hasRoaming","segmentKind":"Enum","segmentType":"Boolean","segmentValue":{"booleanValue":false}}]}],"name":"Cumulative recharge","targetMetricSegment":{"actionType":"Cumulative","domainMapping":{"expressionTemplate":"sellAmount"},"name":"Recharge Amount","type":"Double","unit":"#{currencySymbol}","value":{"doubleValue":100}}}
                        

targetMetricSegment.actionType is Cumulative.
We can optionally have modifier to filter transaction that should be be accumulated.