Connector Builder in Open Connectors – Survey Monkey

In this blog, we’ll create a Survey Monkey Open Connector using Connector Builder. The API can be found here: https://developer.surveymonkey.com/api/v3/

Since the Survey Monkey API is protected with Oauth 2.0, the first step is to register an application to get a key and secret.

Img 1 – Survey Monkey API documentation – Oauth 2.0

 

Img 2 – Survey Monkey Developer Portal – Application Registration

 

This is where you will retrieve the client Id and secret. The Redirect URL is https://auth.cloudelements.io/oauth

Img 3 – Survey Monkey Developer Portal – Create an Application

 

Select the scopes

Img 4 – Survey Monkey Developer Portal – Create an Application – Scopes

 

After you save your application, copy the client Id and secret – we will enter them in Connector Builder. You will also need the authorize URL and the token URL from the Oauth docs (see above).

Let’s build a Connector. First, click on Connectors and then Build a Connector -> Create

Img 5 – Open Connectors Platform – Connectors

 

The first screen, or the Information screen, should be populated like this since the Survey Monkey API is a REST API with Oauth 2.0 Authentication.

Img 6 – Open Connectors – Connector Builder Information Screen

 

The next screen, or the Setup Screen, is where we’ll set up the Base URL, pagination, and the Oauth 2.0 configuration, as well as webhooks.

Img 7 – Open Connectors – Connector Builder Setup Screen – Properties

 

We chose Pagination Type as ‘page starts with 1’ according to this documentation:

Img 8 – Survey Monkey API Documentation – Pagination

 

Moving down to the Authentication, this is where you will enter the Authorize URL, the Token URL, and the clientId and secret.

Img 9 – Open Connectors – Connector Builder Setup Screen – Authentication

Notice how we will not be entering a scope – the registered application takes care of the scopes.

 

Let’s click on the green Try it Out button from the above image.

Img 10 – Open Connectors – Connector Builder Setup Screen – Authentication Try it Out

 

When we create a Connector Instance, the Oauth 2.0 flow will be initiated. You will be redirected to the Survey Monkey login screen

Img 11 – Survey Monkey Oauth 2.0 Login Screen

Afterwards you will be asked to accept the required scope permissions.

 

Once back in Connector Builder, you’ll be able to inspect the Oauth 2.0 responses, and see how Open Connectors will store the access token and append to each call going forward.

Img 12 – Open Connectors – Connector Builder Setup Screen – Authentication Response

 

Now that an Instance has been created, we can start building and testing some resources by clicking on the Resources tab in Connector Builder. Once there, let’s click Add a new resource.

Img 13 – Open Connectors – Connector Builder Resources Screen – Create a Resource

 

Let’s build the contacts resources.

Img 14 – Survey Monkey API Documentation – contacts

 

Notice how we enter contacts in the vendor resource name. This, plus a /, will be appended to the Base URL that we entered on the Setup screen.

After clicking Go, you’ll see this screen. Let’s edit the GET /contacts resource by clicking on the pencil icon.

Img 15 – Open Connectors – Connector Builder Resources Screen – Edit a Resource

 

Expanding out the Configuration section, we’ll keep the Resource Type as API and add a Response Root Key of data.

Img 16 – Open Connectors – Connector Builder Resources Screen – Edit a Resource – Parameters

 

This is because the response looks like this:

{

   "per_page": 50,

   "total": 2,

   "data": [

       {

           "href": "https://api.surveymonkey.com/v3/contacts/2856836347",

           "first_name": "John",

           "last_name": "Doe",

           "id": "2856836347",

           "email": "test@surveymonkey.com"

       },

       {

           "href": "https://api.surveymonkey.com/v3/contacts/2856850975",

           "first_name": "Barbara",

           "last_name": "Allen",

           "id": "2856850975",

           "email": "barbaraallen@fake.com"

       }

   ],

   "page": 1,

   "links": {

       "self": "https://api.surveymonkey.net/v3/contacts?page=1&per_page=50"

   }

}

 

We only care about the objects in the data array.

 

The three parameters added are the default parameters. Looking back at the pagination query parameters in the API:

Img 17 – Survey Monkey API Documentation – Pagination

 

We see we have to map ‘page’ and ‘per_page’ to the Open Connectors normalized parameters of ‘page’ and ‘pageSize.’

Now we are ready to save the resource and try it out.

Img 18 – Open Connectors – Connector Builder Resources Screen – Save a Resource

 

Press Execute to try out the resource

Img 19 – Open Connectors – Connector Builder Resources Screen – Execute a Resource

Img 20 – Open Connectors – Connector Builder Resources Screen – Execute a Resource and Inspect Response

 

Everything looks good. You can also click on Vendor Request to inspect what was actually sent to the vendor.

