Campaign Studio
Custom objects
Objects in Campaign Studio contain all of your records. From contacts to companies, objects store all the important information. With custom objects, users can create more many-to-many relational data tables to associate more items, such as products, orders or transactions, households, and more, with either a single contact or multiple contacts. For example, one family can have multiple cars from multiple manufacturers or with different models. This elaborates a 1:many relationship between the custom object (car) and the custom items (BMW, Porsche, etc).
These associations enable you to easily segment and market to your database, based on buying behavior or other interactions with your organization and its offerings.
To get custom objects enabled, contact your Customer Success Managers or Acquia Support.
In the UI, custom objects are located at the following two places based on the processes required for first creating new custom objects and then creating their associated items:
Customer Objects in Settings
Customer Objects in the left navigation pane
Using the custom objects has two primary phases:
Configuration
Ongoing usage
To create custom objects with data fields:
Log in to Campaign Studio.
In the right navigation pane, click Settings > Custom Objects.
Click +New.
The system displays the New Custom Object page.
On the Details tab:
In Name (Singular), specify the singular name for the custom object.
For example, Pet.
In Name (Plural), specify the plural name for the custom object.
The system displays this value as the name of the custom object. For example, Pets.
In Alias, specify the machine name for the object.
Specify a unique identifier to provide an identity to the custom object. If you leave this field blank, the system populates it with a unique value.
In Description, provide information that can help you and other Campaign Studio users to easily identify the purpose of the object.
In Type, select Master (parent) or Relationship (child).
This field indicates how an object record links to another object record, and establishes a relationship similar to that between a parent and a child.
The following example illustrates the one-to-many relationship that custom objects provide. Here, you can add multiple services to a single car that is attached to a contact.
In Campaign Studio, you can create unique identifiers for custom items to link contacts based on unique values and prevent duplication of custom items.
When creating a custom object, you can use one or more data fields as unique identifiers by individually setting the Is unique identifier toggle bar for each data field to Yes.
When you attempt to create a new custom item in the custom object, the custom item creation page displays the data fields that you configured as unique identifiers. In those data fields:
If you add values that do not match with the values of any existing custom item in the custom object, Campaign Studio creates a new custom item.
If you add values that match with the values of any existing custom item in the custom object, Campaign Studio considers it as a modification to the existing custom item and updates or overrides the data of the custom item, preventing duplication of custom items.
If a custom object configured with unique identifiers contains any custom item, you cannot modify the unique identifiers for that custom object. If you attempt to modify the unique identifiers, Campaign Studio displays a message indicating that the modification is not possible.
For API integrations, Campaign Studio returns the 400 status code for an invalid unique identifier value.
To modify an existing unique identifier for a custom object, create a custom object, import all custom items to the new custom object, and delete the original custom object.
The unique identifier feature can also be used when importing custom items through CSV file uploads or through the API.
Custom items can be linked to contacts and custom items of another custom object within the instance. For more information, see Associating contacts with custom objects.
An item is an instance of a custom object that defines something concrete. Each item may contain values for the fields defined in the custom object.
For example:
Custom object: Products
Data fields: Category, Type, Color
Item name: SKU1234
Properties on the item: Outerwear, Jacket, Yellow
After creating the custom object and its data fields, you must create definite custom items that can hold values for all such fields. Any custom item always has a Name field. Hence, you do not have to create it as a custom data.
To create a custom item:
In the left navigation pane, expand Custom Objects and select the custom object you want to add a custom item to.
Click +New.
In Name, specify a name for the custom item.
Every custom item has a required name field. You do not need to create this as a custom field for the object.
Specify appropriate values in the unique identifier-enabled data fields and all the other data fields.
In each data field, ensure that you specify the value based on the data type of that field. For example, specify a text value in the Text data field.
Users can directly import a .csv file with item data. Users can easily get the existing data from other systems into Campaign Studio by exporting that data to a .csv file and then importing it into Campaign Studio.
To import a list of items:
In the left navigation pane, expand Custom Objects and select the custom object you want to import custom items to.
In the top right corner, click the drop-down next to +New.
Click Import.
Choose the file with your item data.
Adjust the value in Delimiter, Enclosure, and Escape.
Click Upload.
Associate the column headers in your .csv file to the attributes for the object, and click Import.
For information on exporting custom items, see Exporting items.
Once you have created custom objects, fields, and items, you need to associate contacts with the custom objects.
It is possible to:
Manually link a contact with a custom item associated with the custom object.
Associate a custom object with a contact via a campaign. For more information, see Link contact with custom_object.
Leverage APIs to associate contacts with custom objects.
For assistance with implementing APIs for your instance, contact your account manager.
To manually associate a contact with custom objects:
Log in to Campaign Studio.
In the left navigation pane, click Contacts.
Click the contact that you want to associate with the custom object.
On the contact details page, locate the tabs menu and click the tab for the custom object.
To link the existing custom objects to the contact:
Click Link Existing.
In the resulting dialog box, select the existing item that you want to link to the contact.
You must select an individual row and open the drop-down for each row.
To create and link a new custom object to the contact:
Click +Link new.
Create an item and link it to the contact.
Campaign Studio has multiple custom object specific actions and conditions available in campaigns. For example:
For more information, see Campaigns.
With this campaign action, you can link the contact that comes through the campaign workflow with a custom item. Campaign Studio creates separate campaign actions for all the custom objects.
For example, if you have created a custom object called Car:
This campaign action has the following options:
Name: Specify the name of the campaign action accordingly.
Execute this event: Select the time when you want to execute this action.
Link with item: Select the custom item to which you want to link the contact.
Unlink from item: (Optional) Select the time custom item from which you want to unlink the contact.
With this campaign condition, you can define conditions for each custom object. You can set TRUE or FALSE conditions based on the custom item field values.
This campaign condition has the following options:
Name: Specify the name of the campaign action accordingly.
Execute this event: Select the time when you want to execute this condition.
Field: Select a data field from the available options.
Operator: Select an operator from the available options.
Value: Select a custom item for the data field.
You can use custom item values in the email tokens. As a single contact can have multiple custom items, the email token must specify one or more specific custom items that must be used. To show the custom item values to a contact by email, ensure that you link the custom item or items to that contact. For more information, see Associating contacts with custom objects and Email builder.
To use custom objects in email tokens in the email builder:
Log in to Campaign Studio.
Navigate to Channels > Emails.
Click +New and select what type of email you want to create.
On the Templates tab, select the email template that you want to use, and then click Builder.
Navigate to the staging area on the left and add a Text content block.
Alternatively, if a Text content block already exists in the staging area, click the same to load the text editor toolbar. For more information, see Text block.
Click Merge tags to load all the tags.
The system displays all the custom objects along with the associated data fields.
Select one of the available custom objects. For more information, see Sample token.
(Optional) Update the token, if required.
Click Apply to save the token.
Campaign Studio{custom-object=product:color | where=segment-filter | order=latest | limit=1 | default= | format=default}The options in this token are:
custom-object: A static keyword that ensures that the token is replaced.
product: The alias of a specific custom object.
color: The alias of a specific data field associated with the custom object.
where: The where condition that notifies the system about the linked custom items whose values must be considered.
segment-filter: A static keyword that notifies about the custom items. That is the default option for the preceding where clause. This means that the query considers the first segment of the segment email or the first campaign source segment of a campaign email, takes all the custom object related filters from it, and builds the where conditions from them.
If multiple segments are used for segment emails or campaign sources, each segment must have identical filters for custom objects. Only the filters of the first segment are considered during token replacement on email send.
Do not use OR conditions in the source emails.
Do not use include or exclude segment membership filters as the token replacement does not search all included or excluded segments. Only the root level segment filters are searched.
order: The sorting order to display multiple items if the where condition returns multiple values. The default option is .
After you create custom objects, the system adds each data field associated with a custom object as new filter options in segments. Contacts that are available in a segment are the ones who have a custom item linked with the value in the file that you are looking for. Segments consider custom items that are directly linked to the contact. For more information, see: Segments.
To use custom objects in segments:
Log in to Campaign Studio.
Navigate to Segments.
Click +New.
On the Filters tab, select the data field associated with a custom object that you have created.
Select the operator and specify the value for the data field.
Click Save & Close.
To create better segments and target contacts on a more specific level, you can do the following:
Associate a contact with a custom item that belongs to a custom object.
For example:
contact: Jane
custom item 1: Order 123
custom object 1: Orders
Associate that custom item with another custom item that belongs to another custom object.
For example:
custom item 1: Order 123
custom object 1: Orders
custom item 2: Toaster
custom object 2: Products
Create a data field for the second custom object.
For example:
data field: Price
custom object: Products
Create segments to filter data that belongs to the second custom object.
For example:
Segment filter: Products: Price > 500
Based on these examples, if the Price of Toaster is more than 500, the segment filter evaluates that Toaster is linked via Order 123 with Jane and adds Jane to the segment.
The example also applies to dynamic web contents.
Similar to segments, Campaign Studio adds new filter options to dynamic web content for each data field associated with a custom object. For more information, see Dynamic web content.
To use custom objects in dynamic web content:
Log in to Campaign Studio.
Navigate to Components > Dynamic Content.
Click +New.
On the Details tab, specify the relevant information.
Set the Is campaign based toggle bar on the right menu to No.
The system displays the Filters tab.
On the Filters tab, select the data field associated with a custom object that you have created.
Similar to segments, select the operator and specify the value for the data field.
Click Save & Close.
After you have robustly implemented custom objects in your Campaign Studio instance, you can leverage various reporting dashboards to analyze the performance of your campaigns and optimize your marketing strategies. For more information, see Reports.
Log in to Campaign Studio.
Navigate to Reports.
Click +New.
On the Details tab:
In Name, enter the name of the report you want to create for the custom object.
In Data Source, select one of the available custom objects.
In Description, enter a description and adjust the report settings as needed.
On the Data tab:
In Columns, select the column or columns you want to view in the report.
In Order, select a column and the corresponding sort order, Ascending or Descending.
In Filters, select one or more columns by which you want to group similar data.
(Optional) On the Schedule tab, configure the fields based on your requirements.
Click Save & Close.
You can view statistics and details for the data fields and custom items associated with a custom object. These are viewable at two different places in the system.
To view details and statistics for individual custom objects:
Log in to Campaign Studio.
In the right navigation pane, click Settings > Custom Objects.
The system displays a list of all the custom objects.
Click the name of the custom object for which you want to view the details.
The system displays the custom object details page.
To view details and statistics for a custom item of a custom object:
Log in to Campaign Studio.
In the left navigation pane, expand Custom Objects and select the custom object for which you want to view the custom item details.
Click the name of the custom item for which you want to view the details.
The system displays the custom item details page.
Campaign Studio supports exporting the details of custom items in the CSV file format. In the export process, you first send the CSV file download link to the email address registered with your Campaign Studio user profile, and then click the download link from your mailbox to download the zipped CSV file.
Log in to Campaign Studio.
In the left navigation pane, click Custom Objects and select the object from which you want to export custom items.
On the Custom Objects details page, click the drop-down arrow next to +New.
Click Export As CSV.
Campaign Studio displays a message confirming that the CSV file is sent to the email address of the currently logged in user.
In your mailbox, locate the email containing the CSV file download link.
Click the download link.
The system downloads the zipped CSV file containing the details of custom items.
Unzip and open the CSV file.
The CSV file displays the details of custom items in the following columns:
Column | Description |
|---|---|
Custom item ID | The ID number of the custom item. |
Custom item name | The name of the custom item. |
# | The ID number of the custom field. |
Linked contact ID | Comma-separated ID numbers of the contacts linked to the custom item. One cell can display a maximum of 5000 contacts. If the number of linked contacts exceeds 5000, the remaining contacts are displayed in additional rows containing up to 5000 contacts each. |
Master/Parent:
Car |
|---|
Relationship/Child: | Service records for the car |
In Category, select one of the existing categories or create a category.
Set the Published toggle bar to Yes or No.
An unpublished object is not usable in other parts of Campaign Studio.
On the Fields tab:
In Add a new field, select one of the available data fields.
When possible, avoid using the Text data field. Using the correct data fields helps with data quality and performance.
The available data fields are:
Data field | Description |
|---|---|
Country list | To automatically generate a list of countries based on Campaign Studio’s default list. |
Date | To select the date only. |
Datetime | To select the date and time. |
To validate the value in this field to be an email address. | |
Hidden | To hide internal values from the user interface. |
Number | To store only numeric values. |
Phone number | To validate the value to be in a phone format. |
Select | To specify potential values for this field that remain consistent across items. A maximum of one value is saved on a record. |
Multiselect | To specify potential values for this field that remain consistent across items. Multiple values may be saved on a record. |
Text | To store one line text values with a maximum length of 255 characters. |
Textarea | To store multi-line text values. |
URL | To validate the value to be a URL. |
After your select a data field, the system displays a dialog box:
Based on the selected data field, the fields in the modal differ.
On the General tab, provide relevant information in the fields.
Set the Is unique identifier toggle bar to YES to use this data field as a unique identifier. For more information, see Using unique identifiers.
When you set this toggle bar to YES, Campaign Studio sets the Required toggle bar on the Validation tab to YES as the data field becomes mandatory.
On the Validation tab, do one of the following:
If the data field is mandatory, set the Required toggle bar to YES.
If the data field is optional, set the Required toggle bar to NO.
Click Save & Close.
Repeat the same steps until you add all the data fields for this object.
Click Save & Close.
After you create a custom object, the system displays the plural name of the object in Custom Objects in the left navigation pane.
In Category, select one of the existing categories or create a category.
Set the Published toggle bar to Yes or No.
Acquia recommends that you unpublish unused custom items rather than deleting them. Deleting custom items also deletes the tracking data for reports.
Click Save & Close.
The system creates a new custom item only if the values specified in the unique identifier-enabled data fields do not already exist in the system. Otherwise, the system considers the custom item as a modification to the existing custom item and updates or overrides the original data, preventing duplication of custom items.
This process is similar to the previous step of creating a custom item in the left navigation menu.
You must manually select the data from the drop-down of each field.
After associating the custom item with the contact, you can view its details on that custom object’s tab. See the Products tab in the following example:
latest: The order by clause.
limit: The maximum number of custom items. The default limit is 1 even if no limit is provided. If you increase the limit to more than 1, the values are separated by comma.
default: The default text value if no custom item was found. The
probable values are [default|or-list|and-list|bullet-list|numbered-list].
format: The format to display the values. Multiple values are displayed as a separated list. The available formats are:
default: A comma-separated list used by default.
or-list: A comma-separated list with the last value divided by or.
and-list: A comma-separated list with the last value divided by and.
bullet-list: A list where a bullet is used as a list prefix.
ordered-list: A list where a number is used as a list prefix.
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Master/Parent:
Car |
|---|
Relationship/Child: | Service records for the car |
In Category, select one of the existing categories or create a category.
Set the Published toggle bar to Yes or No.
An unpublished object is not usable in other parts of Campaign Studio.
On the Fields tab:
In Add a new field, select one of the available data fields.
When possible, avoid using the Text data field. Using the correct data fields helps with data quality and performance.
The available data fields are:
Data field | Description |
|---|---|
Country list | To automatically generate a list of countries based on Campaign Studio’s default list. |
Date | To select the date only. |
Datetime | To select the date and time. |
To validate the value in this field to be an email address. | |
Hidden | To hide internal values from the user interface. |
Number | To store only numeric values. |
Phone number | To validate the value to be in a phone format. |
Select | To specify potential values for this field that remain consistent across items. A maximum of one value is saved on a record. |
Multiselect | To specify potential values for this field that remain consistent across items. Multiple values may be saved on a record. |
Text | To store one line text values with a maximum length of 255 characters. |
Textarea | To store multi-line text values. |
URL | To validate the value to be a URL. |
After your select a data field, the system displays a dialog box:
Based on the selected data field, the fields in the modal differ.
On the General tab, provide relevant information in the fields.
Set the Is unique identifier toggle bar to YES to use this data field as a unique identifier. For more information, see Using unique identifiers.
When you set this toggle bar to YES, Campaign Studio sets the Required toggle bar on the Validation tab to YES as the data field becomes mandatory.
On the Validation tab, do one of the following:
If the data field is mandatory, set the Required toggle bar to YES.
If the data field is optional, set the Required toggle bar to NO.
Click Save & Close.
Repeat the same steps until you add all the data fields for this object.
Click Save & Close.
After you create a custom object, the system displays the plural name of the object in Custom Objects in the left navigation pane.
In Category, select one of the existing categories or create a category.
Set the Published toggle bar to Yes or No.
Acquia recommends that you unpublish unused custom items rather than deleting them. Deleting custom items also deletes the tracking data for reports.
Click Save & Close.
The system creates a new custom item only if the values specified in the unique identifier-enabled data fields do not already exist in the system. Otherwise, the system considers the custom item as a modification to the existing custom item and updates or overrides the original data, preventing duplication of custom items.
This process is similar to the previous step of creating a custom item in the left navigation menu.
You must manually select the data from the drop-down of each field.
After associating the custom item with the contact, you can view its details on that custom object’s tab. See the Products tab in the following example:
latest: The order by clause.
limit: The maximum number of custom items. The default limit is 1 even if no limit is provided. If you increase the limit to more than 1, the values are separated by comma.
default: The default text value if no custom item was found. The
probable values are [default|or-list|and-list|bullet-list|numbered-list].
format: The format to display the values. Multiple values are displayed as a separated list. The available formats are:
default: A comma-separated list used by default.
or-list: A comma-separated list with the last value divided by or.
and-list: A comma-separated list with the last value divided by and.
bullet-list: A list where a bullet is used as a list prefix.
ordered-list: A list where a number is used as a list prefix.
If this content did not answer your questions, try searching or contacting our support team for further assistance.