Convio Open Development Program Integration Guidelines

CONVIO CONFIDENTAIL

Overview

This document is provided to guide prospects who wish to develop product integrations to

Convio‟s Open platform using the available API interfaces. The intended audience is a

developer or other similar technical resource, working with either Convio‟s Luminate Online

marketing product, Luminate CRM, or Convio Common Ground. Included are document

references, community links, best practices, and tips.

The Convio Open Development Program is the official partner program for recognized vendors

that develop integrations with one or more Convio products. If you wish to apply to become a

Convio Open Partner, please fill out this submit form: http://www.convio.com/our-

partners/become-a-partner.html . You can learn more about the Convio Open Development

Program here: http://open.convio.com/program/ .

Development and Test System

You will be provided access to a temporary system for the purposes of fulfilling the integration

development work on the Convio open platform utilizing our existing published interfaces. The

details will be provided in a separate email by the Convio Open Development Program Partner

Manager.

Force.com Technology Platform

Convio‟s CRM offerings (Luminate CRM and Common Ground) are built upon the Force.com

platform that is offered by SalesForce.com. Convio is a SalesForce Foundation partner and is

currently the only nonprofit vendor licensed by SalesForce to offer a CRM solution leveraging

their CRM platform targeting the nonprofit market. SalesForce offers a rich set of APIs and their

own Apex language to develop integrations- documentation, community, and reference links are

provided below. Flavors of the Force.com APIs available beyond native Apex code to develop

custom integrations include the following:

 REST APIs

 SOAP APIs

 Bulk APIs

 Metadata APIs

We encourage Open partners to list their developed integration applications on the SalesForce

AppExchange, which can provide greater visibility to vendors to reach a wider audience.

CONVIO CONFIDENTAIL

Other Convio products such as Luminate Online are build upon Convio‟s own technology

platform, and Convio offers a fully documented and supported set of APIs to develop custom

integrations to this platform as well. There are two flavors of Convio Open APIs offered for

Luminate Online- REST and SOAP based.

Typical Integration Guidelines

We encourage potential Open partners to develop rich and compelling integration experiences

that will be beneficial and productive for our common clients. At a minimum, we would like to

see seamless authentication and updated constituent profile information demonstrated. We

encourage you to do more and we are happy to guide you during the design phase of your

integration.

It is assumed that prospects wishing to develop integrations to the Convio platform have the

necessary skills and experience to learn and use a new API interface. Beyond the reference

documentation made available for download, there are not any training classes offered to learn

the product if you are not yet a partner, although you can attend a Convio public training class

for a fee. Technical support is limited for Open prospects, so you need to be willing to invest the

time to research product functionality, troubleshoot errors, and resolve problems largely

unassisted.

It is important to decide and document a set of basic use cases that will guide your integration

development efforts. A use case can be thought of as a documented workflow from beginning

to end that one or more stakeholders would participate in to achieve some task or business result.

A documented use case scenario must be a common or frequent activity performed by clients in

order for it to be of value and relevance. It is suggested at least three (3) use cases are provided

in your submit form that you will receive from Convio.

Once you have decided on your use cases to develop, Convio will work with you to set up a time

to demonstrate the prototype integration and discuss further. During this stage, we place more

emphasis on the functionality and usability of the integration rather than the finished look.

For Convio Common Ground and Luminate CRM Integrations

For Open prospects developing integrations to Convio Common Ground or Luminate CRM, the

underlying platform for this product is Force.com. There is a wealth of data and resources

available to developers wishing to develop an integration to this platform. They are as follows:

DeveloperForce main website: http://developer.force.com/

CONVIO CONFIDENTAIL

DeveloperForce online documentation of their APIs, other integration documentation:

 http://wiki.developerforce.com/index.php/Integration

Specific link to the newly available Force.com REST API:

 http://developer.force.com/REST

Core resource libraries:

 http://developer.force.com/coreresources

Community discussion boards for developers:

 http://boards.developerforce.com/sforce/?category.id=developers

