Convio Web Services, General Availability

Kevin Suer

Feature Summary

Release: CWS Version 1.7

Author: Kevin Suer

Overview

As part of its Open product strategy, Convio is introducing Convio Web Services (CWS) in November 2009 to allow application developers to programmatically integrate with and extend the Convio Platform.  This document provides a high-level overview of this exciting new API.  For detailed technical documentation on Convio Web Services, please visit open.convio.com and click on “Web Services”.

Why CWS?

If you are evaluating whether or not CWS will be useful to you, keep in mind that Convio had two primary uses envisioned for this new product when designing it:

• To enable you to build custom data integration applications that synchronize constituent and transactional data between Constituent360 and your offline database.
• To enable you to build custom data retrieval, update, and reporting applications, like as the Convio Data Viewer Sample Application.
  

Key Features

• Bulk Access to Constituent Data: CWS provides full access to all of your constituent data (all records and fields) stored and enabled in Constituent360.  You can use CWS operations to:
  • Create constituents
  • Update constituents
  • Delete constituents
  • Download (all/new/updated/deleted) constituents
• Bulk Access to Transactional Data: CWS provides extensive access to your transactional data stored in Constituent360. Perform the following bulk actions:
  • Download (all/new/updated/deleted) Action Alert Responses
  • Download (all/new/updated/deleted) Calendar Event Ticket Purchases
  • Download (all/new/updated/deleted) Donations
  • Download (all/new/updated/deleted) eCommerce Product Orders
  • Download (all/new/updated/deleted) Personal Fundraising Gifts
  • Download (all/new/updated/deleted) Survey Responses
  • Download (all/new/updated/deleted) TeamRaiser Registrations
  • Download (all/new/updated/deleted) TeamRaiser Gifts
• Bulk Access to Metadata: For all data accessible via the API, either Constituent or Transactional, CWS provides extensive access to metadata.  Perform the Query or Find action to retrieve the most salient data attributes for many of the objects stored in Constituent360, including:
  • Action Alerts and ResponsesConstituents
  • Calendar Events
  • DataSync Cross Reference Types and Values
  • eCommerce Orders, Items, Products, Discounts
  • Donation Campaigns, Forms, and Levels
  • Groups and Group Types
  • Interaction Sources
  • Interests
  • Personal Fundraising Campaigns, Champions, and Gifts
  • Survey Responses, Questions, and Answers
  • TeamRaiser Events, Gifts, Companies, Participation Types, Registrations, and Teams
  • Please note: A full data dictionary of fields available through CWS is available in the Convio Web Services API Reference document located at http://open.convio.com/webservices/#types. Navigate to the “Types” sub-bullet in the left navigation panel for a full listing of fields by data type.
• Sample Application: Along with the new API, Convio has made available a sample desktop application, which we are calling the “CWS Data Viewer Sample Application,” that shows how you can use Convio Web Services to implement a custom client for retrieving and reporting on your data, in this sample Donations and eCommerce data. Source code is provided with this application to serve as a reference for programmers using CWS.  This sample application is provided ‘as-is’ and is not supported by Convio.  The application was built using Adobe AIR, a runtime environment for running Internet applications outside the browser on Windows, Mac OS and Linux and requires that your Convio Site is enabled for Convio Web Services. To use the application, go to the site listed below after you’ve had CWS enabled on your site and click on the link to download, install, and launch it.
  • http://open.convio.com/webservices/conviodataview/
• Constituent Partitions: Partitions enable you to segment your Constituent360 database by only those constituents relevant to the business processes supported by the systems being synchronized.  Constituents can be added or removed from Partitions individually, or in bulk through partition recalculation.  Partitions are defined prior to using Convio Web Services.
• Synchronization Logs Operations: “GetSynchronizationRequestLog” and “GetSynchronizationSessionLog” operations provide data logs for troubleshooting or summarizing your synchronization sessions.
• Collision Detection: CWS is able to recognize and flag collisions whenever a change is made to the record on both the client and server system since the last synchronization.
• Query Group Membership and Interest Assignment: For each constituent in the synchronized partition, CWS can detect a listing of all Groups that a constituent belongs to or Interests they are assigned to.
• CWS Administrator Console: The CWS Administrator Console provides a web-based user interface for testing requests and responses from CWS.

Screen Captures

Figure 1: Convio Web Services Console.

Figure 2: Open API Configuration Page; this page is available to Site Administrators.

