Reference Guide

Connectors

Connectors allow your Nutshell apps to communicate with the rest of your IT eco-system. For example, your app might generate PDF reports that are uploaded to your Google Drive account, or capture photographs that are uploaded to an FTP server.

A REST Connector calling Capsule CRM’s RESTful API to populate a form

There are two kinds of Connector in Nutshell; a generic Connector that will allow you to integrate with just about any third party web service or API (albeit with a little hoop-jumping), and platform-specific Connectors that make the process of connecting with commonly used platforms (such as FTP, Dropbox, Google Drive etc.) much quicker and easier.

The Dropbox Connector makes uploading files a doddle

Our library of platform-specific Connectors is growing all the time, but if your favourite platforms aren’t supported yet, don’t worry – the generic Connector will get you connected.

REST Connector

The REST Connector component allows you to connect your app to any RESTful web service or API. If terms like “web serviceFind more information here“, “APIFind more information here” and “RESTfulFind more information here” have you scratching your head, it might be worth grabbing someone more technical to help you out. It’s not rocket science, but there are a few things you’ll need to understand before you start.

Integrating with APIs is beyond the scope of this Reference Guide, so you’re probably best getting to grips with these concepts first. Once you’re up on the lingo, this guide will help you find your way around Nutshell’s REST Connector.

Before we begin, this guide assumes that you have good grasp of:

• What a web service is, and what it’s used for
• What an API is and how it is used
• What RESTful means
• Basic related terminology, such as: models, methods, requests, calls, parameters etc.

It also assumes that you have a third party RESTful API you’d like to integrate with, and the proper credentials to do so. It’s also a good idea to have the documentation for that API open alongside Nutshell, while you’re working.

Setting up a Connector

The first stage is to set up your Connector – once it’s been set-up, you can use this Connector as many times as you like within your app, to push and pull data back and forth between your app and a third party API.

A good example of this would be integrating a data capture app with your back-end CRM. In fact, that’s the example we’ll be working with here – capsulecrm.com – who provide an excellent RESTful API to pass customer information back and forth to and from their platform.

The Connectors panel will be empty to begin with

In the App Builder, under the Data tab, you’ll find a page for setting up and storing your Connectors. The list will be empty to begin with, but you can quickly change that by clicking the Create New Connector button.

Choose from a growing range of pre-defined Connectors

You’ll be asked what kind of Connector you want to create. All Connectors work in the same way, but we’re interested in the REST Connector for now. Click on the REST icon to continue.

You’ll be asked to provide security credentials for the API you’re integrating with

In the next step, you’ll be asked to provide security credentials for the API you’re going to be using. Different services require different combinations of username/password and/or authentication token to gain access to their APIs – please read the documentation of the API you’re using to find out what they require.

Once you’ve entered your credentials, you’ll need to provide the URIs for each REST end-point. You’ll need to set-up a separate Connector for each model you wish to work with.

Specify the REST end-points for your model, so that you don’t have to re-type them later

If the end-points all use the same URI, that’s fine – just add the same URI for each resource. Whenever you make a call, you’ll be asked which model and which method you’d like to call, and the correct URI will be used automatically.

If you’ve ever worked with Nutshell’s Data component, this should be a familiar concept.

Use Nutshell’s simple model-builder to recreate your model’s data structure

The final stage is to tell Nutshell what the model looks like behind the scenes, but you won’t have to write any XML or JSON by hand. Nutshell’s model-builder allows you to add, indent and re-shuffled nodes until your Connector’s data structure matches that of the service you’re connecting to.

Most API documentation will provide illustrations of the model they expect to receive and dispatch in both XML and JSON format. Simply build out your model structure until it matches.

By telling Nutshell how the data model is structured, it can help you map your incoming/outgoing data to your on-screen form fields, variables and database tables later – making manipulating the data you send and retrieve much, much easier.

Once you’ve created a Connector, it becomes available to your app in the Data tab

Now, when you add a Connector component to your app workflow, you’ll be able to access this model and any methods associated with it.

Implementing a Connector

If you’ve used a Data component to manipulate data within your Nutshell database, then this should be a breeze. In fact, we’d highly recommend getting your head around that first as a good primer on handling and mapping data in Nutshell.

A basic app with two forms: one to search by ID and another to populate with the data retrieved

In this example, we’re just going to retrieve a person from Capsule CRM based on their ID, so we’ve got a form on the left to handle the search criteria, and another on the right, which will be populated with the person’s first and last names after the API call is complete.

You can find the Connector component in the Data tool bar

To add a REST Connector to the workflow, simply drag the Connector component from the Data tool bar on the Canvas.

Add your Connector just like you would a Data component and link it up