Other partner / technical resources:

 http://sites.force.com/partners/PP2Page?p=P_PartnerResources

Introduction to developing commercial apps on Force.com

 http://wiki.developerforce.com/index.php/Introduction_to_Developing_Commercial_App

s_on_Force.com

SalesForce AppExchange

It is encouraged by Convio that Open Partners who develop integrations to work with Convio

Common Ground or Luminate CRM, also complete the necessary steps to have their application

officially registered with the SalesForce AppExchange, located at

http://sites.force.com/appexchange/gettingStarted . This will not only make your application

available to a wider audience, but also it offers an additional measure of confidence to clients

considering downloading and installing your packaged integration. SalesForce provides the

following material to assist developers to prepare for a security review of their submitted

applications located at http://wiki.developerforce.com/index.php/Security_Review .

Common Ground Integrations

CONVIO CONFIDENTAIL

Your Convio Open Development Program Manager will provide you directions on how

to access a temporary instance of Convio Common Ground for integration development

and testing efforts. Please note that only one instance per company/organization is

provided, but can be shared by multiple developers. Also the time for your automated

email notification to arrive upon completing the trial form can be up to 10 minutes. By

default the trial period for a Common Ground test instance is 30 days, but this can be

extended by the Convio Open Development Program Manager

Recording your Organization ID

For your trial version of Common Ground, you should copy down the value of your

Organizational ID so we can more easily locate your particular instance should you need

the expiration period extended. Note that any trial version of SalesForce that goes

beyond 30 days of the expiration date without being renewed is automatically expunged

and the data cannot be retrieved.

Under Setup, go to Administration Setup, and then under Company Profile click on

“Company Information”. Look for the field that has the Organization ID displayed:

Configuring API Access

The API within Common Ground is already enabled out of the box. You will need to

designate a user account that the API will use that has the proper credentials, and setting

up security access.

CONVIO CONFIDENTAIL

1. For the SFDC user account, it is recommended to set up a user as a System

Administrator that also has a Common Ground license. Without the CG license

access, the user won‟t be able to see any CG objects.

Assign / verify Common Ground licenses as follows:

Select „Setup‟ , then under „App Setup‟ select „View Installed Packages‟. You

will see the package name „Convio Common Ground‟ installed. Under the action

column, select „Manage Licenses‟:

From there you can add or remove licensed CG users:

CONVIO CONFIDENTAIL

To view what packages an existing user is licensed to use, that is displayed on the

user‟s detailed profile. On the left navigation bar under Administration Setup,

drill down to Manager Users -> Users and select a user‟s full name link, and then

scroll down to the „Managed Packages”. You can see all the packages that user is

licensed to use:

2. To set up access security for the designated user account that will access the API,

there are two options:

 generate a security token

 update the IP whitelist range to include the trusted network

To generate a security token:

a. While logged in as the designated API user account, go under setup menu

for that user:

CONVIO CONFIDENTAIL

b. On the left navigation bar, under “Personal Setup” expand the section for

“My Personal Information” and then click on the link “Reset My Security

Token”. Then click on the button „Reset Security Token” :

To add a new IP address to the whitelist:

a. Go to the setup selection for the user, then on the left navigation bar under

“Administration Setup”, expand the section for “Security Controls” and click

on “Network Access” :

CONVIO CONFIDENTAIL

b. Enter the IP address for the application or system that will be integrating with

Common Ground via the API.

The standard SFDC enterprise WSDL will provide access to all data objects, including

Common Ground objects defined by the nonprofit organization.

Luminate CRM Integrations

Partner access to Luminate CRM test systems is anticipated at the end of 2011. Please

consult with the Open Development Program Manager for details. Many of the

SalesForce API integration setup steps for Common Ground will also apply to Luminate

CRM, but keep in mind these are two distinct products developed separately, and as such

an integration developed for one of these CRM solutions will not necessarily work for the

other. If you are a partner prospect, please work with your Convio Open Development

Program Manager to determine which Convio product integration is appropriate for your

application on the Force.com platform, as Common Ground and Luminate CRM are not

only separate products, but they also target different market segments.

Caveat Emptor

Because Convio Common Ground and Luminate CRM introduce additional custom

objects and triggers on top of the basic SalesForce.com offering, it is important to

understand how this might affect your planned integration. In general, a package

application written for Force.com will not always cleanly install or operate in a Convio

Common Ground or Luminate CRM environment, without some additional changes or

updates. Convio makes available upon request a copy of the Convio Common Ground

Object Reference, which details all existing triggers and workflows that exist within the

product.

CONVIO CONFIDENTAIL

We recommend that clients consider only third party applications that have been

reviewed and approved through the Convio Open Development Partner program when

considering downloads for your Common Ground or Luminate CRM environment. Such

partners are listed on the Convio website under the partner section.

For Convio Luminate Online Marketing Integrations (formerly COM)

Complete reference documentation for Convio‟s REST-based APIs and SOAP-based Web

Services to access Convio Luminate Online (formerly COM) is available at this site:

http://open.convio.com . Sample code downloads are available for free at this same location.

Please enable API logging when you begin developing your Convio integration. Details for

configuring the API logging level are located in the Convio Open API Reference Manual, under

the section “Logging API Calls”, available for download at http://open.convio.com .

1. Single Sign-On

1.1. Registration

1.1.1. Users who register on the Convio site must be automatically registered on the partner site.

1.1.2. Users who register on the partner site must be automatically registered on the Convio site.

1.1.3. Users must be able to log in using the same credentials to either the Convio or the partner site.

1.2. Authentication

1.2.1. Users logged in on the Convio site and navigating to the partner site must be automatically logged

in on the partner site.

1.2.2. Users logged in on the partner site and navigating to the Convio site must be automatically logged

in on the Convio site.

1.2.3. Tip- be careful mixing domains when making API calls – authenticated sessions established on a

non-secure domain are not recognized on secure domains. Be sure you login on the secure

domain (https://secure.convio.net) vs. the non-secure host site (http://org.convio.net) before

calling API methods that require a login session. Using redirect URLs can work around this

issue if working with a non-Convio domain in the same session.

1.3. Password Changes

1.3.1. When a user changes his password on the Convio site, their password must be automatically

updated on the partner site.

1.3.2. When a user changes his password on the partner site, their password must be automatically

updated on the Convio site.

CONVIO CONFIDENTAIL

2. User Profile

It is recommended that any custom objects, fields or attributes that are created within Convio to

support your integration, that the internal references are uniquely named so as not to have

namespace conflicts with potentially other client customizations before or after your integration

is enabled.

After a user registers on either site and the registration is propagated to the other site, the details

of the user‟s profile information (name, address, email, etc.) that are common to both sites

should be the same on both sites.

When a user updates common profile information (name, address, email, phone, etc.) on either

site, the change should automatically propagate to the other site.

3. Group and Interest Assignment and Synchronization

If your integration will synchronize Convio groups or interests to another application or interface

outside of Convio, it is recommended that you pair both the name of the interest or group along

with the numerical value when displaying for users. So it is more intuitive to see “outdoor

interest (1025)” vs. just “1025”.

Convio‟s Open APIs are more restrictive when assigning a user to a group id vs. interest id,

because site security is affected by internal group membership. Groups that are tied to interests

have no effect on site security permissions and access for an individual. When using the

Constituent API, you cannot use the client version (CRConsAPI) to make an anonymous update

to add a constituent to a group via the add_group_ids parameter. You must instead use the server

version (SRConsAPI) from a white-listed server IP address along with valid API admin user

credentials. Adding or updating opt-in interests via add_interest_ids is supported via

CRConsAPI and is not as constrained for use compared to add_group_ids.

4. Donations

PCI-DSS Compliance

Convio‟s payment processing system is PCI-DSS certified. Partner‟s implementation of any

donation or payment processed by Convio must provide a direct, secure connection from the

cardholder‟s browser to Convio. It must not collect, store, proxy, or transmit sensitive cardholder

information through any other system or network.

Specifically the donations API data must be sent directly to Convio - the form action must be

https://secure2.convio.net/organization/site/CRDonationAPI, not, for example, to a script or page

such as donate.php which then makes a server-side request to the API and parses the resulting

XML. You'll need to use redirect URLs (see

http://open.convio.com/api/#main.using_redirect_parameters.html) to handle the response.

CONVIO CONFIDENTAIL

5. TeamRaiser

A sample TeamRaiser registration work flow:

 You may want to ask the user to login or create a new constituent record in the system.

This is not mandatory; you can register without logging in and the registration will try to

match or create the user record, but this is a good opportunity for the user to positively

identify themselves or possibly review and update their site registration profile.

 getParticipationTypes returns information about participation types available for an

event. There may be more than one participation type available for a user to select, and

since the participation type drives a lot of the subsequent registration workflow you

probably want the user to select it first. Even if the event defines only one participation

type, you will probably need data, such as survey questions, that are returned by this

method.

 Given the event ID and participation type, getRegistrationDocument returns the template

document which must be filled out and passed to processRegistration to complete the

registration process.

 An example contribution exists on the download page of the Convio Open site showing

how to use the TeamRaiser registration API. Please visit

http://open.convio.com/downloads/teamraiser-registration-api.html .

6. Advocacy

You must first create an alert template in the Convio admin interface before accessing it via the

Advocacy API.

By default the temporary Luminate Online test system provided to you by Convio has Advocacy

delivery turned off, as we do not want partners during testing inadvertently sending members of

Congress or the White House test emails. If you wish to preview email messages within

Advocacy, please contact the Open Program Manager to have that enabled. You must create a

custom target for use when sending any action alerts during testing.

The Advocacy API today does not support web forms that use CAPTCHA .

7. Survey

CONVIO CONFIDENTAIL

You must first create a survey template in the Convio admin interface before accessing it via the

Survey API.

8. MultiCenter

The REST based API has a “center_id” parameter that can be used to set the center context for

an API session. You do not need to modify access permissions for the “API_Administrators”

group in order to limit context by a particular center when making API calls.

The Web Services interface is not aware of MultiCenter and does not have the ability to filter or

set context based on a particular center.

9. Interactions

Logging

User registrations that come in through the partner site should log appropriate client-defined origin source

codes in the constituent profile of the Convio site.

Meaningful user interactions with the partner site should log appropriate client-defined interaction records

on the Convio site.

Examples

A contributed example on the open website exists for using custom interactions within Luminate Online.

Please visit http://open.convio.com/downloads/custom-api-example-pet.html .

10. Debugging

It is recommended to enable API logging when developing the integration to Convio‟s Online

Marketing product (COM). Details for configuring the API logging level are located in the

Convio Open API Reference Manual, under the section “Logging API Calls”, available for

download at http://open.convio.com .

If you cannot reach the temporary test system provided by Convio online, be sure to check the

values of the URLs you are using compared to the values within the document provided to you

by Convio to uncover any typographical errors.

Be sure you have the correct API key value and account login password taken directly from the

Convio system you are developing against - the samples provided in the documentation will not

work with live client sites!

CONVIO CONFIDENTAIL

For 403 – Forbidden Status error messages displayed in your browser when attempting to

connect to Convio APIs, check the following:

 sending the request from an IP address that is not white listed under Setup/Site

Options/Open API Configuration

 passing a login_name/login_password to a Server API that is not a valid API

Administrator account

 using an API Administrator account that does not have specific permission for the API

being called (SRTeamRaiserAPI and SRDonationAPI are both disabled by default)

 passing login_name/login_password credentials in the URL rather than in the request

body

An on-line test console at http://open.convio.com/system/api/ is provided via the Convio Open

website, so you can type in API method values and submit them to a real-time instance of

Convio Online Marketing (COM) and view expected return values. A sample screen shot is

provided below: