Build a Plugin with External API

Learn how to build a simple announcements plugin that allows you to communicate directly to your customers from within the banking dashboard, powered by an external spreadsheet.

After completing this tutorial you should have an understanding of integrating third-party APIs into your own plugins.

What We’re Building

The end goal of this project will be to demonstrate how easy it is to build a plugin that integrates one or more external APIs. Specifically, we’ll be using the Airtable platform to build a simple management system for displaying announcements in our plugin. Because of its simplicity and power, it’s a perfect tool to use how you may build more complex plugins with the Banno platform.

What is Airtable?

Airtable is a very simple platform which resembles a basic spreadsheet that you may be more familiar with. The platform itself gives a very visual interface to a traditional database, allowing you to build interesting systems on top of it.


Prerequisites

Before you get started, you’ll need the following:

  • An Airtable account
  • The back office administrator at your financial institution who has access to Banno People

When referencing Banno People, we mean your financial institution’s deployment of Banno People.

If you are developing using a Jack Henry test environment, you will not have access to Banno People. In this case, Jack Henry is the acting administrator of the financial institution and you will have to contact us for any Banno People operations.


Airtable Configuration

Setup the Base

In Airtable, a spreadsheet is simply called a “base”. The simplest way to configure your own for this tutorial is to copy our existing base.

Our base will be simple: a single table named Announcements, containing a Title, Message, and Status column. If you opt to create the base yourselves rather than copying, you will need to make a note of the names you use.

  1. Navigate to our base
  2. Click Copy base
  3. Follow steps to copy the base to your own account
  4. Name your base Events (double click the existing name in order to change it)

Copy Airtable base

API Keys

We’ll need API keys for Airtable.

  1. Navigate to the Airtable Account page
  2. If it is your first time, you’ll need to click Generate keys
  3. Copy your API key and save for later

Base ID

The simplest way to retrieve the ID for your base is simply to navigate to Airtable API docs and select the name of your base (Events if you followed the above).

You will be greeted with a message towards the top:

The ID of this base is xxxxxxxxxxxxx.

Save this ID for later.


Configure the Plugin

External Application

If an administrator for your institution (Or Jack Henry, if you are using the Garden environment) has configured an external application and plugin on your behalf, you may skip this section.

You’ll need to configure an External Application in the External applications section of the Banno People app.

For this example, change the following values:

  1. Create a new external app
  2. Enter a custom name (ex. My Test Application)
  3. Uncheck User consent required (since we are building a Plugin Card)
  4. Click Save Create a new External App

After clicking Save, you will be redirected back to the list of external apps, open your new app from the list

  1. Select PluginCard as the link type
  2. Enter a title for the link (ex. Demo Announcement Plugin)
  3. Enter http://localhost:8080/dynamic for the redirect URI (Note: You may need to change this if you alter the port number later)
  4. Select Enabled to enable the plugin for users (if you do not enable for all users, you will need to use the User Permissions function to enable for select users)

Because this specific plugin will not be requesting any user information, we do not need to use authentication. Because of this we do not need the Client ID or Client Secret to run this plugin. However, this is where you would find those in the future.

Plugin Configuration

Required Steps

You’ll need to create the Plugin Configuration in the Dashboard configuration section of the Banno People app.

  1. Click Add an item to add a new item to the dashboard configuration
  2. Scroll to the botton and click Create a plugin

You will be prompted to enter details about your plugin.

  • Title: My Announcements Plugin
  • Description: A demo plugin for displaying announcements
  • External Application: My Test Application - Demo Announcements Plugin (This is the name we used when configuring the external application above)
  • Initial height: 250
  • Icon: alarm clock (this can be anything)

Configure dashboard app details

Optional Steps

For this example, change the following values:

  • Label : View more
  • External Application: My Test Application - Demo Announcements Plugin

Dashboard Configuration

Clicking the save button will create the plugin configuration.

The administrator can make it available for your users to add to their dashboard.

  • Click Add an item again – this time select the plugin you created
  • Make sure to click Save to preserve your new dashboard configuration
Note

Since we did not enable the option Available to everyone, we will need to enable the plugin for specific users. While building and testing your plugin, you will likely want to utilize this option. Enabling for all users will make the plugin available globally to every user in your institution.

Enable Plugin Card for User

As mentioned in the note above, if you don’t want the plugin enabled for ALL users, we need to select which users to enable the Plugin Card for.

  • From Banno People, click the Users and search by username.
  • Click on the user
  • Click Permissions
  • Find and enable the plugin under Plugin cards

The user will now have the plugin available to them in the Banno Online dashboard.


Running the Plugin

Start by cloning the repository, Simple Announcement Plugin.

The Code

In this plugin, we will be fetching data from an external resource and displaying it to the user within their Banno Online Dashboard. In this simple example, we will not be utilizing any authentication because we do not need any user information.

The plugin will perform 2 simple operations: fetch data from Airtable and display any announcements with the “Live” status to the user.

Notable Files

  • config.js is the file where all configuration settings and API keys will be saved.
  • index.js is the file where the operations to fetch and serve data will occur. The project specifically uses the Express framework as a simple server and the EJS template system for simplicity. You’ll notice that we use the /dynamic route to power our plugin, primarily we chose this so that if you’ve followed the Build Your First Plugin Quickstart, your external app and plugin do not need to be reconfigured.
  • views/announcements.ejs is the template file where the HTML is rendered from. The EJS template system allows us to use both Javascript and HTML to render our data rows (specifically we are able to loop through the rows and render them dynamically).

Setup

Before we run the application, we need to make sure that all the dependencies are available.

  • Install dependencies using the npm install command

Banno Online

User’s Dashboard

You’ll need to add the plugin to your user’s dashboard.

Do these steps:

  • Log into Banno Online
  • Click on Organize dashboard
  • Click on Add a card
  • Click on My Announcements Plugin
  • Click the back arrow on Add a card in the navigation header
  • Click the done button on Organize dashboard

Running the plugin

Configuration

The primary configurations that we need to set are within the config.js file. When you clone the repository above, you will want to start by renaming the config-exmple.js file to config.js.

  • airtable_api_key: Your API key from Airtable
  • airtable_base: Base ID from Airtable (see above to find)
  • airtable_table_name: ‘Announcements’ (unless you changed the name)

Start the plugin

  • Start the server using the npm run start command

The server will now be running locally. You’ll see this log statement in the terminal:

App running at http://localhost:8080

Now, navigate back to Banno Online dashboard, you can see that the plugin now fetches and displays live announcements to users in their dashboard.

Final plugin running


Next Steps

Congratulations! Continue your learning journey:

If you would like to expand on this plugin, some ideas you can borrow as inspiration: