Information for: DEVELOPERS   PARTNERS

Custom objects

Objects in Campaign Studio contain all of your records. From contacts to companies, objects store all the important information. Custom objects enable users to 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.

Using the custom objects has two primary phases:

  1. Configuration
  2. Ongoing usage

Creating custom objects with data fields

To create custom objects with data fields:

  1. Log in to Campaign Studio and go to Settings > Custom Objects.

    custom_objects

  2. Click New.

  3. Under Details, define the following:

    • Name (Singular): Specify the singular name for the custom object. For example, Pet.

    • Name (Plural): Specify the plural name for the custom object. For example, Pets. The system displays this value as the name of the custom object.

    • Alias: This is the machine name for the object. Specify a unique identifier to identify the custom object. If you leave this as blank, the system populates this field with a unique value.

    • Description: Add information that can help you and other Campaign Studio users in your organization easily identify the purpose of the object.

    • Type: Select either 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.

      For example,

      Master/Parent: Car

      Relationship/Child: Service records for the car

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

    • Category: Select one of the existing categories or create a new category.

    • To publish the custom object, set the Published toggle bar to Yes. Alternatively, set it to No. An unpublished object is not usable in other parts of Campaign Studio.

    custom_objects_1

  4. Under Fields, define the following:

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

      Note

      Whenever possible, use field types other than Text. Using the correct field types helps with data quality and performance.

      The available options are listed as follows:

      • Country list: Generates list of countries automatically, based on Campaign Studio’s default list.
      • Date: Allows users to select date only.
      • Datetime: Allows users to select date and time.
      • Email: Validates the value in this field to be an email address.
      • Hidden: Hides internal values from the user interface.
      • Number: Stores only numeric values.
      • Phone number: Validates the value to be in a phone format.
      • Select: Allows you to specify potential values for this field which will remain consistent across items. A maximum of one value is saved on a record.
      • Multiselect: Allows you to specify potential values for this field which will remain consistent across items. Multiple values may be saved on a record.
      • Text: Stores one line text values with a maximum length of 255 characters.
      • Textarea: Stores multi line text values.
      • URL: Validates the value to be a URL.

      custom_objects_2

    2. Specify the relevant information. Based on the selected data type, the fields in the modal differ.

      custom_objects_3

    3. Click Save & Close.

    4. Repeat the same process till you have added all the data fields for this object.

  5. Click Save & Close.

Once you have created a custom object, the same appears in the left side navigation pane under Custom Objects.

custom_objects_4

Creating items

An item is an instance of a custom object and 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

Once you have created a custom object and data fields for the object, you must create definite custom items that can hold values for all such fields. Any custom item will always have a Name field. Hence, you don’t have to create it as a custom data.

Creating items manually

To create a custom item:

  1. Locate Custom Objects in the marketing toolbar on the right side, select the custom object for which you want to add a custom item, and click New.

    Alternatively, go to Settings > Custom Objects and select the object you’d like to add an item to. In the drop-down menu next to the Edit option, select Create new custom item.

    custom_objects_5

  2. In Name, specify the name for the custom item. Every custom item has a required name field. You don’t need to create this as a custom field for the object.

    custom_objects_6

  3. For all the other data fields, specify the appropriate values. For any data field, the specified value must match the corresponding data type.

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

  5. To publish the custom item, set the Published toggle bar to Yes. Alternatively, set it to No.

    Note

    It is recommended that you don’t delete unused custom items but rather unpublish such items. If you delete, you’ll lose all tracking data for future reports.

  6. Click Save & Close.

Importing items

If you don’t want to manually create each item, you can directly import a .csv file with the item data. This is an easier and less time consuming process. This process is particularly effective if you already have existing data in another system. In such a case, you can just export that data into a CSV file and import the same file to Campaign Studio.

To import a list of items:

  1. Go to the custom object’s item list.

  2. In the top right corner, open the drop-down option next to +New and select Import.

    custom_objects_30

  3. Select the file with your item data, specify the delimiter, enclosure, escape characters, and click Upload.

    custom_objects_31

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

    custom_objects_32

Associating contacts with custom objects

Once you have created custom objects, fields, and items, you need to associate contacts with custom objects. Note that you can link a contact with a custom item associated with the custom object manually.

Note

To associate a contact with custom objects manually:

  1. Log in to Campaign Studio and go to Contacts.

    custom_objects_7

  2. Select the contact that you want to associate with the custom object.

  3. Navigate to the bottom of the page to locate the custom object that you have created earlier.

    custom_objects_8

  4. To link the contact with an existing item; which you created earlier, click Link Existing and select the item to which you want to link the contact. Note that you must select an individual row and open the drop-down for each row.

    custom_objects_9

    Alternatively, click Link new to create a new item. This step is similar to the previous step of creating a new custom item.

Once you have associated the custom item with the contact, you can view it below that custom object’s tab. For example, Products.

