Setting up Convio Luminate

Mobile Commons supports Convio Luminate API v1.

The Convio Luminate data sync allows for flexibility in sync type for new and updated records. In all cases, the user records must include a listed mobile number:

• Using Liberal sync, the data is synced in both directions, regardless of the opt-in status in Convio Luminate.

• Using Conservative sync, the data is updated only for those records with an opt-in status of true in your Convio Luminate system.

Note: You must have Administrator access to work with data syncs in Mobile Commons. For assistance, contact Technical Support.

To set up the Convio Luminate data sync:

• Prepare for setup

• Configure the Convio Luminate integration

• Review required and supported fields

• Activate the Convio Luminate sync

Preparing for setup

Before you begin, gather the log-in credentials and set up any other key connection settings for your Convio Luminate CRM system.

1. In Mobile Commons, create or designate a web opt-in path, which will serve as the default opt-in path for any new users pulled from the Convio Luminate data set. For more information, see Adding a new web opt-in path.

   New subscribers will receive the Welcome message associated with the selected opt-in path. For more information, see Data sync paths.

   Tip: Work with your mobile strategist to organize your synced subscribers by mapping specific Convio Luminate groups to different opt-in paths.

2. Make a note of the following credentials from your Convio Luminate system:

   • API User name and password

     Tip: Create a new set of credentials exclusively for use with Mobile Commons (recommended).

   • FTP host name

   • FTP user name

   • FTP password

   • Organization code

   • API key

   • API host name

   • (Optional) Site Admin user name and password

     Tip: The Site Admin credentials can help the Mobile Commons team troubleshoot your integration.

3. Work with your Convio Luminate Support team to set up a recurring file that contains all the records that have changed in the past 24 hours. Mobile Commons will check this file and then use the API credentials to get the updated content for the changed records and update them on the Mobile Commons side.

4. Make a request to Convio to create a new Mobile Commons data sync:

   • Setting up a Liberal sync

   • Setting up a Conservative sync

Setting up a Liberal sync

When you use a Liberal sync, the data is synced in both directions, regardless of the opt-in status in Convio Luminate.

To set up a Liberal sync:

1. Log in to Convio Luminate.

2. Activate the Custom Boolean 50 field and rename it to Mobile Opt-in field.

   Note: Work with your Convio Luminate Support team to set up Convio Admin access to view and change this field.

3. Activate the Mobile_Number field.

   Note: Work with your Convio Luminate Support team to set up Convio Admin and Constituent access to view and change this field.

4. Activate the Mobile Commons Datasync Operation with the option: Mobile_Number field is not null

5. Add the following IPs to the "Convio API IP Filter Block":

   • 100.25.49.244/32

   • 34.194.244.45/32

   • 34.233.191.146/32

   • 34.197.254.25/32

   • 34.198.107.154/32

Setting up a Conservative sync

When you use a Conservative sync, the data is updated only for those records with an opt-in status of true in your Convio Luminate system.

To set up a Conservative sync:

1. Log in to Convio Luminate.

2. Activate the Custom Boolean 50 field and rename it to Mobile Opt-in field.

   Note: Work with your Convio Luminate Support team to set up Convio Admin access to view and change this field.

3. Activate the Mobile_Number field.

   Note: Work with your Convio Luminate Support team to set up Convio Admin and Constituent access to view and change this field.

4. Activate the Mobile Commons Datasync Operation with the options: Mobile_Number field is not null AND the Mobile Opt-in field equals true.

5. Add the following IPs to the Convio API IP Filter Block:

   • 100.25.49.244/32

   • 34.194.244.45/32

   • 34.233.191.146/32

   • 34.197.254.25/32

   • 34.198.107.154/32

Configuring the Convio Luminate integration

To sync data between your Convio Luminate database and Mobile Commons:

1. Select  Home in the left pane, and then select Data Sync.

2. From the Integration Type drop-down list, select Convio Luminate.

3. Select Create.

   The Convio Luminate configuration form opens.

   

   For assistance, select Help next to the field label.

4. In the Login field, enter your user name for your Convio Luminate system, and then enter your password in the Password field.

5. (Optional) If users from Convio Luminate will opt-in to your campaign via a web path opt-in, select the Mobile Commons web opt-in path from the drop-down list. All mobile users from Convio Luminate will receive opt-in messages from the opt-in path you specify.

6. Enter the default URL for the CSV (comma-separated values) export file that will be downloaded nightly from Convio Luminate.

7. Enter the Convio organization code.

   Tip: The organization code is usually found in the Convio URL.

8. Enter the API key for the web service.

9. Enter the host name for API requests.

10. In the Center IDs field, list one or more Convio centers to include in the sync. Separate multiple centers with a , (comma); leave the field blank if the sync will not involve a specific center.

11. Enter the source code identifying Mobile Commons to your Convio Luminate system. The default entry is mcommons.

12. To specify the setting for sending or suppressing a Welcome email message for new subscribers:

    • Leave the field blank to send a Welcome message to new subscribers, if that feature is enabled in the Convio Luminate settings.

    • Enter 1 (one) to set the No_Welcome field to 1. Your Convio Luminate settings will determine whether or not the email is sent.

