Introduction to Custom Objects

An Introduction by ONTRAPORT CEO Landon Ray

In many businesses, you need to manage more than just "Contacts."

Here's a quick example scenario: If you do B2B sales, you probably need to store "Businesses" and maybe "Opportunities" in order to track which Contacts work for which Business, and see and follow up with all the Opportunities for each Business and Contact.

A contractor needs to be able to create ‘bids’ and follow up on each bid. You might find that one Contact requests several bids, and you’d want to see all of that Contact’s bids in one place.

Custom Objects in ONTRAPORT allows you to create and store these new kinds of data sets to match the way your business really works. What’s really amazing is that ONTRAPORT allows you to use the tools you’re already familiar with -- Campaigns, Forms, Messages, etc. -- to create automated systems to manage these new object records.

Let’s use that contractor as an example. He probably does kitchen remodels, bathroom remodels, new decks, and more. Since he’s so good at what he does, he more than likely works repeatedly with the same clients.

For each job, he’ll want to create a new Bid. Each Bid includes a lot of information on the project such as project type, estimated total cost, estimated labor and materials costs, estimated time to complete the project, proposed start date, and more.

To log this data and connect it to the client, our contractor creates a new object in ONTRAPORT called "Bids." Just like Contacts, this new object has its own Field Editor so he can create all those custom fields. He can do this when he’s creating the object or do it later.

Then in order to keep track of which Contact each Bid is created for, he creates a Relationship between this new object, "Bids," and the existing object "Contacts." (Learn more about the three types of Relationships below.)

Once this is all set up (a process that takes mere minutes in the new Object creation wizard), the contractor's system will look like this:

And when he opens an individual Bid, it’ll look like this:

Finally, when he looks at a Contact, the Bids will show up like this:

This is a great start. Now we’ve got a slick way of storing all the information about each Bid for each Contact in ONTRAPORT.

But here’s where things get tricky!

As you can see in the navigation screenshot above, the new Bids object comes complete with its own Campaigns, Forms and Messages (as well as some legacy features in that Pro account!) For this reason, you're able to subscribe the Bid itself to a follow-up Campaign!

Imagine being able to automatically send out an email with your proposal, then follow up a few days later with a phone call to check in on the client. Then, once the Bid is accepted, a new Campaign might kick off, thanking the client for their business, and letting them know what to expect. Maybe a day before the start date, another email or SMS goes out to the client, reminding them that the construction crew is going to show up the next morning. You get the idea …

As you can see, the ability to create Custom Objects and then run automated Campaigns for them provides virtually unlimited possibilities for streamlining and automating more complex business processes.

The rest of this article will give you a deeper look at Custom Objects.

About Custom Objects

Applies to: ONTRAPORT Pro and above.

Note: Each Custom Object record with an email address field, even if the field is blank, is counted as a contact for your plan limits. In most cases you will create Custom Objects without an email address as shown in all of our usecases. Email sent to these Custom Object records' email address field also count as an email sent for your plan limit (if any).

Custom Objects' Features

Several new features are added to ONTRAPORT with Custom Objects:

