Online Help

 Help Table of Contents

Configuring your Site for Convio Open APIs

This help page covers the following topics:


Overview

The use of any Convio Open APIs, including Convio Web Services, requires a degree of site configuration to enable and control API access. The Open API Configuration tool for site administrators performs some automatic configuration, and assists with manual configuration of a site for API access. The Open API Configuration tool is also used to manage cross-domain access to the Open APIs from JavaScript and Flash clients, and allows logging of Open API calls and downloading/viewing of log files.

Convio Open APIs and Convio Web Services permit clients to integrate features and functionality of the Convio platform into other web server applications or web page content. These APIs can be divided into main categories based on how they are accessed. Each category offers slightly different features and has different configuration requirements. These three categories are:

  • Convio Open APIs (Client): REST-style APIs intended to be accessed directly from a constituent’s web browser using client-side scripting. These APIs are the easiest to use, requiring no server-side programming. They are typically called either in the session context of logged-in constituent or as an anonymous user. The information they can access is limited to protect the privacy and security of client and constituent data.
  • Convio Open APIs (Server): REST-style APIs for use by other application servers. Some are administrator-context corollaries to the Client APIs described above. These APIs respond only to secure requests from trusted IP addresses, and require valid API Administrator credentials with each request. As such, they are able to expose more functionality than anonymous client APIs can.
  • Convio Web Services: SOAP-protocol APIs for use by SOAP consumers such as .NET or Java enterprise servers. These are the lowest-level APIs exposed by the Convio platform and as such require session security. Originally designed to provide Data Synchronization services, these versatile and powerful APIs can also be used for other purposes.

The Open API Configuration tool allows a site administrator to easily configure access for any or all of these API categories.


Accessing the Open API Configuration Tool

To access the Open API Configuration tool:

  1. Log in to Convio as an administrator.
  2. Go to Setup->Site Options.
  3. Click the Open API Configuration tab.

A dashboard screen will open showing the configuration status of the various Convio API options. Some of these will be configured automatically by the Open API Configuration tool. Configured options appear in green next to a checkmark, while options that are not yet configured appear in red beside an "X." Note: Not all options must be configured for all API access methods.

The sections of the dashboard correspond to different access methods. Edit the settings for each section by clicking the link next to the section heading. The sections available are:

  • Configure API Keys -- Use this section to configure the site for either client-side or server-side REST-style API access and for Convio Web Services Access. Note: if you wish to use server-side REST-style APIs, you must also define the options under the "Configure API to allow server access" section.
  • Configure API to allow server access -- Use this section to list the addresses of servers authorized to access the Convio Open APIs (Server), and to create API administrative accounts to control access via Convio Open APIs (Server) and Convio Web Services.
  • Configure JavaScript/Flash access to Open APIs -- Use this section to control cross-domain access from web pages containing the Convio Open API JavaScript class library, or from Flash applictions that reference Convio’s cross-domain policy files (crossdomain.xml).
  • Configure AJAX proxy service -- Use this section to designate external domains to which Convio may proxy AJAX JavaScript requests.
  • Configure Web Services -- Use this section to configure the Convio Web Services SOAP-protocol APIs.


Understanding the Open API Configuration Screens

Click the corresponding Edit action on the main Open API Configuration page to access and configure the following pages.

Open API Keys

These API keys must be configured to allow access through any of the REST-style Convio Open APIs (Client), Convio Open APIs (Server), or the Convio Web Services SOAP-protocol APIs. The available options are:

  • Convio API Key -- This key is an arbitrary value that must be passed as the value of the api_key parameter when invoking Convio Open APIs either from a server script or web form. This is not a secure password and it may be included in a hidden field of a web form.
  • Convio API Secret Key -- This key is an arbitrary value that will be used by Convio APIs to sign responses. This key should never be passed in API requests directly and should be a reasonably complex string. It is used by the Convio server along with additional data to generate a secure hash signature on redirect responses to API calls when the sign_redirects aparameter is used.
  • Generate a new Secret Key -- If the value of your secret key has been compromised, click this button to generate a new one.
  • Digital signature encryption algorithm -- Determines the encryption method when the option to sign_redirects is used with API calls. The default is MD5, but SHA-1 offers a more secure encryption algorithm.
  • Single Sign-On APIs -- Check this box to enable the singleSignOn method, which allows a trusted external server to log a Convio constituent into the Convio server using a token returned by the SRConsAPI:getSingleSignOnToken API. Clearing this check box disables singleSignOn (Convio as client).


Open API Server API Configuration

This screen allows site administrators to designate which external systems have access to Convio Open REST-style APIs by adding them to the Convio API IP White List.

Note: The IP White List only permits access to the Convio Open API (Server) REST-style interfaces. Convio Web Services SOAP APIs use a different IP White List, and Open API (Client) interfaces allow connections from any IP.

