Class ConvioApiClient

Encapsulates all access to the Luminate Online Open APIs. To access the Luminate Online javascript APIs, you will need to create an instance of this class using this constructor.
Defined in: ConvioApi.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	ConvioApiClient(apiKey, receiverUrl, responseFormat)

Method Summary
Method Attributes	Method Name and Description
	callConsAPI(method, callback, arguments) Calls the specified method on the Constituent API.
	callDonationAPI(method, callback, arguments) Calls the specified method on the Donation API
	callOrgEventAPI(method, callback, arguments) Calls the specified method on the Event API.
	callRecurringAPI(method, callback, arguments) Calls the specified method on the recurring gift management features of the Donation API which are exposed through the CRRecurringAPI servlet.
	callSurveyAPI(method, callback, arguments) Calls the specified method on the Survey API.
	callTeamraiserAPI(method, callback, arguments) Calls the specified method on the TeamRaiser API.
	doSingleSignon(username, password, callback, remember) Perform a single signon login with the Luminate Online powered site.
	getAuthToken(callback) Invokes the Connect API to request an authentication token to be used in subsequent requests and stashes that token in a cookie.
	getLoggedInConsId(callback) Check to see if a user is already logged in or could be automatically logged in based on a remember me cookie.

Class Detail

ConvioApiClient(apiKey, receiverUrl, responseFormat)

Parameters:
{String} apiKey: The value of the CONVIO_API_KEY.
{String} receiverUrl Optional, Default: /api/api_client.html: The relative URL to a static HTML page on the calling domain that hosts the content provided in the api_client.html file.
{String} responseFormat Optional, Default: "xml": The response format (either xml or json) that you would like the API to provide.

Method Detail

callConsAPI(method, callback, arguments)

Calls the specified method on the Constituent API. Note that the update, createOrUpdate, and getUser* methods require that an auth token be passed. These methods will only be available from the Luminate Online powered site hosting the API or from a third-party domain that is listed in the CONVIO_API_CROSSDOMAINS_TRUSTED parameter and require that a previous API call retrieve the necessary token. Note that the create method will only operate against a session that is not currently logged in. The createOrUpdate method will operate against a session that is either logged in or not logged in (provided the auth token has been retrieved). The update and getUser* methods will only operate against sessions that are already logged in.

var api = new ConvioApiClient("open", "/api/api_client.html", "xml");
api.callConsAPI("getUser", getUserComplete, "fields=email,first_name,last_name");
function getUserComplete(responseXML, status) {
  if (status == 200) {
    var email = responseXML.getElementsByTagName("email").item(0).getElementsByTagName("primary_address").item(0).firstChild.nodeValue;
    var first_name = responseXML.getElementsByTagName("name").item(0).getElementsByTagName("first").item(0).firstChild.nodeValue;
    var last_name = responseXML.getElementsByTagName("name").item(0).getElementsByTagName("last").item(0).firstChild.nodeValue;
    alert ("XML Result: " + " primary_email = " + email + ", name = " + first_name + " " + last_name);
    document.getElementById('first_name').value = first_name;
    document.getElementById('last_name').value = last_name;
  }
  else {
    alert ("Error calling API, status = " + status);
    var code = responseXML.getElementsByTagName("code").item(0).firstChild.nodeValue;
    var message = responseXML.getElementsByTagName("message").item(0).firstChild.nodeValue;
    alert ("Error code = " + code + ": " + message);
  }
}

var api = new ConvioApiClient("open", "/api/api_client.html", "xml");
api.callConsAPI("update", updateComplete, document.forms['updateForm']);
function updateComplete(responseXML, status) {
  if (status == 200) {
    var message = responseXML.getElementsByTagName("message").item(0).firstChild.nodeValue;
    alert ('Update successful: ' + message);
  }
  else {
    alert ("Error calling API, status = " + status);
    var code = responseXML.getElementsByTagName("code").item(0).firstChild.nodeValue;
    var message = responseXML.getElementsByTagName("message").item(0).firstChild.nodeValue;
    alert ("Error code = " + code + ": " + message);
  }
}

Parameters:
{String} method: The method to be invoked within the Constituent API family.
{Function} callback: Callback function to handle the results. The callback will be invoked with 2 arguments. The first argument will either be an XML document containing the response or a Javascript object containing the response depending on whether the response format is set to xml or json respectively. The second will be an HTTP status code from the API.
{Object} arguments: The arguments to be passed to the Constituent API. The arguments can be either a String that has already been properly encoded as a set of name/value pairs separated by ampersands as for a typical AJAX call, an array of name/value pairs that will be automatically encoded by the API or a form element that will be interrogated by the API and the various input elements converted into the appropriate format.

Returns:: HTTP status 200 if the call is successful. Status and Error Codes.

See:: More information about the Constituent API

callDonationAPI(method, callback, arguments)

