About the Oracle Responsys data model
Companies use the Oracle Responsys platform to create and manage data and content. Marketers create campaigns that use the data and content to send personalized messages to their audience. Marketers also create programs that use the marketing data and campaigns to send a series of messages to their customers over time. Responsys represents each of these items in its object data model.
The sections in this topic describe these objects and how you can use the Responsys API to work with them to accomplish a variety of marketing automation goals:
Programs
In Responsys, the term “program” does not refer to a computer program, but to a marketing program. A Program object defines multi-step activities that involve a variety of campaign messaging and routing rules based on individual profile and behavioral attributes. Marketers create an individual Program by using the visual, drag-and-drop Program user interface in Responsys.
What can I do with Program objects through the API?
You can use the Responsys API to trigger Custom Events for individual recipients. Custom Events can enter an individual into a Program or affect the individual's routing in a Program. You can send up to 200 recipients at a time through the Trigger Custom Event API. You can associate dynamic attribute-value pairs with each recipient that your application passes in for a custom event.
Before you can use a Custom Event in a Program, the Responsys Account Administrator must add the Custom Event to the Define Custom Event Types page in Responsys. The Responsys online help provides instructions for doing so. To access the online help, log in to Responsys and select Help. From the Responsys online help Contents pane, choose Account Management | Global Settings | Defining Custom Event Types.
Important Note: Cross Channel Programs, Enactment Batching, and the Trigger Custom Event API
Oracle Responsys Programs enable cross-channel orchestrations with Email, SMS, and Push. If you plan to use the Trigger Custom Event API call with cross-channel marketing programs, please review this section first.
Responsys requires the Enactment Batching feature to be enabled when using the Trigger Custom Event activity in Programs with Mobile App campaigns. Otherwise, the Mobile App campaign events in the Program will not be processed. However, there are some tradeoffs to consider before enabling the feature. When an account has Enactment Batching enabled, triggering a Custom Event cannot be used to perform near-real-time processing for any campaign type. Responsys will batch enactments together into a single enactment group before entering the enactments into a Program. This results in at least a 10-minute delay between Custom Event triggering and entry into a Program.
If your account has Enactment Batching enabled and you need to send near-real-time messages, such as event reactions, then we highly recommend using merge-trigger or trigger API calls instead. Please contact your Customer Success Manager (CSM) for additional assistance or information.
Campaigns
Campaign objects define the basic behavior of a marketing campaign in terms of audience, message, channel type, and related settings.
Campaign properties include the following:
- General properties include name, channel type (Email, SMS, MMS, Push, or In-app Message), description, categorization, and other fields that identify the campaign.
- Audience selection properties define the audience, based on the selected data source and the inclusion and exclusion criteria.
- Message elements include From header, Reply-to header, Subject header, and HTML/Text message documents. HTML message documents can include media assets from the Content Library.
- Data sources define the data used for message personalization. (You can also pass personalization data in as attribute-value pairs through the API payload in the optional data section, without it needing to be in a table.)
- Launch settings store launch-related information, including the launch schedules for the campaign.
- Other settings control tracking options, auto-close behavior, default variables, and the like.
- Testing and analysis enables users to test links and analyze message deliverability.
What can I do with Campaigns through the API?
The Responsys API helps you run Email, SMS, and Push campaigns in batch launch or triggered modes. You can use the Responsys API to:
- Get information about all campaigns for Email (EMD campaigns only) and Push (returns both Push and In-app Message campaigns).
- Work with campaign launch schedules for Email (EMD only) and Push campaigns:
- Create a campaign launch schedule for an immediate launch or for a future launch
- Update a campaign launch schedule
- Get all campaign launch schedules for a given campaign
- Get a launch schedule for a given campaign using the launch ID
- Delete a campaign launch schedule using the launch ID
- Trigger on-demand campaign message delivery to specific recipients for Email, SMS, and Push campaigns. Using the Merge Trigger APIs, you can also merge data into your Profile List and immediately trigger the campaign to the merged recipients.
Campaign Considerations:
- Feature Enablement: By default, Responsys accounts use the classic email channel. Some APIs require the Responsys account to be enabled for Email Message Designer (EMD), SMS, or Push features. For example, the Trigger Push API only works for accounts enabled for Push. Less obviously, when using the Schedule Campaign Launch and Get All Campaigns APIs with email campaigns, the Responsys account must be enabled for EMD.
- Promotional vs. Transactional Campaigns: Campaign purpose is one of the campaign properties. Campaigns can be either promotional or transactional. Knowing the campaign’s purpose may affect how your application uses the APIs to trigger campaigns, in particular, when determining throttling and batching.
Forms
Form objects provide functionality for hosting web forms and for collecting/processing the data that a company’s audience submits. Marketers create forms in Responsys to gather customer preferences or for general-purpose surveys. Data collected from forms can be merged into a list or supplemental table. Form responses can trigger follow-up emails and custom events that place the responder in a Program dialog. This happens automatically, depending on the rules defined in the forms.
What can I do with Form objects through the API?
Forms are not directly accessible through the Responsys API. However, they may use assets from the Content Library, which can be managed through the Responsys API.
Content Library
The Content Library contains the creative content used for campaigns and forms.
Content Library Folder objects are used to organize creative content. (Note that Content Library Folders are different from the generic folders in Responsys.)
Content Library Document objects contain the text-based content for creatives used in campaigns and on forms.
- Document objects can be HTML and text. For example, an email campaign usually comprises an HTML message and a corresponding text message, so that the system can send the message in the recipient’s preferred format. A Push campaign may have a text message for the notification followed by an HTML message when the mobile app launches.
- Documents can be re-used across multiple campaigns and forms, copied, edited, and deleted from the Campaign Workbook.
Content Library Media Item objects contain files stored in binary format in the Content Library, such as images used in campaigns and forms. Media items may be files of type JPG, GIF, PNG, PDF, TIF, or SWF.
What can I do with Content Library objects through the API?
The Responsys API enables you to:
- Get information about documents, images, and folder contents
- Create and delete folders in Content Library
- Upload, download, copy, update (by replacing), and delete document objects
- Upload or download sets of media items referenced in a document
- Upload, download, or delete media items individually
Data Objects
Responsys data objects comprise Profile Lists, Profile Extension Tables, and Supplemental Tables. This section describes each of these objects and what you can do with them through the API.
Profile Lists
Profile Lists store recipient audience database records. Members of your audience might be leads, prospects, customers, contacts, consumers, or visitors, depending on your terminology. Marketers use Profile Lists and related objects (such as Profile Extension Tables and Filters) primarily for campaign targeting and personalization.
The standard set of fields in a Profile List includes:
- Recipient ID (RIID), a unique identifier assigned to a recipient’s record by Oracle Responsys. The RIID allows Responsys to track the behavior of individual recipients over time.
- Email address, mobile number, postal address, which are standard contact channel fields
- Permission/Opt-in status fields for the various marketing channels (email, mobile, postal)
- Email format preference (HTML or text)
- Derived fields for ISP and domain
- Last modified and created timestamps
In addition, Profile Lists can have a number of custom, user-defined fields that you can use to expand the audience profile data for targeting and personalization purposes.
NOTE: An account can have any number of Profile Lists, but it is recommended that a single central Profile List is used for a given enterprise marketing objective. In some cases, it may make sense to have multiple Profile Lists. For example, a company with multiple brands served by a single Responsys account may choose to use a different Profile List for each brand.
These are the Profile List-based objects:
- List filters are the rules to define segments that contain a subset of the members of a list. You can use list filters to include or exclude members from any given campaign launch or from entering into a Program. Marketers use filters in Audience Designer to build highly-targeted audiences.
- List segmentations are used primarily to track segments that meet certain criteria. For example, your list may break down into the segments “multiple purchasers”, “one-time purchasers”, and “non-purchasers”.
- Seed lists store records that share the same schema for a given list, but that are used only for testing and seeding of campaigns. These records do not represent real list members (such as real prospects, customers, and the like).
What can I do with Profile Lists through the API?
For Profile Lists, you can use the API to:
- Get a list of all Profile Lists for an account
- Perform actions on the Profile List records:
- Add new records or update existing records in a Profile List
- Get the Profile List record by RIID
- Get the Profile List record by other query attributes, such as email address or mobile number
- Delete a Profile List record associated with an RIID
Profile Extension Tables (PETs)
Profile Extension Tables (PETs) allow you to store additional information for each unique recipient in your Profile List. Therefore a record in a PET must map to exactly one record in its parent Profile List table. Similar to data in Profile Lists, audience data in PETs can be used for segmentation and targeting in Filters as well as Programs.
General properties:
- One or more PETs can be associated with a Profile List or with an App Channel List. When a user creates the PET, the user must first choose its parent list.
- There must be a one-to-one relationship between a record in a PET and a record in its parent list.
- When the parent list is a Profile List, the relationship is between the PET record and a recipient record in the Profile List. For example, you may store customer birthdays in a PET.
- When the parent list is an App Channel List, the relationship is between a record in a PET and a device record in the App Channel List. For example, you may use an App Channel List Preferences PET to store a preference that shows whether a mobile app user wishes to receive news updates.
What can I do with PETs through the API?
For PETs associated with a Profile List, you can use the API to:
- Create a PET
- Get a list of all PETs for a Profile List
- Perform actions on the PET records:
- Add a new PET record or update an existing PET record by RIID
- Get a PET record by RIID
- Get a PET record by other query attributes
- Delete a PET record associated with an RIID
Supplemental Tables
A Supplemental Table is a collection of database records that supplements a list with additional related information. Because you define the schema for any supplemental table you create, you can use supplemental tables for a wide variety of purposes. Supplemental tables can be used for message personalization and dynamic content, segmentation, storing form responses and campaign events, and the like.
What can I do with Supplemental Tables through the API?
You can perform the following actions on Supplemental Tables through the API:
- Create a Supplemental Table
- Perform actions on the Supplemental Table records:
- Add new records or update existing records in a Supplemental Table with the primary key
- Add new records or update existing records in a Supplemental Table without PK (by specifying a match column)
- Get the Supplemental Table record by query attributes
- Delete a Supplemental Table record based on a query attribute