Utilizing the Audiences feature requires several steps to create and send audiences to downstream systems, e.g. Facebook, Yahoo!, Google Analytics, Nielsen. The high-level steps of how and what data is available for defining attributes, how to utilize the attributes to create audiences, and how to select the audiences to send to the downstream systems are described in the article Building an Audience Workflow.
This article dives into the details of the second of those steps, Creating Attribute Builder apps:
- Creating an Attribute Builder app
- Select the needed datasets
- Define an Attribute Builder process
- Testing the Attribute Builder app
- Activating the Attribute Builder app
Creating an Attribute Builder app
The Audience Apps page is available from the main menu () and then select the submenu item Apps under Audience or, if already within the Audience module, via the apps icon (
).
There are three layers of attribute hierarchy to keep in mind:
- App - An attribute app is at the highest level of grouping, e.g. Brand Attr App, seen as the rounded squares below. Inside an app, we will have one or more attribute groups/processes.
- Group - An attribute group is the next level and created within an app via a process, e.g. Brand, Brand Purchased, seen as the circles below. One or more groups/processes will be within an app. Within a group/process we will define many attribute values.
- Values - The attribute values are the exact names given for a defined condition, e.g. LG, Sony, Microsoft, seen below in the tables within the circles. Each attribute group/process will have several or many attribute values. These attribute values are then used to build audiences.
As noted in Audience Solution Best Practices, there is a needed balance between usability/organization of attribute apps and attribute groups/processes versus performance of the app jobs. If needing to add a new set of attributes it may be appropriate that only a new attribute group, within an existing attribute app, needs to be added instead of an entirely new attribute app.
If/when a new attribute app does need to be created then simply click the green plus icon (). Doing so will bring up the below pop-up allowing you to create the attribute builder app.
The following fields need to be completed to create a new attribute app:
- Name - The name should be descriptive of the set of attribute groups that are going to be created in the app. The name must be unique across all apps within the Syntasa platform.
- Key - The key value you typically can leave as is since it is auto-generated from the name of the app. It too needs to be unique across all apps. The key value cannot be changed after the app is created.
- App Prefix - The app prefix is the abbreviated value used to identify the app's datasets and tables within the workflow canvas. This typically can be left as-is and can be altered after the app has been created.
- Copy an Existing App - Typically not used in the context of attributes because each attribute app should be creating unique attribute groups and attribute values. If this were used, starting a new attribute app based on an existing one, then every process and value would need to be updated.
- Template - This should be selected as "Attribute Builder" for our purposes of creating a new attribute builder app.
- Description - Informational note describing the intent and use of the app.
- Data Layer - As noted in the article Building an Audience Workflow, each organization typically needs a single data layer, but if there are multiple then select the corresponding data layer the attributes are to be built on. Remember that all attribute apps on the same data layer will generate and write results to the same, shared Attribute Result Tables.
- Default Partition Scheme - This will be selected automatically based on the setting of the selected data layer.
-
Override Icon - The icon of the app card can be altered from the default (
). This can also be changed later from the app's overview screen.
Initially, the app will look like the below with no data layer input stores (), one unconfigured attribute builder process (
), and the attribute result table (
), which represents the three result tables as explained in Attribute Result Tables.
As seen on the element selection on the left, an attribute builder app has two types of elements that can be added to the app: one type of input store, data layer; and one type of process, attribute builder.
Each element type can have multiple instances within the same app, but should only be added as needed, e.g. while a data layer may have several datasets available, you should only drag on those datasets needed to build the attributes.
Select the needed datasets
Drag and select the dataset(s)
-
Unlock the app - Before editing an app you need to click the lock/unlock icon (
) to unlock the workflow canvas.
- Drag the store - The only available store seen on the left is Data Layer. Drag the needed number of datasets, which are defined in the Data Layer, onto the workflow canvas. Initially, this new node will be gray in color.
-
Select the dataset - Click on the store node(s) dragged onto the workflow canvas. The bottom panel will have the Dataset option selected. The Data Layer option will be preselected as the value chosen when the app was created. You then need to choose the desired dataset and click the green checkbox (
).
Connect the dataset(s)
The last step for the dataset is to connect it to the needed attribute builder group/process by dragging between and connecting the dots between the two nodes.
As we will see later, a single dataset node can connect to multiple attribute builder group/processes and/or multiple dataset nodes can connect to a single attribute builder group/process.
Define an Attribute Builder process
Process level settings
Now that you have connected the dataset(s) to the attribute builder process, the process can now be configured. Click on the process node, the bottom panel will have the Parameters option selected.
This the primary area for configuration and definition of attributes. Below describes the individual fields and settings that can be set for an attribute group/process.
Group Name
The group name is a descriptive name for the set of attribute values defined in the process. From the example above, an attribute group may be Brand, Brand Purchased, Product, Product Purchased.
The group name should be a unique value across all attribute groups for the data layer. Remember there can be multiple attribute groups within a single app, but also multiple attribute apps, which have their own attribute groups/processes. Since all attribute apps for a single data layer write results to the shared attribute result tables, the attribute group name should be unique across all attribute groups/processes for the data layer.
Recency
Recency defines the number of days that should be considered for the calculation of the attribute values. If set to 1, the condition of the attribute value must be met over the past 1 day; if set to 3, the condition of the attribute value must be met over the past 3 days.
For example, an attribute group may be "Brand Purchased 7 Days" to capture visitors that have purchased specific brands over the past 7 days. In order to produce these attribute values, the recency value would need to be set to 7.
Other attribute examples using different values of the recency field can be found in Sample Attributes.
Auto Extract
The auto-extract option allows for attribute values to be automatically generated from distinct values from the selected source column instead of manually defining each attribute value.
For example, if an attribute group Brand can be derived from a single column in the selected dataset then turning this option on would automatically extract the distinct values and create individual attribute values for each. This includes new values that may appear in future updates to the source dataset.
But if the conditions for the attribute values are more complex and, for example, are met with a combination of columns meeting certain criteria then it is best to leave this option off and thus be able to define the attribute values individually utilizing the condition builder explained below.
Attribute values
Now that the attribute group name and recency value have been entered, the individual attribute values need to be defined. The input of attribute values differs if the auto-extract option is on or off.
Auto Extract
When the auto-extract functionality is enabled the fields Source Column, Regex (optional), and Frequency need to be filled:
- Source Column - Select the column of the connected dataset from where the attribute values are to be extracted.
- Regex - Optional field to locate the values to be extracted from the selected source column. If the attribute values are to be exactly as seen in the source column then this field should be left blank.
-
Frequency - This is an additional factor for the attribute value that defines the minimum number of occurrences that must appear for a given visitor, within the date range defined by the recency value, in order for the attribute condition to be met. The value should be an integer equal to or greater than one.
For example, the value of frequency is set to 5 and the value of recency is set to 3. In order for a given visitor to qualify for the said attribute value, that unique visitor must have at least five occurrences of matching the criteria within the last three days.
User-defined values
When the auto-extract functionality is disabled each attribute value needs to be given a Name, the Frequency needs to be set, and the criteria for meeting the condition of the attribute is to be defined:
The conditions here can be simple using a single pattern match in a single column or more complex combining ANDs and ORs across multiple columns to define when an attribute is met. Several examples of attributes can be found in Sample Attributes.
Switch to code & Test
Switch to Code with Test feature allows users to execute their query and evaluate its performance by estimating the number of records that will fall under the specified attribute. This feature is particularly useful for users who want to understand the impact of their query before fully committing to it, ensuring that they can make informed decisions based on the estimated results. This feature allows users to gain valuable insights into the dataset and refine their queries to better meet their analysis needs.
Confirm process settings
Once the attribute builder process is configured click the green checkbox () to confirm the inputted values of the process. Once this is checked the configuration panel of the process will close. If needing to open the panel again then click on the process node again.
After the checkbox is clicked, the process node on the workflow canvas will be one of two colors indicating the status of the process's configuration. If all configuration has passed validations the node will be a light green (); if the configuration needs to be reviewed and updated then the node will be yellow (
).
Testing the Attribute Builder app
Once the attribute group/process(es) has been configured the attribute builder can be tested within the development section of the app. It is best practice to test, especially a new app, in dev before activating the app into the production section of the app.
There are a few steps detailed below that can be done in multiple iterations as changes are made while building or altering an app to ensure that the desired output is achieved.
If making small changes or additions are made to an existing app, the testing within the development section of the app may be skipped at the user's discretion.
Save & Lock
Before being able to execute the attribute conditions, and therefore preview the desired attribute values, the app needs to be locked. To save and lock the app click either the Save & Lock button () or the Save button (
) followed by the lock icon (
).
Run the process(es)
Once the app is successfully saved and locked the process(es) can be executed. To quickly run all processes within the app then click the Run button (). If wanting to run selected processes then shift-click the process nodes that want to be run and then click the Run button.
The job kicked off by default will run with a date range of "Last 1 day". If you need to run the run for a different date or a date range then click on down arrow next to the Run button and then click Configure Run (). Instead of kicking off the job immediately, as does simply clicking the Run button, this will bring a pop-up allowing the date range to be altered. Once set to the desired setting click Save + Execute (
).
Check activity
Once the job(s) are running the activity icon () in the top right of the workflow canvas will update to (
) indicating there is a job running. Clicking on this tab will open the activity panel on the right. Clicking the right arrow (
) will expand the job and display the details steps. Each process (or all) that were selected to run will show as an individual step, e.g. Product.
More details of monitoring and reviewing job step details and statuses can be found in Operations - Activity Logs.
Check results
After the attribute builder process(es) has completed successfully click on the attribute result table node (). The bottom panel will open where you can preview the results in the three tables, results, metadata, and metrics, as explained in Attribute Result Tables.
Activating the Attribute Builder app
When the attribute builder app is configured to satisfaction it can then be activated into the production section of the app by clicking the Activate button (). This will use the current version of the app in the development section of the app to update/overwrite the current copy of the app in production or create the initial production version if one does not currently exist.
After the app is in the production section of the app the job(s) needs to be run as explained in Run the process(es) above so that results are created in the production version of the attribute result tables. The production attribute results are used to build audiences as explained in Building and Audience Workflow.