Set up Tessitura preferences

In this article

Getting Started with the preferences integration

How does the preferences integration work?

Setting up preferences in WordFly

Test your preference updates in Tessitura

Test Tessitura preference updates from WordFly



Allow your subscribers to choose which communication preferences suit them best. Create your communication preferences in Tessitura and setup the preferences integration to send preference updates back to Tessitura from your WordFly subscribe and unsubscribe pages.



Getting Started with the preferences integration

Preferences are collected in WordFly from the subscribe page and two-step unsubscribe page. Any subscribers with a Tessitura customer number on record can have preference updates go back to Tessitura. Preferences can sync to Tessitura contact purposes, interests, attributes, and contact permissions.


Get started

Go to Account > Tessitura and click the More and Download scripts links under Configure Tessitura Preferences for WordFly to download the installation guide. If you don’t have access to this section of WordFly, please email WordFly support for the guide.


Once you have installed the preferences installation scripts, email WordFly support to have the preferences integration feature enabled for your account.


Steps to complete: 

  • Identify which Tessitura preference type you plan to use for preferences: contact purposes, interests, attributes, or contact permissions. Use one type or a combination of all those types.
  • Run the installation script in the Tessitura database to create the new database tables and stored procedures.
  • Configure the Preferences stored procedure to update preferences on customer records, LP_WF_PREFERENCE_UPDATE_CUSTOMER.
  • Test the updates with our testing script.
  • Update output sets to include preference output set elements.


Installation and configuration are reviewed in the preferences installation materials.




How does the preferences integration work?

Preference updates will be collected in WordFly and sent back to Tessitura to update new local tables in the impressario database. The preference type (contact purpose, interest, attribute, or contact permission) and opt-in value will be sent back to Tessitura when preferences are updates: 1 for opt-in, and 0 for opt-out. A new stored procedure will be configured to update preferences on the constituent record in any way your organization wants to have it reflected. Use preferences in your Tessitura list criteria to target the right subscribers for every email campaign.


Preference can be contact purposes, interests, attributes, or contact permissions. These values are created in Tessitura in system tables.

  • Attributes are set up in system table T_KEYWORD. The Attribute should be set up as: Data Type String, Edit Mask Alphanumeric, Detail Tbl TX_CUST_KEYWORD, Category Constituent.
  • Interests are set up as keywords under system table TR_TKW.
  • Contact Purposes are set up under system table TR_CONTACT_POINT_PURPOSE. Make sure your Contact Purpose category is set up appropriately in the TX_CONTACT_POINT_CATEGORY_PURPOSE table in order for your purpose to display as an email purpose.
  • Contact Permissions are set up under system table TR_CONTACT_PERM_TYPE


New Database Tables

LT_WF_PREFERENCE_HISTORY: Table that stores an audit history of all Preference updates.


LTR_WF_PREFERENCE_TYPE: Table that stores the available reference preference_types. The preference types and IDs are: Purposes (ID 1) , Interests (ID 2), Attributes (ID 3), and Contact Permissions (ID 4).


New stored procedures

LP_WF_PREFERENCE_UPDATE_HISTORY: Stored procedure called by WordFly with each Preference update. This procedure handles standard processing of recording all preference updates in the LT_WF_PREFERENCE_HISTORY table and then calls the LP_WF_PREFERENCE_UPDATE_CUSTOMER procedure for custom processing.


LP_WF_PREFERENCE_UPDATE_CUSTOMER: The RETURN statement on line 28 must be removed for the procedure to run. The procedure has default sample code to update Purposes, Interests, Attributes, and Contact Permissions, and works for all organizations as is. The procedure can be customized for additional data processing.


The following shows sample preferences data that would populate in the LT_WF_PREFERENCE_HISTORY in the impressario database. This data would then update on patron records through the LP_WF_PREFERENCE_UPDATE_CUSTOMER stored procedure.



Updates on the constituent record in Tessitura

Preferences will show up on the constituent record in Tessitura in the following places depending on the preference type:


Contact Purposes will display under the Contact Details tab > Contact Point Purposes radial.



Interests will display under the Attributes tab > Interests radial.


Attributes will display under the Attributes tab > Attributes radial.


