Example 1: Integrating Using CiviCRM and Gmail on Zapier

Purpose of this Wiki Page This page provides the second First Example used as a proof of concept to integrate CiviCRM with Zapier basis on Gmail and CivCRM applications To be able to follow the content of this page Practically, the following is required A CiviCRM install on-line and a user account accessible The API key of the current accessible user and the Site Key of the The CiviCRM install Access a Zapier account http://www.zapier.com Gmail Account. Firefox poster plugin which could be installed directly on your browser visit About Firefox Poster AddOn

Below are the Series of steps followed to test the integration of CiviCRM and Zapier with main Application focus on Gmail

Tasks To Accomplish Integration

The tasks were as follow: Not actually in preference order

• Add CiviCRM as an application on Zapier

• Set up Authentication for CiviCRM App on Zapier

• Install Firefox Addon ‘Poster’

• Learn the basics of using ‘poster’

• Create a new Trigger to reflect a contribution

• Create a new webhook as the data source

• Get a unique URL which will be used to send that data in the webhook

• Configure ‘Poster’ to send a POST request with some sample data ( Json obtained from a sample API query on Contributions)

• Configure the webhook on zapier

• Adding existing CiviCRM account for authentication purposes

• Add a Gmail account for an action ( test )
  
  

Setup the action as a new draft for in my gmail account when the webhook works

These Tasks have been explained in detail below

1. Adding CiviCRM As An Application on Zapier

What is needed to start Task 1 First you require an account which can be obtained ( demo 15 days ), could login from https://zapier.com

From the Zapier Dashboard you click on the user profile drop down and select Developers

 
 

You should then get to the Dashboard where you can add a new Application Clicking the Add new app button leads you to adding the application info such as those you will see on the screen shots below

Now we can Setup the Authentication means ( we  chose the API key authentication for now since in the normal polling URL we provided the site key)

why use the API key as auth method This is done so because as this is a proof of concept, we have not thoroughly dived into the authentication but zapier adviced we should use one so requests are ensured, we have used API-key authentication as it is a primary necessity which a user of a particular CiviCRM install must have to be able to send requests and receive request through rest and webhooks.

After saving the App, click the button add authentication field  ( select API key & query string to make the authentication process complete )

about the Auth mapping fields  The mapping which Zapier does on the Auth mapping is left unchanged  field as it is not required for now

Just below authentication, you will see a trigger section. This is essentially where everything happens when you wish to react to something which was performed within CiviCRM and so help you configure your actions

After Entering the basic information of the server, click Save and next button below the ( “important “ ) check box

• On the section you may be requested to provide a trigger field, Just click next because that is not required for now.

• This navigation then takes you to the most important part, which has to define where data is coming from.

• Select static webhooks as the Data source
  
  

• A polling URL ( A URL which will be used for sample data if no webhooks are found ) 

   
  
  

  Take Noote of the static webhook oprion  By Choosing Static webhooks as data source, make sure that you remember that a URL will be provided to you which you will use in sending the data to the webhook

  
  

  
   

  How to quickly obtain a polling URL  A polling URL can be obtained from the REST URL in the API explorer since the results will always be returned in json which Zapier can make use of

   

  
  

  Polling URL Meaning A polling URL is a URL request which zapier uses to get data by repeatedly hitting the API for some results when webhooks data are not sent or some breakdown had occurred, considered as a “backup plan”, sp for example we can use our API explorer and query the database for results, then use the REST URL which the API explorer provides for a particular query and when we place this as polling URL, Zapier obtaines the same data when it sends the same  request to our CiviCRM install

   

   

  How to quickly obtain a polling URL Always remember that you have to replace the site_key in the URL to your own and the API-key could be confirm by the test above which we used for authentication. So the API key could be left out of the list of parameters in the rest URL as the POLLING URL can only be 200 characters

Note: 

• No sample results are required for the start of the trigger

• For a test Trigger, a polling URL must be provided so after saving the trigger click on the button which says “Manage Trigger settngs “ below the trigger section
  
  

• At the bottom of the next screen, select the trigger you created as test trigger

2. Setting UpAnd Exploring POSTER Firefox plugin

As required, Firefox addon ‘poster’ was to be used to send a request to analyze the validity of the webhooks before there are implemented.

• To install poster, go to firefox browser menu, click on addons, search poster and then click install ( it is less than 50 kb)
  
  

• To be able to use poster, i just looked out a few tutorials which it was used to effect what i had to do.

A couple of them are

 Cool Firefox Addon

Test web services or APIs Easily with poster

Firefox poster Addon for cloud REST API

3. Setting Up A Zap For The Webhook Test

To be able to be sure that the webhook works, we have to create a new zap ( A zap is a link between two applications in which when something happens  one,  Zapier automates some action to happen on the other.

Case: CiviCRM and Gmail Zap

The Following steps will be used to Demonstrate the Zap

• First at the top of the dashboard, click on “Make a Zap” and you should see a screen like this

• On the screenshot above, you will have to select a trigger application which is probably CiviCRM ( the App you just created)

• Next you will have to add a corresponding CiviCRM account which you will be prompted by Zaper ( This is just the API key of the user of your install of CiviCRM ). This is done by clicking “connect new account “

• Zapier then verifies (returns success or failure ) and then goes to the next step of choosing a trigger
   
   
   

  Server Notice The user must be logged in on a server which could be accessed by Zapier for the auth to take place successfully.

Using my API key IT returned a success

• In the next step, Zapier provides you with a URL which will be used as the webhook

Generated Webhook by Zapier This URL is important as it will be used to communicate with Zapier through Poster and why not CURL in our extension (  hopefully ).

• The next step involves testing the Trigger with the webhook. On a success “Everything should be green on Zapier” as i term it.

Next we have to setup the action( which is what we will do when the request to zapier is complete each time it is hitted on POSTER ( or from our extension ).

• First we setup the app which we will perform the action on ( I chose Gmail for the Demo)

• Next we configure that when the request is received the action should be started in my draft in my gmail

The Body of the Draft Looks Like this

For Just One Request we will see what will appear in the draft mail for three different requests

4. Testing The Webhook Using Poster

• Here we see how we can configure poster to send payload ( data ) to zapier through the webhook.
  
  

• To start poster on firefox, use CTRL + ALT + P

• A screenshot shows the configuration of poster with the webhook and payload

Issues to Note on Setting up Poster Note: - The authentication ( api-key ) which was provided is still used here Sample data obtained from the API explorer results is used as content or payload I used a POST request The most important is the URL which is the webhook URL given us by Zapie

From all Indications our POST request returns a 200 status code meaning everything went on well on POSTER

*** we have two more places to veify if really this worked ( you guessed right Gmail and Zapier History Data out )

• For Gmail Below is a screenshot of the Drafts

Check to see that you can see the Contact Id and the amount contributed ( It Works! ) 

^^^ But this is just the action. We have to check if all the data we sent go to zapier through the webhook

• In zapier, on your dashboard where your name displays select task history from the dropdown

Then you should see this a list of all requests which have been made successfully

They are arranged in order of arrival ( latest at the top ) . Choose any of them “latest probably”

This shows you the two applications involved in the request ( Trigger CiviCRM and the action Gmail)

*** Click on data out under CiviCRM to verify that CiviCRM received the payload you sent

From this dataset it shows tha the application (CiviCRM) in Zapier Received the data successfully from the request, and what is found in this set can be compared to what was sent using POSTER ( “ I have tried already and i have confirmed you too can try” )