The Connector works just like the Data component – the main difference being that the data it is accessing isn’t in the Nutshell database, but on a remote server somewhere. Other than that, Nutshell uses them in more or less the same way… with a few subtle differences, which we’ll cover shortly.

With the Connector selected on the Canvas, look at the Properties Panel. The first it asks you for is the Connector you’d like to use. Here, you’ll see a list of any Connectors you’ve already set-up.

Choose the Connector you’d like to use

In this example, we want to retrieve a Party from Capsule’s API, so we select that model. Next, you’ll be asked which of the method you’d like to call – GET, PUT, POST or DELETE. Select the one most appropriate.

In our example, we’re retrieving data, so we’re using the GET method.

Choose one of the methods you set-up earlier

Once you’ve selected the model and the method, it’s time to pass some parameters. There are several ways to pass parameters to an API, all of which are accommodated by Nutshell’s REST Connector.

Passing Parameters in the Headers

You may come across an API that asks for parameters to be passed with the headers. If this is the case, open the Header Data section in the Properties Panel. Use the little “+” button to add new parameters.

Choose which field or variable will provide the value for the parameter named on the left

Into the text field on the left, type in the parameter name as it needs to appear. The dropdown on the right contains a list of all the form-fields and variables in your app. Choose which field or variable will be supplying the value for this parameter.

The end result is a stack of name/value pairs that will be passed to the method in the header. Our example here doesn’t require parameters to be passed with the header, so we’re going to leave this blank.

Passing Parameters with the URL

Most APIs will request that at least some parameters are passed within the URI – sometimes even including security credentials. If this is the case, open the URL Data section of the Properties Panel and you’ll see the current method URL (as defined when you set-up the Connector).

Choose a form-field or variable from the dropdown to insert it automatically when the call is made

Beneath the URL, you’ll see a dropdown containing all of the form-fields and variables in your app. Whatever you choose from this dropdown will be appended to the URL, and will provide the value to be inserted when the call is made.

Input “id_field” on the “Start” Screen will be appended to the URL when the method is called

In our example, Capsule CRM requires the Party’s ID to be passed as the first parameter in the URL. So we insert it, referencing the “id_field” on the Screen called “Start”, and it is inserted automatically.

Once you’ve inserted any parameters your API requires, save your changes.

Passing Parameters as an Object

Many APIs require that data is sent as an XML or JSON object. Ordinarily, this would mean writing and validating a lot of XML or JSON by hand, but Nutshell takes care of this for you.

Open the Input/Request Data section of the Properties Panel to begin mapping.

Request Data can be defined within the Properties Panel

Because you set up the model structure earlier, Nutshell knows what the request object looks like, and will build and validate the object for you. All you need to do is tell Nutshell where the data for each of the model’s attributes will be coming from.

For example, if we were going to pass the ID of our Party within a request object, we’d map our “id_field” on the search form to the “id” field within our model structure.

Use the little “+” button to add new attributes to your object

Add as many fields as you need to pass to the request, and Nutshell will build the model for you, using the structure you defined when you set up the Connector.

Our example doesn’t require the Party ID to be sent within a request object, so we’re going to leave this blank.

So that’s it. Making an API call is easy with Nutshell’s Connector. Just make sure you’ve defined your model structure correctly and that the URL structure is as it should be. The documentation for the API you’re connecting with should give you clear instructions on how to do this.

Handling the Response

Once you’ve made your API call, you’ll need to define what should happen to the data when it comes back. Most of the time, you’ll probably want to pre-populate a form, pushing each attribute to the appropriate field. Alternatively, you might want to insert certain attributes into Variables, so that you can reference them later.

In the same way you mapped form-fields within your app to attributes within your request object, you can map attributes from the response object to form-fields within your app. It’s basically the same process, just the other way around – Nutshell will automatically parse the response object according to the model you’ve defined.

Mapping attributes to form-fields is the same for Responses as it is for Requests

In our example, we’re taking the “firstName” and “lastName” attributes from the response, and inserting them directly into the “first_name” and “last_name” form-fields in our app.

Once your Response mapping is complete, you can save your changes and preview your app. This is where the Debug Log really comes in handy.

The debug log tells you everything that’s going on in the background

There’s a lot going on beneath the surface, where API calls are concerned. It’s easy to make small mistakes – incorrectly spelled attribute names, mistyped URLs, mismatched data-types, incorrect model structure – the list goes on.

The debug log tells you exactly what’s going on behind the scenes, including the final URL generated (including any attributes you passed along with it) and any objects sent or received, so that you can see any errors you might’ve made.

The debug log will also pass on any error messages received from the API server, such as HTTP responses, which can prove invaluable when passing data via the headers.

REST Connector Properties

When a REST Connector component is selected on the Canvas, the following settings are available in the Properties panel: