API Automation Series, Episode 1: Getting Started in Zapier

In our first Episode of this new series we go through creating the integration in Zapier by setting up the authentication portion first and then set up our first “trigger” (GET action) to test the new integration.

Why Choosing Zapier?

    I came across Zapier only recently when I set up my new Patreon account. After reading up quickly on it I found that this service was one of the few that can handle the Vantagepoint authentication process out of the box.

It also comes with a lot of predefined connectors built in that you can use right out of the box (including a lot of Microsoft services). And as far as I can tell right now it does have excellent support by the online community.

It also offers a free starter license and a free developer license that you will need to follow along with this episode.

And no, sadly I’m not sponsored by them…

The Pros and Cons Of Using This Approach:

+ Pros

    • It’s easy to set up
    • There are a ton of predefined connectors that you can immediately use with the new Vantagepoint integration
    • You don’t need your own infrastructure (web servers, etc…)
    • You get quick results
    • No coding required

– Cons

    • There’s no such thing as a free lunch. There are monthly fees if you want to use this more professionally with multiple tasks running multiple times a day
    • It works really well with smaller projects and simple data exchanges. You might hit a wall if you need to implement complex workflows, data transformations and business logic
    • Not having it run in your own infrastructure might also be a problem (legal issues, data residing in another country, etc…You might not be able to solve certain problems with the tools you are given.
    • No Coding is not exactly true. You will have to resort to some javascript tricks for certain tasks (you will see later)

Getting Started

For you to be able to follow along you will need a couple of things first:

    • Create a free Zapier account at https://zapier.com
    • Create a free Zapier Developer account at https://developer.zapier.com
    • Have the Vantagepoint API documentation handy at https://vantagepoint3api.deltek.com
    • Have access to a Vantagepoint Sandbox environment
    • Have a username and password to said environment with admin rights
    • Active the API in Vantagepoint and keep the client id, client secret and database name save for later

Once we have all this, we can get going. The next paragraphs will guide you through setting up the connection and use it step-by-step.

Step 1: Create an Integration

First, we go to your newly created account at https://developer.zapier.com. There Zapier will ask you want to start a new Zapier integration. That’s exactly what we’re planning so click on that button.

In the “Create Integration” page we will have to provide some information before we can get into the thick of it:

    • A Name: really anything you want. This is what you (and other users if you share this) will see when selecting the integration later on.
    • A Description: again, feel free to enter some appropriate text.
    • A Homepage URL: your or your company’s homepage (optional)
    • A Logo: also optional
    • Intended Audience: pick “Private” if you want to use this just for yourself or within your company. Pick “Public” if you want to share this with the world. In this case anyone with a Zapier account can pick your Integration for any purpose.
    • Role: here you can pick from “I am employed by …”, “I was hired by …” or “I have no affiliation with …”, select what is most appropriate. For testing purposes I would pick the last item
    • Category: this lets Zapier know how other people can find this integration. It’s only really important if you plan to make this integration public. You can pick “Accounting”, “Business Intelligence” or any other appropriate item.

Once all is filled out, click on the Create button.

                                    <img width="525" height="517" src="https://www.steepvalley.net/wp-content/uploads/2020/09/step1_createintegration-768x757.png" alt="" loading="lazy" srcset="https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step1_createintegration.png?resize=768%2C757&amp;ssl=1 768w, https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step1_createintegration.png?resize=300%2C296&amp;ssl=1 300w, https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step1_createintegration.png?resize=1024%2C1009&amp;ssl=1 1024w, https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step1_createintegration.png?resize=1536%2C1514&amp;ssl=1 1536w, https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step1_createintegration.png?w=2043&amp;ssl=1 2043w" sizes="100vw" />                                            
        <h2>Step 2: Setting Up Authentication</h2>      
    <p>After you hit the <strong>Create</strong> button you will see the Home dashboard of your new integration. Throughout the series we will explore each available option but first we have to set up the Authentication with Vantagepoint before we can do anything else. So go ahead and click on the <strong>Set Up Authentication</strong> button.

This will bring you to the Authentication page where we select the Session Auth option and click Save.

This brings us to the most important section of the whole authentication setup: the authentication details for Session Auth:

Configure Your Fields

First, we have to set up a couple of fields (or variables) that we will use as placeholders and will prompt a user for these values. You could technically hardcode all the following information if it’s only you that uses this integration but I would highly recommend to use my approach. It makes it a bit safer…

We need to configure the following fields by clicking on the Add Fields button for each of these

Label Key Type Required Comment
Base Url base_url String Yes This is the base url to your vantagepoint instance. Again, you could make this a fixed value if you are not planning to share this outside your company
User Name username String Yes The username you want to use to connect to the Vantagepoint instance
Password password Password Yes The password for the user
Database database String Yes The database name as shown in the API configuration screen in Vantage-point
Client ID client_id String Yes The client id from the API configuration screen
Client Secret client_secret String Yes The client secret from the API configuration screen

Please make sure that the field keys match the list above. This will make it easier to follow the rest of the tutorial.

Click Continue when done.

Configure a Token Exchange Request

Next, we have to send a POST token request to Vantagepoint with the field values provided by the user.

The POST URL must be:

https://{{bundle.authData.base_url}}/api/token

The {{bundle.authData.base_url}} is a placeholder for the vantagepoint instance as defined in the Fields section previously.

Once we entered the POST URL, we click on Show Options and go to the Request Body tab. Delete any default entries Zapier added here and then add the following key/value pairs:

            <table data-id="3c65879"><tbody><tr><td>username</td><td> {{bundle.authData.username}}</td></tr><tr><td>password</td><td> {{bundle.authData.password}}</td></tr><tr><td>grant_type</td><td> password</td></tr><tr><td>integrated    Y</td></tr><tr><td>database</td><td> {{bundle.authData.database}}</td></tr><tr><td>client_id</td><td> {{bundle.authData.client_id}}</td></tr><tr><td>client_secret</td><td> {{bundle.authData.client_secret}}</td></tr></tbody></table>
    <p>If you ever used the Vantagepoint API in Postman then this should look very familiar to you. All the {{bundle.authData…}} values are placeholders that the end user has to provide values for and the keys are the standard keys as you saw them in the Postman templates.

Click Save & Continue when done

Configure a Test Request & Connection Label

In this step we need to provide Zapier with a test endpoint so they can check if the connection was handled correctly. In my sample I used the API call that returns the user details after the connection has been authorized.

The GET URL for this must be:

https://{{bundle.authData.base_url}}/api/security/user/{{bundle.authData.username}}

Click on Show Options and go to the HTTP Headers tab. Delete any default entries Zapier added here and then add the following key/value pair:

            <table data-id="a2127e4"><tbody><tr><td>Authorization</td><td> Bearer {{bundle.authData.access_token}}</td></tr></tbody></table>
    <p>Again, this should look very familiar to anyone that has used Postman before. The way this works is that Zapier adds any field returned from the initial authorization call to their {{bundle.authData…}} collection where we can then use those new fields anywhere in the integration configuration. By default the token request returns a JSON response like this:</p><pre>{<br />"access_token": "xxxx…",<br />"token_type": "bearer",<br />"expires_in": 1799,<br />"refresh_token": "xxx…"<br />}</pre><p>We will not necessarily need any information other than the access token but we will have to add the Authorization entry in the HTTP Headers above to any call we define later.

You can then give it a specific Connection Label if you want and use any of the placeholder values to make the connection label easier to identify for the end user (e.g. add base URL and user name to it)

Test your Authentication

Now we are ready to finally test the connection. Click on Test Authentication and Zapier will present a log in screen with all the fields you defined in the first step. Provide the correct values and click on Yes, continue.

If you followed all the steps and provided the correct values in the login screen you should now see your user details from Vantagepoint in the Response screen. If the test reports any errors then please read the error carefully, correct the issue and try again.

Step 3: Create a Trigger

Now that we are successfully connected to Vantagepoint, we want to add a quick trigger (a GET command) just to see if we can retrieve any data. This is just a quick setup for testing purposes. We will go into more detail with triggers and actions in another post in the near future.

Back on the integration Dashboard we click on Triggers. The system will ask you if you want to create your first trigger. Empathically answer with yes and click on Add Trigger.

Settings Tab

On the new Trigger page we have to provide Zapier with some basic information:

    • A Key: set it to “vpt_contacts”
    • A Name: call it “New Contact”
    • A Noun: set it to “Contacts”
    • A Description: set it to “triggers when new contacts are available”

Click on Save and Continue.

Input Designer Tab

For this initial test we won’t need any input form fields. Click on Save and Continue.

API Configuration Tab

In Step 1, set the Trigger Type to Polling. Then set the API endpoint to the following GET URL:

https://{{bundle.authData.base_url}}/api/contact

Click on Show Options and go to the Url Params tab. Delete any default entries Zapier added here and then add the following key/value pairs:

page {{bundle.Meta.page}}
pageSize 10

This sets up paging with the Vantagepoint Url so we don’t overwhelm the connection with hundreds of result items when calling the API. For this to work we also have to check the Support Paging option under Pagination.

Then we need to go to the HTTP Headers tab. Delete any default entries Zapier added here and then add the following key/value pair:

Accept application/json
Authorization {{bundle.authData.access_token}}

After all this we need to write our first code in our no-code solution. The reason is two-fold:

    1. Zapier starts paging at Zero whereas Vantagepoint starts at One. If we would not fix this in code we would get some errors later.
    2. Zapier expects any record returned by an API call to have an id field which must be the record’s unique identifier. Zapier uses this to filter and pass on only records with a new id to following processes and connections. Vantagepoint’s Contacts record does not have a field called id. So we have to generate one in code.

So go ahead and click on Switch to Code Mode. The system will give you a warning but just confirm that you’re totally OK with this.

Now you’re presented with a javaScript that looks like this:

const options = {
    url: `https://${bundle.authData.base_url}/api/contact`,
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${bundle.authData.access_token}`
    },
    params: {
        'page': bundle.Meta.page,
        'pageSize': '10'
         }
    }

    return z.request(options)
    .then((response) => {
        response.throwForStatus();
        const results = response.json;

        // You can do any parsing you need for results here before returning them

    return results;
    });

We will now modify the code and add the items in blue to it:

const options = {
    url: `https://${bundle.authData.base_url}/api/contact`,
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${bundle.authData.access_token}`
    },
    params: {
        'page': bundle.meta.page + 1,
        'pageSize': '10'
        }
    }

    return z.request(options)
    .then((response) => {
        response.throwForStatus();
        const results = response.json;
        return results.map(function(contact){
            contact.id = contact.ContactID
            delete contact.ContactID
            return contact
        })
    });
                                    <img width="525" height="517" src="https://www.steepvalley.net/wp-content/uploads/2020/09/step16_setup_getcontacts_code-768x757.png" alt="" loading="lazy" srcset="https://i2.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step16_setup_getcontacts_code.png?resize=768%2C757&amp;ssl=1 768w, https://i2.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step16_setup_getcontacts_code.png?resize=300%2C296&amp;ssl=1 300w, https://i2.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step16_setup_getcontacts_code.png?resize=1024%2C1009&amp;ssl=1 1024w, https://i2.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step16_setup_getcontacts_code.png?resize=1536%2C1514&amp;ssl=1 1536w, https://i2.wp.com/www.steepvalley.net/wp-content/uploads/2020/09/step16_setup_getcontacts_code.png?w=2043&amp;ssl=1 2043w" sizes="100vw" />                                            
    <p>The first change makes sure that the pagination starts from one and not zero.

The second change reformats the result on the fly and adds a new id field to the output that has the existing ContactID value. Then it removes the ContactID field from the result. Removing the field is optional if you want to use ContactID in another process.

Once you made all the code changes click on Save API Request & Continue.

Go to Test Your API Request and click on Test Your Request. If you followed all the steps you should see some contact information coming through on the Response tab. Click on Finish Testing & Continue.

In the Sample Data section you can click on Use Response from Test Data to give the user an idea of what content to expect. And then you can click on Generate Output Field Definitions to initiate the list of available fields and then label them accordingly. This step is optional though.

Then click Save Output & Finish and voilà, we’re done with our first trigger.

Next Steps

This concludes our first episode. We have now a working connection from Zapier to Vantagepoint and a quick and simple trigger that we will use in the coming episodes to show you some more scenarios and tips and tricks when working with these features.

Our next episode will deep dive into

    • Adding an employee trigger
    • Include updated records in the Zapier triggers
    • Create a zap (integration) to copy contacts and employee to Outlook
    • Create a zap to write into an Excel sheet

After that we will look into writing back to Vantagepoint using the same techniques.

I hope you enjoyed this

Mike Dobler

                                    <img width="300" height="61" src="https://www.steepvalley.net/wp-content/uploads/2020/08/Digital-Patreon-Wordmark_White-300x61.png" alt="" loading="lazy" srcset="https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/08/Digital-Patreon-Wordmark_White.png?resize=300%2C61&amp;ssl=1 300w, https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/08/Digital-Patreon-Wordmark_White.png?resize=1024%2C209&amp;ssl=1 1024w, https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/08/Digital-Patreon-Wordmark_White.png?resize=768%2C156&amp;ssl=1 768w, https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/08/Digital-Patreon-Wordmark_White.png?resize=1536%2C313&amp;ssl=1 1536w, https://i1.wp.com/www.steepvalley.net/wp-content/uploads/2020/08/Digital-Patreon-Wordmark_White.png?resize=2048%2C417&amp;ssl=1 2048w" sizes="100vw" />                                            
    <p>A special shout-out to my first Patreon supporter:

Rob Hendriksen

I appreciate your support!

Share this post

Share on facebook
Share on google
Share on twitter
Share on linkedin
Share on pinterest
Share on print
Share on email