• Custom Objects Activation: Turn on Custom Objects in Administration > Advanced Features > Custom Objects.
• Custom Objects Creator:Administration > Data > Custom Objects is used to create and edit Custom Objects.
• Navigation Manager: Within Administration > Data > Custom Objects you can specify if a Custom Object is displayed in your primary navigation menu, the icon it uses, and the color of the listing. Click the name of the Custom Object to enter it, then Settings in the left menu.
• To: Fields for Messages: In each Message editor the drop down dialog boxes will include the email fields for the related custom object records. This permits you to send messages to the related Object: for example, sending an email to the employees of a company from the Company object.
• To: Fields in Sequence Email Steps: You can choose the email field for related custom object records in Step and Date Sequence Email steps.
• Changes to Form Builder: You are now able to add fields from more than one object on a single Smart Form, allowing creation or updates of records in multiple objects.
• Object Selector in Dashboards (coming soon!): You will be able to select the Object you want to report on in Dashboard Metrics.
• Related Object Data Fields: This is a new type of field --not the traditional text or numeric field -- that you’ll find in each Field Editor. This "view-only" field allows you to expose the data in any field of the related object record. It is not used as a trigger for Rules, but allows you to view the data in the Object Record. It also appears in the first level of drop down selection boxes for merge fields and column headings.
• API: Each new object has its own API endpoints.
• Notes: Each object has notes under the Task manager tab. Notes from one object can not be seen placed into another object. [newest note] merge fields can be used for task/email notifications, fulfillment lists and are exportable by object.
• Automation Log: Actively records and stores a list of any manual or automated actions performed on your custom objects records. This feature comes in handy when you need to trace the path of your object records through your automated builds for troubleshooting, or want to test any new builds you're likely to implement. The actions can be performed by Users, ONTRAPORT Smart Forms, Campaigns, API, Rules (advanced feature) and in-Sequence Rules (legacy feature). The Automation Log is located in the Object Record on the History tab.

Understanding Relationships

Custom Objects are easy to create and manage once you understand how the relationships between Objects work.

Custom Objects can be related to the Contacts' Object or to any other Custom Object in one of three ways:

• One-to-many
• Many-to-many
• One-to-one

One-to-many Relationships

In one-to-many relationships (sometimes called Parent-Child relationships) a record in one Object (the Parent Object) can be related to any number of records in the other Object (the Child), but the Child object can have only one parent object. This is the most common type of Object you'll create.

Example: In the contractor example from the introduction, the Bid Object is the "Child" Object and Contacts are the "Parent" Object. Each Contact can have many Bids associated with them (e.g., one for remodeling their kitchen, bathroom and deck), but a Bid will only have one related Contact as the parent.

When you create a one-to-many relationship, the related fields in each record look like this example for a "Business" object that is related to the Contacts (as "Employees") :

In the first image the Contacts are listed in the Business Object record in a "sheet" or list view because there can be many of them. The first one listed is Johann Heinrich Abicht. In the individual Contact Record for Johann Heinrich Abicht we see a single field for the Business object because, in our database at least, each Employee / Contact can have only one Business that they work for.

Many-to-many Relationships

Many-to-many relationships allow each Record in either Object to have connections to many Records in the other Object. For example, in a school, the Teachers Object and the Students Object would have a many-to-many relationship. Each Teacher can have many Students and each Student can have many Teachers.

When you create a many-to-many relationship, the related fields look in each Record look like this:

On the left, a Student record can have many teachers and, likewise, a Teacher Record on the right can have many students.

Note: Because of the complexity of many-to-many relationships, certain features are not available when this Object type is selected. For example, you won’t be able to send emails to a Related Object’s email in a many-to-many relationship. That feature is only possible with one-to-one relationships or one-to-many relationships. The same is true for Rules that are triggered by changes to related Objects.

One-to-one Relationships

A one-to-one relationship means one Record in the new Object can be linked to only one record in the other Object. One-to-one relationships are useful in certain circumstances, but will probably be your least used relationship type. In many cases, you can simply add a custom field to the original record to avoid having to create a new database Object.

A common request is the ability to list a spouse and tying the spouses to each other. Creating a separate Custom Object and adding fields to it would seem to make sense. But ONTRAPORT includes a very powerful feature: You can relate any Object to itself where all the fields, etc. are pre-formatted for you. There is no need for a "spouse" Custom Object as you can simply relate the Contacts Object to itself in a one-to-one relationship. Call the relationship "Spouse" and you can select any other Contact to be the spouse.

Of course, you can create a Custom Object and relate it to another object in a one-to-one relationship.

Creating Custom Objects

Please see our Events Usecase for Custom Objects article for an in-depth example. Most of your Custom Objects will be one to many objects just like that one, but from a set up standpoint, all Custom Objects are created the same way.