Contact Permissions will display under the Contact Details tab > Contact Permissions radial.



Update your Output sets to include preferences for all subscribers

WordFly will stay updated with preference updates on the Tessitura constituent record through data provided by your Tessitura output sets.


Each time you import a List Manager list or Extraction you will use an output set to provide data for your subscribers and this data should always include the subscriber's preferences. A 1 should be returned if the subscriber is opted in to the preference and a 0 should be returned if the subscriber is opted out of the preference.


Refer to the installation materials for updating your output sets to include preference information.


Once you have your output sets updated with preferences, make sure to only use these output sets for your WordFly list imports.




Setting up preferences in WordFly

There are a couple account setup steps in WordFly to complete before using the preferences integration.


Step 1: Set up your Tessitura preferences IDs in WordFly

Go to Account > Preferences and setup your preferences. Click on the Add button to start adding your preferences.


  • Type in the name of your preference. Click Save.
  • Add as many preferences as you need for your organization.
  • Do not use special characters in the preference name.
  • Select the type of preference it is in Tessitura (Purpose, Interest or Attribute).
  • Add the appropriate preference ID from Tessitura system tables in the ID field.
  • Preferences in WordFly become subscriber data fields.
  • Use the reorder icon to the left of the preference to move it up or down in the list.
  • The order set here will translate to the order displayed to the subscriber on your subscribe and unsubscribe pages.
  • Click Delete to remove a preference. However, be aware that deleting a preference will delete any stored subscriber data for that preference.
  • Subscribers going to the two-step unsubscribe page will see boxes checked for any preferences they are signed up to receive in the past.



{Optional) Each preference can have a description display below it when the subscribe and unsubscribe form are presented to the subscriber. Since preferences are data fields in WordFly, you will go to Subscribers > Data Fields to add descriptions to your preferences.



Step 2: Create your unsubscribe landing page in WordFly.

Go to Account > Unsubscribe Settings and enable two-step unsubscribe. Next, go to Account > Unsubscribe Pages and customize your Unsubscribe page with your branding.


  • The preferences you set up in step one will automatically populate on this page.
  • You can modify the text, upload a header image, and make updates to match your branding.
  • You must select Save & Publish for the page to be live. Be sure to customize and publish each of the unsubscribe landing pages.


Test your preference updates in Tessitura (wp_preferences_test.sql)

WordFly will provide a testing script (wp_preferences_test.sql) to test your preference updates in Tessitura directly. The script mimics the data WordFly will send back to your database when preference information is sent back to Tessitura. This testing step can be completed after running our install script and configuring your LP_WF_PREFERENCE_UPDATE_CUSTOMER stored procedure.


To use the test script


1. Open Microsoft SQL Server Management Studio.


2. Select the ‘impressario’ database.


3. Open the wp_preferences_test.sql script in the application.


4. Configure Step 1 values.


This step covers all the data WordFly will be sending back to your Tessitura database when a preference is updated.


There will be three parts to Step 1 to configure:


STEP 1A: CUSTOMER DETAILS: This is where you will use a valid customer for your test. You could use your own personal Tessitura record or another test customer. Update the customer number and email address to reflect this subscriber. Also be sure to update the TR_Org ID to your organization’s unique Tessitura Organization ID (feel free to ask Tessitura or WordFly support what your ID is since we are using it for your integration).



Tip: Use ‘Valid Values’ to find correct/available values in your database for each.
Highlight the value and click ‘Execute!’ to query available data in your database.


STEP 1B: PREFERENCE UPDATE: This section specifies the opt in or opt out response WordFly will send back for the preference. For the ‘preference_ind’ use a value of 1 to test opt-in updates for a preference and a value of 0 to test opt-out updates. You can leave ‘preference_dt’ as is unless you want to test sending back a date for the preference update.



STEP 1C: PREFERENCE TYPE: This section allows you to test each type of preference you will be using. Only uncomment one preference at a time for testing. Update the preference_id value to a valid interest value from your database.


Example of an Interest test:
Uncomment the Interest test, then update the preference_id with the appropriate interest id you would like to test.


5. Click Execute! to run the script and verify the results.
The first set of results will show you what WordFly is sending to your database. The second set of results will show you the update in your database. You can even have your Tessitura client open to the specific customer record you are testing where you can verify there as well that the preference updated successful.


