Nintex Workflow – Insightly UDAs
Recently, I was asked whether Nintex Workflow can talk to Insightly. Insightly is Googles CRM product. So as it’s the end of the year (2015) and I want to hit 50 User Defined Actions on this site, I decided to try to talk to Insightly. I created the UDAs that you can reuse in your workflows, but the aim really is to show how to do the common this like, creating an object, querying for objects, querying for objects based on a filter and updating an object.
Firstly, in order to talk to Insightly, make sure you have an API Key for the account you’re going to use to talk to Insightly. Once you have the API Key, you’ll need to convert it to Base64 format. Bing has a built in Base64 encoder.
Once you have an encoded API Key, create yourself a Nintex Workflow Constant. For the User Defined Action I have built for this post, I created a constant called InsightlyBase64AuthorizationToken. If you want to use these UDAs, you either need to have a constant with that name, or update the UDAs (specifically the Web Request action) to use your token.
Talking to Insightly
To see all the things that Insightly exposes through their API, take a look at this : https://api.insight.ly/v2.1/Help/Introduction
When configuring the Web Request action in Nintex Workflow, you will require two Headers to be added.
The Content-type is not absolutely required, but since we are working in Nintex Workflow, leaving that out means the data will come back in JSON format. That’s harder to parse in Nintex Workflow. Therefore, I added Content-Type “text/xml”, and now the data I send to Insightly and receive from it, will be in XML format. Another thing to note, is to make sure you change the “Content type” in the Web Request action, to map what it says in the Insightly APIs. I found that for creating an “Organisation”, if I didn’t do this, it would fail with “400 Bad Request”. It worked fine for “Contact” though.
The other header is Authorization. This is that Base4 encoded API Key we talked about earlier. But make sure you also put “Basic ” in front of the value. That is required.
This is the Insightly API to create an Organisation
This is the Nintex Workflow Web Request configuration for the Content Types
Getting a Contact Email Addresses from Insightly using Nintex Workflow
To query a bunch of contacts, the url is https://api.insight.ly/v2.1/contacts . The Web Request action needs to be configured to perform a GET, with the heads above, and you’ll get a bunch of XML back.
After the Web Request action, I have a Query XML action to pull out the email address of all the contacts. This required an XPath expression : /defaultNS:ArrayOfContact/defaultNS:Contact/defaultNS:CONTACTINFOS/defaultNS:ContactInfo/defaultNS:DETAIL
It’s quite a small UDA. All of these are. The reason, is that I don’t want to have to worry about how to configure these later, each time I need to use them.
This UDA only has one output Parameter “User Email Addresses”, which is a collection.
Getting a Contact by Email Address from Insightly using Nintex Workflow
Now we want to query for all contacts with a specific email address. Now, if you’re getting more than one result here, something is weird with your CRM :).
This UDA has two parameters. An input parameter, which is the email address we are looking for. The output parameter is the XML result from the query. You’re probably wondering, why am I returning XML? Insightly, when updating an object, requires the entire object to be sent via the update. So we need the entire XML, should we need to update that contact.
The Web Request is configured to a slightly different URL : https://api.insight.ly/v2.1/contacts?email=Contact Email Address
Notice that there is a parameter on the end of the URL, called email. The red token is the input parameter that a workflow would send to this UDA.
Updating First Name of a Contact on Insightly using Nintex Workflow
This UDA lets you update the First name property of a contact on Insightly. If you missed this above, when sending an update request to Insightly, you need the entire object. In this case, the entire Contact object. This is why we could use the Get Contact by Email UDA to get the XML, then call this UDA, passing in two parameters. Contact XML and the First Name. The UDA will then use an Update XML action to update the Contact XML and then make the web request call to : https://api.insight.ly/v2.1/contacts but in this case, doing a PUT (that is what is used to update an object).
Creating a Contact on Insightly using Nintex Workflow
The final piece of this puzzle to create an object, like a Contact. In this, we still use the same URL https://api.insight.ly/v2.1/contacts , but since this is a new object, we need to do a POST in the Web Request action. Also, since it’s a new object, we only need a subset of the data in the XML.
Notice how the XML is limited, since in our case, all we want to do is create a contact and three fields, First Name, Last Name and Email.
Wrapping up on what we did here. These aren’t necessarily UDAs you’ll download and use straight away. You will most likely need to tweak them a little. Especially since they are built just for Contacts. There are a number of different object types that it supports and you’ll be able to handle most of those with these Nintex Workflow processes. I say most, because Insightly also support custom object types and I haven’t played with those yet, so I can’t comment on whether you can create, update, query those types of objects.
Don’t forget to tweak the Web Request actions to use your API Key (Base64 format) Workflow Constant!!!
This post is to get you started, because you’ll find you will be able take this, learn from it and build other UDAs for your own needs.