custom_objects_10

Using custom objects in campaigns

Campaign Studio has multiple custom object specific actions and conditions related to campaigns:

<Custom_object> field value

This campaign condition allows you to define conditions for each custom object. You’ll be able to set TRUE/FALSE conditions based on the custom item field values.

custom_objects_13

custom_objects_14

This campaign condition has the following options:

  • Name: This is simply a name for the campaign condition.
  • Execute this event: Select the time when you want to execute this condition.
  • Field: Select a data field from the available options.
  • Operator: Select one of the available options as operators.
  • 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 the specific custom item(s) which must be used. If you want to show the custom item values to a contact via email, ensure that you link the custom item(s) to that contact. For more information, see Associating contacts with custom objects.

To use custom objects in email tokens in the new email builder:

  1. Log in to Campaign Studio, go to Channels > Emails, and click New.

    custom_objects_15

  2. Under the Templates tab, select the email template that you want to use and click Builder.

    custom_objects_22

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

    custom_objects_23

  4. Click Merge tags to load all the tags.

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

    custom_objects_24

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

  6. Update the token, if required.

  7. To save the token, click Apply.

Sample token

{custom-object=product:color | where=segment-filter | order=latest | limit=1 | default= | format=default}‍

The various options in the above token are:

  • custom-object: This is a static keyword that ensures that the token is replaced.

  • product: This is the alias of a specific custom object.

  • color: This is the alias of a specific data field associated with the custom object.

  • where: This is the where condition that informs the system about the linked custom items whose values must be considered.

  • segment-filter: This is a static keyword that informs 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 won’t search all included or excluded segments. Only the root level segment filters are searched.
  • order: This is the sorting order to display multiple items, if the where condition returns multiple values. The default option is latest.

  • latest: This is the order by clause.

  • limit: This is 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: This is the default text value if no custom item was found. The probable values are [default|or-list|and-list|bullet-list|numbered-list].

  • format: This is the format to display the values. Multiple values are displayed as a separated list. The available formats are:

    • default: Comma-separated list, used by default.
    • or-list: Comma-separated with last value divided by or.
    • and-list: Comma-separated with last value divided by and.
    • bullet-list: Bullet is used as list prefix.
    • ordered-list: Numbers are used as list prefix.

Using custom objects in segments and dynamic content

Once you create custom objects, the system adds new filters to segments for each data field associated with a custom object. The contacts that will be 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.

To use custom objects in segments:

  1. Log in to Campaign Studio, navigate to Segments, and click New.

  2. Under Filters, select the data field associated with a custom object that you have created.

    custom_objects_17

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

    custom_objects_18

  4. Click Save & Close.

Similar to segments, Campaign Studio adds new filters to dynamic content as well for each data field associated with a custom object.

To use custom objects in dynamic content:

  1. Log in to Campaign Studio and navigate to Components > Dynamic Content.

  2. Set the Is campaign based toggle bar to No.

    This displays the Filters tab.

  3. Under Details, specify the relevant information.

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

    custom_objects_20

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

    custom_objects_21

  6. Click Save & Close.

In order to create better segments and target specific 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 the above example, 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 above example applies to dynamic content as well.

Reporting

Once you start using custom objects elaborately, you can leverage the various reporting dashboards to analyze the performance of your campaigns and optimize your campaigns further.

You can generate reports for the various custom objects. To generate such a report:

  1. Log in to Campaign Studio and navigate to Reports.

  2. Click New.

    custom_objects_26

  3. Under the Details tab, perform the following steps:

    custom_objects_27

    1. In Name, specify the name for the custom report that you want to create for the custom object.
    2. In Data Source, select one of the available custom objects.
    3. Fill up the other information, as appropriate.
  4. Under the Data tab, perform the following steps:

    custom_objects_28

    1. In Columns, select the column(s) that you want to view in the new report.
    2. In Order, select a column and the corresponding sort order: Ascending or Descending.
    3. In Filters, select the column(s) by which you want to group similar data.
  5. Under the Schedule tab, perform the following steps:

    custom_objects_29

    1. If you want to send the report in an email, set the Email report toggle bar to Yes.

      1. In To, set the email address to which the report needs to be sent.
      2. In Every, select a frequency in which the report needs to be shared via email.

      Alternatively, set the Email report toggle bar to No.

  6. Click Save & Close.

For all the data fields associated with a custom object, you can view a detailed reporting dashboard.

To view such a report:

  1. Log in to Campaign Studio, go to Custom Objects, and select your custom object.

  2. Select a custom item.

    You can view the detailed reports for that item.

    custom_objects_19

Additionally, you can view detailed reports for individual custom objects. To view such a report:

  1. Log in to Campaign Studio, go to Settings > Custom Objects.

  2. Select a custom object.

    You can view detailed reports for that object.

    custom_objects_25