Calls the specified method on the Donation API

Parameters:
{String} method: The method to be invoked within the Donation API family, other than the Recurring Gift managemet methods (CRRecurringAPI).
{Function} callback: Callback function to handle the results. The callback will be invoked with 2 arguments. The first will be an HTTP status code from the API. The second argument will either be an XML document containing the response or a Javascript object containing the response depending on whether the response format is set to xml or json respectively.
{Object} arguments: The arguments to be passed to the Donation API. The arguments can be either a String that has already been properly encoded as a set of name/value pairs separated by ampersands as for a typical AJAX call, an array of name/value pairs that will be automatically encoded by the API or a form element that will be interrogated by the API and the various input elements converted into the appropriate format.

Returns:: HTTP status 200 if the call is successful. Status and Error Codes.

See:: More information about the Donation API

callOrgEventAPI(method, callback, arguments)

Calls the specified method on the Event API. All methods listed are available from any site that can access the javascript libraries as they do not require an authentication token.

Parameters:
{String} method: The method to be invoked within the Event API family.
{Function} callback: Callback function to handle the results. The callback will be invoked with 2 arguments. The first argument will either be an XML document containing the response or a Javascript object containing the response depending on whether the response format is set to xml or json respectively. The second will be an HTTP status code from the API.
{Object} arguments: The arguments to be passed to the Event API. The arguments can be either a String that has already been properly encoded as a set of name/value pairs separated by ampersands as for a typical AJAX call, an array of name/value pairs that will be automatically encoded by the API or a form element that will be interrogated by the API and the various input elements converted into the appropriate format.

Returns:: HTTP status 200 if the call is successful. Status and Error Codes.

See:: More information about the Event API

callRecurringAPI(method, callback, arguments)

Calls the specified method on the recurring gift management features of the Donation API which are exposed through the CRRecurringAPI servlet.

Parameters:

{String} method

The method to be invoked within the Donation API family:

{Function} callback

Callback function to handle the results. The callback will be invoked with 2 arguments. The first argument will either be an XML document containing the response or a Javascript object containing the response depending on whether the response format is set to xml or json respectively. The second will be an HTTP status code from the API.

{Object} arguments

The arguments to be passed to the API. The arguments can be either a String that has already been properly encoded as a set of name/value pairs separated by ampersands as for a typical AJAX call, an array of name/value pairs that will be automatically encoded by the API or a form element that will be interrogated by the API and the various input elements converted into the appropriate format.

Returns:: HTTP status 200 if the call is successful. Status and Error Codes.

See:: More information about the Donation API

callSurveyAPI(method, callback, arguments)

Calls the specified method on the Survey API. Note that the submitSurvey method requires that an auth token be passed, thus is only available from the Luminate Online powered site hosting the API or from a third-party domain that is listed in the CONVIO_API_CROSSDOMAINS_TRUSTED Site Data Parameter and requires that a previous API call be made to retrieve the necessary auth token.

Parameters:
{String} method: The method to be invoked within the Survey API family.
{Function} callback: Callback function to handle the results. The callback will be invoked with 2 arguments. The first argument will either be an XML document containing the response or a Javascript object containing the response depending on whether the response format is set to xml or json respectively. The second will be an HTTP status code from the API.
{Object} arguments: The arguments to be passed to the API. The arguments can be either a String that has already been properly encoded as a set of name/value pairs separated by ampersands as for a typical AJAX call, an array of name/value pairs that will be automatically encoded by the API or a form element that will be interrogated by the API and the various input elements converted into the appropriate format.

Returns:: HTTP status 200 if the call is successful. Status and Error Codes.

See:: More information about the Survey API

callTeamraiserAPI(method, callback, arguments)

Calls the specified method on the TeamRaiser API. Note that all methods other than the getRegisteredTeamRaisers and getFundraisingResults methods require that an auth token be passed and that the user session be logged in. All other methods will only be available from the Luminate Online powered site hosting the API or from a third-party domain that is listed in the CONVIO_API_CROSSDOMAINS_TRUSTED parameter and require that a previous API call retrieve the necessary token.

Parameters:
{String} method: The method to be invoked within the TeamRaiser API family.
{Function} callback: Callback function to handle the results. The callback will be invoked with 2 arguments. The first argument will either be an XML document containing the response or a Javascript object containing the response depending on whether the response format is set to xml or json respectively. The second will be an HTTP status code from the API.
{Object} arguments: The arguments to be passed to the TeamRaiser API. The arguments can be either a String that has already been properly encoded as a set of name/value pairs separated by ampersands as for a typical AJAX call, an array of name/value pairs that will be automatically encoded by the API or a form element that will be interrogated by the API and the various input elements converted into the appropriate format.

Returns:: HTTP status 200 if the call is successful. Status and Error Codes.

See:: More information about the TeamRaiser API

doSingleSignon(username, password, callback, remember)

