CiviService for Google Script is a library for Google Apps Script that provides the ability to interact with your CiviCRM's REST API. This library is designed to work with code samples generated by the CiviCRM API Explorer.

Note: This library is designed to mimic the CiviCRM API AJAX Interface including the done method which allows copy and paste from the CiviCRM API Explorer but the library actually uses the CiviCRM API REST Interface

For an example project that sets up and uses CiviService for Google Script see this blog post which uses a Google Forms to submit events. Responses are validated in a Google Sheet and be created as a CiviEvent on our site.

This library is already published as a Google Script, making it easy to include in your project. To add it to your script, do the following in the Google Apps Script code editor:

1. Click on the menu item "Resources > Libraries..."
2. In the "Find a Library" text box, enter the script ID 1rlzPrAGx2acG1DHAMqZ1egJh6Y9OqUq3cy8e8AwDjLFGfqmr-hQR0YLq and click the "Select" button.
3. Choose a version in the dropdown box (usually best to pick the latest version).
4. Click the "Save" button.

Alternatively, you can copy and paste the files in the /dist directory directly into your script project.

To use this library in your Google Script project requires some basic setup with your CiviCRM installation and script project. For information please follow the CiviCRM Setting up to use the REST API. When using the CiviService Google Script Library you have two choices with the setup you use:

Having added the CiviService Library to your project you can initialize the service my passing your key and base url information. These can be passed as string values e.g.:

CRM.init({'api_base': '[this_bit]', 
	      'api_key'	: 'YOUR_API_KEY',
      	  'key'		: 'YOUR_API_KEY'});
// where api_base [this_bit]/civicrm/extern/rest.php with either http or https

Rather than exposing keys in your script code it's recommended to store and recover this data as Script Properties. This will help protect this information. Script Properties can be set programmatically or via the Script Editor > Project properties and then opening the Script tab. If values are stored with the api_base, api_key and key keys a quick way to initialize the CiviService Library is:

var config = PropertiesService.getScriptProperties().getProperties();
CRM.init(config);

Alternatively the CiviService library has methods for storing credentials as User Properties. User Properties is Google storage only accessible to effective user. The advantage of this method is once credentials have been set they can automatically be used in other script projects using the library.

function setupOneTimeOnly(){
	CRM.setAPIBase('[this_bit]'); 
	CRM.setApiKey('YOUR_API_KEY'); 
	CRM.setKey('YOUR_SITE_SECRET'); 
}
// where api_base [this_bit]/civicrm/extern/rest.php with either http or https

If at any point you'd like to delete stored credentials you can call CRM.deleteKeysAndBase();

This library mimics the CiviCRM API AJAX Interface and permits singluar calls. For example, if you want to add a tag to a contact:

CRM.api3('entity_tag', 'create', {contact_id:512, tag_id:15});

After the api call is complete you might wish to do something with the result. In this case you can use the done method to listen for this event:

CRM.api3('entity_tag', 'create', {contact_id:123, tag_id:42})
	.done(function(result) {
		Logger.log(result);
	});

Here is an example for retrieving active Event Type labels and values and inserting the results into a sheet named EventType:

function updateEventTypeList(){
	CRM.api3("OptionValue", "get", {
			"sequential": 1,
			"option_group_id": "event_type",
			"return": ["label","value"],
			"is_active": 1
		}).done(function(result) {
			if(!result.is_error){      
				var sheet_out = [['label','value']];
				var choice_out =[];
				for (i in result.values){
					sheet_out.push([result.values[i].label, result.values[i].value]); 
				}
				var doc = SpreadsheetApp.getActiveSpreadsheet();
				var sheet = doc.getSheetByName('EventType');
				sheet.getRange(1, 1, sheet_out.length, 2).setValues(sheet_out);
			}
		});
}

This project is created my Martin Hawksey using code from the CiviCRM Core and contributions from Bruce Mcpherson.