Figure 3: New “Edit Center-Level Options” link on Center Admin Homepage.

Limitations

The following is a listing of known limitations for Convio Web Services.

• Full Set of Transactional Data: There are several types of transactional data not presently included in CWS.  These include:
  • Download (all/new/updated/deleted) Calendar Events RSVPs
  • Download (all/new/updated/deleted) Email Transactional Data
  • Download (all/new/updated/deleted) Personal Events Data
  • Download (all/new/updated/deleted) Call Alert Data
  • Download (all/new/updated/deleted) Letter to the Editor Data
  • Download Reporting and Aggregate Summary Statistics
• Upload Transactional Data: There is no ability to upload transactional data into Convio through CWS.
• Group and Interest Change Tracking: It is not possible to use any of the GetIncremental operations to download changes in constituent group and interest assignment.
• Field-Level Change Tracking: It is not possible to detect and download individual field level changes for either Constituents or Transactional Data.

FAQs

Getting Started

When will Convio Web Services be available?

Convio Web Services will be available for use by Convio clients starting on November 16, 2009.

Will there a monthly product license fee or SKU for clients to use Convio Web Services?

No.  This API enables you to gain access to your data and gives you the freedom to work with it in whatever manner you require.  As part of the Open Initiative, Convio does not charge setup or ongoing fees for API access to your data.

How do I request access to Convio Web Services?

Contact your Convio Account Manager.  Your Account Manager will consult with you on your intended use of CWS, provide you an overview of our optional Service offerings, and then initiate an activation request for your Site.

How long should I expect it to take for Convio Web Services to be activated from the time I request activation?

Please expect a six business day turn-around time from Convio IT after submitting your case.  Please set expectations with clients accordingly.

CWS seems like a powerful API, what doesn’t it do? 