Perform a single signon login with the Luminate Online powered site. This method will also retrieve an authentication token to be used in subsequent requests and stash that token in a cookie. This method can only be invoked from the Luminate Online powered site hosting the API or from a third-party domain that is listed in the CONVIO_API_CROSSDOMAINS_TRUSTED parameter. To execute a login from a site that does not support this method, you should use the callConsAPI method.

var api = new ConvioApiClient("open", "/api/api_client.html", "xml");
var username = document.getElementById('username').value;
var password = document.getElementById('password').value;
var remember = document.getElementById('remember_me').checked;
api.doSingleSignon(username, password, loginComplete, remember);
function loginComplete(responseXML, status) {
  if (status == 200) {
    cons_id = responseXML.getElementsByTagName("cons_id").item(0).firstChild.nodeValue;
    alert ("XML Result: " + " cons_id = " + cons_id);
  }
  else {
    alert ("Error calling API, status = " + status);
    var code = responseXML.getElementsByTagName("code").item(0).firstChild.nodeValue;
    var message = responseXML.getElementsByTagName("message").item(0).firstChild.nodeValue;
    alert ("Error code = " + code + ": " + message);
  }
}

Parameters:
{String} username: User Name to be used for the login process.
{String} password: The password that is associated with the user name.
{Function} callback: Callback function to handle the results. The callback will be invoked with 2 arguments. The first argument will either be an XML document containing the response or a Javascript object containing the response depending on whether the response format is set to xml or json respectively. The second will be an HTTP status code from the API.
{boolean} remember Optional: Push a "remember me" cookie to the client if the login is successful.

Returns:: HTTP status 200 and the cons_id of the logged in constituent if the call is successful.

getAuthToken(callback)

Invokes the Connect API to request an authentication token to be used in subsequent requests and stashes that token in a cookie. This method can only be invoked from the Luminate Online powered site hosting the API or from a third-party domain that is listed in the CONVIO_API_CROSSDOMAINS_TRUSTED parameter. Note that whenever you login or logout of a session, any previous values that you had obtained for the authentication token will no longer be valid. You will need to call getAuthToken after any call to the login or logout methods on the Constituent API before you can invoke any privileged methods such as update or getUser.

var api = new ConvioApiClient("open", "/api/api_client.html", "xml");
api.getAuthToken (getAuthTokenComplete);
function getAuthTokenComplete(responseXML, status) {
  if (status == 200) {
    var token = responseXML.getElementsByTagName("token").item(0).firstChild.nodeValue;
    alert ("XML Result: " + " token = " + token);
  }
  else {
    alert ("Error calling API, status = " + status);
    var code = responseXML.getElementsByTagName("code").item(0).firstChild.nodeValue;
    var message = responseXML.getElementsByTagName("message").item(0).firstChild.nodeValue;
    alert ("Error code = " + code + ": " + message);
  }
}

Parameters:
{Function} callback: Callback function to handle the results. The callback will be invoked with 2 arguments. The first argument will either be an XML document containing the response or a Javascript object containing the response depending on whether the response format is set to xml or json respectively. The second will be an HTTP status code from the API.

Returns:: HTTP status 200 if the call is successful.

See:: More information about authentication tokens

getLoggedInConsId(callback)

Check to see if a user is already logged in or could be automatically logged in based on a remember me cookie. This method will also retrieve an authentication token to be used in subsequent requests and stash that token in a cookie. This method can only be invoked from the Luminate Online powered site hosting the API or from a third-party domain that is listed in the CONVIO_API_CROSSDOMAINS_TRUSTED parameter. To execute a login from a site that does not support this method, you should use the callConsAPI method.

var api = new ConvioApiClient("open", "/api/api_client.html", "xml");
api.getLoggedInConsId(getLoggedInComplete);
function getLoggedInComplete(responseXML, status) {
  if (status == 200) {
    cons_id = responseXML.getElementsByTagName("cons_id").item(0).firstChild.nodeValue;
    alert ("XML Result: " + " cons_id = " + cons_id);
  }
  else {
    var code = responseXML.getElementsByTagName("code").item(0).firstChild.nodeValue;
    var message = responseXML.getElementsByTagName("message").item(0).firstChild.nodeValue;
    if (code == 16) {
      alert ("Nobody is logged in");
    }
    else {
      alert ("Error calling API, status = " + status);
      alert ("Error code = " + code + ": " + message);
    }
  }
}

Parameters:
{Function} callback: Callback function to handle the results. The callback will be invoked with 2 arguments. The first argument will either be an XML document containing the response or a Javascript object containing the response depending on whether the response format is set to xml or json respectively. The second will be an HTTP status code from the API.

Returns:: HTTP status 200 and the cons_id of the logged in constituent if the call is successful and the session is logged in. HTTP status 403 and error code 16 (record not found) if nobody is logged in.