The available options are:

  • Add New IP Range to List -- Specify the IP Range for servers authorized to access the Open API (Server) interfaces using CIDR notation.
  • Add Current IP Address to list -- This button automatically adds the IP address of the system on which you are running the Convio Admin application to the White List. This can be useful for testing.
  • Remove Selected IP Range -- This button removes selected server IP ranges from the White list.
  • API Administrative Accounts -- Set up accounts for both the Convio Web Services SOAP APIs and to the Open API (Server) REST-style APIs. These are not used by the Open API (Client) REST-style APIs, which may be accessed anonymously. These accounts are automatically added to the API Administrators Group.

Privileges granted the API Administative Accounts group through the Open API (Server) and Convio Web Services interfaces may be administered elsewhere. To view or update the privileges granted to the API Administrators Group:

  1. Log in to Convio as a system administrator.
  2. Go to Constituent360->Groups.
  3. Click the Administrator Group List tab.
  4. Next to the "API Administrators" group, click Edit Permissions.
  5. From the "Choose Permission Type" dropdown box, select Data Synchronization.
  6. Update the permissions as needed, and click Save when done.


JavaScript and Flash Configuration

Use this page to control cross-domain access from other domains that host Web pages containing the Convio Open API JavaScript class library. These settings also determine how Flash applications hosted on external domains may access the APIs using Convio’s cross-domain policy files (crossdomain.xml). You can grant different levels of access (basic or trusted) to different domains.

Options on this page are:

  • Allow Javascript/Flash API from these domains -- List any external domains which should have basic access. These domains will be able to create constituents (but not update) and retrieve public data. The list should be comma separated and can include wildcards (e.g. *.convio.com).
  • Trust Javascript/Flash API from these domains -- List any external domains which should have trusted access. Scripts hosted from these domains will be able to retrieve an authorization token for use with the Convio APIs. Trusted domains will be able to retrieve personal information about constituents and update constituent data.
  • Minify Javascript files -- Set to TRUE (recommended and default) to minify the Convio API javascript files when they are generated. The minified versions will load faster and improve overall user experience. The only reason to not minify the javascript files is so that you can run the javascript using a debugger.
  • Require Flash files to be served securely -- Set to TRUE (recommended and default) if any Flash movie (.swf file) that is used to access the APIs must be retrieved from a secure URL. Note that this is the URL for the .swf file itself, not the page on which it is hosted.

These settings apply only to JavaScript or Flash access to Convio Open APIs (Client). They do not apply Server APIs or to Convio Web Servcies.


AJAX Proxy Configuration

Use this page to designate other domains from which services may be proxied through the Convio web server.

Options on this page are:

  • AJAX Proxy Allowed Domains -- Use this field to specify a list of domains to which Convio may proxy AJAX requests.
  • Forward cookies -- Set this flag to forward cookies to proxied services (note restrictions).
  • Pass arguments through template rendering -- Set this flag to accept Convio template expressions as tags in script requests from clients and render them before passing the result to the proxied service.
  • Maximum input body length in MBytes -- Use this value to limit the size of the request that Convio will pass to the proxied service.


Convio Web Services API Configuration

Convio provides a set of SOAP-protocol Web Services, designed originally to support data synchronization of the Convio constituent database, but useful for other types of database-level acess. These services are implemented and administered differently from the other (REST-style) Convio Open API interfaces. This screen supports the configuration of Convio Web services. The system administrator must specify the IP range of servers allowed to access Convio Web Services. The administrator can also quickly generate a default partition of the Convio database for access through Convio Web Services, restricting access to data on only those constituents who are not site administrators. None of the settings on this page are applicable to the REST-style Convio Open APIs.

Options on this page include:

  • Convio Web Services URI -- Set this field if the Convio Web Services process runs on a separate system from the Convio Website. Otherwise, leave this field blank.
  • Convio Web Services IP White List -- Designates servers which may access Convio Web Services.
  • Add Current IP Address to list -- Optionally, use this button to automatically add the IP address of the system on which you are running the Convio Admin application to the White List.
  • Remove Selected IP Range -- Use this button to remove servers from the IP White List by clicking the server’s IP range in the list to highlight it, then clicking the button.
  • Create Default Partition -- You must create a partition for Convio Web Services. Click the Create button to automatically create a default database partition that may be accessed via Convio Web Services. The default partition includes data for all constituents except for administrator accounts. If you prefer to use a custom partition, you must set up a custom partition by clicking Data Management on the main menu, selecting Import/Export, and choosing the Partition Management tab.


Configuring or Viewing API Logs

Use the Configure or View API logs page, located under Related Actions, to enable various levels of logging for debugging and trouble-shooting purposes and to view the generated log files. One file is maintained for each instance of the Convio web server running for any given Convio Website (one for each JVM).