6. Test all your preferences for both opt-in (@preference_ind = 1) and opt-out (@preference_ind = 0) to ensure everything is updating as you expect it to.




Test Tessitura preference updates from WordFly

After finishing all your preference setup tasks it's time to test preference updates from WordFly to Tessitura. Create a campaign in WordFly, send it to some internal testers, click the unsubscribe link and update preferences. Verify preference updates in Tessitura within 1-2 hours.


Guide to sending a testing campaign


Verify your preferences updates in Tessitura

After your subscribers click “update” or “unsubscribe” on the preferences page, WordFly sends all the information back to Tessitura and updates the subscriber record. The subscriber's customer number must be logged in WordFly to send preference updates back to Tessitura.






How long will it take to set up the new preference feature?

Every organization will take a different amount of time to set up preferences. The steps are very simple and straightforward. You will have to discuss the steps with your team to gather an accurate estimate.


What happens when the unsubscribe link is clicked after this is set up?

Once you have the new preference page set up your subscribers will all go to the same landing page where there will be an option to unsubscribe and additional options to update email preferences. If the subscriber changes their preferences and submits the page, those preferences are sent back to Tessitura to be processed by the new stored procedure LP_WF_PREFERENCE_UPDATE_CUSTOMER. If a subscriber clicks on the global unsubscribe this response is sent back to Tessitura to be processed by the LP_UPDATE_EMAIL_PROMOTION stored procedure. If you have Member specific preference management pages on your website now you might consider including a link on the unsubscribe preference page that allows special subscribers (like Members) to update their preferences on your website.


Can we link directly to the unsubscribe preferences page?

The unsubscribe preference page - when enabled - is the same dynamic link as the unsubscribe link. Insert this dynamic link into your email template and subscribers who click on this link will go to the new unsubscribe preference page. Updates made on the page directly update their subscriber record in WordFly and Tessitura. A stand-alone preferences page is not available at this time.


How long does it take for updates to appear in Tessitura?

There is a new stored procedure LP_WF_PREFERENCE_UPDATE_CUSTOMER handling the preference updates and it will be running all the time. Expect to see preference updates on customer records in 1-2 hours from the time the preference was updated in WordFly.


Here are some more details about event processing that are helpful to know:

  • WordFly response processing is controlled by a software robot that processes responses until all event processing is finished and then takes a short break (90 minutes) before running again. Once responses are available and the robot is processing events it will continue to process the responses until those are done.
  • The robot may never stop processing events because events for high-volume sending organizations deploying on a daily/consistent basis because events are continuously coming in.
  • Small test campaigns may in theory take longer process if the robot is "on a break" and not running at the time when the response was received, generating a delay of up to 90 minutes.


What data is required in order for preferences to update in Tessitura?

The new stored procedure LP_WF_PREFERENCE_UPDATE_CUSTOMER requires email address and customer number for sending preference data back to Tessitura successfully.


What if a subscriber re-subscribes to our mailing list?

If a user wants to start receiving emails again they would simply modify their preferences again on your website (in a My Account section). Once the user re-subscribes (or updates their mailing preferences) to your email program, the next time you import your list into WordFly the preferences will be updated for that email record based on the data provided by your output sets. If there is an unsubscribe in WordFly for the subscriber that unsubscribe will need to be overriden on the List Summary page after the list with their updated preferences has been imported.


Are these preferences linked to a specific email address? What if we have several different emails for 1 customer or under a household?

The preferences are linked to an email address + customer number. Tessitura allows preferences for multiple addresses on a record. The user would be modifying preferences for the email address + customer number the email was sent to.


Can I use @preferenceHistoryId in the preferences stored procedure?

The @preferenceHistoryId parameter is not used by the default implementation of LP_WF_PREFERENCE_UPDATE_CUSTOMER. It is passed to the stored procedure to provide a link back to the LT_WF_PREFERENCE_HISTORY for cases where additional custom processing is added to LP_WF_PREFERENCE_UPDATE_CUSTOMER. We attempted to implement LP_WF_PREFERENCE_UPDATE_CUSTOMER so that it works as is for everyone, but it is designed to allow an entry point for customization.