CWS is powerful, but please make sure to read about the key limitations of the API in the Limitations section of this document.  Also, the API Reference Document (http://open.convio.com/webservices/#main) is the authority on whether a particular field is, or is not available.  If you do not see the field you are looking for available in that document that means it is not yet available through CWS.  If this is the case, please notify your Account Manager, who will log a product feature request (FR) for CWS.  All CWS FRs are evaluated by Convio Product Management for inclusion into CWS in a future product release.

Support

Does Convio provide online help documentation for CWS?

Yes.  To access online help documentation, including an API Reference document, go to open.convio.com and click on “Web Services” or click here: http://open.convio.com/webservices/apidoc/.

What if I have a question about using CWS, who should I contact?

We strongly encourage you to post all of your questions right here in the Convio Community by going to the following link, http://community.customer.convio.com/community/convioopen/cws, in the Web Services Subcommunity.

Can I call Convio Support or open a case?

Convio offers two levels of support for CWS.  Learn more about Support in the Optional Services section of this FAQ.

• Free Basic Support: If you are a Convio Authorized Administrator you can call support and open support cases for CWS.  Convio Support will be able to help you ensure that the API is behaving as expected for you.  Please note, Free Basic Support will not provide you with consultation, advice, or guidance on how to implement your application code, it will only confirm for you that the API is working as intended within the scope of existing CWS product capabilities.
• Paid Developer Support: This premium level of support provides individual named application developers (looking for code-level support using Convio Web Services) with unlimited phone and email support from a certified Convio Development Support professional.  This support includes How-to help, Code support, Sanity Checks, Error message troubleshooting, Clarification of API Documentation, and Analysis and debugging of application CWS calls (up to 200 lines).

How frequently are new versions of CWS released?

New versions of Convio CWS are released roughly once every few months.

Where can I learn more about new releases?

If you are enabled to use CWS, we will notify you of all new CWS releases.  If you are not enabled for CWS, or want to learn more about new CWS release, go to open.convio.com, click on “Web Services” and sign up for the Convio Web Services email newsletter, which includes new release notifications.

Optional Services

What additional services I can purchase from Convio in conjunction with use of Convio Web Services?

Convio offers you two new services with the release of CWS.  There is no prerequisite to buy services packages to get CWS enabled and clients can access online forums about CWS in the Convio Community about CWS to post questions and chat with each other.

•    Convio Developer Support (CDS): Recommended for anyone doing any programming to CWS or other Open APIs.

•    CWS DataSync Orientation: Recommended for clients undertaking larger data sync projects.

What is Convio Developer Support work?

Application developers are a new category of user of Convio which requires distinct new technical support services. Convio plans to continue to make significant investments in the Open Initiative throughout 2010, expanding CWS, and opening its Data Integration technologies to partners all of which will be used by application developers, thereby driving increasing needs for developer support.

Convio Developer Support (CDS) is available to licensed clients, partners, and other 3rd parties operating on their behalf, and provides individual named application developers looking for code-level support using Convio Web Services unlimited phone, chat, and web case support from a certified Convio Development Support professional.  This support includes How-to help, Code support, Sanity Checks, Error message troubleshooting, Clarification of API Documentation, and Analysis and debugging of application CWS calls (up to 200 lines).  CDS commits to reply within 1 business day of the submission of a request during standard Convio support hours.

How much does Convio Developer Support cost?

CDS costs $100 per Named Developer per Month.  You are required to purchase at a minimum of three-months.

When should I consider buying Convio Developer Support?

If you contact support and request any services outlined in the description of Convio Developer Support above, your Convio Support Representative will determine whether you have a Convio Developer Support agreement and redirect you to Convio Developer Support, or, if not, redirect you to your Account Manager to purchase the agreement.

What is a CWS DataSync Orientation?

CWS DataSync Orientation (SKU number TS-23) places you in contact with a Convio Data Integration consultant for 6 hours of education in applying Convio Web Services to your data integration project and being available for questions about DataSync Web Services.  The engagement will be limited to 6 calendar weeks following the kickoff call.  This orientation will consist of:

•    A review of the DataSync Web Services documentation

•    A discussion of key data integration concepts and best practices

•    Availability to answer Client questions about DataSync Web Services for the duration of the 6-week engagement

The subject matter covered by the engagement will be limited to data integration concepts and best practices and to the functioning of the underlying Convio DataSync Web Services APIs.  Programs created by clients or their partners to work with Convio DataSync Web Services are not covered by this engagement.

If additional Service hours in excess of the limits specified herein are required in order to complete this Service in accordance with Client requirements, additional hours may be provided by Convio if requested and approved by Client in advance (email approval acceptable).  Any such additional hours will be charged in accordance with the Rate Card attached hereto and paid by Client in accordance with the Agreement.

How much does it cost?

TS-23: CWS DataSync Orientation costs $1,200.

When should I consider buying Data Integration Consultation for CWS?

If you call the standard support line, your account manager, or have requested any services outlined in the description of CWS DataSync Orientation above you should consider this service.

Am I ever required to buy Developer Support or Data Integration Consultation?

No.

Convio Data Viewer Sample Application

How do I get access to the Convio Data Viewer?

After you have had your Convio Site activated for CWS, simply go to open.convio.com, click on “Web Services”, and then click on the link for the Convio Data Viewer (http://open.convio.com/webservices/conviodataview/) to download and install the application.

What are the PC system requirements to use the Convio Data Viewer?

The Convio Data Viewer runs on Adobe AIR and has the following system installation requirements.

Windows

• Intel® Pentium® III 1GHz or faster processor, 512MB of RAM
• Recommended: Pentium 4 2GHZ or faster, 1GB RAM
• Windows Vista® Home Premium, Business, Ultimate, or Enterprise including 64 bit editions, Windows Vista SP1, Windows XP Tablet PC Edition SP2 and SP3, Windows XP SP2 and SP3, Windows 2000 SP4, Windows 2003 Server

Mac OS X

• Intel Core™ Duo 1.83GHz or faster processor; PowerPC® G4 1GHz or faster processor
• Mac OS X 10.4.11 or Mac OS X 10.5.4 and 10.5.5
• 512MB of RAM

Linux

• Intel® Pentium® III 1GHz or faster processor, 512MB of RAM
• Recommended: Pentium 4 2GHZ or faster, 1GB RAM
• Fedora 8, Ubuntu 7.10, openSUSE 10.3

Will Convio be releasing new versions of the Convio Data Viewer?

No.  The existing version is the last version of the Convio Data Viewer that Convio will release.  Besides being a useful reporting application for tracking your online donations with Convio, the primary intention of the application is to serve as a reference, with open source code, for you to innovate and build similar applications onto of Convio.

Is the source code of the Convio Data Viewer open and freely available?

Yes, it will be made available on open.convio.com.

What is my login information to the Convio Data Viewer?

In order to log into the Convio Data Viewer, the following information will be requested from you:

• Web Services URL: In order to find this information for your Convio site, contact your Convio site administrator would will need to navigate to “Setup” in the top navigation menu, then click on “Site Options” and then click on “Open API Configure”.  On the page, take the URL first listed under the “Configure Convio WebServices” section and append “/wsdl/” to the end of it.  For example, if your URL says “https://conviotest.corp.convio.com:443/1.0/convio” then the Web Services URL you want to use in the Convio Data Viewer application is: https://conviotest.corp.convio.com:443/1.0/convio/wsdl/
• User name and Password: You will need to create specific administrators in Constituent360 with permission to use the Convio Data Viewer.  In order to do this, contact your site administrator (who has access to your Convio Site as a Site Admin) and have them create a new administrator with the following permission:
  • Contact Management: Use Convio APIs
• The administrator user name and password for this administrator is the user name and password for the Convio Data Viewer.  It is recommended you create an Administrator Security Group that you label as “Convio Data Viewer Users” who are the individuals that have access to the Convio Data Viewer.

Can I set up additional logins to the Convio Data Viewer myself, without asking Convio Support?

Yes.  Any Site Admin on your Convio Site can access and view the URL mentioned in the question above, as well as create the necessary administrator accounts on your Site.

What if I notice a problem with the sample application?

This sample application is provided ‘as-is’ and is not supported by Convio.  If you notice a problem with the sample application you can notify the Convio Community about it, and the Community should feel empowered to fix or enhance it, but Convio Engineering will not resolving any defects, issues, or enhancement requests that may exist related to the sample application.

Data Synchronization

Can I use CWS to integrate between Convio and my offline database?

Yes.  This is one of the two primary applications of CWS.

How many databases do you recommend I synchronize with?

While there is no enforced limit, attempting to synchronize more than one database with Convio greatly increases complexity and the chance for older data to overwrite newer data.  Always keep in mind that Convio is designed to be a “spoke” feeding into the “hub” of your database of record.  Convio Online Marketing is not setup to handle the complex sorts of collisions that can occur when positioned as a hub of integration between multiple external systems.

What is a Partition?

A partition defines the set of constituents in the Convio database to synchronize with a client system. In the most common scenario, all constituents are synchronized; in some cases, the exchange of constituent information must be restricted to a specific subset. For example, if you are synchronizing a donor database with Convio, you may synchronize only those constituents who have a mailing address or who have made at least one donation, as did Claire in the Use Scenario of this document.

The Convio system automatically tracks partition membership according to the criteria you specify. If you define a partition that includes all constituents, then the Convio system will add constituents immediately when they register. If you define a partition that includes only a subset of all constituents, the Convio system will check each time a constituent record is updated, and add or remove the constituent from the partition as appropriate.

Creating and managing partitions

Partition management is part of the Convio CRM administration interface:

1.    Choose Import/Export from the Data Management menu

2.    Click the “Partition Management” tab

That page lists available partitions and allows you to edit, copy and delete them, and to manage their membership.  Below is a screen capture showing all Partition configuration options available in Partition Management.

What criteria are available for creating constituent partitions?

The three primary sets of criteria that are available for defining a partition are listed below.

• Constituents who are members of selected Centers
• Constituent who matches specified Query results (excluding any Query that has a Group clause)
• Constituents who performed none, any, or all of the following interactions:
  • Made a donation
    
  • Purchased tickets for an event
  • Registered for an RSVP event
  • Made an eCommerce purchase
  • Took an advocacy action
  • Registered for a TeamRaiser event
  • Created a Tribute fund
  • Hosted a Personal Event
  • Submitted a survey
• Constituents with none, any, or all of the following specific constituent record attributes:
  • Constituents must have a full name and home address. 
  • Constituents must have a usable email address. 
  • Exclude administrators from this partition. 

Glossary

• API: Stands for Application Programming Interface (API) type of interface used by software programs to interface with Convio Online Marketing, much like the Graphical User Interface (GUI) is a type of interface used by real people to interface with Convio Online Marketing.
• Consume: v. To use Convio Web Service operation(s).
• CWS: Commonly used acronym for “Convio Web Services”.
• Operation: An action supported by Convio Web Services.
• Partition: A set of constituents in Constituent360 who are synchronized with an offline database; partitions are used in conjunction with Convio Web Services synchronization sessions.
• WSDL: Pronounced ‘wiz-dəl’, this is an acronym for Web Services Description Language.  Defines the complete data and functional specification of Convio Convio Web Services.

##END