1. Click the profile icon in the top right of your account, then Administration > Data > Custom Objects.
2. Click the + New Object button.
   
   
3. In the "Name new object" field, type the new object name such as “Events” and add in the same word in the Singular field. Subsequent fields will populate. Ensure that the names are correct. Then click Next at the upper right.
   
   
4. The field editor appears for the Custom Object you are creating. Each Custom Object has the ability to have any type of field just as you find in the Contact Records. Note that if you add an Email Address field the Custom Object record, when created, will count against your Contacts limit even if you never populate the Email Address field (just as a Contact Record without an email still counts.)
5. Add fields as necessary, such as Event Date, Event Time, Event Location, etc.
6. Set the relationship to another Object such as the Contacts database.
   
   
   
   Here's what each of those questions mean:
   • Event is related to: Indicates what object the new object related to. In this case, Contacts.
   • Relationship Type: This indicates what the type of relationship will be between the two objects. Since a contact can attend multiple events, the relationship in this instance will be one to many.
   • This Event is: The Event is the Parent in this case, since there will be many contacts attending one event.
   • Where should we put the other object in the Event's record?: This asks where the contact's information will appear within the Events Object.
   • Where should we put the Event in the other object's record?: This asks where the event's information will appear within the Contact Object.
   • What should we call this relationship in the Event record?: This asks what the header will appear as in the Event's Object.
   • What should we call this relationship in the Contact record?: This asks what the header will appear as in the Contact's Object.
7. Create the settings for how you would like the Events Object to display when you click on the Events record. For reference, Contacts display as "[First Name] [Last Name] [Email]" but in this case you are able to choose how the label will show.
8. Click the Insert Merge Field dropdown to insert Merge Fields. We suggest setting it up something like this:
   
   
   
   If you used the above information, when clicking an Event Object record, the dropdown field settings created above might appear like this:
   
   
9. In the Navigation settings panel, add the Events Object to the Navigation Menu. Select the icon and color associated with the object. Use the up/down arrows to move the location of the object into the desired location.
   
   

Adding Records to Your Custom Object

ONTRAPORT makes it easy to add new Records to any Custom Object. You can:

• Add the new Record manually in the Object Collection.
• Add a new Record from a related Object.
• Create a Smart Form so Records can be added from any web page.
• Upload a CSV file with new Records in it.
• Use the API to create new Records.

Manually Adding Records

Click the Custom Object in the navigation menu and click the New button:

You can also manually add Object Records from a related Object. In this example, we can add a new Business from a Contact Record:

Adding Records Using ONTRAforms

Each Object includes its own ONTRAforms, making it easy to add Records. Create the ONTRAforms using the same process you have always used in ONTRAPORT. (To learn more, check out our ONTRAforms article.)

Fields from some related Objects are available using the Add Field button. This allows you to create multiple Object Records with a single form. Related Object fields are accessed by clicking the right arrow next to the other Object's name:

Object fields are available subject to the following rules:

• One-to-one relationship: All fields from both Objects are available.
• One-to-many relationship: The Parent Object's fields are available in the Child Object's Smart Forms, but not the reverse (the Parent Object cannot access the Child Object's fields).
• Many-to-many relationship: No fields from the other Object are available.

Fields from other Objects do not appear if the current Object is the Parent Object in a one-to-many relationship, or if the relationship between the Objects is a many-to-many relationship.

Upload Records Using a CSV File

If you’d like to mass import Records into your new Object, you can use the same process you use to Import Contacts. Be sure to prepare a standard Comma Separated Values (CSV) file for the import. The CSV format is often available as an export option from other programs, and other file types can be converted using programs such as Microsoft Excel or LibreOffice.

Follow the instructions in the Import Contacts article to format your file for import. If you are located in the EU or northern Africa, Excel may force a semi-colon separator instead of commas; see the information in the above article under the headline "Converting Semicolon Separated Fields (EU Format)" for formatting instructions.

To import your CSV file, click the Object Collection, then Settings and the Import link:

Creating Records With the API

The documentation to create, update and delete Object records using ONTRAPORT’s Application Programming Interface (API)can be found here. This functionality is advanced and should be used by experienced developers or programmers. ONTRAPORT does not provide support that teaches how to use the API.

Merging Records in Your Custom Object

Custom Objects records can be merged using the familiar Merge Duplicate Contacts interface. In the Custom Object collection, select Settings and then Merge Duplicates (Contacts screen shown in this example).

The Merge Duplicates process allows you to select the fields to search for a duplicate, and then presents each duplicate record for you to merge. It is an intuitive process but you can refer to the instructions in our Merge Duplicate Contacts article for more information.

Understanding Rules and Related Custom Objects

Rules in One-to-many Related Objects

• Rules in the Parent Object:
  • Cannot be triggered or act upon a Child Record or the Child Record's fields.
  • Cannot trigger emails, tasks, etc. in the Child Object.
  • Cannot take any action upon a change in a Child Record (e.g., a Child Record is added or removed from the Parent Object).
  • Cannot take any action based upon a change in a Child Record's fields, such as an email address change, address change, etc.
• Rules in the Child Object:
  • Can be triggered by a change of the linked Parent Record but CANNOT be triggered by a change in any of the linked Parent Record's fields.

Rules in Many-to-many Related Objects

Rules cannot be triggered by an event or action in another Object in a many-to-many relationship.

Rules in One-to-one Related Objects

Rules can be triggered by a change of the linked Record but CANNOT be triggered by a change in any of the linked Record's fields.

These restrictions are due to the nature of the database Objects, and may seem limiting at first. Custom Objects expose the fields of the related objects in Messages, Tasks and Forms. You can still automate notifications, etc. without the use of cross-object Rule activity, as shown in our use cases below.

Usecase - Serial Numbers

Track Serial Numbers (One-to-many)

This use case presents a common data configuration, a one-to-many relationship between two Objects that enables automated notification when a field changes in the Parent. Remember the Parent is the "one" side of the one-to-many relationship.

In this use case, we sell multi-user software. The remote employees of a business that buys our software use the serial number to activate their copy of the software. Previously, custom fields were used to store the company name, details and the software serial number in every Contact Record. Updates were difficult because the company name was not always entered into the custom fields correctly, so Rules, Contact Groups, etc. did not always include all the employee records.

Using Custom Objects, we create this automated system:

1. A Custom Object named "Businesses" is created. In addition to the usual company information fields such as address and phone numbers, a text field named "Serial Number" is added.
2. The Businesses' Custom Object is related to the Contacts database, where the employees of the company are stored. The relationship is "one-to-many" with the Business as the parent object. The Business can have many employee Contacts, but each Contact only has one Business as an employer. The Contacts are called "Employees" in the Businesses records.
   
   
3. The Businesses Custom Object has the companies and serial numbers added via a CSV import.
   
   
4. Each of the Contacts are associated with their company by selecting the company in the Contact Record.
   
   
5. Our goal is to automate notifications of a serial number change that happens each time the company renews their software license. We create the notification email first.
   1. In the Businesses Custom Object, we create a new message.
   2. The parent object can send email to related records in a Child Object. The "Send email to" drop down allows us to select the Employees, then select the email field for the Employees.
      
      
      
      
   3. The merge fields in the email editor expose the Child Object's information. We can drill down to find the employee's first name. We complete the email using merge fields for the serial number (stored in the parent object) and the employee's first name.
      
      
      
      
   4. Save the notification email.
6. Create a Step Seqeunce in the Businesses Object and add the email just created as the first step. Set it to "Send Immediately." Because the serial number can change frequently, select the option in Settings to "Unsubscribe contact after last step". Save the Step Sequence.
   
   
7. Create a Rule that adds a Business to the Step Sequence above when the software's serial number changes.
   
   
8. How this works:
   1. When the serial number field in the Businesses record changes, the Rule adds the Company to the Step Sequence.
   2. The Step Sequence sends an email to all the related Contact Records (i.e., the employees).
   3. After the email is sent, the Step Sequence unsubscribes the Businesses record from the sequence. The process will start over next year when the serial number is renewed again.

If you prefer to manually broadcast your email, select the Child Object Records in the Parent Object Record and perform Group Actions, such as sending emails, on them.

Usecase - Teachers and Students (Many-to-many)

Many-to-many relationships are uncommon and, due to the way the objects interrelate, the options available for automation are limited. The Custom Objects cannot act on or effect changes in the related Object.

• Each Object will list the Records in the other Object.
  
  
• You cannot trigger an action based on an event in the related Object Records.
• Sending email to a related object sends to all related Object Records in a many-to-many relationship. If an email is sent from a Teacher then all the related Students receive the email. When creating an email drill down to the Email field.
  
  

Usecase - Spouses (One-to-one)

An Object can be related to itself. Linking two spouses together in a one-to-one relationship in the Contacts database is a common example. Here are the steps to do so:

1. Click your email address in the top right and select Administration from the drop down.
2. Click on the Custom Objects link to open the Objects page.
3. Click on the Contacts Object to open it for setting relationships.
4. Click Manage Relationships.
5. Click the + New Relationship link. Relate the Contact to "Contacts" and set the Relationship Type to "One-to-one." Then add the other Object to the "Contact Information" section in the Contact's Record and call the relationship "Spouse".
   
   
6. Within a Contact Record you can choose a Spouse.
   
   

Search results will show both the Contact Record and the spouse's Contact Record.

You can send an email to the Spouse Record in a Rule or Sequence. In this example, we send a birthday reminder email to the contact's Spouse in a Date Sequence

1. Create a Date Sequence with an email step triggered by the birthday
   
   
2. Send the email to the Spouse >> Email address. Use the [Spouse//First Name] merge field for the salutation and include the regular [First Name and [Birthday abb+0] merge fields for the reminder information. Remember, the spouse Record having the birthday is the one who triggers the reminder email!
   
   
3. Subscribe your Contacts to the Date Sequence. Their spouses will be sent the reminder email according to the schedule set in the email step.

Usecase - Children (One-to-many)

An object can relate to itself in a one-to-many relationship as well. In this example we will be using the Contacts database and creating a relationship for "many" children of a single "parent" Contact Record.

1. Navigate to the Custom Objects screen by clicking on your email address at the top right, selecting Administration and then the Custom Objects link.
2. Open the Contacts tab. Click the Manage Relationships link, then the + New Relationship link. Set the Contact as related to "Contacts" and relationship type "One-to-many." Then put the information into the "Contact Information" section. Call the relationship in this Contact Record "Children" and in the other Contact, call the relationship "Parent"
   
   
3. You can connect the child to the parent Record by choosing the parent in the Contact Record
   
   

The children will be listed in the Parent Contact Record; Group Actions can be performed on them from there.

For instance, you can send an email to the Parent Record in a Rule or Sequence. This example sends a birthday reminder triggered by the Child Record's birthdate in a Date Sequence.

1. Create a Date Sequence with an email step triggered by a birthday.
   
   
2. Create the email to send to the parent of the child. Set the "Send email to" field to Parent >> Email. Remember to use the drill down "Parent" merge fields for the saluation, etc.
   
   
3. Subscribe your Child Contacts to the Date Sequence. The parents will receive the email reminder message according the schedule set in the email step.

Articles in this section

• Introduction to Custom Objects
• Events Usecase for Custom Objects
• Testimonials and Surveys Usecase for Custom Objects
• Accounts and Opportunities Usecase for Custom Objects