13. In the Data Sync user name field, enter your user name to log in to the FTP site, and then enter your password in the Data Sync password field.

14. In the Site Admin user name field, enter your user name to log in to the Convio center, and then enter your password in the Site Admin password field.

15. In the Mobile opt-in Boolean field name field, enter the name of the Convio checkbox field that identifies the constituent as a Mobile Commons subscriber.

16. (Optional) Enter your notes for internal use only.

17. When you are done, select Update.

Note: To help the Mobile Commons team validate the sync from Convio Luminate to Mobile Commons, send them a web form that would generate test users on Convio. Be sure to include a the Mobile Number field and, if they are testing a Conservative sync, a Mobile Opt in field.

Reviewing required and supported fields

The Convio Luminate data sync supports all standard profile fields; it does not sync custom fields. After you configure your Convio Luminate integration with Mobile Commons, review your Convio Luminate system and Mobile Commons user records (profiles) to ensure required and supported fields are available in both data sets.

The following fields are required:

• Phone number

• Email

• Opt-in status (for Conservative syncs)

Supported fields

Category	Field	Default field name
Subscription status	Opt-in (required for Conservative data sync)	"opt_in_status"
Demographic	Phone number (required)	"phone_number"
	First name	"profile_first_name"
	Last name	"profile_last_name"
	Email (required)	"profile_email"
Address/Location	Street address	"address_street_1"
	Street address 2	"address_street_2"
	City	"address_city"
	State	"state"
	Zip Code	"address_postal_code"
	Country	"address_country"
Other	Constituent ID	"constituent ID"
	Donations	"form_id"
		"level_id"
		"donor email"
		"amount of donation"
		"billing address" Note: Mobile Commons stores only one billing address, which it will sync with Convio Luminate.
	Calls	(legislator called) "map recipient_id"
		"alert_id"
		"start time_called"

If you are not using the default field names, use custom field mappings to specify field names in Convio Luminate.

Note: If you are using donation forms, see Mapping Convio Luminate donation forms.

To set up custom field mappings:

1. Select  Home in the left pane, and then select Data Sync.

   The home page for your Convio Luminate sync opens.

2. In the Integration Actions panel on the right, select Edit Field Mappings.

3. Review the field names to ensure that they are correct.

   • The Field column contains the Mobile Commons field name.

   • The API Field Name column contains the API field name in Convio Luminate.

   • The CSV Heading column contains the heading in the CSV export file.

4. To limit the sync to records that contain data in specific fields, select the Required? checkbox next to the field name. When a field is required, it must contain a value in order to be synced. Empty fields are not synced.

   Caution: Do not select Required for Phone number, Email, or Opt-in status fields, which must by default exist in both databases in order to sync data. Use caution if you change the field name for any of these three fields; if the custom field name is incorrect, the data sync will fail.

   Caution: Do not select Required for Constituent as this ID is provided by Convio Luminate. If it is set to Required, Mobile Commons profiles will not have this ID, causing the sync from Mobile Commons to Convio Luminate to fail.

5. When you are done, select Save.

Mapping Convio Luminate donation forms

Certain Convio Luminate donation forms do not require JavaScript or server side changes. For assistance with Convio forms, see the Luminate Online Help (https://webfiles.blackbaud.com/files/support/helpfiles/luminate-online/help/luminateonline.html).

To map Convio Luminate donation forms to Mobile Commons, use our JavaScript. Note that anything starting with profile is the Mobile Commons value, and the second value is the name of the field in Convio Luminate, though your field name may be different.

convio_form_map = {"profile_postal_code":"zip",
"profile_city":"billing_addr_cityname","profile_street1":"billing_addr_street1name",
"phone":"donor_phonename","profile_first_name":"fname",
"profile_state":"billing_addr_state","profile_street2":"billing_addr_street2name",
"profile_email":"email","profile_last_name":"lname"}

Activating the Convio Luminate sync

Before you begin, review the configuration settings for your sync:

1. Select  Home in the left pane, and then select Data Sync.

   The home page for your Convio Luminate sync opens.

2. In the Integration Actions panel on the right, select Configure Integration.

3. Review the configuration settings, making adjustments as needed.

4. When you are done, select Update.

5. To activate the Convio Luminate integration sync, in the Integration Actions panel on the right, select Activate Integration.

   The indicator in the upper-right corner is Active. The first data sync will run the following morning.

Data sync updates

After activation, the Mobile Commons data set and your Convio Luminate database are both updated on a regular basis:

• Mobile Commons checks for updates nightly, processing all recent updates from Convio Luminate during overnight hours.

• Any new opt-ins or opt-outs from Mobile Commons are synced to Convio Luminate  every five minutes during the day.

  • For users whose profile records contain an email address, new opt-ins are added to Convio Luminate as a new record with an opt-in status of true.

  • For users with a matching record in Convio Luminate, new opt-outs update their opt-in status to false.

  Note: Once user records are synced, the record number from the Convio Luminate system is added to the Constituent ID field in Mobile Commons user profile and serves to identify records across both of your systems.

After your data sync runs, you can open the Synchronization report. For more information, see Working with the Synchronization report.

Tip: If you need to shut off the data sync with your CRM system, whether temporarily or permanently, you can deactivate it. For more information, see Deactivating the integration.