Information for: DEVELOPERS   PARTNERS   SUPPORT

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.

Note

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:


Creating custom objects with data fields

To create custom objects with data fields:

  1. Log in to Campaign Studio.

  2. In the right navigation pane, click Settings > Custom Objects.

    settings custom object

  3. Click +New.

    The system displays the New Custom Object page.

    new custom object

  4. On the Details tab:

    1. In Name (Singular), specify the singular name for the custom object.

      For example, Pet.

    2. 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.

    3. 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.

    4. In Description, provide information that can help you and other Campaign Studio users to easily identify the purpose of the object.

    5. 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.

      Master/Parent: Car
      Relationship/Child: Service records for the car
    6. In Category, select one of the existing categories or create a new category.

    7. Set the Published toggle bar to Yes or No.

      Note

      An unpublished object is not usable in other parts of Campaign Studio.

  5. On the Fields tab:

    1. In Add a new field, select one of the available data fields.

      Note

      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.
      Email 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:

      custom objects general tab

      Note

      Based on the selected data field, the fields in the modal differ.

    2. On the General tab, provide relevant information in the fields.

    3. 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.

    4. 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.
    5. Click Save & Close.

    6. Repeat the same steps until you add all the data fields for this object.

  6. Click Save & Close.

    After you create a custom object, the system displays the plural name of the object in Customer Objects in the left navigation pane.

    marketing custom objects

Using unique identifiers

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 setting the Is unique identifier toggle bar to Yes on the General tab.

If you create a custom item with one or more unique identifier values and those values do not exist in the system, the system creates a new custom item. However, if the unique identifier values already exist in the system, 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.

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.

Creating items

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.

Creating items manually

To create a custom item:

  1. In the left navigation pane, expand Custom Objects and select the custom object you want to add a custom item to.

  2. Click +New.

  3. In Name, specify a name for the custom item.

    Note

    Every custom item has a required name field. You do not need to create this as a custom field for the object.

    custom item

  4. Specify appropriate values in the unique identifier-enabled data fields and all the other data fields.

    Note

    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.

  5. In Category, select one of the existing categories or create a new category.

  6. Set the Published toggle bar to Yes or No.

    Important

    Acquia recommends that you unpublish unused custom items rather than deleting them. Deleting custom items also deletes the tracking data for reports.

  7. 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.

Importing items

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:

  1. In the left navigation pane, expand Custom Objects and select the custom object you want to import custom items to.

  2. In the top right corner, click the drop-down next to +New.

  3. Click Import.

    import export custom item

  4. Choose the file with your item data.

  5. Adjust the value in Delimiter, Enclosure, and Escape.

  6. Click Upload.

  7. Associate the column headers in your .csv file to the attributes for the object, and click Import.

    custom_objects_32

For information on exporting custom items, see Exporting items.

Associating contacts with custom objects

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. To use APIs, open a support ticket.

Manually connecting to contacts

To manually associate a contact with custom objects:

  1. Log in to Campaign Studio.

  2. In the left navigation pane, click Contacts.

  3. Click the contact that you want to associate with the custom object.

  4. On the contact details page, locate the tabs menu and click the tab for the custom object.

  5. To link the existing custom objects to the contact:

    1. Click Link Existing.

      custom objects manual linking

    2. In the resulting dialog box, select the existing item that you want to link to the contact.

      custom_objects_9

      Note

      You must select an individual row and open the drop-down for each row.

  6. To create and link a new custom object to the contact:

    1. Click +Link new.

    2. Create a new item and link it to the contact.

      Note

      • This process is similar to the previous step of creating a new 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:

      custom_objects_10

Using custom objects in campaigns

Campaign Studio has multiple custom object specific actions and conditions available in campaigns. For example:

For more information, see Campaigns.

custom_object field value

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.

custom object campaign condition 1

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.

Using custom objects in email tokens

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:

  1. Log in to Campaign Studio.

  2. Navigate to Channels > Emails.

  3. Click +New and select what type of email you want to create.

  4. On the Templates tab, select the email template that you want to use, and then click Builder.

  5. 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.

    custom objects merge tags

  6. Click Merge tags to load all the tags.

    The system displays all the custom objects along with the associated data fields.

    custom_objects_24

  7. Select one of the available custom objects. For more information, see Sample token.

  8. (Optional) Update the token, if required.

  9. Click Apply to save the token.

Sample token

{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.

    Warning

    • 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 latest.

  • 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.

Using custom objects in segments

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:

  1. Log in to Campaign Studio.

  2. Navigate to Segments.

  3. Click +New.

  4. On the Filters tab, select the data field associated with a custom object that you have created.

    custom objects segments

  5. Select the operator and specify the value for the data field.

  6. 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.

Note

The example also applies to dynamic web contents.

Using custom objects in dynamic web content

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:

  1. Log in to Campaign Studio.

  2. Navigate to Components > Dynamic Content.

  3. Click +New.

  4. On the Details tab, specify the relevant information.

  5. Set the Is campaign based toggle bar on the right menu to No.

    The system displays the Filters tab.

  6. On the Filters tab, select the data field associated with a custom object that you have created.

    custom objects dynamic content

  7. Similar to segments, select the operator and specify the value for the data field.

  8. Click Save & Close.

Reporting

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.

Building reports for custom objects

  1. Log in to Campaign Studio.

  2. Navigate to Reports.

  3. Click +New.

  4. On the Details tab:

    custom objects reports

    1. In Name, enter the name of the report you want to create for the custom object.
    2. In Data Source, select one of the available custom objects.
    3. In Description, enter a description and adjust the report settings as needed.
  5. On the Data tab:

    1. In Columns, select the column or columns you want to view in the report.
    2. In Order, select a column and the corresponding sort order, Ascending or Descending.
    3. In Filters, select one or more columns by which you want to group similar data.
  6. (Optional) On the Schedule tab, configure the fields based on your requirements.

  7. 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.

Viewing details for a custom object

To view details and statistics for individual custom objects:

  1. Log in to Campaign Studio.

  2. In the right navigation pane, click Settings > Custom Objects.

    The system displays a list of all the custom objects.

  3. Click the name of the custom object for which you want to view the details.

    The system displays the custom object details page.

    custom objects details

Viewing details for a custom item

To view details and statistics for a custom item of a custom object:

  1. Log in to Campaign Studio.

  2. In the left navigation pane, expand Custom Objects and select the custom object for which you want to view the custom item details.

  3. Click the name of the custom item for which you want to view the details.

    The system displays the custom item details page.

    custom objects item details

Exporting items

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.

  1. Log in to Campaign Studio.

  2. In the left navigation pane, click Custom Objects and select the object from which you want to export custom items.

  3. On the Custom Objects details page, click the drop-down arrow next to +New.

  4. 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.

  5. In your mailbox, locate the email containing the CSV file download link.

  6. Click the download link.

    The system downloads the zipped CSV file containing the details of custom items.

  7. 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.