Convio API Logging Level -- Controls what requests and responses are logged:

  • OFF (no logging)
  • ERROR (log only errors)
  • INFO (log request parameters and responses)
  • DEBUG (most detailed logging)

For performance reasons, INFO and DETAIL logging are typically used only in development and debugging, whereas ERROR logging or OFF may be used in day-to-day operation. Log file size is limited to a 1MB file with one backup (2MB total log size per site, per JVM), to guard against a potential out-of-memory condition in the event that logging is accidentally left on.

These logs and settings apply only to the REST-style Convio Open APIs. They do not apply to Convio Web Services.

 

Glossary

The following terms may be useful when working with this application.

AJAX -- an acronym for "Asynchronous JavaScript and XML," is a programming style that uses JavaScript or other scripting language to asynchronously process XML-format requests and responses from a web server without reloading the current web page. This style of programming is popular because it can mimic the behavior of native applications in a browser-based web application.

API -- an abbreviation for "Application Programming Interface," is an interface that is primarily intended to allow another piece of software, rather than a human user, to interact with the service that exposes it.

REST -- an acronym for "Representational State Transfer." Convio Open APIs (except for Convio Web Services) use a REST-style interface in which parameters are passed via HTTP POST request to the interface URI, and results are returned as either XML or JSON documents.

SOAP -- an acronym for "Simple Object Access Protocol." Convio Web Services use this protocol, in which structured requests and responses are passed as XML request and response documents. Both .NET and Java development platforms provide native support for this protocol.

Client APIs -- APIs typically used by codes or scripts running in a web browser.

Flash -- a scripting language from Adobe that offers rich multimedia and graphics capabilities.

JavaScript -- a scripting language based on Java, typically used to write code that runs in a web browser.

Server APIs -- APIs typically used by codes or scripts running on another server which proxies requests and results from Convio to its clients’ web browsers.

POST URI -- the POST URI for your server is used as the base URI for the REST-style Convio Open APIs. You can find the correct POST URI for your Convio system by opening the login page in your browser, viewing the source of the page, and searching for the <FORM> tag. The action attribute of this tag will contain the POST URI, which will look similar to:

<form action="https://secure2.convio.net/yoursitename/site/ ... >

Back to Top of Page 

Scenarios

The following scenarios describe the steps necessary to configure and verify access through the Convio Open APIs, including Convio Web Services.

Configuring and testing access via Convio Open APIs (Client)

This scenario describes how to set up and verify the configuration of the Convio Open APIs (Client) on your Convio site. This tool will automatically set up an API Key, which you may modify. You will need to supply this key when invoking the Client APIs.

  1. Log in to Convio as an administrator.
  2. Go to Setup->Site Options.
  3. Click the Open API Configuration tab.
  4. In the Configure API Keys section, click the Edit API Keys link.
  5. Note the value automatically generated for the Convio API Key. You must supply this value in the api_key parameter when calling any of the Convio Open APIs. If you want to use a different key, change the Convio API Key value here.
  6. Click Finish to complete the Client API configuration.

To test your configuration:

  1. Determine your Convio site’s POST URI. One way to do this opening your Convio site’s Login form in a browser.
    1. Open your Convio site’s Login form.
    2. Select View->Source from the browser menu.
    3. Search for the <form action= tag. It will contain a URI that resembles
      https://secure2.convio.net/yoursite/site/

  2. Modify this URI, appending the name of the Constituent Client API:
    https://secure2.convio.net/yourSiteName/site/CRConsAPI/

  3. Copy the following into a text file, and change the FORM action= attribute to the correct POST URI for your server:

    <HTML>

     

    <FORM
    action="https://secure2.convio.net/yourSiteName/site/CRConsAPI/"
    method="POST" >
    Method: <INPUT name="method" type="text" value="listUserFields"><BR />
    Version: <INPUT name="v" type="text" value="1.0"><BR />
    API Key: <INPUT name="api_key" type="text" value=""><BR />
    <BR />
    <INPUT type="submit" value="Send">
    </FORM>
    </HTML>
  4. Save the file with an HTML file extension.
  5. Open the file in your browser.
  6. Fill in the API Key value from steps 5 of the site configuration above.
  7. Click Send. If your Client API configuration is correct, you will see a response similar to the following:

    - <listConsFieldsResponse xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd" xmlns="http://convio.com/crm/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    - <field>
    <name>accepts_postal_mail</name>
    <label>Accept Mail</label>
    <required>false</required>
    <valueType>BOOLEAN</valueType>
    </field>
    - <field>
    . . .

Configuring and testing access via Convio Open APIs (Server)

This scenario describes how to set up and verify the configuration of the Convio Open APIs (Server) on your Convio site. This tool will automatically set up an API Key, which you may modify. You will need to supply this key when invoking the Client APIs. You will also have to specify the IP addresses of the servers permitted to access these APIs in the IP White List, and create one or more API Administrator accounts to use when accessing the Server APIs.

  1. Log in to Convio as an administrator.
  2. Go to Setup->Site Options.
  3. Click the Open API Configuration tab.
  4. In the Configure API Keys section of the dashboard view, note the value of the API Key You must supply this value in the api_key parameter when calling any of the Convio Open APIs.
  5. In the "Configure API to allow server access section," click the Edit server API configuration link.
  6. In the Convio API IP White List section, add the IP address ranges for any servers that will use the Server APIs.
  7. To test the Server API configuration, also add your own IP address by clicking the Add Current IP Address to List button (you can remove it later).
  8. Under Manage API Administrative Accounts, add at least one user as API Administrator. You must supply an API Administrator user’s credentials in the user_name and password parameters of all Server API calls.
  9. Click Finish to complete the Server API configuration.

To test your configuration:

  1. If you have not done so, add the IP address of your test system to the Convio Open API IP White List as described above.
  2. Determine your Convio site’s POST URI. One way to do this opening your Convio site’s Login form in a browser.
    1. Open your Convio site’s Login form.
    2. Select View->Source from the browser menu.
    3. Search for the <form action= tag. It will contain a URI that resembles
      https://secure2.convio.net/yoursite/site/

  3. Modify this URI, appending the name of the Constituent Server API:
    https://secure2.convio.net/yourSiteName/site/SRConsAPI/

  4. Copy the following into a text file, and change the FORM action= attribute to the correct POST URI for your server:

    Note: The following form is intended only for testing your API configuration. Do not include login_user and login_password credentials on a site web page where the credentials would be visible to an attacker. Server API calls are permitted only from white-listed systems to your Luminate Online site.

    <HTML>
    <FORM
    action="https://secure2.convio.net/yourSiteName/site/SRConsAPI/"
    method="POST" >
    Method: <INPUT name="method" type="text" value="listUserFields"><BR />
    Version: <INPUT name="v" type="text" value="1.0"><BR />
    API Key: <INPUT name="api_key" type="text" value=""><BR />
    API Admin User: <INPUT name="login_user" type="text" value=""><BR />
    API Admin Password: <INPUT name="login_password" type="text" value=""><BR />
    <BR />
    <INPUT type="submit" value="Send">
    </FORM>
    </HTML>
  5. Save the file with an HTML file extension.
  6. Open the file in your browser.
  7. Fill in the API Key, API Admin User and API Admin Password fields from steps 4 and 8 of the site configuration, above.
  8. Click Send. If your Server API configuration is correct, you will see a response similar to the following:

    - <listConsFieldsResponse xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd" xmlns="http://convio.com/crm/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    - <field>

    <name>accepts_postal_mail</name>

    <label>Accept Mail</label>

    <required>false</required>

    <valueType>BOOLEAN</valueType>
    </field>
    - <field>
    . . .

Configuring and testing access via Convio Web Services

This scenario describes how to set up and verify the configuration of Convio Web Services on your Convio site.

  1. Log in to Convio as an administrator.
  2. Go to Setup->Site Options.
  3. Click the Open API Configuration tab.
  4. In the "Configure API to allow server access" section, click the Edit server API configuration link.
  5. Under Manage API Administrative Accounts, add at least one user as API Administrator. You must supply an API Administrator user’s credentials in the user_name and password parameters of all Server API calls.
  6. Click Finishto return to the dashboard page.
  7. In the "Configure Convio Web Services" section, click the Edit Web Services configuration link.
  8. Under Convio Web Services IP White List, add the IP address ranges for any servers that will access Convio Web Services.
  9. To test the configuration, also add your own IP address by clicking the Add Current IP Address to List button (you can remove it later).
  10. Click the Create Default Partition button to automatically generate a database partition for use by Convio Web Services.
  11. Optionally, rather than create a default partition, you may creaate a custom partition:
    1. Click Data Management on the main menu.
    2. Select Import/Export.
    3. Choose the Partition Management tab.
  12. Click Finish to complete the Convio Web Services configuration.

To test your configuration:

  1. If you have not done so, add the IP address of your test system to the Convio Web Services IP White List as described above.
  2. If Convio Web Services is enabled for your site and if the address of your test system appears in the IP White List, you will be able to access the web services definition (WSDL) from a web browser running on your test machine at the URI: https://[web services hostname]/1.0/[site code]/wsdl where [web services hostname] and [site code] are values assigned by Convio when Web Services was enabled.
  3. Load the Convio Web Services Console URI using a web browser. The URI of the console is https://[web services hostname]/1.0/[site code]/console
  4. Enter the Username and Password for the API Administrator account you set up during the configuration, and click the Login button.
  5. If Convio Web Services has been correctly configured, the Response status should indicate "Success."

Back to Top of Page