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.