Img 21 – Open Connectors – Connector Builder Resources Screen – Execute a Resource and Inspect Vendor Request

 

Finally, let’s utilize the default parameter “where.” This takes in filters and concatenates them together using modified SQL, or OCNQL. Let’s look at the filters offered by the API.

Img 22 – Survey Monkey API Documenation – contact filters

 

Let’s try the GET /contacts resource again, this time with some filters in the where clause

Img 23 – Open Connectors – Connector Builder Resources Screen – Execute a Resource with Where Clause

Let’s also add a Response Model for this GET /contacts resource. Run the resource and copy the response and then click on Response Model.

Img 24 – Open Connectors – Connector Builder Resources Screen – Adding a Response Model

 

Click on Generate from Sample Payload and paste the response.

Img 25 – Open Connectors – Connector Builder Resources Screen – Paste raw response to generate response model

 

Then click Generate.

Img 26 – Open Connectors – Connector Builder Resources Screen – Clicking Generate to create response model

 

Now that we have metadata generated, we can enable bulk. Click on the Bulk tab.

Img 27 – Open Connectors – Connector Builder Resources Screen – Enable Bulk

 

Select id in the dropdown for Primary Key. The response payload does not contain any date fields so we can leave them blank. Select Enable Bulk Download and Save. Now click on the API Docs tab, next to the Resources tab on the top menu. You will now see bulk resources.

Img 28 – Open Connectors – Connector Builder Resources Screen – Execute a Bulk Query

 

Enter in select * from contacts and Execute. You will get back a bulk job Id. Thid Id can be used to get the bulk job status.

Img 29 – Open Connectors – Connector Builder API Docs Screen – Execute /bulk/{id}/status

 

This file can then be retrieved by using the GET /bulk/{id}/{objectName} endpoint.

Now that we’ve enabled bulk, let’s add a POST resource with a body parameter.

Img 30 – Open Connectors – Connector Builder Resources Screen – Create a POST Resource with body parameter

Img 31 – Open Connectors – Connector Builder Resources Screen – Request Model

 

If we add a Request Model using the POST body used to create a contact

{ "first_name": "John", "last_name": "Doe", "email": "test@surveymonkey.com" }

it will populate as a guide when we try the resource out.

Img 32 – Open Connectors – Connector Builder Resources Screen – After request model generation, it appears in body

 

To finish up, let’s add events. The Survey Monkey API supports webhooks. The first step is to navigate back to the Setup screen of Connector Builder and scroll to the bottom to enable events.

Img 33 – Open Connectors – Connector Builder Setup Screen – Enable Webhooks

 

The documentation (https://developer.surveymonkey.com/api/v3/#webhook-callbacks) states that the webhook body will be sent in this format.

Img 34 – The body Survey Monkey sends out as a webhook

 

We can use this structure to create an Event Hook. The Event Data Body above is referenced in this hook as “events.”

Img 35 – Open Connectors – Connector Builder Setup Screen – Formatting Webhooks

 

Once the formatting is achieved and the pertinent information is parsed out in the done statement, it can be saved.

Now, when Survey Monkey sends the Connector Instance an event webhook, the Instance can digest it and parse out the relevant information.

In order to create a webhook in Survey Monkey, we have to POST an API call

Img 36 – Survey Monkey API Documentation – webhooks

 

With this body:

{"name":"My Webhook", "event_type":"survey_created","subscription_url":"https://urltosendwebhookto.com"}

Since we have enabled webhooks, any Instance we create of this Survey Monkey Connector will have a unique URL to send webhooks to. To find it, first go to Connectors and search for Survey Monkey and click the little blue bubble

Img 37 – Open Connectors – Connectors – Finding an Instance

 

Edit the Instance and enable events and you will see the Webhook URL.

Img 38 – Open Connectors – Edit an Instance

 

We would like the Connector Instance to create the needed webhooks right when the Instance is created. To achieve this, we’ll create another POST resource called /webhooks. Here is the documentation for all of the supported webhooks: https://developer.surveymonkey.com/api/v3/#webhooks

Img 39 – Open Connectors – Connector Builder Resources Screen – Create a webhook resource

 

There are two important points to note. First, the Resource Type is not API, but rather ON PROVISION WEBHOOK. This means that as soon as the Instance is created, this resource will run.

Second, the POST payload above to create a webhook is entered as the value in the body parameter. We could place the Webhook URL in that body – however, let’s put in a variable {{webhookCallbackUrl}} so that it enters the correct URL for every Instance created.

To view any collected events, you can click on Activity in the left menu, and then Event Logs.

In this blog, we’ve created a Survey Monkey Connector in Open Connectors using Connector Builder from start to finish. We’ve included the Oauth 2.0 authentication, the contacts resources, bulk, and webhooks.